openai/codex-security 源代码：https://github.com/openai/codex-security

Codex Security

Codex Security 是一个开源 CLI 和 TypeScript SDK，用于查找、验证和审查你自己拥有或有权评估的代码中的安全问题。

该包遵循语义化版本控制。在 1.0.0 之前，其公共 API 可能在次版本之间发生变化。

要求

SDK 和 CLI 支持 macOS、Linux 和 Windows，需要 Node.js 22 或更高版本。扫描和导出结果还需要 Python 3.10 或更高版本。如果使用 Python 3.10，请安装 tomli 包。安装包或运行 --help 和 --version 时不需要 Python。

在运行扫描前，请使用 OpenAI 账户登录或提供 OpenAI API 密钥。仅扫描你自己拥有或明确有权评估的仓库。

安装并扫描

npm install @openai/codex-security
npx codex-security login
npx codex-security scan /path/to/repo

运行 npx codex-security --help 查看所有命令，npx codex-security scan --help 查看扫描选项。

在远程或无头机器上，使用 npx codex-security login --device-auth。

对于 CI 和其他无人值守扫描，请使用 shell、CI 密钥或密钥管理器设置 OPENAI_API_KEY 或 CODEX_API_KEY。在 Windows 上，使用 PowerShell 设置 API 密钥：

$env:OPENAI_API_KEY = "<your-key>"
npx codex-security scan C:\code\repository

要通过 stdin 存储 API 密钥，请执行：

printenv OPENAI_API_KEY | npx codex-security login --with-api-key

使用 npx codex-security login status 检查已存储的登录信息，使用 npx codex-security logout 删除它。

Codex Security 会复用已有的基于文件的 Codex 登录。如果 Codex 在系统密钥环中存储凭据，则在扫描前运行一次 npx codex-security login。环境 API 密钥优先级高于已存储的登录信息。取消设置 OPENAI_API_KEY 和 CODEX_API_KEY 以使用你的 ChatGPT 登录。登录状态命令会报告有效的凭据来源，但不打印其值，包括在没有已存储登录信息时。

扫描仓库的子集或写入机器可读的结果：

npx codex-security scan /path/to/repo --model gpt-5.6-terra
npx codex-security scan /path/to/repo --path src --path tests
npx codex-security scan /path/to/repo --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
npx codex-security scan /path/to/repo --diff origin/main --json
npx codex-security scan /path/to/repo --output-dir /path/outside/repo/results
npx codex-security scan /path/to/repo --output-dir /path/outside/repo/results --archive-existing
npx codex-security scan /path/to/repo --dry-run
npx codex-security scan /path/to/repo --fail-on-severity high
npx codex-security install-hook
npx codex-security bulk-scan
npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans
npx codex-security scans list /path/to/repo
npx codex-security scans list --scan-root /path/outside/repo/results
npx codex-security scans show SCAN_ID
npx codex-security scans rerun SCAN_ID
npx codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
npx codex-security scans match --all
npx codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
npx codex-security export /path/outside/repo/results --export-format sarif --output /path/outside/repo/results.sarif
npx codex-security export /path/outside/repo/results --export-format csv --output /path/outside/repo/findings.csv
npx codex-security export /path/outside/repo/results --export-format json --output /path/outside/repo/findings.json
npx codex-security validate /path/outside/repo/findings.json "Possible SQL injection in src/query.ts:42"
npx codex-security patch /path/outside/repo/findings.json "Missing authorization check in src/routes.ts:18"

install-hook 会在每次提交前扫描暂存和未暂存的更改。它遵循 core.hooksPath，不会替换已有钩子，并会阻止高严重性发现或失败的扫描。设置 --fail-on-severity 来更改阈值。

使用 npx codex-security --version 查看 CLI 版本，npx codex-security info --json 查看包、插件和运行时版本、默认模型和推理努力级别以及下一个扫描命令。添加 --dry-run 以检查有效的模型和推理努力级别，而无需初始化 Codex 或连接网络。

输出目录必须位于被扫描目录及其任何包含的 Git 工作树外部。在 macOS 和 Linux 上，已有的输出目录必须仅限当前用户访问（chmod 700）。扫描产物可能包含源代码片段、漏洞详情和复现步骤。请将它们保存在仓库、公开问题报告和共享位置之外。

生成 SARIF 时，会写入 /exports/results.sarif。

使用 npx codex-security scan --help 查看所有目标、输出和运行时选项。对于多个文件或目录，重复使用 --knowledge-base PATH。目录会递归搜索 Markdown、文本、PDF 和 Word (.docx) 文件。

使用 gh auth login 登录，然后运行 npx codex-security bulk-scan 来发现过去 90 天内推送的 GitHub 仓库。已归档的仓库和 fork 会被排除。在扫描前，搜索仓库列表，选择要扫描的仓库，并确认。私有检出会重用你的 GitHub CLI 登录，而不会更改全局 Git 配置。

对于自动化或已有仓库列表，请传递包含 id、repository 和完整不可变 revision 列的 CSV，并指定 --output-dir。使用 npx codex-security bulk-scan --help 查看所有选项。

CLI 使用 Incur (https://github.com/wevm/incur) 实现代理友好的发现和结构化输出。使用 --llms 获取命令清单，scan --schema --format json 获取命令 schema，使用 mcp add 注册 MCP 服务器，使用 skills add 同步代理技能，使用 completions bash|zsh|fish 获取 shell 补全。扫描结果支持 --format toon|json|yaml|jsonl 和 --full-output。使用 info --json 获取 SDK 和绑定插件的元数据。MCP 仅暴露此只读元数据命令；扫描、认证、导出、验证和补丁保持 CLI 专属，因为 MCP 传输无法取消正在进行的扫描。

如果输出目录已包含结果，请添加 --archive-existing。CLI 会将其移动到 .previous--<timestamp>，并在原始路径开始新的空目录扫描。添加 --dry-run 查看目标而不移动文件。

扫描默认仅生成报告。在 CI 中使用 --fail-on-severity，当完成扫描包含等于或高于所选严重性的发现时，退出码为 1。不完整覆盖和 CLI/运行时错误退出码为 2。不完整的扫描仍会将可用的人类可读或 JSON 结果写入 stdout，并将覆盖警告写入 stderr，包括在仅报告模式下。对于 CI，请将机器可读输出保存在已检出仓库之外，并应用严重性策略。不完整覆盖和运行时错误仍会非零退出：

SCAN_ROOT="$(mktemp -d)"
npx codex-security scan . \
  --diff origin/main \
  --output-dir "$SCAN_ROOT/results" \
  --json \
  --fail-on-severity high > "$SCAN_ROOT/findings.json"

JSON 扫描保持非交互式，包括当 stderr 是终端时。交互式运行 Codex 的命令（validate、patch、login 和 logout）拒绝 --json。当选择 JSON 输出时，将 CSV 导出写入文件。

扫描默认使用 gpt-5.6-sol 和超高推理努力级别。使用 --model 切换模型。使用 --codex 设置其他 Codex 参数：

npx codex-security scan . --model gpt-5.6-terra --codex 'model_reasoning_effort="high"'

扫描会报告其请求的路径以及实际的排名、文件审查、验证和攻击路径阶段。完成时会显示发现严重性、覆盖范围、经过时间、可用的令牌和工作线程数、结果目录以及下一个有用的命令。进度保留在 stderr 上；JSON 结果保留在 stdout 上。

使用 TypeScript SDK

创建一个客户端，选择仓库外部的私有输出目录，并在扫描后关闭客户端：

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

const security = new CodexSecurity();
try {
  const result = await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
  });
  console.log(result.reportPath);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

SDK 还支持路径和 diff 目标、预检、进度回调、取消、安全知识库以及类型化扫描结果。

在 Docker 中运行批量扫描

附带的 Docker 镜像可在 Linux Docker 主机上根据提供的 CSV 运行非交互式批量扫描。附带的 compose.yaml 配置了镜像、持久化文件和加固的 Codex 命令沙箱。

配置 Docker 批量扫描

创建一个 repositories.csv，每个仓库包含一个完整的、不可变的 Git 提交：

id,repository,revision
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567

创建私有的持久化结果和认证目录，并让容器以当前用户身份写入文件：

mkdir -p results state
chmod 700 results state
export CODEX_SECURITY_USER="$(id -u):$(id -g)"
docker compose build codex-security

对于从远程或无头 Docker 主机进行一次性登录，运行：

docker compose run --rm codex-security login --device-auth

在浏览器中打开显示的验证 URL，输入一次性代码。容器退出后，登录信息会保留在 state/ 中。或者，通过主机环境或密钥管理器提供 OPENAI_API_KEY 或 CODEX_API_KEY。对于私有仓库，以相同方式提供 GH_TOKEN 或 GITHUB_TOKEN。Compose 仅将已命名、配置的凭据传递给容器。

使用默认命令启动一个可恢复的四工作线程扫描：

docker compose run --rm codex-security

在默认的超高推理设置下，全仓库扫描每个仓库可能需要数十分钟。将大型活动作为异步批处理作业运行，并在此过程中保持结果和认证目录挂载。完成后，报告、每个仓库的发现以及扫描清单会出现在主机上的 results/ 中。该活动的工台状态保留在 results/.codex-security-state/ 中；可重用的 Codex 登录信息单独保留在 state/ 中。这样，新的结果目录可以使用相同的登录信息启动一个单独的活动，而不会与先前的扫描冲突。使用原始 CSV 和相同的 results/ 和 state/ 目录重新运行相同的命令，以恢复中断的扫描。

要选择不同数量的并行工作线程或重试失败的仓库，请覆盖默认的扫描命令：

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 8 \
  --max-attempts 2

设置 CODEX_SECURITY_CSV、CODEX_SECURITY_RESULTS 或 CODEX_SECURITY_STATE 以使用 Compose 项目外部的现有文件或目录。设置 CODEX_SECURITY_IMAGE 以使用已批准、已构建的镜像。在访问 GitHub Enterprise Server 时设置 CODEX_SECURITY_GIT_HOST。

将凭据、仓库列表和结果保留在镜像和 Git 之外；附带的忽略文件会将它们从镜像构建和提交中排除。所有 CSV 文件，包括自定义命名的仓库清单，都会从 Docker 构建上下文中排除。Compose 会在运行时挂载选定的 CSV 文件。附带的 Compose 配置会删除所有 Linux 功能、阻止新权限、以非 root 用户运行，并应用提供的默认拒绝 seccomp 配置文件。Codex Security 会在单独的非特权 Linux 沙箱中运行每个扫描命令。Docker 的默认 seccomp 配置文件会阻止该沙箱所需的用户和挂载命名空间；提供的配置文件仅允许所需的命名空间操作。Linux 主机必须允许非特权用户命名空间。某些 Docker Desktop 虚拟机还会限制嵌套挂载命名空间，因此对于生产扫描，请使用 Linux 主机。

对于没有 Docker Compose 的环境，等效的低层调用是：

docker run --rm --init \
  --user "$(id -u):$(id -g)" \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --security-opt "seccomp=$PWD/docker/codex-security-seccomp.json" \
  --env OPENAI_API_KEY \
  --env CODEX_API_KEY \
  --env GH_TOKEN \
  --env GITHUB_TOKEN \
  --env CODEX_SECURITY_GIT_HOST \
  --mount "type=bind,source=$PWD/repositories.csv,target=/input/repositories.csv,readonly" \
  --mount "type=bind,source=$PWD/results,target=/output" \
  --mount "type=bind,source=$PWD/state,target=/state" \
  codex-security:local \
  bulk-scan /input/repositories.csv \
  --output-dir /output

当提供 GitHub 令牌时，镜像会为 github.com 配置一个非交互式 Git 凭据助手。该令牌既适用于 HTTPS 仓库 URL，也适用于 [email protected]: 仓库 URL，而无需挂载 SSH 代理。镜像永远不会将该令牌放入仓库 URL、写入镜像层或发送到其他 Git 主机。在需要时，将 CODEX_SECURITY_GIT_HOST 设置为 GitHub Enterprise Server 实例的主机名。使用 --workers 控制并发仓库扫描，使用 --max-attempts 重试失败。当任何仓库失败时，命令返回非零状态。

扫描历史与重新运行

npx codex-security scans list 列出当前仓库的扫描。传递仓库路径以检查另一个检出，--scan-root DIR 按扫描产物目录过滤。scans show SCAN_ID 包含保存的配置、发现和覆盖范围。历史记录保存在 $CODEX_HOME/state/plugins/codex-security 下的现有 Codex Security 工台数据库中。设置 CODEX_SECURITY_STATE_DIR 以选择其他位置。

scans rerun SCAN_ID 对当前检出重复相同的配置。scans match BEFORE_SCAN_ID AFTER_SCAN_ID 链接具有相同根本原因的发现；scans match --all 包含当前仓库所有可用的已完成扫描，包括其他工作树和克隆。使用 --force 重新计算已保存的匹配。scans compare BEFORE_SCAN_ID AFTER_SCAN_ID 读取已保存的匹配并识别新增、持久、重新打开、已解决或未知的发现。当覆盖范围不完整或原始位置未被审查时，缺失的发现保持未知。

使用 export 从已完成的、已封存的扫描中创建 CSV、JSON 或 SARIF，而无需启动 Codex 或加载凭据。JSON 保留已封存的发现文档。CSV 使用可移植的发现列，将发现标记为开放，并且不包含本地工台分类状态。导出器在写入前会验证封存，接受 --output - 以输出到 stdout，并且可以配合 SARIF 使用 --source-root /path/to/repo 添加源行指纹。运行 npx codex-security export --help 查看所有导出选项。

使用 validate 运行绑定的验证技能对候选发现，使用 patch 运行绑定的修复发现技能对安全问题。每个位置参数可以是文件（其内容被读入请求）或纯文本。这两个命令都在当前目录下操作。规范扫描文档的大小限制为：清单 16 MiB，发现 128 MiB，覆盖范围 32 MiB。过大的扫描在封存前会被拒绝。退出码为：0 表示完成的仅报告扫描或通过策略，1 表示完成的策略违规，2 表示无效输入、不完整覆盖或运行时/导出错误，130 表示中断，143 表示终止。

使用 --dry-run 或 await security.preflight(...) 验证本地扫描输入并报告选定的凭据来源，而无需初始化 Codex、加载凭据或启动扫描。干运行不会检查插件、探测 Python 或连接网络；其认证元数据未经验证。

文档、支持与安全

• Codex Security 概述 (https://developers.openai.com/codex/security)
• CLI 快速