Agent Auditeur Code

L'agent auditeur de code est un outil d'analyse autonome assiste par IA. Il se declenche automatiquement apres chaque deploy — analyse le diff du dernier commit via Claude Sonnet, genere un rapport structure, et bloque le deploy si le verdict est BLOQUANT.

Contrairement a un linter qui applique des regles syntaxiques, l'agent raisonne en termes de systemes : il analyse les impacts en cascade sur l'ensemble du site (admin + user), detecte les regressions de securite, et correle avec les vulnerabilites connues du Security Center.

L'agent est intelligent sur le declenchement : il classifie chaque deploy par priorite. Un changement i18n, docs ou sidebar ne declenche pas d'audit. Un changement sur l'auth, les migrations, les webhooks ou les API routes declenche un audit complet.

Page : /backoffice/audit (dashboard monitoring) | Sidebar : Section "IA" (indigo)

Architecture

  +-----------------------+        SSE streaming        +------------------------+
  |   PANNEAU DE SAISIE   |  ========================>  |   RAPPORT D'AUDIT      |
  |                       |                              |                        |
  |  Type : Diff Git /    |        Claude Sonnet         |  Verdict colore        |
  |  Fichier / Contenu    |  <-- system prompt 300 lig.  |  Compteurs C/E/W/I     |
  |                       |      + regles BeePass        |  Markdown en temps reel|
  |  Source / Titre       |      + checks actifs         |  Sections depliables   |
  |  Contenu (textarea)   |      + anti-patterns         |  Copier checklist      |
  |  Contexte (optionnel) |                              |  Telecharger .md       |
  +-----------------------+                              +------------------------+
                                                                    |
                                                                    v
                                                         +------------------------+
                                                         | FINDINGS SECURITE      |
                                                         | - Table preview        |
                                                         | - Checkboxes           |
                                                         | - Push Security Center |
                                                         +------------------------+

Fonctionnement autonome

Declenchement automatique post-deploy

A chaque execution de deploy.sh, l'agent :

Acquiert un verrou exclusif (flock) — un seul deploy a la fois, les autres attendent
Calcule le diff depuis le dernier SHA deploye (pas HEAD~1) — precis meme avec plusieurs commits
Classifie la priorite du deploy (CRITICAL / HIGH / MEDIUM / SKIP)
Si la priorite est SKIP (i18n, docs, assets) → audit saute, deploy continue
Sinon → envoie le diff a Claude Sonnet pour analyse complete
Sauvegarde le rapport + injecte les findings securite dans le Security Center
Si le verdict est BLOQUANT ou A CORRIGER → envoie une notification admin + stoppe le deploy (exit 1)

Multi-terminal : chaque terminal calcule son diff LOCALEMENT avant le SSH (git diff HEAD~1 HEAD), l'uploade sur le serveur avec un ID unique, puis attend le verrou flock. Chaque terminal obtient son propre audit Gandalf couvrant uniquement ses propres commits — pas de contamination entre terminaux, meme avec 10 deploys simultanes.

Scripts exclus : deploy.sh et les scripts cron sont dans les SKIP_PATTERNS de Gandalf (pas de code applicatif → faux positifs).

Bouton "Lancer un audit"

Le dashboard propose aussi un bouton pour lancer un audit manuellement sur le dernier commit. Utile pour re-verifier apres une correction.

Exploiter le rapport

Le rapport suit un format strict avec :

Verdict global : BLOQUANT / A CORRIGER / APPROUVE
Problemes critiques [C-xx] : bugs certains, failles de securite, perte de donnees
Erreurs [E-xx] : comportements incorrects probables
Avertissements [W-xx] : risques potentiels, dette technique
Informations [I-xx] : suggestions d'amelioration
Analyse d'impact en cascade : fichiers impactes + scenarios de regression
Checklist Claude Code : liste de taches copy-pastable

Chaque probleme inclut : fichier + ligne, code problematique, correction exacte, et fichiers impactes en cascade.

4. Pousser vers le Security Center

Si des findings de securite sont detectes (RLS, Auth, Secrets, Injection...), un panneau de preview s'affiche sous le verdict. Vous pouvez :

Decocher les findings que vous ne souhaitez pas pousser
Cliquer sur Pousser vers Security Center pour injecter les findings dans le rapport securite
Les findings sont dedupliques par fingerprint SHA-256 — un meme probleme ne sera pas cree deux fois

Perimetres d'analyse

L'agent couvre 10 perimetres configurables :

Perimetre	Ce qu'il verifie
RLS Supabase	Politiques Row Level Security, tables sans RLS, acces cross-user
Securite Auth	Usage getUser() vs getSession(), middlewares, guards admin
Variables d'env	Cles privees exposees cote client, secrets hardcodes
Side effects React	useEffect sans deps, subscriptions non desinscrites, re-renders infinis
Performance	Requetes N+1, composants non memoises, imports lourds non lazy
Types TypeScript	`any` implicites, assertions dangereuses, interfaces rompues
Stripe & Webhooks	Signature webhooks, idempotence, cascade paiements
Templates email	Compatibilite Gmail, variables Brevo, encodage UTF-8
API routes	Changements de signature, appelants casses, status codes
Cascades DB	Migrations, FK, triggers, fonctions PL/pgSQL, types generes

Chaque perimetre peut etre active/desactive depuis la page de configuration.

Verdicts

Le verdict est strictement determine par la severite maximale des findings :

Verdict	Condition	Action requise
BLOQUANT	Au moins 1 finding [C] critique	Correction immediate, deploy bloque
A CORRIGER	Au moins 1 finding [E] erreur ou [W] avertissement	Corriger avant merge
APPROUVE	Uniquement [I] infos ou aucun finding	Deploy possible

Le verdict ACCEPTABLE a ete supprime (v2.5.0). Les warnings [W] declenchent maintenant A CORRIGER.

Configuration

La configuration de l'agent est accessible via Configuration IA > onglet Auditeur Code (/backoffice/ai-config?tab=code_auditor).

Parametre	Defaut	Description
Modele	claude-sonnet-4-20250514	Sonnet recommande (analyse complexe)
Max tokens	8192	4096–16384
Temperature	0.1	Max 0.3 (audit deterministe)
Seuil signalement	Info	Severite minimum a signaler
Sauvegarde auto	Oui	Sauvegarde automatique des rapports
Push auto Security	Oui	Injection auto findings dans Security Center
Seuil push	Error	Severite minimum pour injection Security

Le system prompt est personnalisable. Les regles BeePass (stack, RLS, anti-patterns, tables, rate limiters) sont injectees automatiquement par le code — inutile de les redupliquer dans le prompt.

Integration Security Center

Les findings de securite detectes par l'agent sont injectables dans le Security Center existant :

Categories : RLS, Auth, Secrets, Injection, TypeSafety, Cryptography, Configuration, DependencyRisk, DataExposure, RaceCondition
Mapping OWASP : chaque categorie est automatiquement associee a une reference OWASP Top 10
Deduplication : fingerprint SHA-256 sur (security_report_id + fichier + titre)
Statut : open, in_progress, resolved, false_positive, accepted_risk (modifiable inline)
Apprentissage : les findings marques false_positive ou accepted_risk sont automatiquement injectes dans le contexte des audits suivants — l'agent apprend a ne plus les re-signaler
Onglet dedie : les findings code apparaissent dans un onglet Code Audit dans la page des rapports securite

Boucle de correction automatique

Apres chaque deploy, Claude Code (dans la meme conversation) :

Lit le rapport d'audit sauvegarde sur le serveur
Applique les corrections de la checklist (chaque probleme inclut le code exact a modifier)
Lance les tests : tsc --noEmit, scan-i18n, tests specifiques du rapport
Commit + redeploy les corrections
Nouvel audit se declenche automatiquement sur le redeploy
Repete jusqu'a obtenir le verdict APPROUVE

Les rapports sont sauvegardes sur le serveur dans /opt/beepass/data/audit-reports/ au format {date}_{verdict}.md.

Garde-fous anti-hallucination

L'agent ne voit que le diff Git, pas les fichiers complets. Pour eviter les faux positifs recurrents, 11 regles sont integrees au system prompt, des metadonnees fichiers et des signatures de fonctions sont injectees dans le contexte de chaque audit (anti-hallucination v4).

Regle supreme

Le build Next.js (tsc --noEmit + next build) a reussi avant l'audit. Si le build passe, tous les imports, types et references de fonctions sont corrects. L'agent ne doit jamais signaler un import manquant, un type inexistant, ou une fonction non definie.

11 regles anti-hallucination

Regle	Explication
Build reussi	Le build a passe → imports, types et references sont tous valides. Ne jamais signaler de probleme structurel.
Nouveaux fichiers	Un fichier avec `+++ b/path` et toutes les lignes `+` est un nouveau fichier — l'agent voit son contenu complet. Ne pas dire qu'il manque quelque chose.
Imports cross-fichiers	Si le fichier A importe depuis le fichier B et que les deux sont dans le diff, l'import est valide.
Codebase existant	Le diff ne montre pas tout le codebase. Les fonctions et constantes importees depuis des fichiers hors du diff existent (ex: `MODEL_PRICING`).
Imports != duplication	Un `import { X } from './file'` n'est pas une duplication de X, c'est une reference.
Colonnes DB	Si un `.select()` inclut une colonne, elle existe. Les migrations sont appliquees avant le deploy.
Traductions admin	L'admin est en francais uniquement. Pas de signalement pour les autres langues.
Constantes inline	Des constantes bien commentees (ex: `12 * 60_000 // 12 min`) sont acceptables. Pas d'externalisation forcee.
Zod sans message	`.min(1)`, `.max()`, `.email()` sans message custom sont acceptables.
Helpers UI projet	`toastSuccess()`, `formatDate()`, `InfoTooltip`, `CopyBlock` existent dans 20+ composants.
catch + toast	`catch { toastError(t('error')) }` est suffisant cote client.

Metadonnees fichiers + Signatures

Avant chaque audit, le systeme injecte dans le contexte :

BUILD STATUS: PASSED — confirme que le build a reussi
NOUVEAUX FICHIERS — liste des fichiers ajoutes (contenu complet visible dans le diff)
FICHIERS MODIFIES — liste des fichiers modifies (seuls les hunks sont visibles)
FICHIERS SUPPRIMES — liste des fichiers supprimes
SIGNATURES DES FICHIERS MODIFIES (v4) — extractFileSignatures() lit chaque fichier .ts/.tsx modifie depuis le disque et extrait les signatures function/export/class/interface/type avec numeros de ligne. Gandalf voit ainsi les definitions hors du diff (ex: verifyToken() ligne 9 quand le changement est a la ligne 230)

Cela permet a l'agent de savoir precisement quels fichiers il voit en entier et lesquels il ne voit que partiellement.

Apprentissage des faux positifs

Les findings marques false_positive ou accepted_risk dans le Security Center sont injectes dans le contexte de chaque audit suivant avec leur fingerprint et categorie — l'agent apprend des erreurs passees.

Dashboard monitoring

La page /backoffice/audit est un dashboard de suivi (pas de saisie manuelle) :

4 KPI cards (audits total, approuves, bloquants, findings total)
TrendPanel avec 5 stat cards (taux approbation, correction moyenne, temps gagne, cout API, correlations scan) + area chart stacked par verdict (7/30/90 jours) + bar chart horizontal "Findings par module" (top 8 modules)
Banniere correlations code ↔ scan (alerte orange, paires matchees, lien Security Center)
Banniere du dernier audit (verdict colore, commit, badge "auto", compteurs, cout estime)
Table historique avec date, verdict, badge corrections i18n, source, compteurs C/E/W/I, statut
Detail rapport Markdown complet au clic + bouton telecharger .md
Rafraichissement automatique toutes les 5 minutes

Suivi des warnings

Depuis la v2.5.0, les warnings [W] declenchent le verdict A CORRIGER (le deploy est bloque). Si un audit A CORRIGER avec uniquement des warnings n'est pas corrige sous 48h, une notification synthetique apparait dans le centre de notifications admin.

Apres 48h sans correction → notification admin (type securite)
Email envoye via le systeme d'alertes existant (cooldown 1h, digest quotidien)
Auto-resolution : la notification disparait quand un deploy plus recent produit un verdict APPROUVE
Pas de ticket : c'est une notification synthetique (comme "disque > 90%" ou "tickets > 48h"), pas un ticket support

Feature flag

L'agent peut etre desactive via /backoffice/settings > Agents IA > toggle Gandalf (Auditeur Code).

Quand desactive :

POST /api/cron/code-audit retourne { verdict: "SKIP" } (deploy non bloque)
POST /api/admin/audit/chat retourne 403

Statuts des rapports

Statut	Badge	Signification
Passe	Vert	Audit APPROUVE (standalone ou via corrections liees dans la chaine)
Corrections appliquees	Vert	Resolution manuelle via bouton "Resoudre" (`resolved_at` en DB)
Resoudre	Rouge	BLOQUANT ou A CORRIGER sans correction — action requise

Resolution manuelle

Quand un rapport BLOQUANT ou A CORRIGER est un faux positif ou que les corrections ont ete faites dans un autre terminal, un bouton "Resoudre" apparait dans la colonne Statut.

Cliquer sur Resoudre → dialog de confirmation
Confirmer → le rapport est marque comme resolu (resolved_at en DB)
La chaine d'audit (.last_audit_id) est nettoyee sur le serveur
Le statut passe a "Corrections appliquees"

L'API correspondante est PATCH /api/admin/audit/reports avec { report_id: UUID }. Authentification : cookie HMAC admin OU Bearer CRON_SECRET (deploy.sh).

Memoire auto-apprenante

Gandalf apprend de ses propres audits. Apres chaque verdict APPROUVE, il extrait 3 sections du rapport et accumule les connaissances (max ~1500 chars) dans la table audit_knowledge.

Extraction enrichie (3 sections)

Section	Source	Description
Patterns valides	`## POINTS POSITIFS`	Coeur de l'apprentissage (max 900 chars)
Suggestions	`## INFORMATIONS [I-*]`	Titres des 10 premieres suggestions
Metadata	Metriques du rapport	Date, scope, severites (C:E:W:I)

Accumulation (pas d'ecrasement)

Etape	Description
Premier audit d'un module	Gandalf lit la spec complete (~4000 chars)
Verdict APPROUVE	Extrait les 3 sections → stocke un bloc structure + la version du spec
Audits suivants du meme module	Lit le resume accumule (~1500 chars) au lieu de la spec complete
Nouveau APPROUVE sur le meme module	Prepend le nouveau bloc devant l'ancien, cap 1500 chars (recents en tete, anciens tronques)
Spec mise a jour (version change)	Gandalf detecte le mismatch → relit la spec complete → recommence l'accumulation

QI Gandalf (5 axes, 0-200)

Le QI mesure l'intelligence de Gandalf sur une echelle de 0 a 200 :

Composante	Points	Description
Couverture (vert)	0-40	% de modules avec un resume
Fraicheur (bleu)	0-30	% de resumes a jour vs version spec
Confiance (violet)	0-40	Profondeur de validation par module (10 APPROUVE = max)
Precision (rouge)	0-50	Penalise les faux positifs (90j glissants). 0 si non teste
Efficacite (orange)	0-40	Tokens reels economises (5 premiers vs 5 derniers audits)

Labels : Debutant (0-39) → Apprenti (40-69) → Intermediaire (70-99) → Avance (100-129) → Brillant (130-159) → Genie (160-200)

Le QI est visible dans la 5e KPI card de /backoffice/audit et dans le tab "Intelligence IA" du dashboard.

33 specs accessibles

Gandalf a acces a l'integralite des 33 specs du projet via le specs-resolver. Chaque fichier modifie est mappe a son spec technique + la doc admin Docusaurus correspondante.

Base de donnees

Deux tables creees par la migration 20260320140000_audit_agent.sql :

audit_reports : rapports d'audit (contenu, metriques, verdict, lien Security Center)
audit_code_findings : findings code injectes (severity, category, recommendation, fingerprint)

Les deux tables ont RLS active avec policy authenticated.

Voir aussi

Centre de securite — les 19 outils d'analyse automatisee
Rapports de securite — rapports enrichis et scores
Configuration IA — configuration unifiee des 7 agents

Architecture​

Fonctionnement autonome​

Declenchement automatique post-deploy​

Bouton "Lancer un audit"​

Exploiter le rapport​

4. Pousser vers le Security Center​

Perimetres d'analyse​

Verdicts​

Configuration​

Integration Security Center​

Boucle de correction automatique​

Garde-fous anti-hallucination​

Regle supreme​

11 regles anti-hallucination​

Metadonnees fichiers + Signatures​

Apprentissage des faux positifs​

Dashboard monitoring​

Suivi des warnings​

Feature flag​

Statuts des rapports​

Resolution manuelle​

Memoire auto-apprenante​

Extraction enrichie (3 sections)​

Accumulation (pas d'ecrasement)​

QI Gandalf (5 axes, 0-200)​

33 specs accessibles​

Base de donnees​

Voir aussi​