OpenAI 开源 Codex Security：AI 驱动的代码安全扫描工具

Codex Security 是一个开源 CLI 和 TypeScript SDK，用于查找、验证和审查您拥有或有权评估的代码中的安全问题。注意：此包遵循语义化版本控制，其公共 API 在 1.0.0 之前的次要版本中可能发生变化。

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\nnpx codex-security login\nnpx codex-security scan /path/to/repo\n运行 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-api-key>"\nnpx codex-security scan C:\code\repository\n要存储 API 密钥，

通过 stdin 传递：printenv OPENAI_API_KEY | npx codex-security login --with-api-key\n使用 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 登录。login status 命令报告有效的凭据来源而不打印其值，包括当没有存储的登录时。

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

\nnpx codex-security scan /path/to/repo --model gpt-5.6-terra\nnpx codex-security scan /path/to/repo --path src --path tests\nnpx codex-

security scan /path/to/repo --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf\nnpx codex-security scan

/path/to/repo --diff origin/main --json\nnpx codex-security scan /path/to/repo --output-dir /path/outside/repo/results\nnpx codex-securi

ty scan /path/to/repo --output-dir /path/outside/repo/results --archive-existing\nnpx codex-security scan /path/to/repo --dry-run\nnpx c

odex-security scan /path/to/repo --fail-on-severity high\nnpx codex-security install-hook\nnpx codex-security bulk-scan\nnpx codex-secur

ity bulk-scan repositories.

csv --output-dir /path/outside/repositories/security-scans\nnpx codex-security scans list /path/to/repo\nnpx codex-security scans list -

-scan-root /path/outside/repo/results\nnpx codex-security scans show SCAN_ID\nnpx codex-security scans rerun SCAN_ID\nnpx codex-security

scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID\nnpx codex-security scans match --all\nnpx codex-security scans compare PREVIOUS_SCAN_ID C

URRENT_SCAN_ID\nnpx codex-security export /path/outside/repo/results --export-format sarif --output /path/outside/repo/results.sarif\nnp

x codex-security export /path/outside/repo/results --export-format csv --output /path/outside/repo/findings.csv\nnpx codex-security expo

rt /path/outside/repo/results --export-format json --output /path/outside/repo/findings.json\nnpx codex-security validate /path/outside/

repo/findings.json "Possible SQL injection in src/query.ts:

42"\nnpx codex-security patch /path/outside/repo/findings.json "Missing authorization check in src/routes.ts:

18"\ninstall-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 时，写入 <scan-dir>/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 仓库。存档仓库和分支被排除。搜索仓库列表，选择要扫描的仓库，并在扫描前确认。

私有检出重用您的 GitHub CLI 登录，而不更改您的全局 Git 配置。对于自动化或现有仓库列表，传递包含 id、repository 和 full immutable revision 列的 CSV，并指定 --output-dir。

使用 npx codex-security bulk-scan --help 查看所有选项。CLI 使用 Incur 进行智能体友好的发现和结构化输出。

使用 --llms 查看命令清单，scan --schema --format json 查看命令模式，通过 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 将它们移动到 <output-dir>.previous-<timestamp>-<id>，并在原始路径的新空目录中开始扫描。添加 --dry-run 以查看目标而不移动文件。默认情况下，扫描仅报告。

在 CI 中使用 --fail-on-severity，当完成的扫描包含等于或高于所选严重性的发现时，退出 1。覆盖不完整和 CLI/运行时错误退出 2。不完整的扫描仍将可用的人类或 JSON 结果写入 stdout，并将覆盖警告写入 stderr，包括在仅报告模式下。

对于 CI，将机器可读输出保存在已检出的仓库之外并应用严重性策略。不完整的覆盖率和运行时错误仍会非零退出：

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

high > "$SCAN_ROOT/findings.

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

扫描默认使用 gpt-5.6-sol 并具有超高推理努力。使用 --model 切换模型。

使用 --codex 设置其他 Codex 选项：\nnpx codex-security scan . --model gpt-5.6-terra --codex 'model_reasoning_effort="high"'\n扫描报告其请求的路径以及实际排名、

文件审查、验证和攻击路径阶段。完成时显示发现严重性、覆盖率、经过时间、可用 token 和工作线程数、结果目录以及下一个有用命令。进度保持在 stderr；JSON 结果保持在 stdout。

创建客户端，选择仓库外部的私有输出目录，并在扫描后关闭客户端：\nimport { CodexSecurity } from "@openai/codex-security";\nconst security = new CodexSecurity();

\ntry {\nconst result = await security.run("/path/to/repository", {\noutputDir: "/path/outside/repository/results",\n});

\nconsole.log(result