Auditer le code et générer des rapports

Configurer le lab

1. Clone le dépôt Galaxium Travels.

   git clone -b bob-learning-path-branch https://github.com/IBM/galaxium-travels

2. Clique sur File puis Open Folder.

3. Navigue vers le répertoire galaxium-travels que tu as cloné et ouvre-le.

4. Ouvre l'interface de chat Bob en cliquant sur l'icône Bob à côté de la barre de navigation, ou utilise le raccourci Option + Command + B (macOS) ou Ctrl + Alt + B (Windows).

5. Dans le champ de saisie du chat, exécute /init pour initialiser l'environnement de développement et créer les fichiers AGENTS.md pour Bob. Clique sur Approve todo tools for task si demandé.

Créer une skill d'audit

Crée une skill, qui est un ensemble d'instructions réutilisable que Bob utilise pour travailler sur une tâche spécifique.

La skill suivante audite la base de code Galaxium Travels contre les exigences OWASP ASVS Niveau 1.

La skill vérifie les contrôles suivants :

1. Sous l'interface de chat, clique sur Bob - Settings, puis clique sur Bob Settings.

2. Clique sur Skills dans la barre latérale gauche.

3. Clique sur le bouton + pour créer une nouvelle skill.

4. Entre asvs-audit dans le champ Skill Name. C'est le nom utilisé pour invoquer la skill avec /asvs-audit dans le chat.

5. Entre une brève description dans le champ Description :

   Audite une base de code contre les exigences OWASP ASVS Niveau 1 de contrôle d'accès, validation d'entrée, sécurité API et configuration.

6. Assure-toi que le toggle Allow Bob to use this skill est activé.

   Avec le toggle activé, Bob peut activer la skill de lui-même quand un prompt ou un plan le demande. Le plan d'audit que tu créeras plus tard dans ce tutoriel fait exactement cela.

7. Change Scope & Location en galaxium-travels.

   Cela sauvegarde la skill dans le répertoire .bob/skills/ du projet, donc elle n'est disponible que dans ce projet et ton équipe peut la versionner avec la base de code. L'emplacement global (~/.bob/skills/) rendrait la skill disponible dans chaque projet sur ta machine.

8. Entre la skill suivante dans la zone de texte Skill Instructions.

   ---
   name: asvs-audit
   description: Audit a codebase against OWASP ASVS Level 1 access control, input validation, API security, and configuration requirements and produce structured findings ready for SARIF and OSCAL export.
   user-invocable: true
   ---
   
   Perform a structured security audit of this codebase. Work through the following phases in order. Do not skip phases or combine them.
   
   ## Phase 1: Discover
   
   Read and understand the application before auditing. Focus on:
   - Entry points: main files, route definitions, controllers
   - Authentication and session handling code
   - Input validation and sanitization code
   - Database query code
   - Any files flagged as high-risk in earlier analysis
   
   Summarize what you find before proceeding to Phase 2.
   
   ## Phase 2: Audit
   
   Check each control below. For each one record: PASS, FAIL, or N/A.
   For every FAIL, record the file path and line number.
   
   ### V4.1 General Access Control
   - V4.1.3 — Users can only access their own resources; other users' data is not accessible
   - V4.1.5 — Access control denies by default — unauthenticated requests are rejected
   
   ### V4.2 Operation Level Access Control
   - V4.2.1 — Sensitive resources cannot be accessed by manipulating a predictable object ID (IDOR protection)
   
   ### V5.1 Input Validation
   - V5.1.1 — All string inputs have defined maximum length constraints
   
   ### V13.1 Generic Web Service Security
   - V13.1.3 — API endpoints do not accept credentials or PII in URL query parameters
   
   ### V14.4 HTTP Security Headers
   - V14.4.1 — HTTP responses include appropriate security headers such as Content-Security-Policy, X-Frame-Options, and X-Content-Type-Options
   
   ### V14.5 HTTP Request Header Validation
   - V14.5.3 — CORS origin is validated against an explicit allowlist — wildcard origins are not permitted
   
   ## Phase 3: Generate Findings
   
   For each FAIL, produce a finding in this format:
   
   **Finding [N]:**
   - Rule: ASVS [control number]
   - Severity: Critical / High / Medium / Low
   - File: [path]
   - Line: [number or range, if identifiable]
   - Issue: [one sentence describing what was found]
   - Fix: [one sentence describing the recommended change]
   
   ## Phase 4: Summary
   
   Produce a short summary:
   - Total controls checked
   - Pass / Fail / N/A counts
   - Two-sentence overall security posture assessment
   
   Save the findings to the location specified by the plan or prompt that invoked this skill. Do not generate SARIF, OSCAL, or other report files — report generation is a separate task. Report that the audit is complete and wait for the next instruction.

   C'est l'ensemble complet d'instructions que Bob suit pendant l'audit.

9. Clique sur Create.

Trouver les zones à haut risque à auditer

Pour économiser des tokens, demande à Bob d'identifier les fichiers et dossiers les plus pertinents pour la sécurité. Tu exécuteras la skill d'audit sur ces zones.

1. Si le panneau de chat n'est pas déjà ouvert, ouvre-le avec Option + Command + B (macOS) ou Ctrl + Alt + B (Windows).

2. Sélectionne Ask dans le sélecteur de mode.

   Chaque mode a des capacités et des styles de raisonnement différents. Le mode Ask fonctionne mieux pour les questions et l'analyse, mais tu ne peux pas écrire ou éditer des fichiers en mode Ask.

3. Dans le champ de saisie du chat, entre le prompt suivant pour explorer la base de code et trouver les zones à plus haut risque de sécurité :

   Explore this codebase as a Senior Security Analyst. Give me a short summary covering:
   
   1. The primary tech stack and framework
   2. Identify the files and folders most relevant to security
   
   Make sure to also review:
   1. How authentication and session management are handled
   2. How user input is accepted and validated
   3. Where database queries are made
   4. Any API endpoints that accept external input
   
   I want to understand the highest security risk areas before running an audit.

   Bob lit les fichiers et répond avec un résumé de la structure de l'application.

Créer un plan pour auditer les zones à haut risque

Crée un plan que Bob suivra lors de l'audit des zones à haut risque.

1. Passe en mode Plan.

2. Demande à Bob de créer un plan pour auditer les zones à haut risque. Clique sur Approve todo tools for task si demandé.

   Create a plan for auditing the high-risk areas found in the previous
   exploration.
   
   When auditing, use the asvs-audit skill to guide the process.
   
   When the plan runs, create the security/ directory if it does not exist and
   save the findings to security/audit-findings.md
   
   Save the plan to plan/audit-plan.md

3. Bob pourrait poser des questions de suivi pour clarifier la portée de l'audit ou les zones spécifiques sur lesquelles se concentrer. Tu peux y répondre ou dire à Bob d'use your recommendation.

4. Ouvre le fichier du plan pour comprendre l'approche d'audit et ce que Bob fera quand tu l'exécuteras.

Auditer la base de code

1. Clique sur le bouton + pour démarrer une nouvelle tâche.

2. Assure-toi d'être en mode Agent dans l'interface de chat.

   Le mode Agent donne à Bob des capacités complètes, y compris l'écriture de fichiers et l'exécution. C'est nécessaire pour les phases d'audit et de génération de rapports.

3. Clique sur le sélecteur Permissions dans l'interface de chat et coche les cases Read, Edit, Execute et Skill. Laisse tous les autres toggles décochés pour cette tâche.

   Permission	État	Pourquoi
   Read	✅ Activé	Bob lit la base de code, le plan d'audit et la skill
   Edit	✅ Activé	Bob écrit les résultats dans security/audit-findings.md
   Execute	✅ Activé	Bob peut exécuter des commandes shell pour résoudre les chemins ou confirmer la structure des fichiers
   Skill	✅ Activé	Le plan d'audit invoque la skill asvs-audit
   MCP	❌ Désactivé	Non nécessaire pour l'analyse de code local

4. Demande à Bob d'implémenter le plan d'audit.

   Implement the @plan/audit-plan.md

5. Examine les résultats dans security/audit-findings.md.

   Le plan indique à Bob de créer le répertoire security/ s'il n'existe pas déjà et de sauvegarder les résultats dans security/audit-findings.md.

   Sauvegarder les résultats te permet de démarrer un nouveau chat avec un modèle utilisant une fenêtre de contexte fraîche. Tu peux pointer Bob vers le fichier de résultats pour générer des rapports sans relire toute la base de code et les instructions de la skill, ce qui préserve la fenêtre de contexte pour la génération de rapports.

   Note sur la fenêtre de contexte : Tous les modèles ont une fenêtre de contexte définie. Lors de l'audit d'une grande base de code, tu peux dépasser la fenêtre de contexte d'un modèle. Pour les grandes bases de code, essaie d'auditer une catégorie ASVS à la fois. Exécute V4 d'abord, puis V5, V13 et V14, et demande à Bob de consolider les résultats à la fin. C'est aussi une bonne raison de garder SKILL.md concis et d'utiliser des mentions de contexte @ ciblées plutôt que de diriger Bob vers l'ensemble du dépôt d'un coup.

Générer des rapports de sécurité

SARIF est le format d'échange standard pour les résultats d'analyse statique. Les IDEs incluant Bob, GitHub Advanced Security et la plupart des pipelines CI/CD peuvent consommer directement les fichiers SARIF.

1. Clique sur le bouton + pour démarrer une nouvelle tâche.

2. Assure-toi d'utiliser le mode Agent.

3. Clique sur Permissions dans le panneau de chat et coche les cases Read, Edit et Execute. Laisse tous les autres toggles décochés pour cette tâche.

   Permission	État	Pourquoi
   Read	✅ Activé	Bob lit les résultats dans security/audit-findings.md
   Edit	✅ Activé	Bob écrit le rapport SARIF dans le répertoire security/
   Execute	✅ Activé	Bob peut exécuter des commandes shell pour résoudre les chemins ou confirmer la structure des fichiers
   Skill	❌ Désactivé	Non nécessaire pour produire des rapports. La skill a déjà créé les résultats nécessaires pour l'agent
   MCP	❌ Désactivé	Non nécessaire pour l'analyse de code local

4. Demande à Bob de générer un rapport SARIF en utilisant une mention de contexte @.

   @security/audit-findings.md
   
   Generate a SARIF 2.1.0 report from the audit findings.
   
   Save it to `security/audit-results.sarif`.
   
   Include:
   - Tool name: "ASVS Security Audit"
   - A rule entry for each ASVS control that was checked, with the control ID and description
   - A result entry for each finding, with severity level, file path, line number, and the fix recommendation in the message field

   Bob génère le fichier et le sauvegarde dans security/audit-results.sarif. Confirme que le fichier contient un tableau runs avec des entrées results, une par résultat de l'audit.

   Bob rapporte également les décisions de mapping qu'il a prises dans le chat :

   Exemple de sortie :

   Severity mapping used: Critical/High → SARIF error; Medium/Low → SARIF warning.
   The message.text for each result contains the full issue description and the fix
   recommendation in one field, so tooling that renders SARIF (GitHub Code
   Scanning, VS Code SARIF Viewer, etc.) will surface the remediation guidance
   inline.

5. Ouvre security/audit-results.sarif dans Bob pour examiner les résultats. Tu peux utiliser ce fichier dans d'autres outils comme GitHub Advanced Security ou un pipeline CI/CD pour afficher les résultats de l'audit.

Générer un plan de remédiation OSCAL (POA&M)

Le POA&M OSCAL est un document JSON lisible par machine qui mappe chaque résultat à une tâche de remédiation structurée avec des informations de risque, des conseils d'implémentation et des affectations de jalons. Bob peut lire ce fichier comme une file de travail. Il travaille sur chaque élément, applique des corrections et marque les jalons comme terminés au fur et à mesure.

1. Clique sur le bouton + pour démarrer une nouvelle tâche.

2. Clique sur le menu de mode dans le panneau de chat et sélectionne Agent.

3. Clique sur Permissions dans le panneau de chat et coche les cases Read, Edit et Execute. Laisse tous les autres toggles décochés pour cette tâche.

   Permission	État	Pourquoi
   Read	✅ Activé	Bob lit les résultats dans security/audit-findings.md
   Edit	✅ Activé	Bob écrit le POA&M OSCAL dans le répertoire security/
   Execute	✅ Activé	Bob peut exécuter des commandes shell pour résoudre les chemins ou confirmer la structure des fichiers
   Skill	❌ Désactivé	Non nécessaire pour produire des rapports. La skill a déjà créé les résultats nécessaires pour l'agent
   MCP	❌ Désactivé	Non nécessaire pour l'analyse de code local

4. Demande à Bob de générer un rapport POA&M OSCAL en utilisant une mention de contexte @.

   @security/audit-findings.md
   
   Generate an OSCAL Plan of Action and Milestones (POA&M) from the audit findings.
   
   Save it to `security/poam.json`.
   
   For each finding include:
   - A unique UUID
   - The ASVS control ID as the finding reference
   - Severity and a one-sentence risk description
   - A concrete remediation task with enough detail for an AI agent to implement it without additional context — include file path, line reference, and the specific change required
   - A milestone label based on severity: Critical and High findings get "sprint-1", Medium and Low get "sprint-2"
   
   Use OSCAL version 1.1.2 structure.

   Bob génère le fichier et le sauvegarde dans security/poam.json.

   Exemple de sortie :

   Each poam-item contains:
   
   props — severity, asvs-control, and milestone label
   risks[] — one risk with a uuid, title, one-sentence risk description, and status: "open"
   
   remediations[] — one remediation with a lifecycle: "planned" flag, a title, and a description 
   that is specific enough for an AI agent to implement without additional context 
   (includes exact file paths, line numbers, and the concrete code change required)
   
   tasks[] — one or more discrete action tasks under each remediation (e.g. the IDOR finding breaks 
   out the short-term ownership check and the long-term UUID migration as separate tasks)

Tu as maintenant deux artefacts dans le répertoire security/ :

• audit-results.sarif — résultats structurés pour les outils de développement et l'intégration CI/CD
• poam.json — une file de travail de remédiation pour la remédiation assistée par IA ou pilotée par l'humain

Examiner les résultats

Avec le POA&M généré, examine les résultats et priorise ceux à corriger en premier.

1. Clique sur le bouton + pour démarrer une nouvelle tâche.

2. Clique sur le menu de mode dans le panneau de chat et sélectionne Ask.

3. Demande à Bob de mettre en évidence les éléments les plus critiques du POA&M en utilisant une mention de contexte @.

   @security/poam.json
   
   Review this remediation plan and identify the 3 most critical items to fix first.
   
   For each one include:
   - What the vulnerability is and why it is the highest priority
   - Which file and line to look at
   - What the fix involves and roughly how long it would take a developer to implement

   Bob lit le fichier et retourne un résumé priorisé :

   Exemple de sortie :

   #1 — No Authentication on Any Endpoint (Finding 1 · ASVS V4.1.5 · critical)
   Why it's the highest priority:
   This is the foundational flaw that makes every other vulnerability worse. With
   zero authentication in place, any anonymous caller on the network can execute
   all booking operations — book flights, read all user records, cancel any
   booking, register accounts. Until this is fixed, findings 2 and 3 also have no
   meaningful barrier.
   
   ...snip...
   
   #3 — PII in URL Query Parameters on GET /user (Finding 5 · ASVS V13.1.3 · high)
   Why it's third:
   Email addresses (PII) appearing in GET /user query strings are passively and
   silently leaked into server access logs, reverse-proxy logs, CDN caches, and
   browser history — a persistent, silent data breach that can violate GDPR. Unlike
   findings 2 and 3, this is an architectural leak that accumulates over time;
   every request compounds the exposure.
   
   Sprint-1 Fix Order Summary
   
   Priority	Finding	Severity	Effort	Dependency
   1	Auth on all endpoints (V4.1.5)	Critical	2–4 h	None — fix first
   2	Wildcard CORS (V14.5.3)	High	30 min	Independent — fix in parallel
   3	PII in query string (V13.1.3)	High	1–2 h	Independent — fix in parallel
   
   Findings 2 and 3 are blockers in the ownership-check fixes (Findings 2 and 3 in
   the POAM) that come afterward, since those require a known caller identity —
   which only exists once authentication (Finding 1) is in place.

   Tu peux également intégrer un serveur Model Context Protocol (MCP) dans tes workflows d'audit et demander à Bob de créer des tickets pour chaque résultat, en les liant au code pertinent et en incluant les conseils de remédiation du POA&M.