Codex Security

@openai/codex-security 是一个用于查找、验证和修复代码中安全漏洞的 CLI 和 TypeScript SDK。

某些网络安全请求和受保护发现需要通过 Trusted Access for Cyber 审批。要申请或检查您的访问权限，请访问 chatgpt.com/cyber。

快速开始

需要 Node.js 22.13.0 或更高版本（22.x 发布线）、Node.js 24.x 或 Node.js 26.x；Python 3.10 或更高版本；以及 Codex Security 的访问权限。

npm install @openai/codex-security
npx @openai/codex-security login
npx @openai/codex-security scan .
npx @openai/codex-security scan . --model gpt-5.6-terra --effort high
npx @openai/codex-security scan . --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
npx @openai/codex-security scan . --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10

对于 CI，请设置 OPENAI_API_KEY 或 CODEX_API_KEY，而无需登录。环境 API 密钥会直接传递给当前扫描，绝不会存储在 Codex 的凭据主目录或系统密钥环中。

要使用其他推理提供商，请设置其 API 密钥并选择模型：

export OPENROUTER_API_KEY="<your-openrouter-api-key>"
npx @openai/codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5

export FIREWORKS_API_KEY="<your-fireworks-api-key>"
npx @openai/codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b

export AWS_BEARER_TOKEN_BEDROCK="<your-bedrock-api-key>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna

Amazon Bedrock 还支持标准 AWS 访问密钥、配置文件、Web 身份、容器凭据以及默认的 AWS 凭据链。

本地登录遵循 Codex 配置的凭据后端，包括托管设备所需的系统密钥环。Codex Security 将登录和扫描凭据保存在同一个私有的持久状态目录中。

如果 ChatGPT 登录和 API 密钥同时可用，交互式扫描会询问使用哪个凭据。CI 和其他非交互式扫描保持现有的 API 密钥优先级。需要时请显式选择凭据：

npx @openai/codex-security scan . --auth chatgpt
npx @openai/codex-security scan . --auth api-key

要将您的 ChatGPT 登录设为自动默认，请取消设置任何已配置的 API 密钥：

unset OPENAI_API_KEY CODEX_API_KEY

扫描历史记录存储在 Codex Security 工作台状态目录中。如果该目录无法写入，请将 CODEX_SECURITY_STATE_DIR 设置为仓库之外的可写目录。

findings list [repository] 显示仓库各次扫描中的未关闭发现，并识别其最新扫描中未确认的发现。

scans compare BEFORE_SCAN_ID AFTER_SCAN_ID 按根本原因自动匹配发现，复用已保存的匹配项，并识别新的、持续存在的、重新打开的、已解决的或未知的发现。当覆盖不完整或其原始位置未被审查时，缺失的发现仍保持未知状态。

详细诊断

添加 --verbose 可将扫描诊断信息打印到 stderr：

npx @openai/codex-security scan . --verbose

CODEX_SECURITY_LOG_LEVEL=debug 也可启用诊断；LOG_LEVEL=debug 作为其回退。JSON 结果仍保留在 stdout 上。

详细诊断可能包含敏感数据。在分享前请审查本地日志。保存的失败摘要、批量扫描回执和交互式仪表板会省略包含可识别凭据的消息。

使用 npx @openai/codex-security scans logs SCAN_ID 检查扫描及其工作线程中保存的会话事件。

TypeScript SDK

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

const security = new CodexSecurity();
const result = await security.run(".");
await security.run(".", {
  mode: "deep",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
});

console.log(result.reportPath);
await security.close();

容器化批量扫描

使用官方镜像和随附的 Docker Compose 配置，对固定到不可变 Git 修订版的仓库执行非交互式、可恢复的扫描。有关身份验证、私有结果存储以及可选的 Ubuntu AppArmor 加固，请参阅容器快速开始。

传递 --knowledge-base PATH 以与每个仓库共享安全文档；重复该选项可指定多个文件或目录。

使用 --scan-prompt-file PATH 添加共享扫描指令，并添加一个 prompt CSV 列以提供仓库特定的指令。使用 --post-scan-prompt-file PATH 在每次扫描后运行后续操作，包括不完整或失败的扫描。

有关完整命令帮助、运行时默认值、原生多智能体工作线程限制、环境变量、深度扫描配置和 SDK 选项，请参阅包 README 和官方 CLI 参考。

codex-security npm-v0.1.8

分类