前言¶
第三方依賴是多數應用的真實攻擊面：直接依賴上的已知漏洞、鎖文件裏解析出的傳遞依賴、上游倉庫歸檔或維護停滯、npm 發佈者集中度過高、安裝階段執行的腳本，都會在「還沒讀業務代碼」之前就構成風險。手工翻 registry、用 gh 估維護者人數或下載量，容易把不同數據源混成一條結論——官方文檔裏就提到，重建本 Skill 之前曾出現「GitHub 貢獻者很多、npm ACL 卻只有一人」「gh 顯示零下載、registry 側卻是每週上億次」這類偏差。
下面介紹 Trail of Bits 在 skills 插件市場裏提供的 supply-chain-risk-auditor：針對項目清單與鎖文件生成供應鏈風險報告，由確定性腳本採集數據，由 Agent 做腳本不自動化的判斷與敘述。
這是什麼¶
supply-chain-risk-auditor 是 Claude Code / Codex 等環境中可加載的 Agent Skill（allowed-tools：Read、Write、Bash、Glob、Grep）。它審計項目的直接依賴（npm、PyPI、Go），並對鎖文件解析出的完整依賴樹做 advisory 掃描；覆蓋版本匹配的漏洞公告、上游廢棄或歸檔、npm 發佈者集中度、安裝時腳本執行等維度。
出品方爲 Trail of Bits，Skill 源碼與說明位於：
https://github.com/trailofbits/skills/tree/main/plugins/supply-chain-risk-auditor/skills/supply-chain-risk-auditor
本 Skill 不安裝、不構建、不執行目標項目，也不讀取依賴包源碼；只基於 manifest、lockfile 以及 registry、advisory、倉庫元數據工作。
核心功能¶
腳本採集，Agent 裁決¶
報告中的數字應來自採集腳本，而非記憶、gh 隨手查詢或網頁搜索。官方明確要求：不要自行估算維護者數量、下載量、陳舊程度或 CVE 歷史——運行 collector，並引用其測量結果。
腳本遵循兩條規則：
- 拿不到的數據不能當作風險證據。 每條準則的結果是：已評估爲乾淨、已評估爲需關注、或不可評估（附原因）。
- 沒有測量結果不能給出「全綠」結論。 若一次運行什麼都沒測到，進程以非零退出，而不是打印一份「零發現」的報告。
支持的生態與清單¶
目標目錄需存在下列之一，否則應說明並停止，不要用手工方式審計未支持的生態：
package.json（npm）pyproject.toml、requirements*.txt（PyPI）go.mod（Go）
用於精確版本與傳遞依賴掃描的鎖文件包括：package-lock.json / npm-shrinkwrap.json、uv.lock、Go 1.17+ 的 go.mod。若存在 yarn.lock、pnpm-lock.yaml、poetry.lock，報告會說明未讀取這些文件，版本可能回退到 pin 或最新 release 的聲明方式——二者在報告裏會分開標註。
報告可讀性約定¶
- Unassessable 不等於有風險（例如 PyPI 無維護者 ACL、Go 無統一 registry 時，部分行只是「無法得知」）。
- 覆蓋範圍表限定所有結論。「無 advisory」指「在已評估範圍內無」，需先看 assessed 數量。
- 數字照抄報告原文，不要重算、四捨五入或潤色。
- 某依賴在 findings 裏未出現，只表示未在本 Skill 的準則下被標出，不是背書。
安裝與啓用¶
Skill 隨 Trail of Bits 的 skills 市場插件分發；插件目錄爲 plugins/supply-chain-risk-auditor/。
Claude Code：
/plugin marketplace add trailofbits/skills
/plugin menu
在菜單中選擇並安裝對應插件（含 supply-chain-risk-auditor）。
Codex：
codex plugin marketplace add trailofbits/skills
codex plugin list
codex plugin add <plugin-name>@trailofbits
本地開發時，可在倉庫父目錄執行 /plugins marketplace add ./skills（路徑以官方 README 爲準）。
Cursor 側若通過兼容 Claude 插件市場的機制加載同一市場，步驟以當前產品文檔爲準；本文僅收錄上述已出現在官方倉庫 README 中的命令。
典型用法¶
1、確認目標與 GitHub 認證¶
- 確認待審計目錄含有支持的 manifest（見上文）。
- 執行
gh auth status。未認證的 GitHub API 約 60 次/小時，認證後約 5000 次/小時；採集器對每個依賴會發起多次請求。未認證時，與倉庫相關的準則可能大量返回 unassessable，應在交付物中說明，而不是靜默忽略。
2、採集並渲染報告¶
輸出建議放在被審計倉庫之外的目錄（除非用戶明確要求否則）：
uv run {baseDir}/scripts/collect.py <project-dir> --json <out-dir>/findings.json
uv run {baseDir}/scripts/render.py <out-dir>/findings.json --out <out-dir>/report.md
{baseDir} 爲 Skill 安裝目錄下的技能根路徑。約 50 個直接依賴時，完整採集可能需要數分鐘（每個依賴多次 HTTP；Go 模塊多會更慢；無 gh 認證會更慢）。
若 collect.py 以非零退出，表示拒絕生成報告——應原樣轉述其錯誤信息，不要擅自重試或繞過。
3、閱讀交付物並補充判斷¶
report.md：面向讀者的主報告（事實由腳本渲染）。findings.json：每條結論背後的結構化數據，便於引用。
Agent 在腳本結果之外、且明確區分「測量」與「判斷」地補充：
- 針對讀者的短敘述：優先處理項及理由。
- Advisory 對應的升級路徑（補丁級還是主版本跳躍）。
- 對廢棄/歸檔依賴的替代候選（須在 registry 覈實存在，並標明爲判斷而非測量）。
- 對 flagged 的安裝腳本：本項目是否可採用
npm ci --ignore-scripts等策略。
補充文字宜採用安全報告體：陳述發現、依據數據、建議動作；避免第一/第二人稱、感嘆號、主觀強化詞；過去時描述審計行爲，現在時描述依賴現狀，將來時描述處置後果。
適用場景與注意¶
適合：
- 接安全評估或代碼審計前，快速摸清依賴樹上的公告與元數據風險。
- 用戶明確要求「審計依賴」「評估供應鏈/第三方包風險」「在 engagement 前審查依賴樹」時觸發本 Skill（與官方
description一致）。
不適合或超出範圍：
- 許可證合規審計。
- 掃描項目自有源碼中的漏洞或密鑰（本 Skill 不讀依賴源碼）。
- 判斷項目能否成功安裝或構建；損壞的安裝與 import 時錯誤不在範圍內。
- npm / PyPI / Go 以外的生態：應說明不支持，勿即興手工審計。
常見誤區（官方明確反對）：
- 用
gh維護者數替代 registry 發佈權限視角。 - 忽視覆蓋表，把「零 finding」說成「依賴安全」。
- 刪掉 unassessable 行，使部分覆蓋看起來像全面通過。
- 把「按 latest-release 檢查的範圍」與「鎖文件解析版本」混爲一談。
結尾¶
supply-chain-risk-auditor 把供應鏈審計裏易出錯的「數字採集」交給 collect.py / render.py，把優先級、升級與替代方案留給 Agent，並在報告邊界上區分 assessed 與 unassessable，減少誤報與漏報。安裝與 Skill 說明見 Trail of Bits 官方倉庫：
https://github.com/trailofbits/skills/tree/main/plugins/supply-chain-risk-auditor/skills/supply-chain-risk-auditor
