前言¶
做应用安全时，威胁建模往往卡在两头：一边是架构图和检查清单过于空泛，写出来和真实代码对不上；另一边是人工翻仓库太慢，信任边界、入口面、缓解措施很难一次对齐。安全左移之后，团队更希望在设计评审、发布前审查时，就能拿到一份贴着当前仓库的威胁模型，而不是事后补一份通用模板。
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
