Des scanners ratissent Internet en continu à la recherche d'un seul fichier : votre documentation d'API. Le SANS Internet Storm Center a de nouveau signalé cette semaine des vagues de scans visant spécifiquement les fichiers swagger.json exposés. Ce n'est pas un développeur curieux qui cherche à comprendre votre produit. C'est de la reconnaissance, à l'échelle d'Internet, automatisée.
Et la plupart des équipes qui exposent ce fichier ne savent même pas qu'il est là.
Les faits
Quand vous construisez une API (Application Programming Interface) moderne, vous générez très probablement une spécification OpenAPI — l'ancien Swagger. C'est une excellente pratique : ce fichier décrit toutes vos routes, leurs paramètres, leurs formats d'entrée et de sortie, parfois leurs exemples. Couplé à une interface comme Swagger UI, il offre une documentation interactive superbe, qui fait gagner un temps fou aux équipes et aux intégrateurs.
Le problème n'est pas le fichier. C'est qu'il se retrouve, par défaut, accessible publiquement, à des emplacements parfaitement prévisibles : /swagger.json, /openapi.json, /v2/api-docs, /swagger-ui.html. Des chemins si standardisés qu'un attaquant n'a même pas besoin de chercher : il connaît l'adresse à l'avance. Il lui suffit de scanner massivement et de collecter ceux qui répondent. C'est exactement ce que les capteurs du SANS observent.
Ma lecture
Une spécification OpenAPI exposée, pour un attaquant, c'est le rêve. En un fichier, il obtient ce qu'il aurait dû construire péniblement par tâtonnement : la carte complète de votre surface d'attaque.
Il y voit vos routes d'administration que vous pensiez « cachées » parce qu'aucun lien ne pointe vers elles. Il y voit les paramètres attendus par chaque endpoint, donc exactement quoi injecter et où. Il y voit vos conventions de nommage d'identifiants — un cadeau pour tester l'IDOR (Insecure Direct Object Reference), cette classe de failles où l'on substitue l'identifiant d'une ressource par celui d'un autre utilisateur pour y accéder sans droit. Il y voit parfois des routes internes, des versions d'API dépréciées laissées en ligne, des fonctionnalités à moitié déployées. La sécurité par l'obscurité, déjà fragile, n'existe tout simplement plus : vous avez publié le plan du bâtiment, avec les portes de service entourées en rouge.
Le cœur du problème, c'est une confusion de périmètre. La documentation d'API a deux publics radicalement différents : vos développeurs et intégrateurs d'un côté, le monde entier de l'autre. On conçoit le fichier pour le premier public, et on l'expose au second sans s'en rendre compte. Ce qui est un outil de productivité en interne devient un outil de reconnaissance en externe. Le même fichier, deux usages opposés, et personne n'a tranché qui devait pouvoir y accéder.
Le scénario que je vois le plus souvent en mission illustre bien le piège. Une équipe construit une API publique propre, bien pensée, documentée avec soin. À côté, pour ses besoins internes, elle ajoute au fil du temps des routes d'administration, des endpoints de débogage, un back-office. Tout ça part dans la même spécification, parce que c'est le même framework, le même générateur automatique de doc. Personne ne décide consciemment de publier la route qui réinitialise un mot de passe ou celle qui exporte la base clients : elles arrivent dans le swagger.json toutes seules, parce que le générateur documente tout ce qu'il voit. L'équipe pense exposer une vitrine ; elle expose aussi l'arrière-boutique, les réserves et le bureau du directeur.
Et c'est là que le danger devient concret. Ces routes « internes » sont souvent les moins bien protégées, précisément parce que leurs auteurs les croyaient invisibles. On met moins d'efforts d'autorisation sur une route qu'on pense que personne ne connaît. L'attaquant, lui, l'a trouvée en téléchargeant un fichier. Le décalage entre « je pensais que c'était caché » et « c'était dans la doc publique » est exactement l'espace dans lequel les incidents se produisent.
Le contre-argument, traité honnêtement
L'objection est légitime, et je la partage en partie : « une API publique est faite pour être appelée. Cacher sa documentation, c'est de la sécurité par l'obscurité, et on sait que ça ne vaut rien. Une route doit être sécurisée qu'elle soit documentée ou non. »
C'est vrai, et c'est même fondamental : si exposer votre swagger.json suffit à vous compromettre, votre vrai problème n'est pas la documentation, ce sont vos contrôles d'accès. Une route correctement authentifiée et autorisée reste sûre même si l'attaquant connaît son existence. Masquer la doc ne corrige jamais une faille ; ça la rend juste un peu plus longue à trouver.
Mais réduire la question à « obscurité contre sécurité » rate un point pratique. La reconnaissance est une étape réelle de toute attaque, et tout ce qui la rend gratuite et instantanée joue contre vous. Vous n'avez pas à offrir le plan. Réduire la surface d'information n'est pas une stratégie de sécurité à soi seule — mais c'est une couche, et les couches comptent. La défense en profondeur, c'est précisément accepter que chaque mesure soit imparfaite, et les empiler quand même. Exposer son schéma complet à des inconnus, ce n'est pas une fatalité technique : c'est un réglage par défaut qu'on n'a pas remis en question.
Ce que ça change pour vous
Trois décisions concrètes, et aucune ne consiste à supprimer votre documentation.
D'abord, séparez la spec interne de la spec publique. Vos développeurs ont besoin de tout voir ; vos clients externes, seulement des routes qui les concernent. Générez deux documents : une documentation complète, derrière authentification, pour vos équipes ; une documentation réduite, publique, qui ne décrit que l'API réellement destinée à l'extérieur. La majorité des frameworks permettent ce découpage.
Ensuite, mettez la documentation derrière un mur quand elle n'a pas vocation à être publique. Concrètement, sur un reverse proxy, refuser l'accès aux chemins de doc depuis l'extérieur est trivial :
location ~* /(swagger|openapi|api-docs) {
allow 10.0.0.0/8; # réseau interne uniquement
deny all; # tout le reste : 403
}Ce n'est pas la sécurité de votre API — c'est juste arrêter de distribuer son plan à qui le demande.
Enfin, et c'est le vrai sujet : partez du principe que votre schéma est déjà entre les mains de l'attaquant, et sécurisez en conséquence. Chaque route documentée doit appliquer l'authentification et surtout l'autorisation par objet. Les routes d'administration ne doivent pas dépendre de leur discrétion pour être protégées. Les versions d'API dépréciées doivent être réellement éteintes, pas seulement « plus liées ». Faites l'exercice inverse de l'attaquant : récupérez votre propre spec, et pour chaque route, demandez-vous ce qui se passe si un inconnu authentifié l'appelle avec l'ID du voisin. Si une seule réponse vous gêne, vous savez par où commencer. C'est typiquement le réflexe qu'on travaille dans la formation OWASP Web Security : lire son propre code avec les yeux de l'attaquant.
Comment vérifier en cinq minutes si vous êtes exposé
Pas besoin d'outil sophistiqué pour savoir où vous en êtes. Voici l'inspection que je fais en début d'audit, et que vous pouvez reproduire vous-même.
D'abord, testez les chemins standards à la main, depuis l'extérieur de votre réseau (un navigateur, en navigation privée, sans vos cookies internes). Essayez les classiques sur votre domaine public : /swagger.json, /swagger-ui.html, /openapi.json, /v2/api-docs, /api/docs. Si l'un d'eux répond avec votre spécification ou l'interface interactive, vous savez déjà ce que l'attaquant sait.
Ensuite, si la spec est accessible, lisez-la en attaquant, pas en développeur. Comptez les routes : combien y en a-t-il que vous pensiez non publiques ? Cherchez les mots qui font tilt — admin, internal, debug, test, legacy, v1 alors que vous êtes en v3. Chacun est une piste. Repérez les endpoints qui prennent un identifiant en paramètre : ce sont vos candidats IDOR. Vous venez de faire, en cinq minutes, la moitié du travail de reconnaissance d'un attaquant — autant le faire avant lui.
Enfin, élargissez le regard au-delà de la doc. Le même réflexe vaut pour tout ce qu'on expose sans y penser : les fichiers .git laissés accessibles, les .env traînant à la racine, les pages de statut de framework en mode debug, les sauvegardes oubliées. La documentation d'API n'est qu'un cas particulier d'un problème plus large : on déploie vite, et on laisse en ligne des artefacts pensés pour le développement, pas pour le public. La discipline, c'est de se demander systématiquement, pour chaque chose qu'on met en ligne : est-ce que ceci doit vraiment être lisible par le monde entier ? C'est exactement la posture qu'on installe dans le Bootcamp DevSecOps — faire de cette question un réflexe de pipeline, pas une revue ponctuelle.
Cet exercice, refait régulièrement, vaut mieux qu'un scanner lancé une fois. Parce que ce qui vous expose, ce n'est pas une faille exotique : c'est l'accumulation de petits oublis que personne n'a la responsabilité de surveiller.
Ce qu'il faut retenir
Le scan de swagger.json n'est pas une attaque en soi. C'est le premier coup d'œil de l'attaquant sur votre maison, et il est gratuit tant que vous laissez le plan sur le paillasson. Vous n'avez pas à choisir entre une bonne documentation et la sécurité : séparez les publics, protégez ce qui doit l'être, et surtout, ne faites jamais reposer la sécurité d'une route sur le fait que personne n'en connaît l'adresse. Une bonne documentation et une bonne posture de sécurité ne s'opposent pas ; elles cohabitent dès lors qu'on a décidé, explicitement, qui a le droit de lire quoi.
La bonne question à se poser n'est pas « est-ce que mon API est documentée ? ». C'est « qu'est-ce que ma documentation raconte à quelqu'un qui me veut du mal — et est-ce que ça lui suffit pour entrer ? ».