Auditar código y generar informes

Configurar el laboratorio

1. Clona el repositorio de Galaxium Travels.

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

2. Haz clic en File y luego en Open Folder.

3. Navega al directorio galaxium-travels que clonaste y ábrelo.

4. Abre la interfaz de chat de Bob haciendo clic en el icono de Bob junto a la barra de navegación, o usa el atajo Option + Command + B (macOS) o Ctrl + Alt + B (Windows).

5. En el campo de entrada del chat, ejecuta /init para inicializar el entorno de desarrollo y crear los archivos AGENTS.md para Bob. Haz clic en Approve todo tools for task si se te solicita.

Crear una skill de auditoría

Crea una skill, que es un conjunto de instrucciones reutilizable que Bob usa para trabajar en una tarea específica.

La siguiente skill audita la base de código de Galaxium Travels contra los requisitos de OWASP ASVS Nivel 1.

La skill verifica los siguientes controles:

1. Debajo de la interfaz de chat, haz clic en Bob - Settings y luego en Bob Settings.

2. Haz clic en Skills en la barra lateral izquierda.

3. Haz clic en el botón + para crear una nueva skill.

4. Ingresa asvs-audit en el campo Skill Name. Este es el nombre usado para invocar la skill con /asvs-audit en el chat.

5. Ingresa una breve descripción en el campo Description:

   Audita una base de código contra los requisitos de OWASP ASVS Nivel 1 de control de acceso, validación de entrada, seguridad de API y configuración.

6. Asegúrate de que el toggle Allow Bob to use this skill esté activado.

   Con el toggle activado, Bob puede activar la skill por sí mismo cuando un prompt o plan lo requiera. El plan de auditoría que crearás más adelante en este tutorial hace exactamente eso.

7. Cambia Scope & Location a galaxium-travels.

   Esto guarda la skill en el directorio .bob/skills/ del proyecto, por lo que solo está disponible en este proyecto y tu equipo puede versionarla con la base de código. La ubicación global (~/.bob/skills/) haría que la skill estuviera disponible en cada proyecto de tu máquina.

8. Ingresa la siguiente skill en el cuadro 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 es el conjunto completo de instrucciones que Bob sigue durante la auditoría.

9. Haz clic en Create.

Encontrar áreas de alto riesgo para auditar

Para ahorrar tokens, pide a Bob que identifique los archivos y carpetas más relevantes para la seguridad. Ejecutarás la skill de auditoría en estas áreas.

1. Si el panel de chat no está abierto, ábrelo con Option + Command + B (macOS) o Ctrl + Alt + B (Windows).

2. Selecciona Ask del selector de modo.

   Cada modo tiene diferentes capacidades y estilos de razonamiento. El modo Ask funciona mejor para preguntas y análisis, pero no puedes escribir o editar archivos en el modo Ask.

3. En el campo de entrada del chat, ingresa el siguiente prompt para explorar la base de código y encontrar las áreas de mayor riesgo de seguridad:

   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 lee los archivos y responde con un resumen de la estructura de la aplicación.

Crear un plan para auditar las áreas de alto riesgo

Crea un plan para que Bob lo siga al auditar las áreas de alto riesgo.

1. Cambia al modo Plan.

2. Pide a Bob que cree un plan para auditar las áreas de alto riesgo. Haz clic en Approve todo tools for task si se te solicita.

   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 podría hacer preguntas de seguimiento para aclarar el alcance de la auditoría o las áreas específicas en las que enfocarse. Puedes responderlas o decirle a Bob que use your recommendation.

4. Abre el archivo del plan para entender el enfoque de auditoría y lo que Bob hará cuando lo ejecutes.

Auditar la base de código

1. Haz clic en el botón + para iniciar una nueva tarea.

2. Asegúrate de estar en modo Agent en la interfaz de chat.

   El modo Agent le da a Bob capacidades completas, incluyendo escritura de archivos y ejecución. Esto es necesario para las fases de auditoría y generación de informes.

3. Haz clic en el selector Permissions en la interfaz de chat y marca las casillas Read, Edit, Execute y Skill. Deja todos los demás toggles sin marcar para esta tarea.

   Permiso	Estado	Por qué
   Read	✅ Activado	Bob lee la base de código, el plan de auditoría y la skill
   Edit	✅ Activado	Bob escribe los hallazgos en security/audit-findings.md
   Execute	✅ Activado	Bob puede ejecutar comandos de shell para resolver rutas o confirmar la estructura de archivos
   Skill	✅ Activado	El plan de auditoría invoca la skill asvs-audit
   MCP	❌ Desactivado	No es necesario para análisis de código local

4. Pide a Bob que implemente el plan de auditoría.

   Implement the @plan/audit-plan.md

5. Revisa los hallazgos en security/audit-findings.md.

   El plan le indica a Bob que cree el directorio security/ si aún no existe y guarde los hallazgos en security/audit-findings.md.

   Guardar los hallazgos te permite iniciar un nuevo chat con un modelo usando una ventana de contexto fresca. Puedes apuntar a Bob al archivo de hallazgos para generar informes sin volver a leer toda la base de código y las instrucciones de la skill, lo que preserva la ventana de contexto para la generación de informes.

   Nota sobre la ventana de contexto: Todos los modelos tienen una ventana de contexto establecida. Al auditar una base de código grande, puedes exceder la ventana de contexto de un modelo. Para bases de código grandes, intenta auditar una categoría de ASVS a la vez. Ejecuta V4 primero, luego V5, V13 y V14, y pide a Bob que consolide los hallazgos al final. Esta también es una buena razón para mantener SKILL.md conciso y usar menciones de contexto @ enfocadas en lugar de dirigir a Bob a todo el repositorio de una vez.

Generar informes de seguridad

SARIF es el formato de intercambio estándar para resultados de análisis estático. Los IDEs incluyendo Bob, GitHub Advanced Security y la mayoría de los pipelines de CI/CD pueden consumir archivos SARIF directamente.

1. Haz clic en el botón + para iniciar una nueva tarea.

2. Asegúrate de estar usando el modo Agent.

3. Haz clic en Permissions en el panel de chat y marca las casillas Read, Edit y Execute. Deja todos los demás toggles sin marcar para esta tarea.

   Permiso	Estado	Por qué
   Read	✅ Activado	Bob lee los hallazgos en security/audit-findings.md
   Edit	✅ Activado	Bob escribe el informe SARIF en el directorio security/
   Execute	✅ Activado	Bob puede ejecutar comandos de shell para resolver rutas o confirmar la estructura de archivos
   Skill	❌ Desactivado	No es necesario para producir informes. La skill ya creó los hallazgos necesarios para el agente
   MCP	❌ Desactivado	No es necesario para análisis de código local

4. Pide a Bob que genere un informe SARIF usando una mención 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

   Bob genera el archivo y lo guarda en security/audit-results.sarif. Confirma que el archivo contiene un array runs con entradas results, una por hallazgo de la auditoría.

   Bob también informa sobre las decisiones de mapeo que tomó en el chat:

   Ejemplo de salida:

   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 en Bob para revisar los hallazgos. Puedes usar este archivo en otras herramientas como GitHub Advanced Security o un pipeline de CI/CD para mostrar los hallazgos de la auditoría.

Generar un plan de remediación OSCAL (POA&M)

El POA&M de OSCAL es un documento JSON legible por máquina que mapea cada hallazgo a una tarea de remediación estructurada con información de riesgo, orientación de implementación y asignaciones de milestones. Bob puede leer este archivo como una cola de trabajo. Trabaja en cada elemento, aplica correcciones y marca los milestones como completos a medida que avanza.

1. Haz clic en el botón + para iniciar una nueva tarea.

2. Haz clic en el menú de modo en el panel de chat y selecciona Agent.

3. Haz clic en Permissions en el panel de chat y marca las casillas Read, Edit y Execute. Deja todos los demás toggles sin marcar para esta tarea.

   Permiso	Estado	Por qué
   Read	✅ Activado	Bob lee los hallazgos en security/audit-findings.md
   Edit	✅ Activado	Bob escribe el POA&M de OSCAL en el directorio security/
   Execute	✅ Activado	Bob puede ejecutar comandos de shell para resolver rutas o confirmar la estructura de archivos
   Skill	❌ Desactivado	No es necesario para producir informes. La skill ya creó los hallazgos necesarios para el agente
   MCP	❌ Desactivado	No es necesario para análisis de código local

4. Pide a Bob que genere un informe POA&M de OSCAL usando una mención 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.

   Bob genera el archivo y lo guarda en security/poam.json.

   Ejemplo de salida:

   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)

Ahora tienes dos artefactos en el directorio security/:

• audit-results.sarif — hallazgos estructurados para herramientas de desarrollo e integración de CI/CD
• poam.json — una cola de trabajo de remediación para remediación asistida por IA o impulsada por humanos

Revisar hallazgos

Con el POA&M generado, revisa los hallazgos y prioriza cuáles corregir primero.

1. Haz clic en el botón + para iniciar una nueva tarea.

2. Haz clic en el menú de modo en el panel de chat y selecciona Ask.

3. Pide a Bob que resalte los elementos más críticos del POA&M usando una mención 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

   Bob lee el archivo y devuelve un resumen priorizado:

   Ejemplo de salida:

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

   También puedes integrar un servidor de Model Context Protocol (MCP) en tus flujos de trabajo de auditoría y pedir a Bob que cree tickets para cada hallazgo, vinculándolos al código relevante e incluyendo la orientación de remediación del POA&M.