---
title: "改進威脅模型"
description: "這頁說明 threat model 是什麼，以及編輯它如何改善 Codex Security 的 suggestions。"
verifiedAt: "2026-05-07"
---

> [!NOTE]
> **這一篇用 10 分鐘換什麼**：把 threat model 從"審計長文件"重新理解成**給掃描器的 5 行業務上下文**——入口在哪、信任邊界在哪、敏感資料在哪、特權動作有哪些、希望優先看什麼。讀完後你寫出來的 threat model 不再是安全口號，而是真正影響 finding 排序的掃描提示。

這頁說明 threat model 是什麼，以及編輯它如何改善 Codex Security 的 suggestions。

在 Codex Security 中，threat model 不是安全團隊寫給審計報告看的長文件，而是掃描時使用的專案安全上下文。它告訴系統：這個儲存庫怎麼工作、外部輸入從哪裡進來、信任邊界在哪裡、哪些資產最敏感、團隊希望優先檢查哪些風險。

```mermaid
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 的結構

推薦用短段落加清單，不要寫成泛泛的安全口號。

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

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

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

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

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

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

## 示例：SaaS API 儲存庫

```text
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 工具儲存庫

```text
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](https://chatgpt.com/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：

| 變化 | 為什麼要複查 |
| --- | --- |
| 新增 public API / webhook | 新入口會改變攻擊面 |
| 新增檔案上傳或解析器 | 輸入處理風險變化 |
| 新增 admin 功能 | 許可權邊界變化 |
| 新增支付、賬號、組織許可權邏輯 | 業務影響面變大 |
| 新增第三方整合 | 信任邊界和 secret 流動變化 |
| 架構拆分或服務合併 | 呼叫路徑和責任邊界變化 |
| findings 長期偏離重點 | 當前上下文不足或過期 |

## 常見錯誤

| 錯誤寫法 | 問題 | 改法 |
| --- | --- | --- |
| This is a web app. Scan for security issues. | 沒有入口、資產、邊界 | 寫清 public routes、auth、資料型別 |
| Focus on everything. | 無法排序 | 只列最重要的 3 到 6 個風險區域 |
| The system is secure. | 這是結論，不是上下文 | 描述安全假設和需要驗證的地方 |
| See README. | 掃描器需要直接上下文 | 摘出和安全相關的關鍵事實 |
| 只寫技術堆疊 | 技術堆疊不等於威脅模型 | 補業務動作和信任邊界 |

## 好的完成標準

一份 threat model 可以先不完美，但應滿足：

- 非安全同事也能看懂這個儲存庫的安全邊界。
- 至少列出主要 entry points。
- 至少列出主要 sensitive data。
- 至少列出主要 privileged actions。
- 明確哪些模組應該優先 review。
- 能解釋為什麼某些 findings 更重要。

## 自檢清單

- 你是否寫清了外部輸入？
- 你是否寫清了 trust boundaries？
- 你是否寫清了 sensitive data 和 privileged actions？
- 你是否寫清了 review priorities？
- 架構變化後是否重新編輯過？
- Findings 偏離重點時，是否先回到 threat model 檢查？

## 相關文件

- [Codex Security setup](https://developers.openai.com/codex/security/setup)：repository setup 和 findings review。
- [Codex Security](https://developers.openai.com/codex/security)：product overview。
- [FAQ](https://developers.openai.com/codex/security/faq)：common questions。
- [Improving the threat model](https://developers.openai.com/codex/security/threat-model)：官方 threat model 編輯說明。

## 接下來去哪

<Cards>
  <Card title="安全執行時" href="/zh-Hant/docs/codex/official/02-config-security/73-secure-runtime" description="把掃描接入和運營節奏串起來" />
  <Card title="安全模型" href="/zh-Hant/docs/codex/official/02-config-security/72-security-model" description="Codex 的整體安全設計假設" />
  <Card title="安全排障" href="/zh-Hant/docs/codex/official/02-config-security/74-security-troubleshoot" description="findings 偏離重點 / 誤報多時怎麼調" />
  <Card title="規則與命令控制" href="/zh-Hant/docs/codex/official/02-config-security/53-rules-command-control" description="把掃描結果落到執行邊界上" />
  <Card title="批准與安全模式" href="/zh-Hant/docs/codex/official/02-config-security/07-approval-security" description="日常開發的安全模式選擇" />
</Cards>
