Comment lire un rapport CodeAuditAgent et agir dessus

Un rapport de sécurité n’a d’utilité que s’il se transforme en correctifs fusionnés. Les rapports CodeAuditAgent sont conçus dans cet esprit : chaque résultat est assez précis pour être vérifié rapidement et s’accompagne d’un correctif que vous pouvez adapter. Ce guide explique chaque partie d’un rapport, comment le trier lorsque vous n’avez pas d’ingénieur sécurité dédié, et comment confirmer que vos correctifs ont fonctionné.

Ce qui est audité

Un audit porte soit sur un dépôt GitHub public, soit sur un extrait de code que vous collez. Pour les dépôts, CodeAuditAgent lit la branche par défaut. Les dépôts privés ne peuvent pas être audités par URL, et il n’y a pas encore de commentaires sur les pull requests ; les résultats vivent dans le tableau de bord et dans les exports.

La part d’un dépôt qui est lue dépend de votre plan. Le plan Gratuit couvre 1 dépôt, 3 audits par mois et jusqu’à 20 fichiers par audit. Starter, à 49 $ par mois, couvre 5 dépôts, 50 audits et 40 fichiers par audit. Pro, à 199 $ par mois, couvre un nombre illimité de dépôts, 500 audits et 80 fichiers par audit. Les fichiers individuels de plus de 60 Ko sont ignorés. Les compteurs d’audits mensuels sont remis à zéro au début de chaque mois calendaire (UTC). Un extrait collé est aussi un moyen rapide de vérifier un fichier qui vous inquiète avant d’auditer tout le dépôt.

Lorsque des fichiers sont laissés de côté à cause de ces limites, le rapport est signalé comme un instantané partiel. Prenez cette mention au sérieux. Un rapport partiel propre signifie que les fichiers qui ont été lus paraissent propres, pas que le dépôt l’est. Si le code qui vous importe le plus a été omis, auditez-le sous forme d’extrait collé ou sur un plan qui couvre davantage de fichiers.

Le score de risque

En haut de chaque rapport figure un score de risque de 0 à 100 ; l’export Markdown indique également la gravité globale à côté. Plus il est élevé, plus le risque est grand. C’est un résumé des résultats de cet audit, utile pour deux choses : décider avec quelle urgence examiner un dépôt, et suivre s’il s’améliore avec le temps.

N’accordez pas trop d’importance aux petits écarts entre des dépôts sans rapport entre eux. Un score est toujours relatif à ce qui a été audité, et un instantané partiel voit moins de code. C’est en comparant le même dépôt avant et après les correctifs que le chiffre prend tout son sens.

Gravité et confiance

Chaque résultat possède une gravité et un niveau de confiance. Ils répondent à des questions différentes : la gravité dit à quel point ce serait grave si le résultat est réel, et la confiance dit à quel point le relecteur est sûr qu’il l’est.

• Critique : directement exploitable avec un impact sérieux, comme une injection sur un endpoint public, un contournement d’authentification ou des identifiants de production exposés.
• Élevée : une vraie vulnérabilité qui exige une condition préalable, ou dont l’impact est significatif mais limité.
• Moyenne : une faiblesse qui compte en combinaison avec d’autres bugs, ou dont l’impact est modéré.
• Faible : des points de durcissement et des lacunes de défense en profondeur.
• Info : des observations utiles à connaître qui ne sont pas des vulnérabilités en elles-mêmes.

La confiance est élevée, moyenne ou faible. Un résultat à confiance élevée s’appuie sur des preuves claires dans le code qui a été lu. Un résultat à confiance faible dépend généralement de quelque chose que l’audit n’a pas pu voir, comme un middleware dans un autre fichier, une politique de base de données ou une valeur de configuration définie au déploiement. Une confiance faible ne veut pas dire qu’il faut l’ignorer ; elle veut dire qu’un humain doit vérifier le contexte manquant avant de corriger.

Anatomie d’un résultat

Chaque résultat suit la même structure, afin que vous puissiez le vérifier dans un ordre constant.

• Titre et CWE : la classe de faiblesse, comme CWE-639 pour un contournement d’autorisation via une clé contrôlée par l’utilisateur. La CWE vous indique le type de correctif à attendre.
• Localisation : le fichier et la ligne, pour ouvrir le code directement.
• Preuve : le code pertinent cité depuis le fichier. Vérifiez que la citation correspond à votre code actuel ; si la ligne a déjà changé, le résultat peut être obsolète.
• Scénario d’exploitation : comment un attaquant utiliserait concrètement la faiblesse, étape par étape. C’est le moyen le plus rapide de juger si elle est réelle dans votre contexte.
• Correctif proposé : une modification suggérée dans le style du code environnant.

Traitez le correctif comme un très bon point de départ, pas comme un commit prêt à fusionner. Il est écrit à partir du code que l’audit a lu, il peut donc ignorer vos fonctions utilitaires, vos conventions d’ORM ou un appelant situé ailleurs dans la base de code. Un correctif typique est court et ciblé :

--- a/app/api/invoices/[id]/route.ts
+++ b/app/api/invoices/[id]/route.ts
@@
-  const invoice = await db.invoice.findUnique({ where: { id } });
+  const invoice = await db.invoice.findFirst({
+    where: { id, userId: session.user.id },
+  });
   if (!invoice) return Response.json({ error: 'not_found' }, { status: 404 });

Observations positives et étapes suivantes

Les rapports listent aussi ce qui est bien fait : des requêtes paramétrées utilisées de façon cohérente, des secrets chargés depuis l’environnement, une configuration de cookies stricte. Cela vaut la peine d’être lu. Ces points vous disent quels motifs conserver et recopier dans le nouveau code, et ils sont utiles pour expliquer l’état d’une base de code à quelqu’un d’autre.

La section des étapes suivantes recommandées transforme les résultats en un plan ordonné. Elle regroupe souvent des résultats liés, par exemple plusieurs vérifications de propriété manquantes qu’il vaut mieux corriger avec un seul helper partagé plutôt qu’avec cinq correctifs distincts.

Un flux de triage pour les petites équipes

Sans ingénieur sécurité, le risque n’est pas d’ignorer un rapport ; c’est de passer une journée sur des résultats faibles pendant qu’un résultat critique attend. Un ordre simple fonctionne bien :

• Lisez d’abord tous les résultats critiques et élevés. Pour chacun, lisez le scénario d’exploitation et tranchez : réel, pas réel, ou contexte manquant.
• Corrigez les résultats critiques réels le jour même. Si un correctif demande du temps, ajoutez une mitigation temporaire, par exemple désactiver l’endpoint ou durcir une vérification.
• Pour les résultats qui demandent du contexte, vérifiez la pièce manquante : existe-t-il un middleware, une politique au niveau des lignes ou une configuration qui l’empêche déjà ? Notez la réponse.
• Planifiez les résultats élevés dans le sprint en cours, les moyens dans le backlog, et regroupez les faibles et les informatifs dans une passe de durcissement.
• Quand un résultat n’est pas réel, consignez pourquoi. Cette note évitera à la personne suivante d’enquêter à nouveau.

Attribuez chaque résultat à un unique responsable. Les résultats partagés par toute l’équipe finissent par n’appartenir à personne.

L’explorateur de résultats et les exports

Une fois que vous avez plusieurs audits, l’explorateur de résultats est plus pratique que les rapports pris un par un. Il liste les résultats de tous les audits et les filtre par gravité, CWE et dépôt. Le filtrage par CWE est particulièrement utile : si la même faiblesse apparaît dans trois dépôts, cela pointe généralement vers un motif partagé ou un helper manquant, et corriger le motif coûte moins cher que corriger chaque occurrence.

Les résultats peuvent être exportés en CSV depuis l’explorateur, ce qui est pratique pour les importer dans un outil de suivi ou un tableur. Les rapports individuels peuvent être exportés en Markdown, format qui se lit bien dans une description de pull request, un wiki interne ou un message adressé à un prestataire chargé du correctif.

Relancer l’audit pour confirmer le correctif

Un correctif n’est pas terminé tant que vous ne l’avez pas vérifié. Après la fusion, lancez un nouvel audit sur le même dépôt. Chaque rapport peut être comparé à l’audit précédent, de sorte que vous voyez quels résultats ont disparu, lesquels demeurent et si quelque chose de nouveau est apparu. Le score de risque devrait baisser quand de vrais problèmes sont corrigés ; si ce n’est pas le cas, regardez la comparaison pour comprendre pourquoi.

Gardez la comparaison équitable. Si le premier audit était un instantané partiel et que le second a lu des fichiers différents, l’écart reflète la couverture autant que les correctifs. Les audits sont décomptés de votre quota mensuel, il vaut donc généralement mieux regrouper plusieurs correctifs avant de relancer un audit plutôt que d’en relancer un après chaque commit.

Ce qu’un rapport ne couvre pas

Connaître les limites aide à combler les manques. Les audits lisent votre code source ; ils n’analysent pas les dépendances à la recherche de versions vulnérables connues, gardez donc aussi un scanner de dépendances actif, comme celui intégré à votre gestionnaire de paquets ou à GitHub. Les audits ne voient pas la configuration définie au déploiement, l’infrastructure située hors du dépôt, ni les fichiers qui ont été ignorés. Et comme tout relecteur, humain ou IA, l’audit peut se tromper : les preuves et les niveaux de confiance sont là pour que vous puissiez le vérifier rapidement plutôt que de le croire sur parole.

Utilisé ainsi, un rapport devient une liste courte et priorisée de changements, preuves à l’appui. Corrigez les critiques, vérifiez les incertains, relancez l’audit, et regardez le score bouger.