Codex Security

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

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

功能

扫描仓库、选定路径或 Git 变更。深度扫描会重复标准扫描并返回去重后的发现结果。
验证候选发现、生成补丁并验证现有修复。
起草 SECURITY.md 策略并保存威胁模型以供后续审查。
浏览已保存的扫描和发现，识别重复项，依据你自己的评分标准评估严重性，并根据源代码和 Git 历史建议负责人。
预览第三方扫描器的发现结果，将其保存到本地，或将受支持的报告发布到 Codex Security Cloud。扫描器导入指南。
在 Linear、Jira 或 GitHub 中跟踪发现，发布已完成的扫描，或导出 SARIF、JSON 和 CSV。集成工作流。
跨仓库或项目组件自动化扫描，包括在 CI 和容器中。

在 Codex 中使用

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

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

完成的扫描会保存报告和发现结果。阅读报告以了解源代码证据和排除项，然后请求补丁或让 Codex 验证现有修复。有关设置、任务选择和恢复，请参阅代理工作流指南。

快速开始

需要 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 scan .

扫描完成后，在终端中打开 REPORT 路径下的 Markdown 文件。在同一仓库中运行 cs scans show，再次查找其最新完成的扫描。有关如何解读报告中的排除项，请参阅扫描范围与后续工作。

cs 和 codex-security 运行相同的 CLI。如果短名称与其他命令冲突，请使用 codex-security。如需跳过全局安装，或 npm 报告 EEXIST 冲突，请在登录和扫描时使用 npx @openai/codex-security 代替 cs。

对于 CI，请在扫描进程的环境中设置 OPENAI_API_KEY 或 CODEX_API_KEY。对于无头机器，请参阅设备或 SSH 登录。

扫描选项

选择范围和扫描模式：

# 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 分钟 Standard 调查时限。有关时间语义和 Deep Scan 限制，请参阅调查时间。

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

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

扫描会使用现有的根目录和组件 SECURITY.md 指南。如需编写或修订该文件，请参阅生成 SECURITY.md。

某些网络安全请求和受保护的发现需要 Trusted Access for Cyber。对于拥有 Daybreak 访问权限的账户，请参阅 Daybreak 选择加入了解 Codex 开关，并参阅网络安全访问计划以显式选择计划。

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。关于 ServiceNow 应用程序漏洞响应，请参阅为 ServiceNow 导出发现项。

GitHub Actions

要在 GitHub 托管的 Ubuntu 上运行每周仓库扫描：

将 OpenAI API 密钥添加为仓库密钥 CODEX_SECURITY_API_KEY。
将每周工作流复制到 .github/workflows/codex-security.yml。将 REPLACE_WITH_REVIEWED_COMMIT 替换为来自 Action 发布版本的已审核分发提交 SHA。
要在下次计划运行之前试用该工作流，请打开 Actions → Codex Security repository → Run workflow。

该示例使用每次扫描估计 $5 的上限，并报告发现项而不使作业失败。进行中的请求可能超出该上限。有关严重性阈值、拉取请求检查或运行器要求，请参阅 Action 指南。有关符合条件的账户，请参阅 Daybreak 访问权限。

容器化批量扫描

使用随附的 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 密钥并选择受支持的模型。有关示例，请参阅提供商配置。

文档

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