Auditar código e gerar relatórios

Configurar o laboratório

1. Clona o repositório Galaxium Travels.

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

2. Clica em File e depois em Open Folder.

3. Navega para o diretório galaxium-travels que clonaste e abre-o.

4. Abre a interface de chat do Bob clicando no ícone Bob ao lado da barra de navegação, ou usa o atalho Option + Command + B (macOS) ou Ctrl + Alt + B (Windows).

5. No campo de entrada do chat, executa /init para inicializar o ambiente de desenvolvimento e criar os ficheiros AGENTS.md para o Bob. Clica em Approve todo tools for task se solicitado.

Criar uma skill de auditoria

Cria uma skill, que é um conjunto de instruções reutilizável que o Bob usa para trabalhar numa tarefa específica.

A seguinte skill audita a base de código Galaxium Travels contra os requisitos OWASP ASVS Nível 1.

A skill verifica os seguintes controles:

1. Abaixo da interface de chat, clica em Bob - Settings e depois clica em Bob Settings.

2. Clica em Skills na barra lateral esquerda.

3. Clica no botão + para criar uma nova skill.

4. Insere asvs-audit no campo Skill Name. Este é o nome usado para invocar a skill com /asvs-audit no chat.

5. Insere uma breve descrição no campo Description:

   Audita uma base de código contra os requisitos OWASP ASVS Nível 1 de controle de acesso, validação de entrada, segurança de API e configuração.

6. Certifica-te de que o toggle Allow Bob to use this skill está ativado.

   Com o toggle ativado, o Bob pode ativar a skill autonomamente quando um prompt ou plano o exigir. O plano de auditoria que criarás mais tarde neste tutorial faz exatamente isso.

7. Altera Scope & Location para galaxium-travels.

   Isto guarda a skill no diretório .bob/skills/ do projeto, portanto está disponível apenas neste projeto e a tua equipa pode versioná-la com a base de código. A localização global (~/.bob/skills/) tornaria a skill disponível em cada projeto na tua máquina.

8. Insere a seguinte skill na caixa de texto 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.

   Este é o conjunto completo de instruções que o Bob segue durante a auditoria.

9. Clica em Create.

Encontrar áreas de alto risco para auditar

Para poupar tokens, pede ao Bob para identificar os ficheiros e pastas mais relevantes para a segurança. Vais executar a skill de auditoria nestas áreas.

1. Se o painel de chat não estiver já aberto, abre-o com Option + Command + B (macOS) ou Ctrl + Alt + B (Windows).

2. Seleciona Ask no seletor de modo.

   Cada modo tem capacidades e estilos de raciocínio diferentes. O modo Ask funciona melhor para perguntas e análise, mas não podes escrever ou editar ficheiros no modo Ask.

3. No campo de entrada do chat, insere o seguinte prompt para explorar a base de código e encontrar as áreas de maior risco de segurança:

   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.

   O Bob lê os ficheiros e responde com um resumo da estrutura da aplicação.

Criar um plano para auditar as áreas de alto risco

Cria um plano para o Bob seguir ao auditar as áreas de alto risco.

1. Muda para o modo Plan.

2. Pede ao Bob para criar um plano para auditar as áreas de alto risco. Clica em Approve todo tools for task se solicitado.

   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. O Bob pode fazer perguntas de acompanhamento para esclarecer o âmbito da auditoria ou as áreas específicas em que se focar. Podes respondê-las ou dizer ao Bob para use your recommendation.

4. Abre o ficheiro do plano para entender a abordagem de auditoria e o que o Bob fará quando o executares.

Auditar a base de código

1. Clica no botão + para iniciar uma nova tarefa.

2. Certifica-te de que estás no modo Agent na interface de chat.

   O modo Agent dá ao Bob capacidades completas, incluindo escrita de ficheiros e execução. Isto é necessário para as fases de auditoria e geração de relatórios.

3. Clica no seletor Permissions na interface de chat e marca as caixas Read, Edit, Execute e Skill. Deixa todos os outros toggles desmarcados para esta tarefa.

   Permissão	Estado	Porquê
   Read	✅ Ativado	O Bob lê a base de código, o plano de auditoria e a skill
   Edit	✅ Ativado	O Bob escreve os resultados em security/audit-findings.md
   Execute	✅ Ativado	O Bob pode executar comandos shell para resolver caminhos ou confirmar a estrutura de ficheiros
   Skill	✅ Ativado	O plano de auditoria invoca a skill asvs-audit
   MCP	❌ Desativado	Não necessário para análise de código local

4. Pede ao Bob para implementar o plano de auditoria.

   Implement the @plan/audit-plan.md

5. Revê os resultados em security/audit-findings.md.

   O plano indica ao Bob para criar o diretório security/ se ainda não existir e guardar os resultados em security/audit-findings.md.

   Guardar os resultados permite-te iniciar um novo chat com um modelo usando uma janela de contexto fresca. Podes apontar o Bob para o ficheiro de resultados para gerar relatórios sem reler toda a base de código e instruções da skill, o que preserva a janela de contexto para a geração de relatórios.

   Nota sobre a janela de contexto: Todos os modelos têm uma janela de contexto definida. Ao auditar uma base de código grande, podes exceder a janela de contexto de um modelo. Para bases de código grandes, tenta auditar uma categoria ASVS de cada vez. Executa V4 primeiro, depois V5, V13 e V14, e pede ao Bob para consolidar os resultados no final. Esta é também uma boa razão para manter SKILL.md conciso e usar menções de contexto @ focadas em vez de direcionar o Bob para todo o repositório de uma vez.

Gerar relatórios de segurança

SARIF é o formato de intercâmbio padrão para resultados de análise estática. IDEs incluindo o Bob, GitHub Advanced Security e a maioria dos pipelines de CI/CD podem consumir ficheiros SARIF diretamente.

1. Clica no botão + para iniciar uma nova tarefa.

2. Certifica-te de que estás a usar o modo Agent.

3. Clica em Permissions no painel de chat e marca as caixas Read, Edit e Execute. Deixa todos os outros toggles desmarcados para esta tarefa.

   Permissão	Estado	Porquê
   Read	✅ Ativado	O Bob lê os resultados em security/audit-findings.md
   Edit	✅ Ativado	O Bob escreve o relatório SARIF no diretório security/
   Execute	✅ Ativado	O Bob pode executar comandos shell para resolver caminhos ou confirmar a estrutura de ficheiros
   Skill	❌ Desativado	Não necessário para produzir relatórios. A skill já criou os resultados necessários para o agente
   MCP	❌ Desativado	Não necessário para análise de código local

4. Pede ao Bob para gerar um relatório SARIF usando uma menção de contexto @.

   @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

   O Bob gera o ficheiro e guarda-o em security/audit-results.sarif. Confirma que o ficheiro contém um array runs com entradas results, uma por resultado da auditoria.

   O Bob também reporta as decisões de mapeamento que tomou no chat:

   Exemplo de saída:

   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. Abre security/audit-results.sarif no Bob para rever os resultados. Podes usar este ficheiro noutras ferramentas como GitHub Advanced Security ou um pipeline de CI/CD para mostrar os resultados da auditoria.

Gerar um plano de remediação OSCAL (POA&M)

O POA&M OSCAL é um documento JSON legível por máquina que mapeia cada resultado para uma tarefa de remediação estruturada com informações de risco, orientação de implementação e atribuições de marcos. O Bob pode ler este ficheiro como uma fila de trabalho. Trabalha em cada item, aplica correções e marca os marcos como completos à medida que avança.

1. Clica no botão + para iniciar uma nova tarefa.

2. Clica no menu de modo no painel de chat e seleciona Agent.

3. Clica em Permissions no painel de chat e marca as caixas Read, Edit e Execute. Deixa todos os outros toggles desmarcados para esta tarefa.

   Permissão	Estado	Porquê
   Read	✅ Ativado	O Bob lê os resultados em security/audit-findings.md
   Edit	✅ Ativado	O Bob escreve o POA&M OSCAL no diretório security/
   Execute	✅ Ativado	O Bob pode executar comandos shell para resolver caminhos ou confirmar a estrutura de ficheiros
   Skill	❌ Desativado	Não necessário para produzir relatórios. A skill já criou os resultados necessários para o agente
   MCP	❌ Desativado	Não necessário para análise de código local

4. Pede ao Bob para gerar um relatório POA&M OSCAL usando uma menção de contexto @.

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

   O Bob gera o ficheiro e guarda-o em security/poam.json.

   Exemplo de saída:

   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)

Agora tens dois artefactos no diretório security/:

• audit-results.sarif — resultados estruturados para ferramentas de desenvolvimento e integração CI/CD
• poam.json — uma fila de trabalho de remediação para remediação assistida por IA ou conduzida por humanos

Rever resultados

Com o POA&M gerado, revê os resultados e prioriza quais corrigir primeiro.

1. Clica no botão + para iniciar uma nova tarefa.

2. Clica no menu de modo no painel de chat e seleciona Ask.

3. Pede ao Bob para destacar os itens mais críticos do POA&M usando uma menção de contexto @.

   @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

   O Bob lê o ficheiro e retorna um resumo priorizado:

   Exemplo de saída:

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

   Também podes integrar um servidor Model Context Protocol (MCP) nos teus workflows de auditoria e pedir ao Bob para criar tickets para cada resultado, ligando-os ao código relevante e incluindo a orientação de remediação do POA&M.