Sécurité de la Documentation API: Votre Spécification est-elle Sûre dans Git?

La sécurité de la documentation API est la partie de votre programme API que presque personne n'audite. Vous renforcez l'API elle-même avec l'authentification, les limites de débit et les tests de sécurité. Mais les documents qui décrivent cette API, la spécification OpenAPI, la page Swagger UI, le markdown expliquant votre flux d'authentification, vivent souvent dans un dépôt Git ou sur un hébergeur statique que personne n'a examiné depuis le jour de sa mise en place. Le 20 mai 2026, GitHub a confirmé que des attaquants avaient volé des données dans environ 3 800 de ses dépôts de code internes. Le point d'entrée était une extension VS Code piégée installée sur l'ordinateur portable d'un employé de GitHub. Cette brèche est une bonne raison de poser une question inconfortable sur votre propre configuration : si quelqu'un pouvait modifier discrètement vos documents API publiés, le remarqueriez-vous, et vos consommateurs d'API le remarqueraient-ils ?

TL;DR

Une documentation API sécurisée signifie que vos documents ont un contrôle d'accès, un historique des versions, une intégrité que vous pouvez vérifier et une piste d'audit, de sorte qu'un dépôt ou un hébergeur compromis ne puisse pas alimenter silencieusement de mauvais points d'accès, jetons ou instructions d'authentification aux développeurs qui les copient en production. Le « docs-as-code » dans Git est acceptable pour de nombreuses équipes et vous offre la révision et l'historique gratuitement. Cela devient une vulnérabilité lorsque le dépôt est public sans contrôle d'accès, lorsque des spécifications obsolètes divergent de l'API en direct, ou lorsqu'un exemple falsifié atteint les consommateurs sans être détecté. Une couche de documentation gérée comme Apidog ajoute une protection par mot de passe, des listes blanches IP et e-mail, des domaines personnalisés, le versionnement et une spécification maintenue synchronisée avec la conception de votre API comme source de vérité.

Pourquoi la brèche de GitHub devrait vous faire examiner votre documentation API

L'incident de GitHub mérite d'être compris avant de paniquer. Le groupe de menaces TeamPCP a exfiltré des dépôts internes de GitHub et vend maintenant l'ensemble de données pour plus de 50 000 $ sur un forum clandestin. La couverture de BleepingComputer confirme que l'extension VS Code malveillante provenait directement du marché officiel et a été exécutée sur l'appareil d'un employé. GitHub affirme n'avoir trouvé aucune preuve que les données clients stockées en dehors de ses dépôts internes aient été affectées, et l'enquête est en cours.

Ce que la brèche fait, c'est vous donner un indice. C'est un rappel d'examiner où et comment votre documentation API réside, et si elle peut être altérée. La plupart des équipes n'ont jamais posé cette question. Elles ont publié Swagger UI sur GitHub Pages il y a trois ans, y ont pointé un CNAME et sont passées à autre chose. Le dépôt est public. La spécification est ce qui a été fusionné en dernier. Personne n'examine les changements apportés au site de documentation avec le même soin qu'ils appliquent au code d'application.

Cet écart est important car la documentation API est une instruction. Lorsqu'un développeur s'intègre à votre API, il copie les chemins des points d'accès, les formes des requêtes, les en-têtes d'authentification et souvent les exemples de valeurs directement de votre documentation dans son code. Si un attaquant peut modifier ces instructions, il ne dégrade pas une page marketing. Il modifie du code que d'autres personnes exécuteront. La même logique apparaît dans les revues post-incident d'autres brèches de 2026 ; notre article sur les leçons de sécurité API tirées de la brèche de Vercel explique comment un petit changement dans une surface de confiance se propage.

Cet article aborde quatre points : les façons concrètes dont des documents API compromis nuisent à vos consommateurs, quand le "docs-as-code-in-Git" est réellement acceptable et quand il devient une vulnérabilité, ce que signifie réellement une "documentation API sécurisée" comme liste de contrôle, et comment une couche de documentation gérée comble les lacunes. Deux articles connexes approfondissent des aspects liés : ce que la brèche de GitHub signifie pour les outils API auto-hébergés et la sécurité des clés API des extensions VS Code.

Ce qui se passe mal lorsque le dépôt ou l'hébergeur de votre documentation API est compromis

Commencez par le modèle de menace. Votre documentation API se trouve sur une surface : un dépôt Git, une pipeline CI qui les construit, et un hôte qui les sert. Compromettez l'un d'entre eux et quelques résultats néfastes spécifiques s'ensuivent. Aucun d'entre eux n'est théorique.

L'altération de la documentation atteint le code de production

C'est le pire des cas et le moins évident. Un attaquant ayant un accès en écriture à votre dépôt de documents, ou à l'hôte servant le site construit, fait une petite modification. Il change https://api.payments.acme.com/v2/charge par un domaine qu'il contrôle. Il échange le jeton d'authentification "bearer" exemple dans votre page "Démarrage rapide" contre un qui passe par son proxy. Il réécrit une seule phrase dans votre section OAuth afin que l'échange de jetons poste vers la mauvaise URL.

Rien de tout cela ne casse votre site. La page s'affiche toujours. La CI passe toujours, car la spécification est toujours un YAML valide. Mais le prochain développeur qui s'intègre à votre API copie ce point d'accès ou ce flux dans son service. Le changement est maintenant exécuté dans son environnement de production, et il l'a fait confiance parce qu'il venait de votre documentation officielle.

Considérez un fragment OpenAPI réaliste. Une équipe documente un point d'accès de paiement comme ceci :

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

Une seule modification de cette URL de `servers`, fusionnée via un compte compromis ou poussée vers un hôte détourné, et chaque consommateur qui régénère un client à partir de la spécification envoie désormais les données de carte au domaine de l'attaquant. La différence est de deux mots. Personne ne signale deux mots dans un commit de documentation.

Les points d'accès internes et non documentés fuient

Les dépôts de documentation accumulent des choses. Une spécification qui a commencé comme API publique s'enrichit souvent de chemins internes, de points d'accès d'administration, de routes de débogage ou d'opérations réservées aux partenaires qui n'étaient jamais censées être publiées. Si le dépôt est public, ou devient public suite à une mauvaise configuration, ces points d'accès sont désormais une carte pour quiconque scanne votre surface d'attaque.

Même un dépôt privé pose problème ici. Une brèche comme celle de GitHub exfiltre des dépôts privés. Dès l'instant où votre spécification d'API interne se trouve dans un dépôt volé, un attaquant dispose d'un inventaire précis de vos points d'accès, paramètres et charges utiles attendues. Il n'a pas besoin de deviner. Vous leur avez fourni le schéma. Si vous souhaitez un cadre pour trouver ces lacunes avant que quelqu'un d'autre ne le fasse, notre liste de contrôle des tests de sécurité API pour 2026 est conçue autour de ce type d'examen de surface.

Les pages publiques de GitHub n'ont pas de contrôle d'accès

GitHub Pages est un hôte statique. Il sert des fichiers. Il n'a aucune notion de qui les lit. Pour une API véritablement publique, c'est correct et acceptable. Pour une documentation qui ne devrait être visible que par les clients payants, par un ensemble de partenaires nommés ou par votre propre équipe, c'est le mauvais outil, car il n'y a aucune barrière.

Les équipes contournent ce problème avec la "sécurité par une URL difficile à deviner". La documentation se trouve à un chemin que personne ne lie. Ce n'est pas un contrôle d'accès. Les URL fuient via l'historique du navigateur, les en-têtes de référence, les journaux de proxy et les favoris partagés. Quiconque trouve le lien voit tout, pour toujours, sans que vous ne puissiez savoir qu'il l'a fait.

Documents obsolètes et invérifiables

Le mode de défaillance plus silencieux n'a pas besoin d'un attaquant. Les documents dans un dépôt Git dérivent. Quelqu'un livre un changement d'API, oublie de mettre à jour la spécification, et le markdown décrit maintenant un point de terminaison qui se comporte différemment en production. Les consommateurs s'intègrent au comportement documenté, rencontrent le comportement réel et passent une journée à déboguer.

Lorsque les documents sont compromis, ce problème s'aggrave, car vous perdez la capacité de distinguer la dérive de l'altération. Ce point de terminaison a-t-il toujours été faux, ou quelqu'un l'a-t-il changé ? Sans un historique vérifiable lié à la conception réelle de votre API, vous ne pouvez pas y répondre. Les documents deviennent invérifiables, et des documents invérifiables ne sont pas beaucoup mieux que pas de documents du tout.

Quand le "docs-as-code" dans Git est acceptable et quand il devient une vulnérabilité

Le "docs-as-code" est une pratique légitime et populaire, et cette section n'est pas un argument contre elle. Placer votre spécification OpenAPI et votre markdown dans un dépôt Git, construire Swagger UI ou Redoc avec CI, et déployer sur un hôte statique vous procure de réels avantages. Vous bénéficiez d'une révision par pull-request sur les modifications de la documentation. Vous obtenez un historique complet de qui a changé quoi et quand. Vous avez les documents versionnés en même temps que le code. Ce sont exactement les propriétés qui rendent l'altération détectable, lorsque le flux de travail est suivi.

La question n'est donc pas "Git ou pas Git". C'est "cette configuration particulière est-elle sûre pour cette API particulière". Voici comment les deux cas se répartissent.

Le "docs-as-code" dans Git est acceptable lorsque

La pratique fonctionne bien sous un ensemble spécifique de conditions :

• L'API est entièrement publique, donc il n'y a rien à cacher et aucun contrôle d'accès n'est nécessaire.
• Le dépôt dispose d'une protection de branche, de révisions obligatoires et d'un petit groupe de personnes auditées ayant un accès en écriture.
• Les modifications de documentation passent par la même rigueur de révision que le code, de sorte qu'une URL ou un jeton échangé est détecté lors de la révision.
• La pipeline de construction est verrouillée : actions épinglées, pas d'étapes tierces non révisées, informations d'identification de déploiement à portée limitée.
• La spécification est générée ou validée par rapport à l'API réelle, et non éditée à la main et espérée.
• Quelqu'un est responsable de la mise à jour de la spécification, de sorte que la dérive ne s'accumule pas.

Si toutes ces conditions sont réunies, la documentation hébergée sur Git est un système solide et transparent. L'historique est votre piste d'audit. Les révisions sont votre contrôle d'intégrité.

Le "docs-as-code" dans Git devient une vulnérabilité lorsque

La même configuration devient risquée lorsque les conditions glissent :

• Les documents devraient être privés ou réservés aux partenaires, mais l'hébergeur n'a pas de contrôle d'accès, donc "privé" signifie "non lié".
• L'accès en écriture est large, ou inclut des comptes de service et des jetons CI que personne ne surveille.
• Les commits de documentation sont validés sans examen, car "ce ne sont que des documents", de sorte qu'un diff malveillant passe inaperçu.
• La spécification est maintenue à la main et diverge de l'API en direct, de sorte que les consommateurs ne peuvent pas lui faire confiance.
• Le dépôt contient des points d'accès internes ou non documentés aux côtés des points d'accès publics.
• Il n'y a pas de signal d'intégrité : personne ne pourrait dire si le site déployé correspond à la source révisée.

La brèche de GitHub tombe directement dans ces modes de défaillance. L'attaque est passée par un point d'accès développeur et a atteint des dépôts internes. Si votre spécification d'API privée vivait dans l'un de ces dépôts, la brèche a exposé votre schéma quelle que soit la rigueur de votre processus de révision. Git vous offre la transparence ; il ne vous offre pas la confidentialité une fois que le dépôt lui-même est volé. Pour une comparaison plus complète des approches de documentation auto-hébergées sur ces compromis, consultez notre comparaison de la documentation API auto-hébergée.

Le message est intentionnellement équilibré. Conservez le "docs-as-code" si votre API est publique et que votre pipeline est discipliné. Réfléchissez-y si votre documentation nécessite un contrôle d'accès, si votre processus de révision traite les documents comme de seconde zone, ou si vous ne pouvez pas répondre à la question "le site en direct correspond-il à la source révisée".

Ce que signifie réellement une « documentation API sécurisée »

Une « documentation API sécurisée » est vague tant qu'on ne la décompose pas en propriétés vérifiables. Quatre d'entre elles ont un poids considérable.

Contrôle d'accès

La documentation n'est visible que par les personnes qui devraient la voir. Publique pour une API publique. Restreinte pour les documents réservés aux clients, aux partenaires ou internes. La restriction doit être une véritable barrière, mot de passe, liste blanche d'IP, liste blanche d'e-mails ou SSO, et non une URL obscure. Le test : pouvez-vous nommer exactement qui peut lire votre documentation en ce moment, et en révoquer un en moins d'une minute ?

Gestion des versions

Chaque version publiée des documents est conservée et identifiable. Les consommateurs de votre API v1 voient la documentation v1 ; les consommateurs v2 voient la v2. Vous pouvez montrer ce que disait la documentation à une date donnée. Le test : un développeur s'intégrant à votre ancienne version d'API peut-il toujours trouver une documentation précise pour celle-ci, au lieu d'une documentation qui a été silencieusement mise à jour vers la v2 ?

Intégrité

Vous pouvez vérifier que les documents publiés correspondent à ce que vous vouliez. Soit les documents sont générés à partir d'une source de vérité contrôlée, soit il existe une piste de révision et d'historique suffisamment solide pour qu'une modification non autorisée se démarque. Le test : si quelqu'un a changé une URL de point d'accès sur vos documents en direct il y a une heure, est-ce que quelque chose vous le dirait ?

Piste d'audit

Vous pouvez savoir qui a modifié les documents, ce qu'ils ont modifié et quand. L'historique Git vous fournit cela pour le dépôt ; vous en avez également besoin pour la surface publiée, car l'étape de déploiement est un point d'attaque en soi. Le test : pouvez-vous produire un journal des modifications pour vos documents publiés au cours des 90 derniers jours ?

Une configuration qui satisfait ces quatre points est une documentation sécurisée. La documentation hébergée sur Git peut atteindre le versionnement, l'intégrité et la piste d'audit grâce à la protection des branches et à l'historique. Ce qui manque généralement sur un hôte statique, c'est le contrôle d'accès, et cette lacune est l'argument en faveur d'une couche de documentation gérée.

Comment Apidog vous offre une documentation API sécurisée

Apidog est une plateforme API tout-en-un pour la conception, le débogage, le test, le mocking et la documentation des API. La partie documentation est construite de manière à ce que les quatre propriétés ci-dessus soient des valeurs par défaut plutôt que des éléments que vous devez ajouter. Pour suivre, téléchargez Apidog et ouvrez n'importe quel projet avec une définition d'API.

Documentation publiée à partir d'une source de vérité contrôlée

Dans Apidog, la documentation est générée à partir de la conception de votre API au sein du projet. Vous concevez les points d'accès, les schémas et l'authentification dans le concepteur visuel, et Apidog génère automatiquement la documentation à partir de cette définition. Appuyez sur Publier et vous obtenez un site de documentation interactif avec une console "Essayer" et des exemples de code multilingues.

L'avantage en termes d'intégrité est structurel. Les documents publiés ne sont pas un markdown modifiable séparément qui pourrait dériver ou être falsifié de manière autonome. Ils reflètent la définition de l'API. Changez la définition, les documents suivent. Pour modifier ce que les consommateurs voient, vous modifiez la conception à l'intérieur du projet, qui a ses propres autorisations et historique des modifications, au lieu de modifier un fichier libre sur un hôte statique.

Contrôle d'accès à la documentation

C'est là qu'Apidog comble la lacune de GitHub Pages. Lorsque vous publiez, vous choisissez la visibilité, et les options sont de véritables barrières, pas de l'obscurité :

• Public : toute personne ayant le lien peut le lire. Correct pour une API véritablement ouverte.
• Protection par mot de passe : définissez un mot de passe (ou générez-en un aléatoire) et partagez-le avec les parties prenantes. Seules les personnes ayant le mot de passe peuvent y accéder.
• Liste blanche d'IP : restreignez l'accès à des IP ou des plages spécifiques, comme votre bureau ou votre VPN. Utile pour les documents internes.
• Liste blanche d'e-mails : listez les adresses e-mail ou les domaines autorisés ; les utilisateurs vérifient avec un code à usage unique. Les jokers comme *@votreentreprise.com couvrent toute une organisation.
• Connexion personnalisée : connectez votre propre système d'authentification ; votre serveur émet un JWT, Apidog le vérifie, et l'accès dépend de la validité.

Apidog documente les cinq méthodes dans son guide de contrôle d'accès à la documentation API. Cela répond directement au test de contrôle d'accès : vous pouvez indiquer qui peut lire les documents, et vous pouvez révoquer un mot de passe ou retirer un e-mail de la liste blanche immédiatement.

Nom de domaine personnalisé

Vous pouvez servir la documentation publiée sur votre propre domaine, de sorte que les consommateurs voient developer.yourcompany.com au lieu d'une URL générique. Apidog prend en charge un domaine personnalisé via un CNAME DNS (le chemin recommandé) ou un proxy inverse. Un domaine personnalisé seul n'est pas un contrôle de sécurité, mais il maintient votre documentation sur une infrastructure que vous administrez et gouvernez, plutôt que dispersée sur des hôtes que personne ne possède.

Spécification OpenAPI maintenue synchronisée avec la conception de votre API

La dérive est un problème de sécurité de la documentation car elle rend les documents invérifiables. Apidog considère la conception de l'API comme la seule source de vérité et maintient la documentation synchronisée à mesure que la conception change. Apidog importe OpenAPI 3.0, 3.1 et Swagger 2.0, et prend en charge les importations planifiées afin qu'une spécification externe reste automatiquement à jour.

Si vous maintenez actuellement une spécification à la main dans un dépôt Git, c'est la configuration la plus sujette à la dérive et la plus difficile à vérifier. Déplacer la spécification dans Apidog en tant que source de vérité signifie que les documents publiés correspondent toujours à une définition que vous contrôlez. Les équipes venant de SwaggerHub peuvent suivre notre guide de migration de la documentation API SwaggerHub vers Apidog.

Gestion des versions de la documentation

Apidog prend en charge la gestion des versions de la documentation, de sorte que vous publiez et conservez plusieurs versions côte à côte. Un consommateur s'intégrant à votre API v1 lit la documentation précise de la v1 même après la sortie de la v2. Le versionnement est lié aux branches et à l'historique des modifications, de sorte que l'évolution de l'API et de sa documentation reste tracée. Cela couvre à la fois les tests de versionnement et de piste d'audit.

Rien de tout cela n'aurait empêché TeamPCP de compromettre l'ordinateur portable d'un développeur. Cela signifie autre chose : une réponse claire sur qui peut lire vos documents, si la version publiée correspond à votre conception, et ce qui a changé au fil du temps. C'est l'audit que la brèche de GitHub devrait vous pousser à effectuer.

Comparaison des options d'hébergement de documentation

Un rapide comparatif des approches courantes par rapport aux quatre propriétés de sécurité.

Il n'y a pas de ligne universellement correcte. GitHub Pages public est un excellent choix pour une API publique avec un pipeline verrouillé. L'auto-hébergement convient aux équipes ayant des exigences strictes en matière de résidence ou d'isolation ; notre comparaison de la documentation API auto-hébergée et la comparaison Scalar vs SwaggerHub vs Apidog détaillent ces compromis. L'important est de choisir délibérément en fonction des quatre propriétés, et non d'hériter d'une configuration d'il y a trois ans sans jamais la revoir.

Conclusion

La brèche de GitHub n'est pas une raison d'abandonner le "docs-as-code" ou de se méfier de GitHub. C'est une incitation à auditer une surface que la plupart des équipes ont ignorée : où réside votre documentation API et si elle peut être altérée.

Étape suivante : listez tous les endroits où votre documentation API est publiée, vérifiez chacun d'eux par rapport aux quatre propriétés, et comblez la lacune la plus importante. Si le contrôle d'accès est la lacune, téléchargez Apidog et publiez la documentation d'un projet avec un mot de passe ou une liste blanche d'e-mails pour voir comment une couche gérée le gère.

bouton