defending-code-reference-harness

Compétences en modélisation des menaces, scan, tri, correction, plus un harnais de scan autonome que vous pouvez /customize

Contenu

• Compétences Claude Code : /quickstart, /threat-model, /vuln-scan, /triage, /patch, /customize : cadrage interactif, scan, triage, et correction. Ouvrez ce dépôt dans Claude Code et exécutez /quickstart pour vous orienter.
• harness/ : le pipeline de référence autonome (reconnaissance → recherche → vérification → rapport → correctif), configuré pour trouver des vulnérabilités mémoire C/C++ en utilisant Docker et ASAN. Ce harnais est une référence, pas un produit. La structure générale, les invites et le sandboxing sont réutilisables, mais le harnais ne fonctionnera pas sur toutes les bases de code sans adaptation. Exécutez /customize pour le porter vers votre langage, détecteur ou classe de vulnérabilité.

⚠️ Sécurité : /quickstart, /threat-model, /vuln-scan et /triage ne font que lire et écrire des fichiers. Exécuter /patch sur des résultats statiques (TRIAGE.json ou VULN-FINDINGS.json) est également en lecture et écriture seule. /customize modifie le code du harnais et exécute des commandes de validation. Toutes ces compétences peuvent être exécutées sans sandbox, à condition que vous examiniez et approuviez chaque utilisation d'outil dans Claude Code. Le pipeline de référence autonome (y compris /patch sur les résultats du pipeline) exécute du code cible, donc il refuse de s'exécuter en dehors d'un sandbox gVisor sauf si explicitement outrepassé. Pour configurer, exécutez scripts/setup_sandbox.sh une fois, puis invoquez le pipeline via bin/vp-sandboxed. Voir docs/security.md et docs/agent-sandbox.md pour plus de détails.

Pour Commencer

Lectures Complémentaires

• Article de Blog · L'article de blog associé avec les apprentissages et bonnes pratiques
• Pipeline · Comment ça marche : diagramme, étapes, options CLI
• Sécurité · Sandboxing, ce qu'il ne faut pas monter
• Sandbox agent · Isolation gVisor + liste blanche de sortie pour chaque agent
• Personnalisation · Porter vers ma stack ; quels fichiers changent et pourquoi
• Correction · Générer et vérifier des correctifs pour les crashes vérifiés
• Dépannage · Doublons, limites de débit, épinglage de modèle de sous-agent
• Sauvegardes · Blocage pour les travaux cyber dangereux

Montée en Puissance

Les équipes de sécurité avec lesquelles nous avons le mieux collaboré sont celles qui ont été opérationnelles le plus rapidement. Bien qu'il soit tentant de passer des mois à concevoir le pipeline parfait, nous recommandons de commencer petit dès le Jour 1 et de construire à partir de là au fur et à mesure des apprentissages. Les étapes ci-dessous suivent ce schéma et fixent un rythme ambitieux (mais raisonnable) basé sur ce que nous avons observé.

Étape 1 (Jour 1) : Construire un modèle de menace et effectuer votre premier scan statique + triage

Le Jour 1 est consacré à voir l'ensemble du cycle de bout en bout. En utilisant uniquement les compétences interactives, vous allez construire un modèle de menace, exécuter un scan statique cadré par celui-ci, trier les résultats obtenus et rédiger des correctifs candidats. Vous terminerez la journée avec un modèle de menace, une liste classée de résultats statiques et des correctifs candidats.

Les compétences concernées ne font que lire et écrire des fichiers dans votre dépôt. Tant que vous exécutez Claude Code de manière interactive et approuvez chaque utilisation d'outil, aucun sandbox n'est nécessaire.

Ce flux produit THREAT_MODEL.md, VULN-FINDINGS.{json,md}, TRIAGE.{json,md} et PATCHES/.

Les candidats de vulnérabilité produits à l'Étape 1 proviennent de l'examen statique de Claude du code source (rien n'est construit ni exécuté), attendez-vous donc à plus de faux positifs sur toute cible autre que canari. À l'Étape 2, vous produirez des résultats vérifiés par exécution.

Remarque : sur la cible canari, /triage peut rejeter les résultats du scan comme faux positifs. entry.c s'annonce comme un code de démonstration délibérément vulnérable, et /triage exclut correctement les bogues dans le code de test / fixture. Pour voir le flux complet de confirmation / dédoublonnage / faux positif, exécutez-le sur la fixture sélectionnée à la place (/triage .claude/skills/triage/fixtures/canary-findings.json --repo targets/canary) ou orientez les compétences de l'Étape 1 vers votre propre code.

Étape 2 (Jour 2) : Exécuter le pipeline de référence sur une bibliothèque C/C++

Au Jour 2, vous passerez des compétences interactives à votre première exécution autonome en utilisant le pipeline de référence. Vous exécuterez le cycle complet reconnaissance → recherche → vérification → rapport dans votre environnement sur une bibliothèque open source connue pour être vulnérable, puis générerez un correctif candidat pour ce qu'il trouve. Vous terminerez avec un ensemble de crashes reproductibles, des rapports d'exploitabilité et des correctifs candidats, ainsi qu'une idée du fonctionnement du pipeline.

Exécuter le pipeline est simple :

Les résultats du cycle atterrissent dans un répertoire results/drlibs/<timestamp>/. Avec l'option --stream, le premier rapport apparaîtra en quelques minutes sous reports/bug_NN/.

⚠️ run génère des agents autonomes. Le pipeline exécute chaque agent dans un conteneur gVisor avec une restriction de sortie vers l'API Claude uniquement. Les sous-commandes générant des agents refusent de démarrer en dehors de celui-ci sauf si elles sont explicitement outrepassées. Pour plus d'informations, voir docs/security.md et docs/agent-sandbox.md.

Sous le capot, le pipeline parcourt sept étapes :

1. Build : Compile la cible dans une image Docker avec ASAN (le détecteur d'erreurs mémoire pour C et C++). Le pipeline construit cette image automatiquement lors de la première exécution en utilisant le Dockerfile de la cible.
2. Reconnaissance : Un agent léger lit le code source dans un conteneur isolé du réseau et propose une partition, c'est-à-dire "voici N sous-systèmes distincts d'analyse d'entrée qui méritent d'être attaqués séparément", afin que les agents de recherche parallèles explorent des zones différentes au lieu de converger sur le même bogue. Sans l'option --auto-focus, le pipeline utilise la liste focus_areas du config.yaml de la cible.
3. Recherche : N agents s'exécutent en parallèle, chacun dans son propre conteneur isolé. Chaque agent lit le code source, fabrique des entrées malformées et exécute le binaire ASAN jusqu'à ce qu'une entrée donnée produise un crash 3 fois sur 3.
4. Vérification : Un agent correcteur séparé reproduit chaque crash dans un conteneur frais que l'agent de recherche n'a pas touché. La seule chose qui passe de l'agent de recherche à l'agent correcteur est la preuve de concept qu'il a produite.
5. Dédoublonnage : Un agent juge compare les crashes vérifiés avec les bogues déjà signalés et décide si chacun est un nouveau bogue, un meilleur exemple d'un bogue connu, ou un doublon à ignorer.
6. Rapport : Un agent rapporteur rédige une analyse d'exploitabilité structurée par bogue unique, incluant des détails sur la classe de primitive, l'atteignabilité, le chemin d'escalade et la sévérité.
7. Correctif (la commande de correctif séparée ci-dessus) : Un agent correcteur écrit une correction proposée, et un agent correcteur confirme que le nouveau code compile, que l'entrée de la preuve de concept d'origine ne provoque plus de crash, que la suite de tests de la cible passe toujours, et qu'un agent de recherche frais ne peut pas trouver un moyen de contourner le correctif.

Pour plus de détails, voir docs/pipeline.md.

Étape 3 (Jours 3-5) : Personnaliser le pipeline pour votre cible

Aux Jours 3-5, vous personnaliserez le harnais pour votre propre cible. D'abord, vous orienterez les compétences de l'Étape 1 vers votre code, puis vous utiliserez /customize pour porter le pipeline vers votre stack. À la fin de la semaine, vous aurez un répertoire targets/<votre-service>/ que le pipeline pourra utiliser, validé par une seule exécution test du pipeline, et prêt à être mis à l'échelle à l'Étape 4.

Bien que le pipeline de référence soit conçu pour trouver des vulnérabilités mémoire dans du code C et C++, sa structure est générique. Le porter vers une nouvelle classe de vulnérabilité ou un nouveau langage consiste simplement à répondre aux questions suivantes pour votre stack cible :

Avant de personnaliser, orientez les compétences de l'Étape 1 vers votre propre code. Pour rappel, elles sont en lecture et écriture seule, donc elles peuvent s'exécuter sans sandbox.

Ensuite, utilisez les artefacts produits par ces compétences dans la compétence /customize, qui modifie le harnais pour votre base de code.

Quand /customize a terminé, vous aurez un répertoire targets/mon-service/ configuré. Validez-le avec une exécution test du pipeline avant de passer à l'échelle.

Pour plus de détails, voir docs/customizing.md.

Étape 4 (Semaine 2) : Commencer le scan, le triage et la correction autonomes

À la Semaine 2, vous utiliserez le pipeline que vous avez personnalisé à l'Étape 3 sur vos propres cibles, en ajoutant une boucle externe à la boucle interne du pipeline - exécutez plusieurs scans du pipeline, triez les résultats de ces différentes exécutions, corrigez en fonction de la priorisation, et répétez.

⚠️ Suivez les mêmes directives de sandboxing que dans Étape 2

Une exécution donnée du pipeline vérifie et dédoublonne déjà ses propres résultats. /triage fonctionne sur plusieurs exécutions du pipeline. Lorsqu'il est pointé vers le répertoire results/, il réduit les doublons de toutes les exécutions (et de tous les résultats statiques de /vuln-scan s'ils sont présents), recalibre les évaluations de sévérité par rapport à votre modèle de menace, et tente d'acheminer chaque résultat vers le propriétaire du composant.

Quand c'est possible, corriger rapidement les résultats aide à maintenir la boucle externe aussi productive que possible. Lorsque les résultats sont corrigés, le modèle ne peut pas les retrouver, et à la place fera remonter de nouveaux problèmes, généralement plus profonds. À mesure que vous exécutez plus de vagues du pipeline, le nombre de résultats diminuera probablement, mais la complexité augmentera probablement aussi. Si une correction rapide n'est pas possible, même le simple fait d'enregistrer les résultats antérieurs dans known_bugs de la cible peut aider à orienter les exécutions futures vers des bogues plus récents.

Le triage et la correction autonomes sont encore des problèmes ouverts, et ce harnais de référence ne les résout pas complètement. Les stratégies de vérification dans /patch aident à relever le niveau, mais la sévérité et la priorisation sont en fin de compte des jugements sur votre environnement, et les correctifs vérifiés ne sont pas toujours intégrables en amont. De nombreux partenaires ont signalé ces étapes comme leurs goulots d'étranglement actuels, et vous devez prévoir du temps d'ingénierie réel pour eux.

Pour plus de détails, voir docs/triage.md et docs/patching.md.

Perspectives d'Avenir

Après la montée en puissance initiale, les équipes avec lesquelles nous avons travaillé ont eu tendance à investir dans quelques directions :

1. Passer en revue tous leurs dépôts internes et dépendances open source clés, classer lesquels sont les plus importants à scanner (par exemple, en fonction de leur exposition, historique de CVE, criticité métier), puis travailler à travers la liste dans l'ordre de priorité.
2. Mettre en place une infrastructure sur mesure pour le scan, afin de sortir les scans des ordinateurs portables ou des VM ponctuelles. Les équipes les plus performantes résistent à la tentation de construire la plateforme de scan parfaite avant de passer à l'échelle.
3. Intégrer les scans dans leur cycle de vie du développement logiciel. Certaines équipes ont mis en place des scans récurrents (par exemple, quotidiennement, hebdomadairement) ou ont ajouté le scan dans leurs pipelines CI.
4. Tester et expérimenter avec les modèles pour trouver ce qui fonctionne le mieux pour elles.