改進威脅模型

這頁說明 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 編輯說明。

接下來去哪