---
title: "配置安全运行环境"
description: "说明 Codex Security 从授权接入到 reviewed findings、remediation pull request 的基本流程。"
verifiedAt: "2026-05-07"
---

> [!NOTE]
> **这一篇用 12 分钟换什么**：把 Codex Security 从"点一下扫一下"重新理解成**五步运营闭环**——接入 → 扫描 → 等回填 → 完善威胁模型 → 处理 finding 与 PR。读完后你不会再把"扫描创建成功"当作完成标准。

这页带你从 initial access 走到 reviewed findings，以及 Codex Security 中的 remediation pull requests。

开始前，先确认已经设置 Codex Cloud。还没有的话，从 [Codex Cloud](https://developers.openai.com/codex/cloud) 开始。

这不是一篇"打开开关"的说明。Codex Security 的有效性取决于三件事：repository 是否正确接入 Codex Cloud、scan 是否覆盖了合适的 history window、threat model 是否能表达真实架构和风险优先级。

```mermaid
flowchart LR
    S1["1️⃣ 接入<br/>Cloud env / 权限 / secrets"]
    S2["2️⃣ 创建扫描<br/>选 branch / history window"]
    S3["3️⃣ 等待回填<br/>commit-level pass<br/>可能要数小时"]
    S4["4️⃣ 完善威胁模型<br/>架构 / 边界 / 敏感数据"]
    S5["5️⃣ Triage 与修复<br/>finding → PR → review"]
    S1 --> S2 --> S3 --> S4 --> S5
    S5 -.->|架构变更后| S4
    S5 -.->|新入口后| S2
```

## 1. Access and Environment

Codex Security 会扫描通过 [Codex Cloud](https://developers.openai.com/codex/cloud) connected 的 GitHub repositories。

先确认：

- workspace 已有 Codex Security access。
- 你想扫描的 repository 已在 Codex Cloud 中可用。

打开 [Codex environments](https://chatgpt.com/codex/settings/environments)，检查该 repository 是否已有 environment。

如果没有，请先在那里创建 environment，再继续。

入口：

[https://chatgpt.com/codex/settings/environments](https://chatgpt.com/codex/settings/environments)

### environment 要检查什么

创建 scan 前不要只看 repository 是否出现在列表里，还要检查 environment 是否能支撑后续验证：

- setup steps 是否能安装依赖。
- 默认 branch 是否正确。
- 构建和测试命令是否能在 cloud environment 中运行。
- secrets 是否只在 setup 阶段可用，且没有进入 agent phase。
- repository 权限是否只覆盖需要扫描的范围。

如果环境本身不能构建或运行关键路径，Codex Security 仍可能产出 findings，但自动验证质量会下降。安全扫描不是孤立动作，它依赖可复现的工程环境。

## 2. New Security Scan

environment 存在后，打开 [Create a security scan](https://chatgpt.com/codex/security/scans/new)，并选择刚刚 connected 的 repository。

入口：

[https://chatgpt.com/codex/security/scans/new](https://chatgpt.com/codex/security/scans/new)

Codex Security 会先从 newest commits 往回扫描 repository。它用这种方式在 new commits 进入时构建和刷新 scan context。

配置 repository：

1. 选择 GitHub organization。
2. 选择 repository。
3. 选择要 scan 的 branch。
4. 选择 environment。
5. 选择 **history window**。更长的 window 会提供更多 context，但 backfill 需要更长时间。
6. 点击 **Create**。

### history window 怎么选

history window 决定 initial backfill 回看多长的提交历史。

| 场景 | 建议 |
| --- | --- |
| 新接入的小仓库 | 可以选择更长窗口，换取更多上下文 |
| 大型 monorepo | 先选择较短窗口验证流程，再扩大范围 |
| 安全事故复盘 | 覆盖事故相关时间段和关键改动 |
| 只关注新增风险 | 选择较短窗口，后续依赖增量扫描 |
| 审计前准备 | 预留足够 backfill 时间，不要临近发布才启动 |

不要为了“更全面”盲目选择最长窗口。窗口越长，初始扫描越慢，findings 也更需要分层 triage。

## 3. Initial Scans Can Take a While

创建 scan 后，Codex Security 会先对 selected history window 运行 commit-level security pass。

initial backfill 可能需要几个小时，尤其是 larger repositories 或 longer windows。

如果 findings 没有立刻出现，这是 expected behavior。请等待 initial scan 完成后，再开 ticket 或 troubleshooting。

initial scan setup 是 automatic 且 thorough 的，可能需要几个小时。第一批 findings 延迟出现时，不需要紧张。

### 初始等待期间做什么

等待 backfill 时，可以先准备这些材料：

1. 当前 repository 的系统边界说明。
2. 外部入口列表，例如 HTTP API、webhook、CLI、worker、上传入口。
3. 敏感数据路径，例如 token、支付、用户隐私、内部管理操作。
4. 已知高风险模块，例如 auth、permission、serialization、file parsing。
5. 负责 review findings 的 code owner 和 security owner。

这些材料会在下一步 threat model review 中用到。

## 4. Review Scans and Improve the Threat Model

review scans 入口：

[https://chatgpt.com/codex/security/scans](https://chatgpt.com/codex/security/scans)

initial scan 完成后，打开 scan，review 自动生成的 threat model。

initial findings 出现后，更新 threat model，让它匹配你的 architecture、trust boundaries 和 business context。

这会帮助 Codex Security 为你的 team rank issues。

如果你希望 scan results 改变，可以编辑 threat model，更新 scope、priorities 和 assumptions。

initial findings 出现后，要 revisit model，让 scan guidance 持续对齐当前 priorities。

保持 threat model current，有助于 Codex Security 产出更好的 suggestions。

关于 threat models 如何影响 criticality 和 triage，见 [Improving the threat model](https://developers.openai.com/codex/security/threat-model)。

### threat model review 模板

打开自动生成的 threat model 后，至少补齐下面几类信息：

```text
Repository type:
主要服务形态，例如 public API、SaaS backend、CLI、desktop app、worker。

Entry points:
外部请求、webhook、文件上传、命令行参数、后台任务、第三方回调。

Trust boundaries:
用户到服务、服务到内部服务、CI 到生产、浏览器到 API、插件到主进程。

Sensitive data:
token、账号、支付、密钥、用户内容、内部配置、审计日志。

High-priority review areas:
认证、授权、输入解析、文件处理、权限提升、依赖边界。
```

编辑后的 threat model 应该短，但不能空泛。它要让扫描器知道“这个仓库真正危险的地方在哪里”。

## 5. Review Findings and Patch

initial backfill 完成后，在 **Findings** view 中 review findings。

入口：

[https://chatgpt.com/codex/security/findings](https://chatgpt.com/codex/security/findings)

有两个 view：

- **Recommended Findings**：repo 中最 critical issues 的动态 top 10 list。
- **All Findings**：覆盖 repository 的 sortable、filterable findings table。

Recommended findings view：

[https://developers.openai.com/codex/security/images/aardvark_recommended_findings.png](https://developers.openai.com/codex/security/images/aardvark_recommended_findings.png)

点击 finding 可以打开 detail page，其中包括：

- issue 的 concise description。
- commit details 和 file paths 等 key metadata。
- 关于 impact 的 contextual reasoning。
- relevant code excerpts。
- 可用时包含 call-path 或 data-flow context。
- validation steps 和 validation output。

你可以 review 每个 finding，并直接从 finding detail page 创建 PR。

review findings 并创建 PR 的入口：

[https://chatgpt.com/codex/security/findings](https://chatgpt.com/codex/security/findings)

## Review finding 的顺序

每个 finding 建议按这个顺序看：

1. 看 title 和 severity，只作为初筛。
2. 看 affected files 和 commit context，确认是否在真实代码路径里。
3. 看 root cause，判断是否和 threat model 里的入口或边界相关。
4. 看 validation output，确认是否有复现证据。
5. 看 suggested patch，判断是否最小、可维护、符合团队风格。
6. 看测试覆盖，决定是否补 security regression test。
7. 决定 reject、defer、open PR 或手动改写 patch。

不要把 validation success 当成合并许可。它只说明问题更值得审查，不说明补丁可以跳过 code review。

## Remediation PR 的标准

从 finding detail page 创建 PR 前，至少确认：

- patch 没有扩大权限边界。
- patch 没有吞掉错误或隐藏异常。
- patch 有测试或可复现验证。
- patch 没有把风险转移到调用方。
- 变更范围聚焦在 finding 相关代码。
- code owner 能看懂修复意图。

安全补丁比普通功能补丁更需要小范围、可复现、可回滚。

## 运营节奏

Codex Security 接入后建议形成固定节奏：

| 周期 | 动作 |
| --- | --- |
| 每周 | Review recommended findings，处理 top risk |
| 每次架构变化后 | 更新 threat model |
| 每次新增外部入口后 | 检查 scan context 是否覆盖 |
| 每次重大 release 前 | 复查高危 findings 和 deferred findings |
| 每次误报后 | 记录原因，调整 threat model 或环境 |

如果 findings 长期没人 review，扫描价值会快速下降。工具负责发现和证据，人负责取舍和闭环。

## 完成标准

一轮安全 scan 不应以“scan 创建成功”为完成标准。更可靠的完成标准是：

- repository 和 environment 接入正确。
- initial backfill 已完成。
- threat model 已人工 review 并更新。
- recommended findings 已被 triage。
- 高危 findings 有 owner 和处理状态。
- proposed patch 已经过 code 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)：如何 improve scan context 和 finding prioritization。
- [Codex Security setup](https://developers.openai.com/codex/security/setup)：access、environment、scan、findings 和 PR workflow。

## 接下来去哪

<Cards>
  <Card title="威胁模型" href="/docs/codex/official/02-config-security/75-threat-model" description="把扫描真正变得有价值的关键文档" />
  <Card title="安全模型" href="/docs/codex/official/02-config-security/72-security-model" description="Codex 的整体安全设计假设" />
  <Card title="安全排障" href="/docs/codex/official/02-config-security/74-security-troubleshoot" description="扫描没产出 / 误报多时怎么排" />
  <Card title="Sandbox 边界" href="/docs/codex/official/02-config-security/49-sandbox-boundaries" description="代理执行的物理边界" />
  <Card title="网络安全" href="/docs/codex/official/02-config-security/50-network-security" description="出站访问的最小必要" />
  <Card title="Cloud 运行时" href="/docs/codex/official/05-cloud-remote/18-cloud-runtime" description="扫描底层依赖的环境" />
</Cards>
