Rapports IA — 3 formats

Depuis la version v0.127.0 (migration 000172_ai_report_artifacts.up.sql), chaque rapport AI généré par Scanyze produit trois artefacts distincts correspondant à trois audiences différentes.

Tous les artefacts sont uploadés sur S3 (MinIO) sous code-scans/{scan_id}/ai-reports/{timestamp}/, hashés en SHA-256 pour intégrité, et indexés dans la table code_scan_ai_report_artifacts (RLS multi-tenant).

Vue d'ensemble

Source : secuscan-api/internal/services/codescan/ai_report_formats.go et ai_report_formats_i18n.go.

Executive PDF

Audience

• RSSI / CISO qui doit présenter au board
• Direction générale qui veut comprendre la posture sans entrer dans la technique
• Auditeur externe qui veut une preuve d'analyse

Contenu

1. Couverture avec branding (logo tenant si configuré, sinon Scanyze)
2. Résumé exécutif — 1 page : posture globale, top 5 risques business, recommandations stratégiques
3. Score de posture : visualisation graphique avec comparaison vs scan précédent
4. Top 5 findings critiques avec impact business simple (sans jargon technique excessif)
5. Quick wins : 3-5 actions à faible coût et fort impact
6. Roadmap recommandée : feuille de route à 30 / 90 / 180 jours
7. Conformité : statut vis-à-vis des cadres CIS / ISO / OWASP / PCI / SOC2 si applicable
8. Annexes : méthodologie de scan, périmètre

Style

• Langue : claire, accessible, peu de termes techniques. Une CVE est expliquée en 1 phrase contextuelle.
• Format visuel : graphiques radar, tableaux, code couleur (vert/orange/rouge).
• Bilingue : FR ou EN selon la préférence locale du tenant (Settings → Préférences → Langue).

Technical PDF

Audience

• Équipes DevSecOps qui doivent corriger les findings
• Développeurs qui ont besoin du code snippet et de l'expected fix
• Architectes qui doivent évaluer les patch strategies

Contenu

1. Table des matières détaillée avec liens cliquables
2. Méthodologie : outils utilisés, périmètre, profil de scan
3. Pour chaque finding :
   • Identifiant unique (FINDING-001, FINDING-002, ...)
   • Titre, sévérité, CVSS, CWE, CVE associés
   • File path + line number où le finding a été détecté
   • Code snippet avec syntax highlighting
   • Current code : ce qui est actuellement écrit
   • Expected fix : la correction proposée par l'IA, prête à copier-coller
   • Patch strategy : local (fix dans le fichier) / architectural (refacto plus large)
   • Dependencies : autres findings ou modules à corriger d'abord
   • Acceptance criteria : conditions binaires testables pour valider que le fix est correct
4. Recommandations infrastructure : changements WAF, DNS, IAM
5. Annexes : raw outputs des outils SAST

Source précise du contenu : EnrichedFinding struct dans secuscan-api/internal/domain/models/code_scan_ai_report.go (champs : Title, Category, RuleID, FilePath, LineNumber, CodeSnippet, CurrentCode, ExpectedFix, PatchStrategy, Dependencies, AcceptanceCriteria).

Style

• Riche en détails techniques
• Code blocks avec syntax highlighting
• Liens directs vers les références (NIST NVD, OWASP, CWE Mitre)

Machine MD

Audience

• Pipelines CI/CD qui ingèrent le rapport pour automatiser des tickets ou des PR
• Agents LLM (ex. Claude Agent en aval) qui doivent raisonner sur les findings
• Scripts qui parsent les findings pour générer des dashboards externes

Contenu

Format Markdown structuré avec YAML front-matter :

---
scan_id: 5a3b8c2d-...
report_id: 9f2e1d4c-...
generated_at: 2026-04-29T14:32:11Z
total_findings: 47
severity_breakdown:
  critical: 2
  high: 8
  medium: 15
  low: 18
  info: 4
language: en
schema_version: "1.0"
---

# Code Security Findings — machine-readable report

## FINDING-001
- title: SQL injection in user lookup
- severity: critical
- cwe: CWE-89
- file_path: api/handlers/users.go
- line_number: 142
- rule_id: gosec-G201
- category: injection
- current_code: |
    query := "SELECT * FROM users WHERE id = " + userID
    rows, _ := db.Query(query)
- expected_fix: |
    query := "SELECT * FROM users WHERE id = $1"
    rows, _ := db.Query(query, userID)
- patch_strategy: local
- dependencies: []
- acceptance_criteria:
  - Code uses parameterized queries
  - Input userID is validated as UUID
  - SQL injection test (' OR 1=1) returns 400

Caractéristiques clés

• Toujours en anglais : assure la compatibilité avec les LLMs en aval (la majorité étant entraînée majoritairement en anglais).
• Structure stricte : chaque finding suit la même schema, ce qui permet le parsing déterministe.
• Auto-suffisant : les valeurs file_path, line_number, code_snippet sont denormalisées depuis CodeIssue au moment de la génération, donc le rapport reste valide même si la base est modifiée.
• Schema versionné : schema_version: "1.0" permet aux consommateurs de gérer les évolutions futures.

Cas d'usage typiques

1. Auto-création de PR : un script lit le machine.md, regroupe les findings par fichier, et crée une PR par fichier avec les expected_fix appliqués.
2. Ingestion par un agent LLM : un agent IA en aval (ex. Cursor, GitHub Copilot Workspace) lit le rapport et propose des fix interactifs.
3. Reporting externe : un dashboard Grafana ingère les rapports machine.md de tous vos repos et affiche une posture agrégée.
4. Création de tickets Jira/Linear : un workflow Zapier/Make.com lit le rapport et crée un ticket par finding critical/high.

Architecture de génération

[1] Scan terminé → CodeIssue persistés en DB
       ↓
[2] AI orchestrator déclenché (GPU ou Premium)
       ↓
[3] EnrichEnrichedFindings denormalise file_path/line/code_snippet
       ↓
[4] AI génère un EnrichedFinding par CodeIssue
       ↓
[5] Cache par (issue_id, content_hash) sauvegardé dans code_issue_ai_analyses
       ↓
[6] GenerateExecutiveMarkdown / GenerateTechnicalMarkdown / GenerateMachineMarkdown
       ↓
[7] Renderer Maroto v2 (PDF) pour exec + tech
       ↓
[8] Publisher S3 upload tous les artefacts (PDF + MD)
       ↓
[9] Persiste dans code_scan_ai_report_artifacts
       ↓
[10] Notification SSE au frontend → bouton « Télécharger » apparaît

Source : secuscan-api/internal/services/codescan/ai_report_publisher.go.

Ré-télécharger un rapport historique

Tous les rapports générés sont conservés sur S3 indéfiniment (sauf demande explicite de purge). Sur la page d'un scan terminé :

• Onglet Reports
• Liste des rapports générés (le plus récent en haut, anciens accessibles)
• Boutons de téléchargement pour chaque format
• Hash SHA-256 affiché pour vérification d'intégrité

Génération à la demande sur un scan ancien

Si vous voulez régénérer un rapport AI sur un scan ancien (ex. après avoir activé Premium) :

1. Page du scan → bouton Régénérer le rapport AI.
2. Choisissez le provider (GPU ou Premium).
3. Si la cache d'analyses (code_issue_ai_analyses) existe et content_hash n'a pas changé, les analyses sont réutilisées (coût zéro). Sinon, l'IA est appelée.
4. Les nouveaux artefacts sont uploadés avec un nouveau timestamp ; les anciens restent accessibles via l'historique.

Coût de génération

Voir Crédits IA pour le détail. La génération n'incrémente pas davantage les crédits que la phase d'analyse — les rapports sont déterministes (générés à partir des analyses cachées) et leur rendu PDF/MD n'invoque pas l'IA.

Sources de cette page

• Backend : secuscan-api/internal/services/codescan/ai_report_formats.go, ai_report_formats_i18n.go, ai_report_publisher.go
• Modèle : secuscan-api/internal/domain/models/code_scan_ai_report.go (EnrichedFinding, AIReportArtifact, constants AIArtifactFormat*)
• Migration : secuscan-api/internal/migrations/000172_ai_report_artifacts.up.sql

À jour pour Scanyze v0.130.x.