Code auditieren und Berichte generieren

Lab einrichten

1. Klone das Galaxium Travels-Repository.

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

2. Klicke auf File und dann auf Open Folder.

3. Navigiere zum geklonten galaxium-travels-Verzeichnis und öffne es.

4. Öffne das Bob-Chat-Interface, indem du auf das Bob-Icon neben der Navigationsleiste klickst oder den Shortcut Option + Command + B (macOS) oder Ctrl + Alt + B (Windows) verwendest.

5. Führe im Chat-Eingabefeld /init aus, um die Entwicklungsumgebung zu initialisieren und die AGENTS.md-Dateien für Bob zu erstellen. Klicke auf Approve todo tools for task, wenn du dazu aufgefordert wirst.

Audit-Skill erstellen

Erstelle eine Skill, die ein wiederverwendbares Anweisungsset ist, das Bob verwendet, um eine bestimmte Aufgabe durchzuarbeiten.

Die folgende Skill auditiert die Galaxium Travels-Codebase gegen OWASP ASVS Level 1-Anforderungen.

Die Skill überprüft die folgenden Controls:

1. Klicke unter dem Chat-Interface auf Bob - Settings und dann auf Bob Settings.

2. Klicke in der linken Seitenleiste auf Skills.

3. Klicke auf den +-Button, um eine neue Skill zu erstellen.

4. Gib asvs-audit im Feld Skill Name ein. Dies ist der Name, der verwendet wird, um die Skill mit /asvs-audit im Chat aufzurufen.

5. Gib eine kurze Beschreibung im Feld Description ein:

   Auditiert eine Codebase gegen OWASP ASVS Level 1 Access Control, Input Validation, API Security und Configuration-Anforderungen.

6. Stelle sicher, dass der Toggle Allow Bob to use this skill aktiviert ist.

   Mit aktiviertem Toggle kann Bob die Skill selbstständig aktivieren, wenn ein Prompt oder Plan danach verlangt. Der Audit-Plan, den du später in diesem Tutorial erstellst, macht genau das.

7. Ändere Scope & Location auf galaxium-travels.

   Dies speichert die Skill im .bob/skills/-Verzeichnis des Projekts, sodass sie nur in diesem Projekt verfügbar ist und dein Team sie mit der Codebase versionieren kann. Der globale Speicherort (~/.bob/skills/) würde die Skill in jedem Projekt auf deinem Rechner verfügbar machen.

8. Gib die folgende Skill in der Skill Instructions-Textbox ein.

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

   Dies ist das vollständige Anweisungsset, dem Bob während des Audits folgt.

9. Klicke auf Create.

Hochrisikobereiche zum Auditieren finden

Um Tokens zu sparen, bitte Bob, die Dateien und Ordner zu identifizieren, die für Security am relevantesten sind. Du wirst die Audit-Skill auf diese Bereiche anwenden.

1. Falls das Chat-Panel noch nicht geöffnet ist, öffne es mit Option + Command + B (macOS) oder Ctrl + Alt + B (Windows).

2. Wähle Ask aus dem Mode-Selector.

   Jeder Modus hat unterschiedliche Fähigkeiten und Reasoning-Stile. Der Ask-Modus funktioniert am besten für Fragen und Analysen, aber du kannst im Ask-Modus keine Dateien schreiben oder bearbeiten.

3. Gib im Chat-Eingabefeld den folgenden Prompt ein, um die Codebase zu erkunden und die Bereiche mit dem höchsten Security-Risiko zu finden:

   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 liest die Dateien und antwortet mit einer Zusammenfassung der Anwendungsstruktur.

Plan zum Auditieren der Hochrisikobereiche erstellen

Erstelle einen Plan, dem Bob beim Auditieren der Hochrisikobereiche folgen soll.

1. Wechsle in den Plan-Modus.

2. Fordere Bob auf, einen Plan zum Auditieren der Hochrisikobereiche zu erstellen. Klicke auf Approve todo tools for task, wenn du dazu aufgefordert wirst.

   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 könnte Folgefragen stellen, um den Scope des Audits oder die spezifischen Bereiche zu klären, auf die du dich konzentrieren möchtest. Du kannst sie beantworten oder Bob sagen, dass er use your recommendation soll.

4. Öffne die Plan-Datei, um den Audit-Ansatz zu verstehen und was Bob tun wird, wenn du ihn ausführst.

Codebase auditieren

1. Klicke auf den +-Button, um einen neuen Task zu starten.

2. Stelle sicher, dass du im Agent-Modus im Chat-Interface bist.

   Der Agent-Modus gibt Bob volle Fähigkeiten, einschließlich Dateischreiben und Ausführung. Dies ist für die Audit- und Report-Generierungsphasen notwendig.

3. Klicke auf den Permissions-Selector im Chat-Interface und aktiviere die Checkboxen Read, Edit, Execute und Skill. Lasse alle anderen Toggles für diesen Task deaktiviert.

   Permission	Status	Warum
   Read	✅ An	Bob liest die Codebase, den Audit-Plan und die Skill
   Edit	✅ An	Bob schreibt die Findings in security/audit-findings.md
   Execute	✅ An	Bob kann Shell-Befehle ausführen, um Pfade aufzulösen oder die Dateistruktur zu bestätigen
   Skill	✅ An	Der Audit-Plan ruft die asvs-audit-Skill auf
   MCP	❌ Aus	Nicht für lokale Code-Analyse benötigt

4. Bitte Bob, den Audit-Plan zu implementieren.

   Implement the @plan/audit-plan.md

5. Überprüfe die Findings in security/audit-findings.md.

   Der Plan weist Bob an, das security/-Verzeichnis zu erstellen, falls es noch nicht existiert, und die Findings in security/audit-findings.md zu speichern.

   Das Speichern der Findings ermöglicht es dir, einen neuen Chat mit einem Modell mit einem frischen Context Window zu starten. Du kannst Bob auf die Findings-Datei verweisen, um Reports zu generieren, ohne die gesamte Codebase und Skill-Anweisungen erneut zu lesen, was das Context Window für die Report-Generierung bewahrt.

   Context Window-Hinweis: Alle Modelle haben ein festgelegtes Context Window. Beim Auditieren einer großen Codebase kannst du das Context Window eines Modells überschreiten. Für große Codebases versuche, jeweils eine ASVS-Kategorie zu auditieren. Führe zuerst V4 aus, dann V5, V13 und V14, und bitte Bob am Ende, die Findings zu konsolidieren. Dies ist auch ein guter Grund, SKILL.md prägnant zu halten und fokussierte @ Context Mentions zu verwenden, anstatt Bob auf das gesamte Repository auf einmal zu verweisen.

Security-Reports generieren

SARIF ist das Standard-Austauschformat für Static-Analysis-Ergebnisse. IDEs einschließlich Bob, GitHub Advanced Security und die meisten CI/CD-Pipelines können SARIF-Dateien direkt konsumieren.

1. Klicke auf den +-Button, um einen neuen Task zu starten.

2. Stelle sicher, dass du den Agent-Modus verwendest.

3. Klicke auf Permissions im Chat-Panel und aktiviere die Checkboxen Read, Edit und Execute. Lasse alle anderen Toggles für diesen Task deaktiviert.

   Permission	Status	Warum
   Read	✅ An	Bob liest die Findings in security/audit-findings.md
   Edit	✅ An	Bob schreibt den SARIF-Report in das security/-Verzeichnis
   Execute	✅ An	Bob kann Shell-Befehle ausführen, um Pfade aufzulösen oder die Dateistruktur zu bestätigen
   Skill	❌ Aus	Nicht benötigt, um Reports zu erstellen. Die Skill hat bereits die vom Agent benötigten Findings erstellt
   MCP	❌ Aus	Nicht für lokale Code-Analyse benötigt

4. Bitte Bob, einen SARIF-Report mit einer @ Context Mention zu generieren.

   @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 generiert die Datei und speichert sie in security/audit-results.sarif. Bestätige, dass die Datei ein runs-Array mit results-Einträgen enthält, einen pro Finding aus dem Audit.

   Bob berichtet auch über die Mapping-Entscheidungen, die er im Chat getroffen hat:

   Beispielausgabe:

   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. Öffne security/audit-results.sarif in Bob, um die Findings zu überprüfen. Du kannst diese Datei in anderen Tools wie GitHub Advanced Security oder einer CI/CD-Pipeline verwenden, um die Audit-Findings anzuzeigen.

OSCAL-Remediation-Plan (POA&M) generieren

Der OSCAL POA&M ist ein maschinenlesbares JSON-Dokument, das jedes Finding auf eine strukturierte Remediation-Aufgabe mit Risikoinformationen, Implementierungsanleitung und Meilenstein-Zuweisungen abbildet. Bob kann diese Datei als Work Queue lesen. Er arbeitet jeden Punkt durch, wendet Fixes an und markiert Meilensteine als abgeschlossen.

1. Klicke auf den +-Button, um einen neuen Task zu starten.

2. Klicke auf das Mode-Menü im Chat-Panel und wähle Agent.

3. Klicke auf Permissions im Chat-Panel und aktiviere die Checkboxen Read, Edit und Execute. Lasse alle anderen Toggles für diesen Task deaktiviert.

   Permission	Status	Warum
   Read	✅ An	Bob liest die Findings in security/audit-findings.md
   Edit	✅ An	Bob schreibt den OSCAL POA&M in das security/-Verzeichnis
   Execute	✅ An	Bob kann Shell-Befehle ausführen, um Pfade aufzulösen oder die Dateistruktur zu bestätigen
   Skill	❌ Aus	Nicht benötigt, um Reports zu erstellen. Die Skill hat bereits die vom Agent benötigten Findings erstellt
   MCP	❌ Aus	Nicht für lokale Code-Analyse benötigt

4. Bitte Bob, einen OSCAL POA&M-Report mit einer @ Context Mention zu generieren.

   @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 generiert die Datei und speichert sie in security/poam.json.

   Beispielausgabe:

   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)

Du hast jetzt zwei Artefakte im security/-Verzeichnis:

• audit-results.sarif — strukturierte Findings für Developer-Tooling und CI/CD-Integration
• poam.json — eine Remediation-Work-Queue für KI-gestützte oder menschengesteuerte Remediation

Findings überprüfen

Nachdem der POA&M generiert wurde, überprüfe die Findings und priorisiere, welche zuerst behoben werden sollen.

1. Klicke auf den +-Button, um einen neuen Task zu starten.

2. Klicke auf das Mode-Menü im Chat-Panel und wähle Ask.

3. Bitte Bob, die kritischsten Items aus dem POA&M mit einer @ Context Mention hervorzuheben.

   @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 liest die Datei und gibt eine priorisierte Zusammenfassung zurück:

   Beispielausgabe:

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

   Du kannst auch einen Model Context Protocol (MCP) Server in deine Audit-Workflows integrieren und Bob bitten, Tickets für jedes Finding zu erstellen, sie mit dem relevanten Code zu verknüpfen und die Remediation-Anleitung aus dem POA&M einzuschließen.