Cloudflare security-audit-skill 完整教學 2026：3.9 萬星的 AI 安全稽核技能，六階段找出「真漏洞」（安裝、三種模式、findings.json 格式、沙箱要求與五個限制）

Cloudflare 開源的 security-audit-skill 是一套給 coding agent 用的安全稽核技能：它把「找漏洞」拆成偵察、覆蓋率導向狩獵、候選驗證、結構化輸出、獨立複核、產生報告六個階段，每個候選漏洞都要交給「不是發現它的那個 agent」想辦法反駁，只有真的越過信任邊界、有具體影響的才給嚴重性。目前 39,131 星、MIT 授權，是 Cloudflare 自家漏洞發現 harness 的種子版本。

如果你已經在用 Claude Code、Cursor、Codex 這類工具寫程式，這篇的價值不在「又一個 AI 工具」，而在它示範了一件更重要的事：怎麼樣讓 AI 的資安結論「可以被查證」，而不是一份看起來很專業的猜測。

為什麼這個技能值得花時間看

多數人對「AI 找漏洞」的印象是：把 repo 丟給模型，它回你一堆「可能存在 SQL injection」的段落。問題是那份清單通常不能拿去修東西——沒有行號、沒有攻擊路徑、沒有重現方式，而且充滿誤報。

security-audit-skill 的差別在於它是一份流程規定，不是一段提示詞。它在 SKILL.md 裡直接寫死「什麼不算漏洞」：

• 沒有具體受影響主體（principal）、資源、或安全結果的候選，不准標成 confirmed；
• 只是「少了縱深防禦」而前一層已經擋住的，不算漏洞，只能算加固建議；
• 嚴重性必須由「影響」推導，不能因為「偏離檢查清單」就給高分。

而且它的出身有點硬：這是 Cloudflare 那個「vulnerability harness」的起點。官方部落格說得很直白——他們一開始就是一個 約 450 行的 security-audit skill，先跑在單一 repo 上，一路調整 prompt 直到真的挖到 bug，後來才長成跨 128 個 repo 的 fleet 掃描系統。開源出來的這個版本，就是那個還沒長成系統之前的樣子。

一表看懂

六個階段：它到底怎麼跑

這是全篇最值得記住的部分。技能的流程長這樣：

幾個藏在細節裡的設計，比流程本身更關鍵：

• 驗證者不能是發現者。 官方原則寫得很白：「the agent that checks a finding is never the agent that found it.」這是為了避免同一個推理路徑自我確認。
• 覆蓋率是顯性資產。 coverage-ledger.json 由 parent agent 獨占寫入，每次有 agent 回報就更新。它讓「這次掃了哪些、哪些沒掃」變成可稽核的資料，而不是一句「應該差不多都看了」。
• 多次執行是加法。 同一 repo 重跑會讀先前的帳本與 findings，針對缺口補、把改過的原始碼重新驗證，而不是從零開始。

安裝：官方指令原文

技能用 Skills CLI 安裝（skills.sh），兩行就結束：

npx skills add https://github.com/cloudflare/security-audit-skill \
  --skill security-audit

想裝在使用者層級（所有專案共用）：

npx skills add https://github.com/cloudflare/security-audit-skill \
  --skill security-audit \
  --global

其他代理選擇、非互動安裝的參數，用 npx skills --help 查。裝好之後不需要記指令，用自然語言觸發就行。

三種觸發方式，但只有兩種模式

官方給的範例提示很樸素，貼進代理就能用：

security audit this codebase

find security vulnerabilities in ./src

do a security review, output to ~/audits/my-project

要注意的是它刻意分成兩種模式，而且預設是保守的那一個：

原文的規定是：「Loading it does not authorize the complete audit workflow or file creation.」——載入技能不等於授權它開始跑全套。如果一句話兩種都說得通，它會先問你一個問題再動手。

Full audit 模式的輸出目錄預設是 ~/security-audit-skill/<repo-name>/run-<N>，N 自動取沒用過的流水號。要寫在目標 repo 裡，必須是你明確指定、而且 parent 確認整個目錄被版控忽略，否則會停下來要求給一個外部路徑——這條規定是為了避免稽核產物污染 repo。

三種 profile：quick／standard／deep

不是每次稽核都需要一樣的力氣，所以它有 profile 概念：

Profile 只改變「廣度與冗餘」，不改變證據標準。文件寫得很清楚：候選門檻、原始碼／本地執行的邊界、needs_validation 紀律、schema 驗證、confirmed 的獨立複核，都不能因為選了 quick 就被縮掉。

另外有一個很實用的設計：預算是用「agent 呼叫次數」計價的。你可以在 run-metadata.json 裡設 budget，parent 會先保留「偵察 4 次＋critic＋至少 1 個 verifier」的額度，再決定能派幾個 hunter。如果預算連最低儲備都不夠，它會直接一個 agent 都不派，把狀態設成 incomplete 並告訴你原因——而不是硬跑一場假的稽核。

輸出長什麼樣

Full audit 會產出這些檔案，全部由 parent 獨占寫入：

findings.json 只有三種判決，界線分得非常乾淨：

一條 confirmed 紀錄必填的欄位有 13 個：verdict、fingerprint、title、description、root_cause、intended_behavior、trace、evidence、conditions、execution、remediation、severity、confidence。骨架大概長這樣：

[
  {
    "verdict": "confirmed",
    "fingerprint": "src/api/export.ts:42:tenant-scope",
    "title": "匯出 API 未檢查 tenant 邊界",
    "description": "已驗證：跨租戶讀取 dummy 資料成功。",
    "root_cause": "查詢條件只帶 resource_id，未帶 tenant_id。",
    "intended_behavior": "每個查詢都必須以呼叫者的 tenant 為主鍵。",
    "trace": [
      { "kind": "entrypoint", "file": "src/api/export.ts", "line": 42, "scope": "router.export", "description": "未驗證 tenant 的入口" },
      { "kind": "sink", "file": "src/db/export.ts", "line": 88, "scope": "buildQuery", "description": "缺少 tenant 條件" }
    ],
    "evidence": [
      { "file": "src/db/export.ts", "line": 88, "description": "WHERE 子句僅含 resource_id" }
    ],
    "conditions": "需要已登入的低權限帳號，攻擊者需知道他人的 resource_id。",
    "execution": {
      "attacker_perspective": "以 tenant A 的帳號請求 tenant B 的資源",
      "payloads": ["/api/export?resource_id=t2-001"],
      "instructions": ["在沙箱啟動本機服務", "以 dummy 帳號 A 呼叫上述路徑"],
      "observed_result": "回應 200 並回傳 tenant B 的 dummy 匯出檔"
    },
    "remediation": "在 buildQuery 強制注入呼叫者的 tenant_id，並補一條跨租戶拒絕的迴歸測試。",
    "severity": {
      "likelihood": { "score": "high", "reason": "只需低權限帳號與一個可猜測的 ID" },
      "impact": { "score": "high", "reason": "跨租戶讀取真實資料，屬明確的邊界突破" },
      "overall_severity": "high"
    },
    "confidence": { "score": "high", "reason": "已有有界本地重現結果" }
  }
]

嚴重性分五級，判準寫在 SKILL.md 裡（不是感覺）：

驗證器：唯一「可機器檢查」的部分

這是這個技能最實用的地方——它不是只給你一份 Markdown，而是附了兩支零依賴驗證器，用 Node.js 就能跑：

node <skill-dir>/validate-findings.cjs <output-dir>/findings.json
node <skill-dir>/validate-coverage-ledger.cjs <output-dir>/coverage-ledger.json

validate-findings.cjs 會照 report-schema.json 檢查（自己實作 schema 直譯器，不裝任何套件），validate-coverage-ledger.cjs 檢查覆蓋率帳本的結構。規則是：帳本建立後驗一次、之後每次更新再驗；findings 在第 4 階段驗一次，第 5 階段每次替換後再驗。

這代表你可以把它塞進 CI：「報告存在」不算通過，「報告通過 schema」才算。 這兩支腳本也有自己的測試檔（.test.cjs），這在 AI 工具裡算少見的誠實。

沙箱：沒有它，技能會拒絕執行目標程式碼

這是很多人會忽略、但實務上最卡的一關。技能的規定是：只有在 OS 層級沙箱裡，才允許跑目標自己的 build、測試、瀏覽器、模擬器、fuzzer，而且沙箱必須同時滿足：

• 對外網路關閉（需要本地 client/server 時只用隔離的 loopback）；
• 環境變數從白名單重建（空的 HOME、暫存、cache）；
• 目標與工具鏈唯讀，目標程式只能寫進被分派的 scratch/；
• 明確的 CPU、記憶體、process 數、檔案大小、磁碟、wall-clock 上限。

做不到怎麼辦？文件寫得很硬：不要執行，把缺的沙箱能力當成 needs_validation 的 blocker 回報，並給一份安全的驗證計畫。另外原始碼檢視全程唯讀，不准對已部署的端點、共享基礎設施、正式身分、別人的資料做探測。

換句話說，這個技能在設計上就把「AI 亂打你的 production」這條路堵掉了——代價是你得先準備好沙箱環境。

五個要講清楚的限制

一篇只講優點的工具文沒有價值，這幾個限制必須寫在前面：

1. 單次執行只抓到約一半的漏洞。 官方在 README 的設計原則裡自己承認：在他們的測試裡，單次 run 大約只找到「多次 run 加總」的一半，而且找到的偏向比較簡單、不那麼隱蔽的那些。部落格講得更白：「一旦你的流程變成『跑十次再人工比對』，你就該開始考慮真正的 harness 了。」
2. 128 個 repo 那個數字不是這支技能的成績。 那是 Cloudflare 內部 harness 六週長出來的規模（含跨 repo 依賴追蹤、SQLite 持久化、sibling forking 等）。開源版是單一 repo 的起點，別把它當企業級掃描器。
3. 沒有公開的第三方獨立評測。 星數 39,131 是社群關注度，不等於「實測優於某某商業 SAST」。文章裡所有效能數字都是官方自述。
4. 吃資源，也吃模型品質。 它要求模型支援 tool use 與平行子代理，一場 standard 或 deep 稽核會派出大量 agent；部落格提到他們把每個 agent 的 context 壓在視窗的 25% 以下才不會開始幻覺。模型越弱，誤報越多、驗證輪數越長。
5. 它只描述修法，不改你的程式碼。 這是刻意設計（稽核不該動目標原始碼），所以「找到→修好」之間仍然要你自己接手。

跟其他做法怎麼選

實務上最合理的組合是：SAST／SCA 當每天的門禁，這個 skill 當「重大改版前或高風險模組」的深度檢查，正式上線前再排一次人工滲透測試。

誰適合、誰不需要

適合：正在用 Claude Code／Cursor／Codex 的後端或全端工程師；要對自家服務做定期內部稽核的小團隊；想學「怎麼把 AI 稽核流程做得可查證」的人（就算不裝，SKILL.md 那 190 行的流程規定本身就值得讀）。

不需要：只是想知道「這段 code 有沒有明顯問題」的人（guidance 模式就夠，別開 full audit）；沒有沙箱環境又打算讓它跑 build 的人（它會拒絕，你也別硬開）；期待它取代 SAST 或滲透測試的人。

站內延伸閱讀

• Open Code Review 完整教學 2026：阿里巴巴開源的 AI 程式碼審查 CLI
• Agent Skills 完整教學：Addy Osmani 開源專案，讓 Claude Code、Cursor 自動遵循工程紀律
• MCP 完整教學 2026：Model Context Protocol 入門到實戰
• llms.txt 與 agent 供應鏈：AI 爬蟲時代的新入口
• Claude Skills 最佳實務 2026：官方 7 條新規則

資料來源與查證方法

• GitHub 倉庫：cloudflare/security-audit-skill（README、skills/security-audit/SKILL.md、report-schema.json、validate-findings.cjs、VALIDATION-AND-REPORTING.md 皆直接讀取原始檔）
• 星數／Fork／授權／建立與推送時間：api.github.com/repos/cloudflare/security-audit-skill，查證時間 2026-10-22（網頁顯示的星數可能是快取，以 API 為準）
• 當日熱度 +2,979 星：GitHub Trending 頁面（github.com/trending）2026-10-22 抓取
• 背景與實測數字（450 行起家、128 個 repo、單次約抓到一半、context 壓在 25% 以下、SQLite 依 (run_id, repo, stage) 持久化）：Cloudflare 官方部落格 Build your own vulnerability harness（2026-06-18，Dan Jones、Alexandra Godoi、Grant Bourzikas）
• 未實測的部分：本文沒有實際安裝此技能、也沒有對任何 repo 跑過一場稽核（全程以官方原始檔與部落格取材）。因此「跑起來效果如何」屬於官方自述，尚未經本文獨立驗證。