security-planning

安全规划

此技能封装了 Security Planner、Security Reviewer 和 Code Review 使用的持久化安全规划与计划偏差分析功能，包括操作性分类指导、STRIDE 分析模式、标准交叉引用、NIST 控制族参考、安全专用待办事项格式，以及将 Security Planner 基线与当前安全发现相关联的功能。

使用场景

在以下情况下使用此技能：

• 在规划期间，将应用程序组件归类到操作性安全分类中。
• 使用基于 STRIDE 的分析评估威胁；当 raiEnabled 为 true 时，还包括 AI 专用扩展。
• 将分类发现映射到标准参考和控制族，而不重复嵌入冗长的标准表格。
• 推导安全专用待办事项优先级和 RAI 工作项类别，以便移交给 Phase 5。
• 将 Security Planner 基线与调用方提供的当前发现相关联，以识别已验证的控制、控制偏差、剩余计划风险、新引入的威胁以及过时的计划项。
• 根据 YAML/JSON 威胁模型规范生成双输出 TM7 模型和 markdown 报告，用于人工审核的审计工作流。

安全计划偏差分析

当 Security Planner 基线和当前状态安全发现均已存在时，使用偏差分析功能。它仅关联已提供的证据：不会扫描、分析特征、选择安全技能、验证发现、重新评定严重程度、调用其他 Agent，也不会修改源文件、计划、审查结果、待办事项或状态构件。

1. 根据 drift-input-contracts.md 定位并提取基线。
2. 规范化调用方提供的审计、差异或 Code Review 发现，但不将计划模式证据视为仓库状态。
3. 过滤默认排除项，然后仅对 drift-comparison-model.md 支持的结论进行分类。
4. 根据 drift-report-contract.md 生成直接输出、Security Reviewer、Security Planner 或 Code Review 适配结果。
5. 使用 drift-worked-examples.md 查看确定性行为场景和预期的类别抑制规则。

在完整的对话式或持久化偏差输出之前，逐字显示此技能中的 Security Planning CAUTION 块。在规范正文的“当前仓库证据”部分报告以下默认排除项。范围受限的 Code Review 部分可以引用这些块，因为其所属审查已包含 Code Review 免责声明。

默认排除项已生效。 偏差发现不包含规划和 Agent 自定义构件：

• 路径：.copilot-tracking/**、docs/planning/**、docs/adrs/**、.github/agents/**、.github/prompts/**、.github/instructions/**、.github/skills/**
• 文件 glob：*.prompt.md、*.agent.md、*.instructions.md、SKILL.md

如需覆盖，请显式传入 scope=。重叠的用户范围优先，并作为警告报告。

具有写入能力的直接调用方可以在 .copilot-tracking/security-audits/<project-slug>/ 下创建一份序列安全的报告。Security Reviewer 和 Security Planner 在对话中生成结果。Code Review 生成范围受限的部分以及可选的 security_plan_drift 字段。所有目标均保持输入只读，并建议后续操作，但不进行任务分派。

当基线不完整、所需事实尚未解决、证据范围不足以支持相关主张，或输入格式偏差导致无法应用排除项时，应停止生成受影响的结论。将被抑制的类别报告为证据不足，而不是零项发现。如果无法解析任何基线，或没有可用于执行排除规则的发现位置，则应停止整个关联分析。

TM7 生成工作流

当用户请求 TM7 威胁模型时，运行时可以根据同一份规范生成 .tm7 文件和对应的 Markdown 报告。生成器支持 pre-populated-comprehensive 和 diagram-only-defer-to-tmt 模式，也可以使用 --update 更新现有模型。使用 generate_tm7.py 和 generate_markdown.py 入口，并通过 --template 选择配置文件。

.tm7 输出会映射 Microsoft Threat Modeling Tool 的真实 SerializableModelData DataContract，并能通过该工具自身的 DataContractSerializer 正常反序列化。验证会使用该工具自身的程序集，由 scripts/Deserialize-Tm7.ps1 完成；pytest 测试套件会在安装了该工具时运行此脚本，否则会正常跳过。经过验证的契约见 references/tm7-generation.md。

原生 TM7 视觉反馈工作流

此技能还支持一种可选启用、仅限 Windows 本地的原生 Microsoft Threat Modeling Tool UI 反馈循环。此功能默认关闭。未提供反馈标志时，生成器和标准验证器会保持现有的可移植行为。只有在运行 validate_tm7_with_tmt.py 时同时指定 --feedback-loop、--spec 和 --overlay-output，才会启用原生反馈；可选参数 --overlay-input、--max-iterations 和 --require-feedback-evidence 可进一步细化执行约定。

此工作流需要 Microsoft Threat Modeling Tool 7.3.51110.1、Windows 桌面会话和 UI Automation 访问权限。循环限定为一次基线运行，最多再进行三次优化迭代；默认执行一次基线运行和一次优化迭代。单次运行期间，鼠标和键盘会在基线运行及每次优化迭代中持续由程序控制；只有出现释放通知时，控制权才会交还。重放修正后的覆盖层属于一次新的运行，也意味着再次接管。退出代码、停止原因和发现失败规则均在生成参考文档中定义。

该测试框架会控制 TMT 窗口，并可能打开、关闭和重新打开应用以验证保存和重新打开功能。自动化开始前，它会发出开始通知；在基线运行和每个优化候选方案期间会发送进度更新；循环完成或中止时会发出释放通知，让操作人员知道何时恢复控制权。这些仅为通知；测试框架不会等待操作人员确认。一次运行期间面向 Agent 的锁定和释放义务由 tm7-generation-workflow.instructions.md 规定。

该循环会在指定的证据目录下为每次运行记录一个证据包，其中包含每次迭代的屏幕截图、UI Automation 快照、摘要和候选模型。如果运行至少捕获了一个界面，并且通过了自动化门槛或因布局迭代耗尽而停止，还会在证据包根目录生成 agent-review-request.json。覆盖层载荷会保持 approval_state: pending 状态；没有任何运行时路径或标志会自动将其提升为 approved，也不会重写规范基线。

评分会将确定性的几何门槛与提示性的屏幕截图启发式规则分开。屏幕截图启发式规则不是语义审批信号。

以下 Windows 原生示例使用该技能锁定的 Windows 依赖组：

uv run --project "<security-planning-skill-root>" --group windows \
  python "<security-planning-skill-root>/scripts/validate_tm7_with_tmt.py" model.tm7 \
  --evidence-dir ./artifacts/feedback \
  --feedback-loop \
  --spec ./specs/model.yaml \
  --overlay-output ./artifacts/feedback/overlay.json \
  --max-iterations 3 \
  --require-feedback-evidence

运行命令前，请根据已加载的技能位置确定 <security-planning-skill-root>。

覆盖层契约采用版本控制且具有确定性。它通过命名规则集合携带布局意图，并且只有在完整指纹区块匹配时才有效，因此，过时的覆盖层会被拒绝，而不会被重放到已更改的模型上。

完整 CLI 参数、退出代码、停止原因、几何阈值、证据包布局、覆盖层指纹契约，以及涵盖前提条件、中止、恢复和回滚的操作手册，请参阅 references/tm7-generation.md。

Agent 辅助视觉审查

有些布局缺陷不会体现在任何指标中。TM7 不会持久化连接器标签的几何信息，而 UI Automation 不会公开标签元素，因此标签重叠、标签文本难以辨认和视觉拥挤都不会被确定性门禁检测到。读取渲染后截图的 Agent 可以发现这些问题，并将修正写入测试框架发布的覆盖层。

此审查是每次反馈循环运行的默认步骤，而非可选附加项。只要一次运行至少捕获了一个界面，并且自动化门禁全部通过或因布局耗尽而停止，就会在证据根目录生成 agent-review-request.json，其中按界面提供截图和 UI Automation 路径、节点与区域矩形、连接器控制点、模型坐标中的预测标签矩形，以及坐标转换常量和端口约定。Agent 根据此载荷进行审查，而无需手动解析 UI Automation 树。automated-ready-pending-human 表示自动化门禁已通过，结果正在等待审查；这并不代表已获批准。补救措施仍停留在文档说明层面，尚未通过真实缺陷的端到端演示验证。

在成功路径中，已发布的覆盖层会涵盖所有捕获的界面，因此可以针对其中任意界面编写修正。如果运行未找到自动化修正，该覆盖层就是种子结构，带有 overlay-seed- 标识符和空规则集合。因布局耗尽而停止时，也会发布相同的种子结构；因正确性或环境问题而停止时，则不会发布任何内容。

有关协议、请求载荷、接受的规则字段、坐标转换，以及限制 Agent 编写的覆盖层的约束，请参阅 references/tm7-generation.md。

注意

免责声明： 此 Agent 仅为辅助工具，不提供法律、监管或合规建议，也不能替代专业安全审查委员会、渗透测试团队、合规审计人员、法律顾问或其他具备相应资质的人工审查人员。其输出包括建议的操作和注意事项，旨在支持用户自行开展内部安全审查并作出决策。使用此工具生成的所有安全计划、威胁模型、安全模型和缓解建议，都必须在使用前由适当的安全与合规审查人员独立审查和验证。此工具的输出不构成安全批准、合规认证或监管签署。

有关作者身份确认、原生反馈循环的操作安全，以及布局覆盖层晋级的人工参与流程约定，由 tm7-generation-workflow.instructions.md 负责。本技能仅负责具体机制。

技能布局

加载与所需阶段或主题相对应的参考文件。

参考资料	主题
references/00-index.md	导航目录和汇总归属信息
references/operational-buckets.md	运营分类定义、GS 叠加层和分类指南
references/stride-model.md	STRIDE 方法、AI 扩展、风险矩阵和数据流分析
references/standards-cross-reference.md	分类与标准映射表及组件映射输出格式
references/nist-control-families.md	NIST 800-53 优先级层级和 NIST AI RMF 子类别映射
references/backlog-formats.md	安全专属优先级排序和 RAI 工作项类别
references/data-classification.md	可公开的数据分类法、层级／类别／保留期限及架构映射
references/threat-model-review.md	威胁模型完整性检查清单、PASS/INCOMPLETE 判定和差距列表
references/drift-input-contracts.md	Security Planner 基线提取、规范化的当前发现格式、证据范围和漂移处理
references/drift-comparison-model.md	排除项、证据前置条件、五种计划漂移类别、匹配顺序和仅提供建议的交接
references/drift-report-contract.md	规范正文以及面向直接目标、Security Reviewer、Security Planner 和 Code Review 的适配
references/drift-worked-examples.md	合成的完整、不完整、格式错误、限定差异范围、排除项和调用方回归行为场景
references/tm7-generation.md	TM7 输入架构、双输出生成契约、配置映射、输出契约、原生反馈循环、叠加层和指纹契约，以及操作员运行手册

捆绑的可执行文件和数据资源：

资源	用途
scripts/generate_tm7.py	运行此脚本，根据威胁模型规范生成 .tm7 文件
scripts/generate_markdown.py	运行此脚本，将同一规范渲染为 Markdown 报告
scripts/generate_tb7.py	运行此脚本，生成模板文件
scripts/validate_tm7_with_tmt.py	运行此脚本，进行原生 Windows TMT 验证和可选的反馈循环
scripts/Deserialize-Tm7.ps1	运行此脚本，检查与工具自身程序集的往返保真度
assets/schemas/tm7-layout-overlay.schema.json	查看布局叠加层架构
assets/schemas/tm7-agent-review-request.schema.json	查看 Agent 视觉审查请求架构
assets/schemas/tm7-visual-feedback-manifest.schema.json	查看证据清单架构
templates/threat-model-spec-example.yaml	复制此文件，作为新规范的起点

该技能提供分类体系和完整性检查清单的公开默认配置。组织特有的内部详情，例如内部数据类型分类体系、内部身份验证服务名称和内部审查关卡步骤，通过 state.overlayConfigPath 引用的私有配置叠加层提供，绝不会嵌入公开技能中。

致谢

此技能中的持久参考内容按参考文件组织，并在 references/00-index.md 中汇总。汇总的致谢和委派说明请参阅该索引。