---
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="/docs/codex/official/02-config-security/73-secure-runtime" description="把扫描接入 → backfill → triage 串起来" />
  <Card title="威胁模型" href="/docs/codex/official/02-config-security/75-threat-model" description="决定扫描质量的最关键文档" />
  <Card title="安全排障" href="/docs/codex/official/02-config-security/74-security-troubleshoot" description="findings 不到位时怎么调" />
  <Card title="Sandbox 边界" href="/docs/codex/official/02-config-security/49-sandbox-boundaries" description="另一侧安全：执行边界" />
  <Card title="批准与安全模式" href="/docs/codex/official/02-config-security/07-approval-security" description="日常 sandbox + approval 怎么搭" />
</Cards>
