安全審查技能
使用 Claude Code 子代理程式，對程式碼儲存庫進行完整、多階段的安全審查。每個階段都有狹窄的責任範圍，並將其輸出傳遞給下一個階段。
先決條件
在執行之前，請確保以下 CLI 工具可用（如果缺少，請安裝）：
gitleaks— 使用 git 歷史記錄進行秘密掃描。建議安裝。osv-scanner— 主要的 CVE 掃描器；涵蓋所有生態系統的鎖定檔案。建議安裝。semgrep— 用於種子 OWASP 掃描的靜態分析。建議安裝。jq— 用於 EPSS 擴充（階段 3）和執行時 Docker 路徑（階段 5）。建議安裝。pip-audit— 補充性的 Python CVE 掃描（資料庫與 osv-scanner 不同）。可選（僅限 Python 儲存庫）。grype— 補充性的 Java/Maven CVE 掃描。可選（僅限 Java 儲存庫）。poetry— 匯出poetry.lock以便 pip-audit 讀取。可選（僅限 Poetry 專案）。docker— 執行時 PoC 驗證。可選（僅適用於--runtime標誌）。
npm audit 未列出 — 它與 npm 捆綁在一起，可在任何 Node.js 專案中自動使用。
檢查並安裝：
bash scripts/setup.sh
輸入
使用者提供：
- 儲存庫路徑（必要）：已克隆儲存庫的路徑
- 跳過標誌（可選）：要跳過的階段列表，以逗號分隔
- 報告輸出路徑（可選）：最終報告的寫入位置
- 執行時驗證（可選）：是否啟動 Docker 進行 PoC 測試
使用以下格式從 $ARGUMENTS 解析這些參數：
/repo-security-review /path/to/repo [--skip phase1,phase3] [--output /path/to/report.md] [--runtime]
參數解析規則
| 參數 | 預設值 | 描述 |
|---|---|---|
| (第一個位置參數) | 必要（單一儲存庫模式） | 儲存庫路徑。使用 --repos 時省略。 |
--repos | 無 | 多儲存庫模式的儲存庫路徑列表，以逗號分隔。啟動階段 0 和階段 7。設定此參數時，第一個位置參數非必要。 |
--skip | 無 | 要跳過的階段名稱列表，以逗號分隔：secrets、architecture、dependencies、owasp、validation |
--output | 無 — 所有工件保留在 {repo_path}/.security-review/（單一儲存庫）或 ./system-security-review/（多儲存庫）中 | 執行後，將最終報告和 PoC 腳本複製到的目錄。如果不存在則建立。強烈建議在多儲存庫模式下使用。 |
--poc | false | 選擇加入：在階段 5 驗證發現（CONFIRMED / CONFIRMED_LOW_CONFIDENCE）後，為其產生 PoC。若無此標誌，階段 5 會驗證每個發現，報告包含完整判定，但不會寫入 PoC 檔案。在 PR 模式（永不產生 PoC）或供應商模式（強制關閉 PoC 產生 — 請參閱供應商模式）中無效。 |
--runtime | false | 啟用基於 Docker 的執行時 PoC 驗證。隱含 --poc — 執行時驗證會執行產生的 PoC 腳本，因此沒有 PoC 就無從驗證。 |
--vendor | false | 供應商/開源審計模式。審計公司考慮採用的第三方儲存庫；受眾是內部安全團隊；交付成果是採用風險判斷（而不是提供給供應商的修復清單）。強制跳過 secrets、dependencies 和 poc；將每個階段固定為已解析的 Standard 層級模型（永不使用 Opus）；並將階段 6 切換為供應商報告格式。請參閱下方的供應商模式。 |
--pr | 無 | PR 審查模式。--pr <base>...<head>（或 --pr <base> 作為 <base>...HEAD 的簡寫）僅審查合併請求的差異，而不是整個儲存庫 — 用 references/pr-review.md 取代 6/7 階段流程，固定為已解析的 Standard 層級模型，並寫入 pr-report.md 而非 final-report.md。與 --repos 和 --vendor 互斥。請參閱 PR 審查模式。 |
--context | 無 | 內聯的 key=value,key=value 威脅模型，用於校準嚴重性。可選 — 省略則使用預設行為。請參閱 --context。 |
--yes | false | 非互動模式。自動確認所有使用者提示：--output 複製確認、Docker 執行時關卡（--runtime）以及純技能儲存庫自動跳過級聯。路徑驗證安全檢查（拒絕敏感的 --output 目標）永遠不會被繞過。在 CI 或腳本化執行中使用。 |
--debug | false | 將一個易於貼上的執行日誌寫入 {repo_path}/.security-review/execution-log.md，記錄檔案讀取階段的實際執行方式 — 每個讀取的檔案及其行範圍和完整/部分標誌、哪些檔案被分類為安全相關以及是否被完整讀取、執行的 grep/工具、以及已執行與已跳過的檢查。用於檢查技能行為；與報告模式無關。請參閱執行日誌。 |
如果未提供儲存庫路徑且未設定 --repos，請在繼續之前詢問使用者。
例外：如果設定了 --yes 但未提供儲存庫路徑，則以明確的錯誤中止，而不是提示 — 因為互動輸入不可用。
多儲存庫模式由 --repos 的存在觸發。在此模式下：
- 以逗號分隔的路徑是要分析的服務列表。
- 如果未提供
--output，則預設為./system-security-review/。 - 階段 0（服務拓撲映射）在每個儲存庫階段之前執行一次。
- 階段 1–6 按順序為每個儲存庫獨立執行。
- 階段 7（跨儲存庫綜合）在所有每個儲存庫階段完成後執行一次。
- 輸出目錄包含每個服務的子目錄和系統層級的報告。
跳過階段別名：
secrets→ 階段 1architecture→ 階段 2dependencies→ 階段 3 + 3bowasp→ 階段 4validation→ 整個階段 5（驗證，以及如果設定了--poc，則 PoC 也會被跳過）skill-security→ 階段 4b
級聯規則：
--skip owasp→ 也跳過validation（階段 5 無從入手）。如果跳過驗證，則--poc無效。--skip validation→--poc無效（PoC 需要驗證判定；但不存在）。--runtime但未設定--poc→ 隱含--poc；執行 PoC 產生，以便執行時驗證有東西可以驗證。
PR 模式 (--pr) 中的跳過別名會針對 references/pr-review.md 的步驟重新解釋相同的名稱，而非編號的階段：secrets → 步驟 3、dependencies → 步驟 5、owasp → 步驟 4、validation → 步驟 6。architecture 在 PR 模式下不是有效的跳過目標 — 步驟 1/2 的結構上下文對於其他每個步驟都至關重要，不能跳過；傳遞它會以明確的錯誤中止。skill-security 在 PR 模式下無效（階段 4b 不會執行）。--poc 在 PR 模式下無效 — 此模式永不產生 PoC（請參閱下面的 PR 審查模式），無論標誌為何。
模型配置
此技能始終使用可用的最高品質模型。模型 ID 在執行時透過下面的後備鏈解析 — 協調器在階段 1 之前探測可用性，並將解析的 ID 記錄在 run-metadata.json 中。
模型層級
所有階段使用兩個層級：
| 層級 | 使用於 | 用途 |
|---|---|---|
| 深度 | 階段 2 | 擴展推理：架構 |
| 標準 | 階段 0、1、3、4、4b、5、6、7 | 聚焦分析：拓撲提取、秘密、CVE、OWASP、LLM/AI 技能安全性、驗證、報告、跨儲存庫綜合 |
只有階段 2 使用深度層級 — 這是一個經過深思熟慮的明確選擇，而非後備。 階段 0 已於 2026-07-30 移至標準層級（拓撲映射是結構提取，而非安全判斷）。階段 4b 和階段 7 也已移至標準層級，因此深度層級現在僅保留給架構分析。如果 LLM 安全性或跨儲存庫綜合品質因此下降，請重新審視。
後備鏈
依序嘗試每個系列。使用目前 API 金鑰/帳戶層級上第一個可用的系列 — 接受該系列解析到的任何具體快照。切勿定位、偏好或探測特定的日期版本（無 "claude-opus-4-8"，無 "claude-sonnet-4-6"）— 鏈僅按系列命名。
深度層級：
1. Opus 系列 ← 偏好；支援自適應思考
2. Sonnet 系列 ← 後備，僅在 Opus 系列完全不可用時使用
標準層級：
1. Sonnet 系列 ← 偏好
2. Haiku 系列 ← 後備，僅在 Sonnet 系列完全不可用時使用
claude-fable-5 永遠不會在任何層級的任何位置被選中 — 其發布後的護欄可能會在階段 2 和階段 4b 所依賴的攻擊路徑和注入向量推理上導致過於謹慎的拒絕。這是此技能仍然強制執行的唯一模型級別排除；系列內的其他所有內容都是公平競爭的，無論帳戶目前提供哪個快照。
如果一個層級的系列（及其唯一後備系列）中確實沒有任何可用模型，請以明確的錯誤中止。 不要從不同層級（例如，絕不能從標準降至深度，反之亦然）取代模型 — 唯一的例外是 Fable 5，無論什麼不可用，都不得將其取代進來。
僅按系列設計 — 無任何版本固定。 此技能從不命名、定位或偏好特定的日期快照 — 僅有層級（深度/標準）和系列（Opus/Sonnet/Haiku）。帳戶目前為該系列提供的任何具體模型都按原樣接受；解析到更新或更舊的快照是預期行為，而非失敗條件，並且永遠不需要為此設閘、詢問或提示。實際解析的內容會記錄在
run-metadata.json中 — 這是對結果的觀察，而非技能目標。
供應商模式 (
--vendor) 會覆蓋層級解析。 當設定--vendor時，每個階段都使用已解析的標準層級模型 — Sonnet 系列，僅在 Sonnet 完全不可用時才後備到 Haiku 系列 — 永遠不使用 Opus。如果兩者都不可用，請以明確的錯誤中止（該模式的合約是「僅限標準層級，永遠不用深度」— 請不要悄悄借用深度層級模型）。請參閱供應商模式。
在互動式 Claude Code 會話內部的調度現實： 當階段是透過會話自己的子代理調度工具產生，而非原始 Anthropic API 呼叫時，模型選擇僅暴露為一組小的通用系列別名（例如
opus/sonnet/haiku）加上一個推理努力層級 — 永遠不是一個精確的日期模型 ID，也永遠不是一個明確的thinking參數。這些通用別名解析為目前帳戶上當前該系列的規範模型 — 按原樣接受，根據上述僅按系列的說明。無論使用哪條路徑，都將實際解析和調度的內容記錄在run-metadata.json → fallback_notes中，以便讀者始終可以判斷哪個具體模型產生了給定階段的輸出。唯一會中止的情況是系列本身完全不可用（例如根本沒有opus系列模型）或唯一可解析的選項是claude-fable-5。
思考規則（應用於解析後的模型）
按系列鍵入，而非確切版本 — 無論解析的快照是 4.x 還是 5 世代，相同的系列/層級行都適用。
| 解析的系列 | 層級 | thinking 參數（原始 API 調度） | 代理工具努力（別名調度） |
|---|---|---|---|
| Opus（任何世代） | 深度 | thinking: {type: "adaptive"} | "high" |
| Sonnet（任何世代） | 深度（後備）/ 標準 | 省略 thinking 參數，除非解析的快照是 Sonnet 5（也支援 adaptive） | "medium" |
| Haiku（任何世代） | 標準（後備） | 省略 thinking 參數 | "medium" |
絕不傳遞
thinking: {type: "disabled"}— 僅支援自適應思考的 Opus 快照會為此返回 400。當不需要思考時，完全省略該參數。
模型解析步驟
在產生階段 1 之前（或在多儲存庫模式下為階段 0 之前）：
1. 透過逐系列嘗試探測來解析每個層級：
- 嘗試一個最小的代理程式呼叫，請求深度層級的主要系列
(Opus)。如果成功，那就是已解析的深度模型 — 接受
回傳的任何具體快照；從不定位或偏好特定
的日期版本。
如果失敗並出現 model-not-found / model-unavailable 錯誤，請嘗試
深度層級的唯一後備系列 (Sonnet)。如果也失敗，請中止
並顯示明確的錯誤 — 不要在這兩個系列之外取代模型。
- 對標準層級重複相同的步驟（主要：Sonnet 系列；
後備：Haiku 系列）。
- 在互動式 Claude Code 會話中，此「嘗試」僅是
透過子代理調度工具請求該層級的系列別名 (`opus` / `sonnet` / `haiku`)，
而非字面上的日期 ID — 請參閱上面的「調度現實」。在該路徑中沒有按精確 ID 探測；
無論別名解析為何，那就是已解析的模型。
- 注意：不要將 `claude models list` 作為 Bash 命令執行。在
互動式 Claude Code 會話中，該字串會被路由到對話
介面，而非 CLI 二進位檔案，並會產生澄清回覆，而非
模型列表。
2. 確定解析系列的思考參數 / 努力程度（上表）。
3. 寫入 run-metadata.json，包含已解析的 ID 和 fallback_notes 欄位。
每當某個層級使用了其後備系列而非其主要系列時，
都包含 fallback_notes，以便事後可以審計該次執行的
模型解析結果。
run-metadata.json
單一儲存庫： 寫入 {repo_path}/.security-review/run-metadata.json。
多儲存庫： 將一個共用副本寫入 {output_dir}/run-metadata.json。
下面的具體 ID 僅作說明之用 — 它們顯示了記錄內容的形狀，而非技能的目標。實際值取決於執行當天每個系列解析到的快照（可能與此處顯示的 Opus 或 Sonnet 快照不同）。