改进威胁模型

这页说明 threat model 是什么，以及编辑它如何改善 Codex Security 的 suggestions。

在 Codex Security 中，threat model 不是安全团队写给审计报告看的长文档，而是扫描时使用的项目安全上下文。它告诉系统：这个仓库怎么工作、外部输入从哪里进来、信任边界在哪里、哪些资产最敏感、团队希望优先检查哪些风险。

flowchart LR
    Code["📦 仓库代码"]
    Auto["🤖 自动生成 threat model<br/>（结构层）"]
    Human["✏️ 人工补业务语义<br/>入口 / 边界 / 优先级"]
    TM["📜 完整 threat model"]
    Scan["🔍 后续扫描"]
    Findings["🎯 排序与 prioritization"]

    Code --> Auto --> Human --> TM --> Scan --> Findings
    Findings -.->|偏离重点| Human

threat model 是什么

threat model 是一段简短 security summary，说明你的 repository 如何工作。

在 Codex Security 中，你会把它作为 project overview 编辑；system 会把它作为未来 scans、prioritization 和 review 的 scan context。

Codex Security 会先根据 code 创建 first draft。

如果 findings 看起来不准，threat model 是第一个应该编辑的地方。

一个有用的 threat model 会指出：

• entry points 和 untrusted inputs。
• trust boundaries 和 auth assumptions。
• sensitive data paths 或 privileged actions。
• team 希望优先 review 的 areas。

示例：

Public API for account changes. Accepts JSON requests and file uploads. Uses an internal auth service for identity checks and writes billing changes through an internal service. Focus review on auth checks, upload parsing, and service-to-service trust boundaries.

这会给 Codex Security 一个更好的起点，用于 future scans 和 finding prioritization。

为什么它会影响结果

Codex Security 会从代码生成初版 threat model，但代码只能告诉系统“结构上可能是什么”，不一定知道业务上的优先级。

例如：

• 同样是 file upload，头像上传和合同附件上传的风险级别不同。
• 同样是 admin route，内部运维脚本和公网管理后台的攻击面不同。
• 同样是 token，临时 session token 和长期 cloud credential 的处置方式不同。

threat model 把这些业务语义补进去。它不会让扫描器变成万能安全专家，但能减少“扫到了不重要的地方，漏掉了真正关键的入口”的问题。

一份可用 threat model 的结构

推荐用短段落加清单，不要写成泛泛的安全口号。

Project overview:
这个仓库提供什么服务，核心运行形态是什么。

Entry points:
外部用户、第三方系统、CLI 参数、文件、队列、webhook、cron。

Trust boundaries:
用户和服务、服务和内部服务、插件和宿主、CI 和生产、admin 和普通用户。

Sensitive data:
密钥、token、个人信息、支付数据、企业客户数据、内部配置。

Privileged actions:
改账号、改权限、付款、删除数据、执行命令、写文件、部署。

Review priorities:
最希望扫描器关注的模块和风险类型。

示例：SaaS API 仓库

This repository is a public SaaS API. It accepts JSON requests from browser
clients and webhooks from payment providers. Authentication is handled by an
internal auth service. Billing updates are written through an internal billing
service. Sensitive data includes user profile data, API tokens, invoice records,
and organization membership.

Focus review on authorization checks for organization-scoped resources,
webhook signature validation, file upload parsing, billing mutations, and
service-to-service trust boundaries.

这个版本比“scan for security issues”更有用，因为它说明了入口、资产、边界和优先级。

示例：CLI 工具仓库

This repository is a local developer CLI. It reads configuration files, runs
subcommands, writes generated files into user-selected directories, and can call
external APIs when credentials are configured. Sensitive data includes local
API keys, config files, generated release artifacts, and filesystem paths.

Focus review on command injection, path traversal, unsafe file writes,
credential logging, config parsing, and network calls that may expose secrets.

CLI 仓库的风险重点和 Web API 不同。threat model 应该明确这种差异。

改进和复查 threat model

如果想改善 results，先编辑 threat model。

当 findings 漏掉你关心的 areas，或出现在你不预期的位置时，就使用它。

threat model 会改变 future scan context。

有些 users 会把 current threat model 复制到 Codex 中，围绕想更仔细 review 的 areas 对话优化，然后把更新后的版本粘回 web UI。

编辑步骤

1. 打开 Codex Security scans。
2. 进入对应 repository。
3. 打开当前 scan。
4. 找到自动生成的 project overview / threat model。
5. 点击 Edit。
6. 补充 entry points、trust boundaries、sensitive data、review priorities。
7. 保存后让后续 scans 使用更新后的上下文。

编辑时问自己

• 外部输入从哪里进入系统？
• 哪些模块能改变账号、权限、钱、数据或部署状态？
• 哪些服务调用默认信任上游？
• 哪些文件、请求、配置或消息来自不可信来源？
• 哪些 secrets 可能出现在日志、artifact、错误信息或测试输出中？
• 如果只能优先查 3 个模块，你会选哪里？

什么时候必须复查

这些变化发生后，应复查 threat model：

常见错误

好的完成标准

一份 threat model 可以先不完美，但应满足：

• 非安全同事也能看懂这个仓库的安全边界。
• 至少列出主要 entry points。
• 至少列出主要 sensitive data。
• 至少列出主要 privileged actions。
• 明确哪些模块应该优先 review。
• 能解释为什么某些 findings 更重要。

自检清单

• 你是否写清了外部输入？
• 你是否写清了 trust boundaries？
• 你是否写清了 sensitive data 和 privileged actions？
• 你是否写清了 review priorities？
• 架构变化后是否重新编辑过？
• Findings 偏离重点时，是否先回到 threat model 检查？

相关文档

• Codex Security setup：repository setup 和 findings review。
• Codex Security：product overview。
• FAQ：common questions。
• Improving the threat model：官方 threat model 编辑说明。

接下来去哪