稽核程式碼並產生報告

設定實驗室

1. 複製 Galaxium Travels 儲存庫。

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

2. 點選 File，然後點選 Open Folder。

3. 導覽到你複製的 galaxium-travels 目錄並開啟它。

4. 透過點選導覽列旁邊的 Bob 圖示開啟 Bob 聊天介面，或使用快速鍵 Option + Command + B（macOS）或 Ctrl + Alt + B（Windows）。

5. 在聊天輸入欄位中，執行 /init 以初始化開發環境並為 Bob 建立 AGENTS.md 檔案。如果出現提示，請點選 Approve todo tools for task。

建立稽核技能

建立一個技能，這是 Bob 用來完成特定任務的可重複使用指令集。

以下技能根據 OWASP ASVS Level 1 要求稽核 Galaxium Travels 程式碼庫。

該技能檢查以下控制：

1. 在聊天介面下方，點選 Bob - Settings，然後點選 Bob Settings。

2. 點選左側邊欄中的 Skills。

3. 點選 + 按鈕建立新技能。

4. 在 Skill Name 欄位中輸入 asvs-audit。這是在聊天中使用 /asvs-audit 呼叫技能的名稱。

5. 在 Description 欄位中輸入簡短描述：

   Audits a codebase against OWASP ASVS Level 1 access control, input validation, API security, and configuration requirements.

6. 確保 Allow Bob to use this skill 切換開關已開啟。

   當切換開關開啟時，當提示或計畫呼叫時，Bob 可以自行啟動技能。你稍後在本教學中建立的稽核計畫正是這樣做的。

7. 將 Scope & Location 變更為 galaxium-travels。

   這會將技能儲存在專案的 .bob/skills/ 目錄中，因此它僅在此專案中可用，你的團隊可以與程式碼庫一起進行版本控制。全域位置 (~/.bob/skills/) 將使技能在你機器上的每個專案中可用。

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

   這是 Bob 在稽核期間遵循的完整指令集。

9. 點選 Create。

尋找要稽核的高風險區域

為了節省權杖，請讓 Bob 識別與安全最相關的檔案和資料夾。你將在這些區域執行稽核技能。

1. 如果聊天面板尚未開啟，請使用 Option + Command + B（macOS）或 Ctrl + Alt + B（Windows）開啟它。

2. 從模式選擇器中選擇 Ask。

   每種模式都有不同的功能和推理風格。Ask 模式最適合問題和分析，但你無法在 Ask 模式下編寫或編輯檔案。

3. 在聊天輸入欄位中，輸入以下提示以探索程式碼庫並找到最高安全風險區域：

   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 讀取檔案並傳回應用程式結構的摘要。

建立稽核高風險區域的計畫

建立 Bob 在稽核高風險區域時要遵循的計畫。

1. 切換到 Plan 模式。

2. 提示 Bob 建立稽核高風險區域的計畫。如果出現提示，請點選 Approve todo tools for task。

   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 可能會提出後續問題以釐清稽核範圍或要關注的特定區域。你可以回答它們或告訴 Bob use your recommendation。

4. 開啟計畫檔案以了解稽核方法以及 Bob 在執行時將執行的操作。

稽核程式碼庫

1. 點選 + 按鈕開始新任務。

2. 確保你在聊天介面中處於 Agent 模式。

   Agent 模式為 Bob 提供完整的功能，包括檔案寫入和執行。這對於稽核和報告產生階段是必需的。

3. 點選聊天介面中的 Permissions 選擇器，並選取 Read、Edit、Execute 和 Skill 核取方塊。對於此任務，保持所有其他切換開關未選取。

   權限	狀態	原因
   Read	✅ 開啟	Bob 讀取程式碼庫、稽核計畫和技能
   Edit	✅ 開啟	Bob 將發現寫入 security/audit-findings.md
   Execute	✅ 開啟	Bob 可能執行 shell 命令來解析路徑或確認檔案結構
   Skill	✅ 開啟	稽核計畫呼叫 asvs-audit 技能
   MCP	❌ 關閉	本機程式碼分析不需要

4. 讓 Bob 實施稽核計畫。

   Implement the @plan/audit-plan.md

5. 在 security/audit-findings.md 中查看發現。

   該計畫告訴 Bob 如果 security/ 目錄尚不存在則建立它，並將發現儲存到 security/audit-findings.md。

   儲存發現可以讓你使用新的內容視窗啟動與模型的新聊天。你可以將 Bob 指向發現檔案以產生報告，而無需重新讀取整個程式碼庫和技能指令，這為報告產生保留了內容視窗。

   內容視窗注意事項： 所有模型都有設定的內容視窗。在稽核大型程式碼庫時，你可能會超出模型的內容視窗。對於大型程式碼庫，請嘗試一次稽核一個 ASVS 類別。首先執行 V4，然後執行 V5、V13 和 V14，最後讓 Bob 合併發現。這也是保持 SKILL.md 簡潔並使用集中的 @ 內容提及而不是一次將 Bob 指向整個儲存庫的好理由。

產生安全報告

SARIF 是靜態分析結果的標準交換格式。包括 Bob 在內的 IDE、GitHub Advanced Security 和大多數 CI/CD 管線可以直接使用 SARIF 檔案。

1. 點選 + 按鈕開始新任務。

2. 確保你使用的是 Agent 模式。

3. 點選聊天面板中的 Permissions，並選取 Read、Edit 和 Execute 核取方塊。對於此任務，保持所有其他切換開關未選取。

   權限	狀態	原因
   Read	✅ 開啟	Bob 讀取 security/audit-findings.md 中的發現
   Edit	✅ 開啟	Bob 將 SARIF 報告寫入 security/ 目錄
   Execute	✅ 開啟	Bob 可能執行 shell 命令來解析路徑或確認檔案結構
   Skill	❌ 關閉	產生報告不需要。技能已經建立了代理所需的發現
   MCP	❌ 關閉	本機程式碼分析不需要

4. 使用 @ 內容提及讓 Bob 產生 SARIF 報告。

   @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 產生檔案並將其儲存到 security/audit-results.sarif。確認檔案包含一個 runs 陣列，其中包含 results 條目，稽核中的每個發現一個。

   Bob 還在聊天中報告它做出的對應決策：

   範例輸出：

   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. 在 Bob 中開啟 security/audit-results.sarif 以查看發現。你可以在 GitHub Advanced Security 或 CI/CD 管線等其他工具中使用此檔案來顯示稽核發現。

產生 OSCAL 修復計畫 (POA&M)

OSCAL POA&M 是一個機器可讀的 JSON 文件，它將每個發現對應到具有風險資訊、實施指導和里程碑分配的結構化修復任務。Bob 可以將此檔案作為工作佇列讀取。它處理每個項目，套用修復，並在進行時將里程碑標記為完成。

1. 點選 + 按鈕開始新任務。

2. 點選聊天面板中的模式選單並選擇 Agent。

3. 點選聊天面板中的 Permissions，並選取 Read、Edit 和 Execute 核取方塊。對於此任務，保持所有其他切換開關未選取。

   權限	狀態	原因
   Read	✅ 開啟	Bob 讀取 security/audit-findings.md 中的發現
   Edit	✅ 開啟	Bob 將 OSCAL POA&M 寫入 security/ 目錄
   Execute	✅ 開啟	Bob 可能執行 shell 命令來解析路徑或確認檔案結構
   Skill	❌ 關閉	產生報告不需要。技能已經建立了代理所需的發現
   MCP	❌ 關閉	本機程式碼分析不需要

4. 使用 @ 內容提及讓 Bob 產生 OSCAL POA&M 報告。

   @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 產生檔案並將其儲存到 security/poam.json。

   範例輸出：

   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)

你現在在 security/ 目錄中有兩個工件：

• audit-results.sarif — 用於開發人員工具和 CI/CD 整合的結構化發現
• poam.json — 用於 AI 輔助或人工驅動修復的修復工作佇列

查看發現

產生 POA&M 後，查看發現並確定首先修復哪些發現的優先順序。

1. 點選 + 按鈕開始新任務。

2. 點選聊天面板中的模式選單並選擇 Ask。

3. 使用 @ 內容提及讓 Bob 突顯 POA&M 中最關鍵的項目。

   @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 讀取檔案並傳回優先順序摘要：

   範例輸出：

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

   你還可以將 Model Context Protocol (MCP) 伺服器整合到你的稽核工作流程中，並讓 Bob 為每個發現建立工單，將它們連結到相關程式碼，並包含來自 POA&M 的修復指導。