Auditare il codice e generare report

Configurare il lab

1. Clona il repository Galaxium Travels.

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

2. Clicca su File e poi su Open Folder.

3. Naviga alla directory galaxium-travels che hai clonato e aprila.

4. Apri l'interfaccia chat di Bob cliccando sull'icona Bob accanto alla barra di navigazione, o usa la scorciatoia Option + Command + B (macOS) o Ctrl + Alt + B (Windows).

5. Nel campo di input della chat, esegui /init per inizializzare l'ambiente di sviluppo e creare i file AGENTS.md per Bob. Clicca su Approve todo tools for task se richiesto.

Creare una skill di audit

Crea una skill, che è un set di istruzioni riutilizzabile che Bob usa per lavorare su un task specifico.

La seguente skill audita la codebase Galaxium Travels contro i requisiti OWASP ASVS Livello 1.

La skill verifica i seguenti controlli:

1. Sotto l'interfaccia chat, clicca su Bob - Settings, poi clicca su Bob Settings.

2. Clicca su Skills nella barra laterale sinistra.

3. Clicca sul pulsante + per creare una nuova skill.

4. Inserisci asvs-audit nel campo Skill Name. Questo è il nome usato per invocare la skill con /asvs-audit nella chat.

5. Inserisci una breve descrizione nel campo Description:

   Audita una codebase contro i requisiti OWASP ASVS Livello 1 di controllo degli accessi, validazione dell'input, sicurezza API e configurazione.

6. Assicurati che il toggle Allow Bob to use this skill sia attivo.

   Con il toggle attivo, Bob può attivare la skill autonomamente quando un prompt o un piano lo richiede. Il piano di audit che creerai più avanti in questo tutorial fa esattamente questo.

7. Cambia Scope & Location in galaxium-travels.

   Questo salva la skill nella directory .bob/skills/ del progetto, quindi è disponibile solo in questo progetto e il tuo team può versionarla con la codebase. La posizione globale (~/.bob/skills/) renderebbe la skill disponibile in ogni progetto sulla tua macchina.

8. Inserisci la seguente skill nella casella di testo 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.

   Questo è il set completo di istruzioni che Bob segue durante l'audit.

9. Clicca su Create.

Trovare aree ad alto rischio da auditare

Per risparmiare token, chiedi a Bob di identificare i file e le cartelle più rilevanti per la sicurezza. Eseguirai la skill di audit su queste aree.

1. Se il pannello chat non è già aperto, aprilo con Option + Command + B (macOS) o Ctrl + Alt + B (Windows).

2. Seleziona Ask dal selettore di modalità.

   Ogni modalità ha capacità e stili di ragionamento diversi. La modalità Ask funziona meglio per domande e analisi, ma non puoi scrivere o modificare file in modalità Ask.

3. Nel campo di input della chat, inserisci il seguente prompt per esplorare la codebase e trovare le aree a più alto rischio di sicurezza:

   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 legge i file e risponde con un riepilogo della struttura dell'applicazione.

Creare un piano per auditare le aree ad alto rischio

Crea un piano che Bob seguirà quando audita le aree ad alto rischio.

1. Passa alla modalità Plan.

2. Chiedi a Bob di creare un piano per auditare le aree ad alto rischio. Clicca su Approve todo tools for task se richiesto.

   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 potrebbe fare domande di follow-up per chiarire lo scope dell'audit o le aree specifiche su cui concentrarsi. Puoi rispondere o dire a Bob di use your recommendation.

4. Apri il file del piano per comprendere l'approccio di audit e cosa farà Bob quando lo eseguirai.

Auditare la codebase

1. Clicca sul pulsante + per avviare un nuovo task.

2. Assicurati di essere in modalità Agent nell'interfaccia chat.

   La modalità Agent dà a Bob capacità complete, inclusa la scrittura di file e l'esecuzione. Questo è necessario per le fasi di audit e generazione di report.

3. Clicca sul selettore Permissions nell'interfaccia chat e spunta le caselle Read, Edit, Execute e Skill. Lascia tutti gli altri toggle deselezionati per questo task.

   Permesso	Stato	Perché
   Read	✅ Attivo	Bob legge la codebase, il piano di audit e la skill
   Edit	✅ Attivo	Bob scrive i risultati in security/audit-findings.md
   Execute	✅ Attivo	Bob può eseguire comandi shell per risolvere percorsi o confermare la struttura dei file
   Skill	✅ Attivo	Il piano di audit invoca la skill asvs-audit
   MCP	❌ Disattivo	Non necessario per l'analisi del codice locale

4. Chiedi a Bob di implementare il piano di audit.

   Implement the @plan/audit-plan.md

5. Esamina i risultati in security/audit-findings.md.

   Il piano indica a Bob di creare la directory security/ se non esiste già e salvare i risultati in security/audit-findings.md.

   Salvare i risultati ti permette di avviare una nuova chat con un modello usando una finestra di contesto fresca. Puoi puntare Bob al file dei risultati per generare report senza rileggere l'intera codebase e le istruzioni della skill, il che preserva la finestra di contesto per la generazione di report.

   Nota sulla finestra di contesto: Tutti i modelli hanno una finestra di contesto impostata. Quando auditi una codebase grande, potresti superare la finestra di contesto di un modello. Per codebase grandi, prova ad auditare una categoria ASVS alla volta. Esegui prima V4, poi V5, V13 e V14, e chiedi a Bob di consolidare i risultati alla fine. Questo è anche un buon motivo per mantenere SKILL.md conciso e usare menzioni di contesto @ focalizzate piuttosto che dirigere Bob all'intero repository in una volta.

Generare report di sicurezza

SARIF è il formato di scambio standard per i risultati di analisi statica. Gli IDE incluso Bob, GitHub Advanced Security e la maggior parte delle pipeline CI/CD possono consumare direttamente i file SARIF.

1. Clicca sul pulsante + per avviare un nuovo task.

2. Assicurati di usare la modalità Agent.

3. Clicca su Permissions nel pannello chat e spunta le caselle Read, Edit e Execute. Lascia tutti gli altri toggle deselezionati per questo task.

   Permesso	Stato	Perché
   Read	✅ Attivo	Bob legge i risultati in security/audit-findings.md
   Edit	✅ Attivo	Bob scrive il report SARIF nella directory security/
   Execute	✅ Attivo	Bob può eseguire comandi shell per risolvere percorsi o confermare la struttura dei file
   Skill	❌ Disattivo	Non necessario per produrre report. La skill ha già creato i risultati necessari per l'agente
   MCP	❌ Disattivo	Non necessario per l'analisi del codice locale

4. Chiedi a Bob di generare un report SARIF usando una menzione di contesto @.

   @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 genera il file e lo salva in security/audit-results.sarif. Conferma che il file contiene un array runs con voci results, una per risultato dall'audit.

   Bob riporta anche le decisioni di mapping che ha preso nella chat:

   Esempio di output:

   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. Apri security/audit-results.sarif in Bob per esaminare i risultati. Puoi usare questo file in altri strumenti come GitHub Advanced Security o una pipeline CI/CD per mostrare i risultati dell'audit.

Generare un piano di remediation OSCAL (POA&M)

Il POA&M OSCAL è un documento JSON leggibile da macchina che mappa ogni risultato a un task di remediation strutturato con informazioni sul rischio, guida all'implementazione e assegnazioni di milestone. Bob può leggere questo file come una coda di lavoro. Lavora su ogni elemento, applica correzioni e segna i milestone come completati man mano che procede.

1. Clicca sul pulsante + per avviare un nuovo task.

2. Clicca sul menu modalità nel pannello chat e seleziona Agent.

3. Clicca su Permissions nel pannello chat e spunta le caselle Read, Edit e Execute. Lascia tutti gli altri toggle deselezionati per questo task.

   Permesso	Stato	Perché
   Read	✅ Attivo	Bob legge i risultati in security/audit-findings.md
   Edit	✅ Attivo	Bob scrive il POA&M OSCAL nella directory security/
   Execute	✅ Attivo	Bob può eseguire comandi shell per risolvere percorsi o confermare la struttura dei file
   Skill	❌ Disattivo	Non necessario per produrre report. La skill ha già creato i risultati necessari per l'agente
   MCP	❌ Disattivo	Non necessario per l'analisi del codice locale

4. Chiedi a Bob di generare un report POA&M OSCAL usando una menzione di contesto @.

   @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 genera il file e lo salva in security/poam.json.

   Esempio di output:

   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)

Ora hai due artefatti nella directory security/:

• audit-results.sarif — risultati strutturati per strumenti di sviluppo e integrazione CI/CD
• poam.json — una coda di lavoro di remediation per remediation assistita da IA o guidata dall'uomo

Esaminare i risultati

Con il POA&M generato, esamina i risultati e dai priorità a quali correggere per primi.

1. Clicca sul pulsante + per avviare un nuovo task.

2. Clicca sul menu modalità nel pannello chat e seleziona Ask.

3. Chiedi a Bob di evidenziare gli elementi più critici dal POA&M usando una menzione di contesto @.

   @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 legge il file e restituisce un riepilogo prioritizzato:

   Esempio di output:

   #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.

   Puoi anche integrare un server Model Context Protocol (MCP) nei tuoi workflow di audit e chiedere a Bob di creare ticket per ogni risultato, collegandoli al codice rilevante e includendo la guida alla remediation dal POA&M.