前言¶
做應用安全時，威脅建模往往卡在兩頭：一邊是架構圖和檢查清單過於空泛，寫出來和真實代碼對不上；另一邊是人工翻倉庫太慢，信任邊界、入口面、緩解措施很難一次對齊。安全左移之後，團隊更希望在設計評審、發佈前審查時，就能拿到一份貼着當前倉庫的威脅模型，而不是事後補一份通用模板。
security-threat-model 就是爲此準備的 Agent Skill。它要求 Agent 只在你明確提出威脅建模、濫用路徑枚舉或 AppSec 威脅建模時觸發，基於倉庫證據列出信任邊界、資產、攻擊者能力、濫用路徑與緩解措施，並輸出可審閱的 Markdown 報告。本文按官方 SKILL.md 與參考模板，說明它是什麼、怎麼裝、怎麼用。
這是什麼¶
security-threat-model 來自 OpenAI 的 Agent Skills 精選目錄（openai/skills），定位是「倉庫接地（repository-grounded）」的威脅建模工作流：面向指定倉庫或子路徑，產出偏 AppSec 可用的威脅模型，而不是通用漏洞清單。
Trail of Bits 在其 curated skills 市場中提供了同能力的 Claude Code 插件版本（openai-security-threat-model），說明中寫明：內容源自 OpenAI 精選目錄，並轉換爲 Claude Code 插件格式。這類 Skill 遵循通用的 SKILL.md 格式，在 Codex、Cursor、Claude Code 等支持 Agent Skills 開放標準的工具裏都可以安裝使用。
它要解決的核心問題很具體：把威脅建模從「憑經驗寫檢查表」變成「從代碼與文檔裏抽系統模型 → 標定邊界與資產 → 寫出可優先級排序的濫用路徑 → 給出帶證據的緩解建議」。
核心功能與亮點¶
根據官方 SKILL.md，工作流大致分爲以下幾步。
-
範圍與系統模型
識別主要組件、數據存儲、外部集成與入口；分清運行時行爲與 CI/構建/開發工具、測試與示例；沒有證據的組件、數據流或控制措施不得寫入。 -
信任邊界、資產與入口
把信任邊界寫成組件之間的具體邊（協議、認證、加密、校驗、限流等）；資產覆蓋數據、憑證、模型、配置、算力、審計日誌等；入口包括接口、上傳面、解析器、任務觸發、管理工具、日誌/錯誤出口等。 -
攻擊者能力標定
按真實暴露面與用法描述攻擊者能做什麼，並明確寫出「做不到什麼」，避免把嚴重級別抬得過高。 -
濫用路徑與優先級
威脅寫成攻擊者目標驅動的路徑（如竊取、提權、完整性破壞、拒絕服務），用定性的可能性與影響（low/medium/high）給出優先級，並說明哪些假設會顯著改變排序。 -
與用戶覈對假設
正式報告前，先彙總關鍵假設，並提出 1～3 個針對性問題（部署方式、暴露面、鑑權、數據敏感度、多租戶等）；用戶無法回答時，也要在報告裏保留假設及其對優先級的影響。 -
緩解措施與質量檢查
區分「倉庫裏已有的緩解（需證據）」與「建議新增的緩解」，並落到具體組件、邊界或入口；出稿前確認入口與邊界覆蓋、運行時與 CI 分離、假設與未決問題寫清楚。
報告格式由 references/prompt-template.md 約定，常見章節包括：執行摘要、範圍與假設、系統模型（含 Mermaid 流程圖）、資產表、攻擊者模型、入口面、Top 濫用路徑、威脅模型表（TM-001 等形式）、嚴重度標定、後續人工審查的焦點路徑等。最終 Markdown 文件名約定爲 <倉庫或目錄名>-threat-model.md。
另外還有一份可選參考 references/security-controls-and-assets.md，用來統一資產類別與控制類別的表述，避免每份報告用詞漂移。
安裝與啓用¶
下面按常見工具分別說明。以官方目錄仍可訪問爲前提；OpenAI 的 openai/skills 倉庫 README 已標註 deprecated，並指向新的 Plugins 倉庫，但該精選 Skill 目錄與 SKILL.md 目前仍可直接讀取。若你主要用 Claude Code，也可直接裝 Trail of Bits 的插件轉換版。
Codex¶
精選 Skill 可用內置的 $skill-installer 按名稱安裝：
$skill-installer security-threat-model
也可以用 GitHub 目錄 URL：
$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/security-threat-model
安裝後如未自動發現，重啓 Codex。調用時可用 $security-threat-model，或直接用自然語言說明要對某個倉庫做威脅建模（需匹配 Skill 的觸發描述）。
官方爲該 Skill 提供的默認提示詞（agents/openai.yaml）是：
Create a repository-grounded threat model for this codebase with prioritized abuse paths and mitigations.
Cursor¶
把整個 security-threat-model 目錄放到項目或用戶級 Skills 路徑即可，例如：
mkdir -p .cursor/skills/security-threat-model
# 將 SKILL.md、references/、agents/ 等一併放入該目錄
Cursor 會掃描 .cursor/skills/、.agents/skills/，以及用戶級的 ~/.cursor/skills/、~/.agents/skills/；爲兼容也會讀取 .claude/skills/、.codex/skills/ 等路徑。在 Agent 對話裏輸入 /，搜索 security-threat-model 可顯式調用。
Claude Code（Trail of Bits 插件）¶
Trail of Bits 文檔給出的安裝方式：
/plugin install trailofbits/skills-curated/plugins/openai-security-threat-model
也可以手動把官方 Skill 目錄複製到 ~/.claude/skills/security-threat-model/（個人）或項目內 .claude/skills/security-threat-model/（隨倉庫共享）。
典型用法示例¶
官方強調：僅在你明確要求威脅建模、枚舉威脅/濫用路徑，或做 AppSec 威脅建模時觸發；不要把它當成普通架構總結或代碼審查的默認流程。
一個可直接複用的提示示例如下（按需填入上下文）：
請使用 security-threat-model，對當前倉庫做威脅建模。
範圍：
- 倉庫根目錄：.
- 重點路徑：app/、services/api/
已知上下文（未知的請標成假設）：
- intended_usage：對內 API 服務
- deployment_model：Kubernetes，多副本
- internet_exposure：僅經 API 網關對外
- authn_authz_expectations：OIDC + 服務端 RBAC
- data_sensitivity：含用戶 PII
- out_of_scope：第三方支付 SDK 源碼
請先按 Skill 要求列出關鍵假設並提出澄清問題；
我確認後再輸出最終的 <repo>-threat-model.md。
如果你還沒有倉庫級安全摘要，Skill 會引導先用 references/prompt-template.md 裏的「Repository summary prompt」生成一份偏安全視角的倉庫摘要，再進入威脅建模。輸出側應儘量貼近模板中的章節順序與表格字段（威脅 ID、可能性、影響、優先級、證據路徑等）。
適用場景與注意事項¶
適合這些場景：
- 發佈前或設計評審前，需要一份貼着當前代碼的威脅模型初稿
- 對某個服務/子目錄做聚焦審查，先排出濫用路徑與人工複審焦點文件
- AppSec 與研發協作時，需要統一的報告結構與證據錨點
使用時注意：
- 證據優先：沒有倉庫路徑、符號或配置依據的架構斷言不應當作確定事實。
- 先澄清再定稿：Skill 要求在最終報告前暫停，等你確認部署、暴露面、鑑權等上下文。
- 觸發面刻意收窄：它不會因爲你做了架構討論就自動跑威脅建模，避免上下文被無關安全流程佔用。
- 輸出是輔助材料：報告面向 AppSec 工程師可讀、可複查，不能替代正式滲透測試或合規審計結論。
- 密鑰衛生：模板明確要求遇到 token/密鑰時脫敏，只描述存在與位置，不要把祕密寫進報告。
小結¶
security-threat-model 把威脅建模收成一套可複用的 Agent 工作流：從倉庫抽系統模型，標定信任邊界與資產，寫出帶優先級的濫用路徑，再給出可落到代碼位置的緩解建議，並固定輸出結構。OpenAI 精選目錄提供了原始 Skill；Trail of Bits 則把它納入了自己的 curated 插件市場，方便在 Claude Code 裏一鍵安裝。
官方地址：
https://github.com/openai/skills/tree/main/skills/.curated/security-threat-model
Trail of Bits 插件版：
https://github.com/trailofbits/skills-curated/tree/main/plugins/openai-security-threat-model
