Codex Security

Codex Security 帮助你发现、调查并修复代码中的漏洞。你可以在 Codex 中使用其安全工作流，或通过 @openai/codex-security CLI 和 TypeScript SDK 将其自动化。

在 Codex 中：选择安全工作流。
在终端中：安装 CLI 并扫描你的仓库。
**在自动化中：**使用 TypeScript SDK 或 GitHub Action。

功能

扫描仓库、选定路径或 Git 变更。深度扫描会在仓库和选定路径上并行运行发现工作进程。
验证候选发现、生成补丁并验证现有修复。
起草 SECURITY.md 策略并保存威胁模型以供后续审查。
浏览已保存的扫描和发现、识别重复项、依据你自己的评分标准评估严重性，并根据源代码和 Git 历史建议负责人。
导入 GitHub 代码扫描警报，导出 SARIF、JSON 或 CSV，并将发现发布到 Linear 或发现服务。
跨仓库或项目组件自动化扫描，包括在 CI 和容器中。

在 Codex 中使用

在启用了 Codex Security 插件的 Codex 会话中打开你的仓库，然后询问：

对此仓库运行 Codex Security 扫描，重点关注身份验证和授权。返回已保存的报告、源证据和覆盖范围限制。

扫描完成后会保存报告、发现、覆盖范围以及可用的威胁模型。使用这些结果来调查发现、请求补丁或验证现有修复。有关插件设置、任务选择以及在所需工具不可用时的恢复方法，请参阅代理工作流指南。

快速开始

需要 Node.js 22.13.0+（在 22.x 范围内），或 Node.js 24.x 或 26.x，以及 Python 3.10+。 Python 3.10 还需要 tomli。

全局安装 CLI 并登录：

npm install --global @openai/codex-security
cs login

cs 是 codex-security 的简短别名；两个命令运行的是同一个 CLI。安装过程会在 npm 的全局可执行文件目录中创建这两个命令，该目录必须位于你的 PATH 中。如果 cs 已经指向其他工具，请改用 codex-security。如果 npm 因 cs 报 EEXIST 错误而停止，请使用 npx @openai/codex-security，而不要进行全局安装。

在仓库目录中运行扫描：

cs scan .

如果你拥有 Daybreak Blue 访问权限，请在扫描命令中添加 --cyber-access-program daybreak_blue。否则，请省略该标志或使用 --cyber-access-program standard。

要使用 Codex 的 Daybreak 开关，请传入 --codex daybreak=true。该开关默认关闭，并且需要兼容的访问权限。有关 SDK 和插件的用法（包括 Deep Scan worker），请参阅 Daybreak 配置。

扫描会使用你现有的 SECURITY.md 指南。要定义或更新该指南，可以选择起草策略：

cs policy .

草稿保存在你的仓库之外。请查看 diff 和说明，编辑草稿，然后仅将 SECURITY.md 复制到所示的 Policy target。你可以在不生成策略的情况下进行扫描。

要在不进行全局安装的情况下运行，请将这些示例中的 cs 替换为 npx @openai/codex-security，例如：

npx @openai/codex-security scan .

对于 CI，请在扫描进程的环境中设置 OPENAI_API_KEY 或 CODEX_API_KEY。在远程或无头机器上，如果你的工作区允许，请使用 login --device-auth，或者通过 SSH 登录。

某些网络安全请求和受保护的发现需要 Trusted Access for Cyber 批准。

扫描选项

选择范围和扫描模式：

# Scan selected paths.
cs scan . --path src --path tests

# Scan committed changes from a base revision to HEAD.
cs scan . --diff origin/main

# Run a deep scan of the repository.
cs scan . --mode deep

使用 cs scan . --max-time 15 可设置建议的 15 分钟标准调查时间额度。有关时间语义和 Deep Scan 限制，请参阅调查时间。

使用 cs --help 浏览命令，或使用 cs scan --help 查看扫描选项、成本限制以及扫描后的修补。

对于跨多个仓库分布的应用程序，请参阅跨仓库审查一个系统。使用批量扫描可在一次可恢复的活动中对独立仓库进行审查。

扫描后，检查其范围和后续工作以了解已记录的排除项，并决定是审查发现结果、运行聚焦扫描，还是恢复中断的运行。

TypeScript SDK

在你的 TypeScript 项目中本地安装该包：

npm install @openai/codex-security

然后导入它：

import { CodexSecurity } from "@openai/codex-security";

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository");
  console.log(result.reportPath);
} finally {
  await security.close();
}

SDK 指南包含深度扫描配置、验证、严重性分类、负责人建议以及结果处理。

读取现有的 Cloud 发现项

当你的账户可以使用 Codex Security Cloud 时，Security 插件的 $cloud-findings 技能可以在 Codex 桌面端或 Codex CLI 中读取发现项、报告、记录的分配与验证以及扫描状态。Cloud 是可选连接；本地扫描无需它即可工作。

有关身份验证要求和只读示例，请参阅 Cloud 连接设置与 CLI 读取。

生成 SECURITY.md

使用 policy 起草新的 SECURITY.md 或更新现有的 SECURITY.md。使用 --path 选择组件：

cs policy .
cs policy . --path services/api --knowledge-base architecture.md

该命令会将草稿保存在仓库之外，并且不会改动现有文件。请审阅差异和说明，编辑草稿，然后仅将 SECURITY.md 复制到所显示的 Policy target。请将保存的架构文档和威胁模型文档保留在仓库之外。

扫描已经使用根目录和组件级的 SECURITY.md 文件。如果当前策略无需更改，请保留它。更新策略时，请保留其中的漏洞报告说明。如果命令提示策略已是最新，则无需复制。

位于 .github/SECURITY.md 或 docs/SECURITY.md 的文件通常包含报告说明。起草策略时请保留这些说明；这些位置不会自动提供仓库范围的扫描指导。有关策略位置、未解答问题、已保存产物和 SDK 用法，请参阅策略指南。

保存并导出威胁模型

扫描和策略生成会随结果一起保存威胁模型。无需启动另一次分析即可导出已保存的模型：

cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md

省略 --scan 以使用当前仓库最近一次完成的扫描。导出指南还涵盖了发现结果、用于 CI 的 SARIF 输出以及离线 TypeScript API。

GitHub Actions

使用 GitHub Action 运行定时、手动或拉取请求扫描。对于每周一次的仓库扫描，请将 OpenAI API 密钥添加为仓库密钥 CODEX_SECURITY_API_KEY，然后将此工作流保存到 .github/workflows/codex-security.yml。将 REPLACE_WITH_REVIEWED_COMMIT 替换为某个 Action 提交的完整 SHA。

此工作流请求 Daybreak Blue。请使用已启用 Blue 的项目中的 API 密钥；如果没有 Daybreak 访问权限，请省略 cyber-access-program 或将其设置为 standard。

name: Codex Security
on:
  workflow_dispatch:
  schedule:
    - cron: "23 7 * * 1" # Mondays at 07:23 UTC

permissions:
  contents: read

jobs:
  security:
    runs-on: ubuntu-24.04
    steps:
      # Configure Bubblewrap and AppArmor so Codex Security can run safely in its sandbox.
      - name: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: openai/codex-security@REPLACE_WITH_REVIEWED_COMMIT
        with:
          model: gpt-5.6-sol
          effort: high
          cyber-access-program: daybreak_blue
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

默认情况下，发现结果仅作报告。设置严重性阈值，以便在报告的发现结果达到或超过该阈值时判定失败。扫描器和必需的报告错误会导致任务失败；有意的文件排除和调查说明不会。有关 PR 扫描、严重性阈值和报告上传，请参阅 Action 设置和输入参考。

容器化批量扫描

使用随附的 Docker Compose 配置扫描仓库列表，该配置会在多次运行之间保留结果和身份验证信息。请参阅容器快速入门。工作流运行器在容器中运行各个 CLI 阶段，并可连接到单独部署的发现结果服务。

发现结果存储与去重

发现结果指南涵盖本地存储、去重，以及通过 publish scan --to custom 和显式 --findings-url 与独立运营的端点兼容。本地 serve 命令和浏览器仪表板已被移除；现有数据库和扫描产物仍然可用。

其他提供商

扫描支持 OpenAI、Amazon Bedrock、OpenRouter、Fireworks AI 和 Cheaper Inference。Bedrock 使用 AWS 凭证，无需单独的 OpenAI 登录。有关 AWS 配置文件、区域和模型访问，请参阅 Bedrock 设置。

对于 OpenRouter、Fireworks AI 和 Cheaper Inference，请设置提供商的 API 密钥并选择受支持的模型。有关示例，请参阅提供商配置。

文档

如需私下报告漏洞，请遵循安全策略。

codex-security

最受欢迎