security-threat-model 技能实战：基于仓库证据的 AppSec 级威胁建模全流程指南-港品优选

security-threat-model 技能实战：基于仓库证据的 AppSec 级威胁建模全流程指南

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本指南围绕 Codex 技能目录（Skills Catalog）中的security-threat-model技能展开，系统讲解如何基于仓库真实代码证据，产出可供 AppSec 工程师直接使用的威胁模型：从收集输入、提取系统模型、划定信任边界与资产、枚举滥用路径（abuse paths），到风险定级、用户澄清、缓解建议与最终报告格式。读完本文，你将掌握一套可复制的"仓库扎根型"（repo-grounded）威胁建模工作流，并理解其配套 Prompt 模板与输出契约的每个细节。

该技能位于 skills/.curated/security-threat-model/SKILL.md，其核心主张是：交付具体到某个仓库或项目路径、而非泛化检查清单的、可落地的 AppSec 级威胁模型。所有架构结论必须以仓库中的证据为锚点，假设必须显式保留，并优先关注真实攻击者目标与具体影响。

技能定位与触发条件

security-threat-model是一个供 Codex 等 Agent 使用的技能（Skill），其元数据声明在 SKILL.md 的 frontmatter 中：

name:security-threat-model
description: 基于仓库的威胁建模——枚举信任边界、资产、攻击者能力、滥用路径与缓解措施，并输出一份简洁的 Markdown 威胁模型。

触发条件非常明确：仅当用户显式要求对某个代码库或路径进行威胁建模、枚举威胁/滥用路径，或执行 AppSec 威胁建模时触发；不得为一般的架构总结、代码评审或非安全设计工作而触发。这条纪律确保了技能不会被误用为通用代码分析工具。

技能还提供了 Agent 界面配置 agents/openai.yaml，其中声明了：

展示名称：Security Threat Model
简短描述：Repo-grounded threat modeling and abuse-path analysis（基于仓库的威胁建模与滥用路径分析）
默认提示词："Create a repository-grounded threat model for this codebase with prioritized abuse paths and mitigations."（为该代码库创建基于仓库的威胁模型，包含按优先级排序的滥用路径与缓解措施）

这意味着在 Codex 中，Agent 可以按名称发现并调用该技能，一条默认提示词即可启动整个威胁建模流程。

快速开始：收集或推断输入

技能的第一步是准备输入，主要包括四类信息：

仓库根路径与所有范围内的路径（in-scope paths）；
预期用途、部署模型、互联网暴露面、认证/授权预期（如已知）；
任何已有的仓库摘要或架构规格文档；
使用references/prompt-template.md中提供的提示词生成仓库摘要，并逐字遵循其中的输出契约。

输入质量直接决定威胁模型的质量——尤其是"预期用途"与"暴露面"这类服务上下文（service context），它们影响攻击者模型和风险定级。若上下文缺失，技能要求将其显式标记为假设，而不是静默猜测。

配套的 references/prompt-template.md 提供了两段提示词来支撑这一环节：

仓库摘要提示词（Repository summary prompt）要求以"帮助后续安全工程师快速理解系统、足以构建初步威胁模型并调查潜在安全假设"为目标，产出安全导向的仓库摘要，覆盖：

项目概览：主要语言、框架、构建系统、核心目的、高层架构、主要组件及其交互方式；
安全态势与入口点：用户入口点、信任边界、现有安全层（认证、授权、校验、沙箱、隔离、权限边界），以及"系统要保持安全就必须成立的安全关键组件与假设"。

摘要还需按项目类型适配分析重点：

Web 应用：请求如何进入、用户数据如何被解析、路由、认证与存储；
命令行工具：支持的输入（参数、文件、环境变量、stdin）及其处理方式；
网络守护进程：暴露的端口、支持的协议、消息格式与请求处理路径；
操作系统或底层组件：可能通向本地提权（LPE）或远程代码执行（RCE）的常见漏洞类别（如内存破坏、逻辑缺陷）。

工具层面，提示词建议：如果 Ripgrep（rg）可用，就用它探索代码库；使用grep/rg时始终携带-I标志以避免搜索二进制文件。

八步工作流：从系统模型到最终报告

SKILL.md 定义了八个步骤，构成完整闭环：

1) 界定范围并提取系统模型（Scope and extract the system model）

从仓库摘要中识别主要组件、数据存储与外部集成；
判断系统的运行形态（服务器 / CLI / 库 / worker）及其入口点；
将运行时行为与 CI/构建/开发工具链、测试与示例严格分离；
把范围内的位置映射到对应组件，并显式排除范围外内容；
没有证据，就不声称存在某个组件、流程或控制措施。

2) 推导信任边界、资产与入口点（Derive boundaries, assets, and entry points）

将信任边界枚举为组件之间具体的边（edge），并注明协议、认证、加密、校验与速率限制；
列出驱动风险的资产（数据、凭据、模型、配置、计算资源、审计日志）；
识别入口点：端点、上传面、解析器/解码器、任务触发、管理工具、日志/错误汇聚点。

3) 校准资产与攻击者能力（Calibrate assets and attacker capabilities）

列出驱动风险的资产（凭据、PII、完整性关键状态、可用性关键组件、构建产物）；
基于暴露面与预期用途，描述现实可行的攻击者能力；
显式注明攻击者不具备的能力（non-capabilities），避免人为抬高严重性。

4) 将威胁枚举为滥用路径（Enumerate threats as abuse paths）

优先采用能映射到资产与边界的攻击者目标：数据外泄、提权、完整性破坏、拒绝服务；
对每个威胁分类并关联到受影响的资产；
威胁数量保持"小而精"，追求高质量而非数量堆砌。

5) 用显式的可能性与影响推理来定优先级（Prioritize with explicit likelihood and impact reasoning）

采用定性的可能性与影响（低/中/高），并附简短论证；
用"可能性 × 影响"计算总体优先级（critical/high/medium/low），并根据已有控制措施进行调整；
明确指出哪些假设对排序影响最大。

6) 与用户校验服务上下文与假设（Validate service context and assumptions）

汇总对威胁排序或范围有实质影响的关键假设，请用户确认或纠正；
提出1～3 个针对性问题，以补齐缺失上下文（服务所有者与环境、规模/用户数、部署模型、认证/授权、互联网暴露面、数据敏感度、多租户）；
暂停并等待用户反馈，再产出最终报告；
若用户拒绝或无法回答，则说明哪些假设仍然保留，以及它们如何影响优先级。

7) 推荐缓解措施与聚焦路径（Recommend mitigations and focus paths）

区分已有缓解措施（附证据）与推荐缓解措施；
将缓解措施绑定到具体位置（组件、边界或入口点）与控制类型（授权检查、输入校验、模式强制、沙箱、速率限制、密钥隔离、审计日志）；
偏好具体的实现提示而非泛泛建议——例如"在网关处对上传载荷强制执行 schema"优于"校验输入"；
建议要基于已确认的用户上下文；若假设仍未解决，将建议标记为条件性（conditional）。

8) 定稿前运行质量检查（Run a quality check before finalizing）

确认所有发现的入口点都已覆盖；
确认每个信任边界都在威胁中有所体现；
确认运行时与 CI/开发环境的分离；
确认用户澄清（或明确的不回应）已反映在报告中；
确认假设与开放问题都已显式列出；
确认报告格式与 references/prompt-template.md 定义的必需输出格式高度一致；
将最终 Markdown写入名为<repo-or-dir-name>-threat-model.md的文件（使用仓库根目录的 basename；若被要求建模某个子路径，则用该范围内目录的 basename）。

风险定级参考：illustrative，非穷举

SKILL.md 给出了定级的方向性指引（明确标注为"示例性、非穷举"）：

High（高）：预认证 RCE、认证绕过、跨租户访问、敏感数据外泄、密钥或令牌窃取、模型或配置完整性受损、沙箱逃逸；
Medium（中）：对关键组件的针对性 DoS、部分数据暴露、可度量影响的速率限制绕过、影响检测能力的日志/指标投毒；
Low（低）：低敏感度信息泄露、易缓解的嘈杂 DoS、需要极不可能前提条件的问题。

这套参考的价值在于统一不同团队、不同报告之间的定级口径，但最终定级必须结合具体仓库的资产与暴露面做校准（对应输出契约中的 "Criticality calibration" 小节）。

输出契约：Prompt 模板与必需报告结构

references/prompt-template.md 是技能的核心配套，定义了系统提示词、用户任务提示词与精确的最终报告格式，是整个流程"可复现、输出一致"的保证。

系统提示词（System prompt）：证据与纪律

系统提示词把模型设定为"面向其他 AppSec 工程师的资深应用安全工程师"，核心规则包括：

证据与锚定：不得凭空发明组件、数据存储、端点、流程或控制；每条架构主张必须至少有一个"证据锚点"（Evidence anchor），引用仓库路径（尽量附带符号名、配置键或简短引用片段）；信息缺失时显式陈述假设，并列出验证假设所需的开放问题；
安全卫生：绝不输出秘密。若遇到令牌/密钥/密码，一律脱敏，只描述其存在位置；
建模方法：用数据流与信任边界建模；枚举威胁并产出攻击目标与滥用路径；用显式的可能性/影响推理定优先级（定性低/中/高可接受）；
范围纪律：严格分离生产/运行时行为 vs CI/构建/开发工具链 vs 测试/示例；严格分离攻击者可控输入 vs 运维者可控输入 vs 开发者可控输入；若某漏洞类别所需的攻击者控制在本仓库真实使用中大概率不存在，应明确说明并降低严重性；
沟通质量：面向 AppSec 工程师写作——简洁但具体，使用精确术语，包含缓解措施与残余风险；避免大段复述 README/规格文档，应总结并指向证据；
图表要求：产出单个紧凑的 Mermaid 流程图，展示主要组件与信任边界，并强制使用保守语法子集：
- 仅用flowchart TD或flowchart LR，且只使用-->箭头；
- 使用简单的节点 ID（仅字母/数字/下划线）与带引号的标签（如A["Label"]），避免A(Label)形状语法；
- 不使用 Mermaid 的title行或style指令；
- 边标签只用纯单词/空格，通过-->|label|表达；避免{}、[]、()或引号（必要时干脆去掉标签）；
- 节点标签保持简短可读：不包含文件路径、URL 或 socket 路径（这些放到图外的正文中）；
- 用 Markdown fenced 块包裹图：

用户任务提示词：结构化的上下文槽位

用户提示词模板以占位符形式定义了输入槽位：

# Inputs Context (fill as available; otherwise infer and mark assumptions): - intended_usage: {intended_usage} - deployment_model: {deployment_model} - data_sensitivity: {data_sensitivity} - internet_exposure: {internet_exposure} - authn_authz_expectations: {authn_authz_expectations} - out_of_scope: {out_of_scope} Provided summaries (may be incomplete): - repository_summary: {repository_summary} In-scope code locations (if known): - in_scope_paths: {in_scope_paths}

随后任务主体要求"构建一个以仓库为中心的威胁模型，帮助 AppSec 工程师理解最重要的安全风险以及人工评审应聚焦何处"，并规定必须遵循的 10 步过程：

仓库发现（证据收集）：识别仓库形态（语言/框架、运行方式、入口点、构建产物）；按证据类别搜索安全相关面与控制，包括：网络监听/路由/端点、RPC 处理器、消息消费者；认证、会话/令牌处理、授权检查、RBAC/ACL 逻辑；解析/序列化/反序列化（JSON/YAML/XML/protobuf）、模板渲染、eval/动态代码；文件上传/读取路径、归档解压、图片/文档解析；数据库/队列/缓存客户端与查询构造；密钥/配置加载、环境变量、密钥管理；可 SSRF 的 HTTP 客户端、webhook、URL 抓取器；沙箱/隔离、权限边界、子进程执行；日志/审计与错误处理路径；CI/构建/发布：流水线、依赖管理、产物发布。
系统模型：汇总主要组件；枚举数据流与信任边界（每条边界注明源→目的、跨越的数据类型、通道/协议、安全保证与校验）；提供紧凑的 Mermaid 图。
资产与安全目标：列出资产（数据、凭据、完整性关键状态、可用性关键组件、构建产物），并说明每个资产为何重要（机密性/完整性/可用性、合规、用户伤害）。
攻击者模型：能力（基于预期用途与暴露面的现实远程攻击者假设）与非能力（除非显式纳入范围，否则攻击者无法做到的事）。
威胁枚举：将威胁写成关联到入口点、信任边界、特权组件的攻击者故事；优先多步滥用路径而非单行泛化威胁。
风险优先级：每个威胁给出可能性（低/中/高，1～2 句论证）、影响（低/中/高，1～2 句论证）、总体优先级（critical/high/medium/low，基于可能性 × 影响并考虑已有控制调整）；显式说明哪些假设对风险影响最大。
与用户校验假设与服务上下文（最终报告前必须）：汇总关键假设；问 1～3 个针对性问题；暂停等待反馈；用户无法回答则以显式假设继续，并把条件性结论标记出来。
缓解与建议：对每个高/严重威胁给出：已有缓解（附证据锚点）、缺口/弱点、推荐缓解（代码/配置/流程）、检测/监控思路（日志、指标、告警）。
人工安全评审聚焦路径：输出2～30 个仓库相对路径（文件或目录），每个路径配一句与威胁模型关联的理由。
质量检查：提供简短清单，确认覆盖了：发现的所有入口点、每个信任边界至少在威胁中出现一次、运行时与 CI/开发分离、用户澄清（或明确不回应）、假设与开放问题。

必需输出格式（精确）

模板要求：在产出最终 Markdown 报告之前，先做一次假设校验的 check-in——用 3～6 条列出关键假设，提出 1～3 个针对性上下文问题，等待用户回复后再用澄清后的上下文产出最终报告。

最终报告必须按以下顺序、以下小节组织：

## Executive summary（执行摘要）：一段话概括顶级风险主题与最高风险区域；
## Scope and assumptions（范围与假设）：范围内路径、范围外项、显式假设；以及会实质改变风险排序的开放问题清单；
## System model（系统模型）：### Primary components、### Data flows and trust boundaries（用箭头式 bullet 序列表示系统，如Internet → API Server、User Input → Application Logic；每条边界记录：跨边界的主要数据类型、通信通道/协议、安全保证（认证、来源检查、加密、速率限制）、执行的输入校验/规范化/schema 强制）；#### Diagram（单个紧凑 Mermaid 图，flowchart TD/LR，仅-->，避免title/style，节点标签简短无路径/URL，边标签仅纯单词）；
## Assets and security objectives（资产与安全目标）：表格列Asset | Why it matters | Security objective (C/I/A)；
## Attacker model（攻击者模型）：### Capabilities与### Non-capabilities；
## Entry points and attack surfaces（入口点与攻击面）：表格列Surface | How reached | Trust boundary | Notes | Evidence (repo path / symbol)；
## Top abuse paths（顶级滥用路径）：5～10 条简短滥用路径，每条为编号步骤序列（攻击者目标 → 步骤 → 影响）；
## Threat model table（威胁模型表）：Markdown 表格，列：Threat ID | Threat source | Prerequisites | Threat action | Impact | Impacted assets | Existing controls (evidence) | Gaps | Recommended mitigations | Detection ideas | Likelihood | Impact severity | Priority；规则：Threat ID 稳定且格式化为TM-001、TM-002…；Priority 只能是 critical/high/medium/low；Prerequisites 控制在 1～2 句；推荐缓解保持具体；
## Criticality calibration（严重性校准）：定义对本仓库与上下文而言什么算 critical/high/medium/low，每级给出 2～3 个贴合该仓库资产与暴露面的示例；
## Focus paths for security review（安全评审聚焦路径）：表格列Path | Why it matters | Related Threat IDs；
## Notes on use（使用说明）：填充已知上下文但允许模型推断并标记假设；每项主要主张附 1～2 个仓库路径锚点，不要倾倒所有匹配结果。

这套输出契约的价值在于：任何一次威胁建模运行，无论由哪个团队或哪次会话触发，都会产出结构一致、可对比、可追踪的报告，而"证据锚点"与"假设显式化"两条规则则保证了报告的事实基础。

配套清单：安全控制与资产分类

references/security-controls-and-assets.md 提供了一份轻量级清单，用于跨团队保持输出一致性，并强调"优先具体、系统相关的条目，而非泛化文本"。

资产分类（只挑选适用的）：

用户数据（PII、内容、上传物）
认证产物（密码、令牌、会话、Cookie）
授权状态（角色、策略、ACL）
秘密与密钥（API 密钥、签名密钥、加密密钥）
配置与功能开关（feature flags）
模型与权重（若为 ML 系统）
源代码与构建产物
审计日志与遥测
可用性关键资源（队列、缓存、速率限制、计算预算）
租户隔离边界与元数据

安全控制分类：

身份与访问：认证、授权、会话处理、mTLS、密钥轮换；
输入防护：schema 校验、解析加固、上传扫描、沙箱；
网络防护：TLS、网络策略、WAF、速率限制、DoS 控制；
数据保护：静态/传输中加密、令牌化、脱敏；
隔离：进程沙箱、容器边界、租户隔离、seccomp；
可观测性：审计日志、告警、异常检测、防篡改；
供应链：依赖锁定、SBOM、来源证明（provenance）、签名；
变更控制：CI 检查、部署审批、配置护栏。

缓解措施的措辞模式（可复用的表述模板）：

"Enforce schema at<boundary>for<payload>before<component>."（在<边界>处对<载荷>强制执行 schema，再进入<组件>。）
"Require authZ check for<action>on<resource>in<service>."（在<服务>中对<资源>的<动作>要求授权检查。）
"Isolate<parser/component>in a sandbox with<resource limits>."（将<解析器/组件>隔离在带<资源限制>的沙箱中。）
"Rate limit<endpoint>by<key>and apply burst caps."（按<键>对<端点>限速并应用突发上限。）
"Encrypt<data>at rest using<key management>and rotate<keys>."（使用<密钥管理>对<数据>静态加密并轮换<密钥>。）

这些模式与 SKILL.md 第 7 步"偏好具体实现提示"的原则一脉相承，帮助把泛化建议改写成可直接落地到具体组件/边界的行动项。

实践要点与注意事项

结合上述全部内容，在 Codex 中使用security-threat-model技能时，值得记住以下几点：

证据优先，拒绝编造：任何组件、端点、控制措施都必须能在仓库中找到对应路径作为锚点；找不到就写成假设并附开放问题。这是该技能区别于传统安全清单的核心。
服务上下文决定一切：同一个仓库，部署为内网服务与公网服务、有无认证、是否多租户，其攻击者模型与定级完全不同。因此第 6 步的"暂停并等待用户反馈"不是可选项，而是流程的强制环节。
运行时与开发工具链分离：CI 流水线中的漏洞与生产运行时中的漏洞，暴露面与影响完全不同，报告必须分开呈现。
数量服从质量：威胁以"小但精"为原则，滥用路径优先采用多步序列，而不是罗列几十条单行威胁。
输出文件命名：最终报告写入<repo-or-dir-name>-threat-model.md，便于按仓库持久保存与检索。
Mermaid 语法收敛：为了确保图表在任何渲染环境下都能干净渲染，只使用模板允许的保守子集——这正是"可渲染优先"工程纪律的体现。

延伸阅读

技能主文档：skills/.curated/security-threat-model/SKILL.md
输出契约与完整 Prompt 模板：skills/.curated/security-threat-model/references/prompt-template.md
可选的控制/资产清单：skills/.curated/security-threat-model/references/security-controls-and-assets.md
Agent 界面配置：skills/.curated/security-threat-model/agents/openai.yaml

在 Codex 中安装该技能后（例如通过$skill-installer security-threat-model），即可用一句话触发完整流程："Create a repository-grounded threat model for this codebase with prioritized abuse paths and mitigations."技能会自行读取仓库、提取系统模型、在关键节点向你确认服务上下文，并最终产出一份符合统一输出契约、证据可追溯的威胁模型 Markdown 报告。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析