---
title: "理解 Codex 安全模型"
description: "介紹 Codex Security 的模型：如何在連線的 GitHub repositories 中發現、驗證和修復潛在漏洞。"
verifiedAt: "2026-05-07"
---

> [!NOTE]
> **這一篇用 10 分鐘換什麼**：先把兩個易混的"安全"分清楚——**Agent approvals & security**（Codex 自己跑命令時的許可權邊界）vs **Codex Security**（掃描你 GitHub 儲存庫找漏洞的工作流）。讀完後你能識別一個安全問題該走哪條路：調 sandbox / approval，還是補 threat model / 發起 scan。

Codex Security 是 OpenAI Codex 面向工程和安全團隊的安全分析產品，用來在 connected GitHub repositories 中發現、驗證並推進修復 likely vulnerabilities。

```mermaid
flowchart LR
    Issue["🛡 安全問題"]
    Q{"問題在哪一側？"}
    Agent["Agent 自己執行時<br/>許可權/沙箱/網路"]
    Repo["儲存庫程式碼本身<br/>有沒有漏洞"]
    Path1["Agent approvals & security<br/>sandbox / approval / network"]
    Path2["Codex Security<br/>scan / threat model / patch"]
    Issue --> Q
    Q -->|執行邊界| Agent --> Path1
    Q -->|程式碼漏洞| Repo --> Path2
```

這頁介紹的是 Codex Security 這個 product：它會掃描 connected GitHub repositories，找出 likely security issues。

如果你要了解 Codex sandboxing、approvals、network controls 和 admin settings，請看 [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security)。

Codex Security 可以幫助 teams：

1. **Find likely vulnerabilities**：使用 repo-specific threat model 和真實 code context。
2. **Reduce noise**：在你 review 之前先驗證 findings。
3. **Move findings toward fixes**：提供 ranked results、evidence 和 suggested patch options。

## 它和 sandbox security 不是一回事

Codex 文件裡有兩個容易混淆的“安全”：

| 名稱 | 解決什麼問題 | 典型頁面 |
| --- | --- | --- |
| Agent approvals & security | Codex 自己執行命令、訪問檔案、使用網路時的許可權邊界 | sandbox、approval、network access、managed config |
| Codex Security | 掃描你的 GitHub repository，發現、驗證、修復程式碼裡的安全問題 | security setup、findings、threat model、patch workflow |

這篇只講第二類。不要把 Codex Security 當成“開啟後 Codex 就更安全”的開關，它是一個針對儲存庫安全分析的工作流。

## How It Works

Codex Security 會按 commit 掃描 connected repositories。

它會根據 repo 構建 scan context，把 likely vulnerabilities 放到該 context 中檢查，並在 surfacing 前，把 high-signal issues 放到 isolated environment 中驗證。

這個 workflow 重點關注：

- repo-specific context，而不是 generic signatures。
- validation evidence，用來減少 false positives。
- 可以在 GitHub 中 review 的 suggested fixes。

更完整的官方 pipeline 可以理解成四段：

1. **Analysis**：為 repository 建立 threat model，理解架構、入口、信任邊界和關鍵資產。
2. **Commit scanning**：掃描 merged commits 和 repository history，找出 likely issues。
3. **Validation**：在 isolated container 中嘗試復現 high-signal issues，降低 false positives。
4. **Patching**：與 Codex 結合，生成可審閱的 proposed patch，供維護者決定是否開 PR。

## Threat model 的作用

Codex Security 的 threat model 是掃描時使用的安全上下文。官方文件把它描述為 repository 工作方式的簡短安全摘要，在 Codex Security 中以 `project overview` 的形式編輯。

一個有用的 threat model 應該說明：

- entry points 和 untrusted inputs
- trust boundaries 和 auth assumptions
- sensitive data paths 或 privileged actions
- 團隊希望優先 review 的區域

例如，一個 SaaS API 儲存庫可以寫：

```text
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.
```

這類上下文會影響後續 scans 的 prioritization 和 review quality。發現結果偏離重點時，優先編輯 threat model，而不是先懷疑掃描器“沒用”。

## Access and Prerequisites

Codex Security 透過 Codex Web 處理 connected GitHub repositories。

OpenAI 管理 access。

如果你需要 access，或某個 repository 不可見，請聯絡你的 OpenAI account team，並確認該 repository 已透過 Codex Web workspace 可用。

正式使用前需要確認：

1. Workspace 已獲得 Codex Security access。
2. 目標 repository 已連線到 Codex Cloud。
3. repository 對應的 Codex environment 已建立。
4. 你有許可權建立 security scan。
5. 初始掃描的 history window 與儲存庫規模相匹配。

## 建立第一次 scan

官方 setup 流程是：

1. 進入 Codex environments，確認目標 repository 已有 environment；沒有就先建立。
2. 開啟 Create a security scan。
3. 選擇 GitHub organization。
4. 選擇 repository。
5. 選擇 branch。
6. 選擇 environment。
7. 選擇 history window。
8. 點選 Create。

Codex Security 會從最新 commits 往回掃描。較長的 history window 可以提供更多上下文，但 backfill 會更久。

初始掃描可能需要數小時。大型儲存庫或較長曆史視窗可能更久。官方建議初始 findings 沒有馬上出現時先等待掃描完成，再進入排障。

## Review findings

初始 backfill 完成後，從 Findings view 審閱結果。官方頁面提到兩個檢視：

- **Recommended Findings**：動態維護的 top 10 critical findings。
- **All Findings**：可排序、可過濾的全量 findings table。

單個 finding detail 通常包含：

- issue description
- commit details 和 file paths
- impact reasoning
- relevant code excerpts
- call-path 或 data-flow context
- validation steps 和 validation output

有 proposed patch 時，不應直接信任自動修復。正確做法是先審閱 evidence、復現路徑、diff 範圍，再決定是否建立 PR。

## Patch review 邊界

Codex Security 不等於自動合併安全修復。FAQ 明確說明 proposed patch 是 recommended remediation，使用者可以審閱並從 findings UI 推進到 GitHub PR，但它不會自動把 patch 應用到 repository。

團隊應保留三道門：

1. Security reviewer 確認 finding 是否真實、是否高優。
2. Code owner 審閱 proposed patch 是否符合架構和風格。
3. CI / tests / security regression checks 驗證補丁沒有破壞行為。

## 適合什麼團隊

適合：

- 已經把核心儲存庫接入 GitHub 和 Codex Cloud 的團隊。
- 有安全 backlog，但缺少足夠 triage 人力的團隊。
- 希望讓安全 findings 附帶 evidence 和 suggested remediation 的團隊。
- 想把 repository threat model 變成持續掃描上下文的團隊。

不適合直接替代：

- SAST、dependency scanning、secret scanning。
- 人工 threat modeling 和安全架構評審。
- 高風險補丁的 code owner review。
- 生產釋出前的安全驗收。

FAQ 明確說 Codex Security complements SAST，不是替代 SAST。

## 常見失敗模式

| 問題 | 常見原因 | 處理方式 |
| --- | --- | --- |
| repository 不可見 | 沒接入 Codex Cloud，或 workspace 沒有 access | 檢查 Codex environment 和賬號許可權 |
| 初始 findings 很慢 | history window 大、儲存庫大、驗證耗時 | 等待 initial backfill 完成 |
| findings 偏離業務重點 | threat model 沒說明關鍵入口和信任邊界 | 編輯 project overview / threat model |
| false positives 仍然存在 | 自動驗證不等於完整安全證明 | 結合 evidence 和人工 review |
| proposed patch 不適合合併 | patch 只解決區域性 finding，未覆蓋架構約束 | 讓 code owner review，並補測試 |

## 相關文件

- [Codex Security](https://developers.openai.com/codex/security)
- [Codex Security setup](https://developers.openai.com/codex/security/setup)
- [FAQ](https://developers.openai.com/codex/security/faq)
- [Improving the threat model](https://developers.openai.com/codex/security/threat-model)
- [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security)

## 接下來去哪

<Cards>
  <Card title="安全執行時" href="/zh-Hant/docs/codex/official/02-config-security/73-secure-runtime" description="把掃描接入 → backfill → triage 串起來" />
  <Card title="威脅模型" href="/zh-Hant/docs/codex/official/02-config-security/75-threat-model" description="決定掃描質量的最關鍵文件" />
  <Card title="安全排障" href="/zh-Hant/docs/codex/official/02-config-security/74-security-troubleshoot" description="findings 不到位時怎麼調" />
  <Card title="Sandbox 邊界" href="/zh-Hant/docs/codex/official/02-config-security/49-sandbox-boundaries" description="另一側安全：執行邊界" />
  <Card title="批准與安全模式" href="/zh-Hant/docs/codex/official/02-config-security/07-approval-security" description="日常 sandbox + approval 怎麼搭" />
</Cards>
