Comment utiliser security-audit-skill ? Audit de sécurité automatisé avec Cloudflare AI Coding Agent, analyse des vulnérabilités, validation du code et rapport de sécurité en pratique

Un agent signale des vulnérabilités, mais ses commandes, ses permissions et ses preuves restent impossibles à contrôler.

La solution la plus rapide consiste à utiliser security-audit-skill pour un premier audit de dépôt et les recherches répétitives, dans un bac à sable à privilèges minimaux, puis à faire vérifier chaque résultat par un humain. Cette compétence ne remplace ni un test d’intrusion ni la validation de mise en production.

À qui s’adresse ce guide ?

Ce guide vise les responsables techniques qui doivent unifier une procédure d’audit, les ingénieurs sécurité qui veulent réduire le travail répétitif et les développeurs qui maintiennent un projet ouvert ou sensible. Vous y trouverez surtout une méthode de décision sur les permissions, les journaux, la validation humaine et le choix entre exécution locale et environnement distant.

La documentation officielle décrit une chaîne d’audit en six phases, avec reconnaissance, recherche guidée par la couverture, découverte de candidats, validation, production structurée des résultats et contrôle de la sortie. Cette architecture est plus importante que la simple capacité de l’agent à « trouver un bug » : elle détermine la qualité des preuves et la possibilité de relire le travail. Consultez le dépôt officiel de security-audit-skill et son fichier SKILL.md avant chaque déploiement, car l’installation et les exigences peuvent évoluer.

Dernière mise à jour : 21 septembre 2026. Les éléments relatifs aux phases, au schéma de sortie et au fonctionnement attendu ont été vérifiés à partir du dépôt officiel, du fichier SKILL.md, du script de validation et des tests référencés. La compatibilité pratique avec chaque agent doit être confirmée dans votre propre environnement.

Le bon périmètre avant la première commande

security-audit-skill convient à trois situations différentes, qui ne doivent pas être mélangées.

• Audit initial d’un dépôt : l’agent cartographie l’architecture, les frontières de confiance, les entrées et les zones sensibles, puis propose des candidats à examiner. C’est une étape de triage et de couverture, pas une certification.
• Recherche ciblée : vous lui demandez de suivre un flux précis, par exemple une entrée utilisateur vers une couche d’authentification, un traitement de fichier audio ou vidéo, une API interne ou un module de conception qui importe des ressources externes. Le périmètre est plus étroit, mais les hypothèses doivent être écrites.
• Question de sécurité : vous cherchez à comprendre un mécanisme, une permission ou une configuration. L’agent peut expliquer le code et proposer des contrôles, mais une réponse textuelle ne constitue pas une preuve de vulnérabilité.

Un test d’intrusion exige généralement un périmètre autorisé, des règles d’engagement, des observations dynamiques et un compte rendu signé par une personne compétente. L’audit assisté par IA peut préparer une partie de ce travail, mais il ne doit pas être présenté comme son équivalent automatique. Cette distinction protège votre équipe contre deux erreurs coûteuses : publier une alerte non vérifiée ou déclarer sûr un composant que l’agent n’a jamais couvert.

Les prérequis à vérifier avant l’installation

Préparez les éléments suivants, sans donner à l’agent davantage d’accès que nécessaire :

• une version de Node.js compatible avec votre chaîne d’outils, téléchargée depuis la page officielle de Node.js ;
• le dépôt placé dans un répertoire de travail clairement identifié ;
• un compte ou un jeton limité à la lecture lorsque l’audit ne nécessite pas de modification ;
• un mécanisme d’appel des outils autorisés par l’agent ;
• un répertoire de sortie séparé, destiné aux journaux et à findings.json ;
• une procédure d’approbation humaine avant toute commande qui compile, exécute ou modifie le code.

Ne copiez pas les secrets de production dans le répertoire audité. Un fichier de configuration de développement peut contenir des identifiants, des URL internes ou des certificats oubliés. Avant de lancer l’agent, recherchez ces éléments et remplacez-les par des valeurs factices.

Installation et déclenchement sans faux diagnostic

L’installation réussie d’une compétence ne signifie pas que l’agent l’utilisera. Le problème le plus fréquent est une compétence placée dans un chemin que l’agent ne parcourt pas, suivie d’une conversation où la demande reste trop générale.

Procédez dans cet ordre :

1. Installez le runtime nécessaire. Vérifiez la commande node et l’accès aux outils requis dans le même environnement que l’agent. Une installation faite dans votre terminal principal peut être invisible dans un conteneur ou une session distante.
2. Ajoutez la compétence depuis la source officielle. Suivez la commande indiquée dans le dépôt, sans recopier une ancienne instruction trouvée dans une discussion. Le dépôt peut modifier son arborescence ou sa procédure.
3. Ouvrez l’agent dans le bon répertoire. Le dossier courant doit être la racine du projet audité, et non le dossier parent contenant plusieurs dépôts.
4. Demandez une reconnaissance explicite. Indiquez que l’objectif est un audit de code contrôlé, donnez le périmètre et demandez une liste des zones couvertes avant toute recherche de vulnérabilité.
5. Vérifiez l’appel réel de la compétence. L’agent doit charger ses instructions, utiliser les outils attendus et produire des sorties identifiables. Une réponse générale sur les bonnes pratiques ne prouve pas que security-audit-skill a été déclenchée.
6. Commencez par un sous-périmètre. Choisissez un module sans secret et suffisamment représentatif. Comparez les fichiers examinés avec la couverture annoncée.
7. Conservez les journaux. Enregistrez la demande, les commandes approuvées, les erreurs, les résultats intermédiaires et la version du dépôt utilisée.

Pour tester Claude Code, appuyez-vous sur son guide officiel de démarrage, puis vérifiez séparément le chargement de la compétence et l’appel des outils. Pour Codex, ne déduisez pas la compatibilité d’un simple nom de format : reproduisez le même test minimal. Si la compétence n’est pas reconnue, contrôlez successivement le chemin, le répertoire de travail, les permissions de lecture, le format attendu par l’agent et la présence des outils.

Un message du type « audit terminé » sans liste de fichiers, sans couverture et sans sortie structurée doit être traité comme un échec de déclenchement, non comme un audit propre.

Comment éviter qu’un audit explore seulement les dossiers populaires ?

La phase de reconnaissance doit produire une représentation exploitable du projet : composants, flux de données, frontières de confiance, entrées externes, dépendances et zones qui exécutent ou désérialisent des données. Le registre de couverture, ou coverage ledger, sert ensuite à noter ce qui a été inspecté, ce qui a été ignoré et pourquoi.

Prenons un exemple anonymisé. Un dépôt de traitement vidéo contient api/, workers/, plugins/, assets/ et tools/. Une première passe se concentre souvent sur api/, car les routes sont visibles. Le registre doit pourtant mentionner que workers/ consomme des fichiers importés, que plugins/ charge des extensions et que tools/ lance des commandes pendant la génération des aperçus. Si seuls les contrôleurs HTTP sont examinés, une entrée dangereuse peut être déplacée vers le travailleur asynchrone et rester invisible.

Un registre utile associe chaque zone à une justification :

• Zone : chemin ou composant exact ;
• Rôle : entrée, transformation, stockage, exécution ou sortie ;
• Frontière : utilisateur, service interne, fichier ou dépendance ;
• Statut : examiné, partiellement examiné, exclu ou à reprendre ;
• Raison : preuve disponible, outil manquant, code généré ou permission refusée ;
• Prochaine action : lecture manuelle, test isolé ou validation par le propriétaire.

Cette méthode de couverture guidée par les risques évite de confondre volume de texte parcouru et qualité d’audit. Elle est également utile lorsque le dépôt contient du code audio, vidéo ou de conception : les importateurs de médias, les prévisualisations et les convertisseurs peuvent constituer des entrées aussi importantes qu’une route web.

Les limites à rendre visibles

L’agent peut ignorer une logique générée, une configuration injectée à l’exécution, une dépendance récupérée dynamiquement ou un service externe absent du dépôt. Il peut aussi interpréter un garde-fou comme actif alors qu’il n’est appliqué que dans un environnement particulier.

Demandez donc une liste des hypothèses. Une conclusion qui dépend d’un paramètre non observé doit rester conditionnelle. Si une zone est inaccessible, son absence doit apparaître dans le registre plutôt que disparaître de la synthèse finale.

Comment réduire les faux positifs sans autoriser une exécution dangereuse ?

La séparation entre le rôle de découverte et celui de vérification est le contrôle central. Le premier cherche des chemins suspects ; le second doit établir si le flux, la condition et l’impact sont réellement présents. Mélanger les deux encourage l’agent à confirmer sa propre hypothèse.

Le schéma officiel distingue trois états à conserver dans findings.json :

• confirmed : les éléments recueillis établissent suffisamment le problème dans le périmètre défini ;
• needs_validation : le candidat est plausible, mais il manque une reproduction, une inspection ou une preuve indépendante ;
• rejected : l’hypothèse ne tient pas après vérification ou ne correspond pas au périmètre.

Le schéma officiel de report-schema.json et le script officiel de validation doivent être utilisés avant diffusion du rapport. Ils vérifient la forme attendue, mais pas la vérité de chaque affirmation. La validation syntaxique ne remplace donc pas la revue sécurité.

Un candidat devrait comporter au minimum son emplacement, le chemin de données observé, la condition nécessaire, l’impact possible, les éléments qui contredisent l’hypothèse, la méthode de reproduction autorisée et le niveau de confiance. Évitez les démonstrations directement exploitables contre une cible réelle. Pour vérifier un comportement, utilisez un projet de test, une donnée inoffensive et un service volontairement isolé.

Contrôle du bac à sable et des permissions

L’exécution du code cible, de la compilation, d’un navigateur automatisé ou d’un fuzzing doit se faire dans un bac à sable au niveau du système d’exploitation. Un simple dossier séparé ne suffit pas : le processus peut encore lire les clés de votre compte, contacter un service interne ou remplir le disque.

Avant le lancement, contrôlez les points suivants :

• Réseau : refus par défaut, puis liste blanche des dépendances indispensables ;
• Secrets : aucune clé de production, aucun agent SSH, aucun trousseau ou fichier d’identifiants monté ;
• Écriture : seul le répertoire de travail temporaire et le dossier de sortie sont inscriptibles ;
• Dépôt source : copie de travail non critique, sans accès aux autres projets ;
• Ressources : limites de processeur, mémoire, processus, espace disque et durée d’exécution ;
• Processus enfants : liste explicitement autorisée, avec journalisation des commandes ;
• Nettoyage : destruction de l’environnement après la session et conservation séparée des preuves.

Cette approche a un coût opérationnel : les audits sont moins pratiques lorsqu’une commande est bloquée ou qu’un paquet ne peut pas être téléchargé. Mais ce coût est préférable à une exécution incontrôlée. Pour un projet sensible, une machine locale partagée avec les outils de développement n’est pas le meilleur point de départ.

Transformer findings.json en rapport que l’équipe peut relire

Un fichier structuré n’est pas encore un livrable. Pour être utile, le rapport doit relier chaque conclusion à une preuve et à une décision.

Pour chaque élément, conservez les champs suivants :

• identifiant stable et titre descriptif ;
• état confirmed, needs_validation ou rejected ;
• composant, fichier et emplacement concernés ;
• description du chemin de données ;
• préconditions nécessaires ;
• impact dans le périmètre observé ;
• éléments de preuve et limites de la preuve ;
• étapes de reproduction sûres ;
• recommandation de correction ;
• méthode de vérification après correction ;
• propriétaire et statut de revue humaine.

Un problème de sécurité doit être séparé d’une recommandation de durcissement. Par exemple, une permission plus large que nécessaire peut être une faiblesse à corriger, sans démontrer à elle seule une exploitation. De même, un candidat non reproductible ne doit pas être présenté comme une vulnérabilité confirmée pour donner une impression de volume.

Vous pouvez convertir le résultat en Markdown avec une structure simple :

## SEC-001 — Validation insuffisante d’une entrée

- État : needs_validation
- Zone : workers/import
- Preuve : flux observé de l’importateur vers le parseur
- Condition : format externe accepté sans contrôle documenté
- Limite : reproduction dynamique non effectuée
- Action : tester dans le bac à sable avec une donnée factice
- Revue humaine : requise avant toute correction

Après génération, faites relire le document par le propriétaire du composant et par une personne indépendante de la découverte. Le premier connaît les hypothèses fonctionnelles ; la seconde peut repérer une conclusion trop confiante. Les tests officiels du projet sont également utiles pour détecter une divergence de structure ou de comportement lors d’une mise à jour.

Le choix d’exécution : poste local ou environnement distant isolé

Utilisez cette grille de décision avant de lancer un dépôt réel :

• Poste local dédié, accès limité : choisissez cette option pour un petit dépôt non sensible, lorsque vous contrôlez le système, les secrets et les dépendances. Avantage : démarrage rapide. Limite : journaux et sessions souvent liés à une machine individuelle.
• Environnement de développement distant isolé : retenez-le lorsque plusieurs personnes doivent reprendre l’audit, consulter les sorties ou conserver une session longue. Avantage : séparation plus nette et meilleure continuité. Limite : il faut configurer l’accès, la rétention des journaux et la destruction des données.
• Mac distant avec environnement dédié : envisagez-le lorsque votre équipe manque de matériel local compatible, doit reproduire un environnement macOS ou veut séparer l’audit des postes personnels. Avantage : poste réservé et accessible à distance. Limite : il faut vérifier la persistance de session, le stockage des preuves, la disponibilité du nœud et les permissions du projet.
• Machine de production ou poste de développeur principal : écartez cette option. Les secrets, les dépôts sans rapport et les outils d’administration y créent une surface inutile.

Pour préparer cette dernière option, consultez le guide de location d’un Mac pour un environnement distant. La présentation de Kvmzen peut aussi vous aider à vérifier le périmètre du service avant de transmettre un dépôt sensible. Ne transférez toutefois un code propriétaire qu’après avoir défini la durée de conservation, les accès autorisés et la procédure d’effacement.

Questions fréquentes

Les réponses ci-dessous complètent la procédure : elles ne remplacent pas la vérification du dépôt officiel ni un essai contrôlé dans votre environnement.

Avant de conclure : l’audit assisté ne vaut que par son environnement

Si votre équipe dispose déjà d’un poste dédié, d’un bac à sable système et d’une politique de conservation des journaux, l’exécution locale peut suffire pour un premier dépôt. En revanche, un poste partagé rend les secrets plus difficiles à isoler, une session interrompue peut perdre son contexte et un disque local peut mélanger preuves d’audit et fichiers personnels. Une machine non macOS peut également empêcher une reproduction fidèle lorsque votre chaîne de développement dépend de cet environnement.

Dans ce cas, louer un Mac auprès de Kvmzen peut offrir une base plus propre pour préparer la session : vous séparez le projet audité de votre poste principal, vous planifiez la conservation des sorties et vous pouvez organiser l’accès autour d’un environnement distant plutôt que d’une machine personnelle. Cela ne garantit ni la découverte d’une vulnérabilité ni la qualité du rapport ; vous devez toujours configurer le bac à sable, limiter les permissions et faire relire les résultats par un humain. Pour préparer cette partie sans promettre un résultat d’audit automatique, commencez par le guide d’usage d’un Mac distant.

Questions fréquentes