项目简介

codex-security 是 OpenAI 官方推出的 Codex Security CLI 和 TypeScript SDK，用于查找、验证和修复代码中的安全漏洞。Apache-2.0 许可，主语言 TypeScript，原项目 GitHub 9959 stars。

• 原项目：https://github.com/openai/codex-security
• 中文版：https://github.com/yangshun2005/codex-security-cn
• npm 包：@openai/codex-security

它的核心思路是把「发现漏洞 → 验证漏洞 → 修复漏洞 → 提交 PR」压缩成一条命令链，让安全扫描融入日常开发和 CI 流水线。

环境要求

• Node.js 22.13.0 或更高版本（22.x 版本线）、Node.js 24.x 或 Node.js 26.x
• Python 3.10 或更高版本
• Codex 安全的访问权限（部分网络安全请求需到 chatgpt.com/cyber 申请「网络可信访问」审批）

快速开始

npm install @openai/codex-security
npx @openai/codex-security login
npx @openai/codex-security scan .

CI 环境无需交互登录，设置环境变量即可：

export OPENAI_API_KEY="<your-key>"   # 或 CODEX_API_KEY
npx @openai/codex-security scan .

环境 API 密钥会直接传给当前扫描，不会存储到 Codex 的凭据目录或系统密钥环——这对流水线安全至关重要。

核心命令详解

1. 基础扫描

npx @openai/codex-security scan .

扫描后显示发现结果摘要，交互式扫描会询问是否打开发现结果浏览器，可在其中查看完整详情、选择严重性阈值、挑选单个发现结果并为每个结果添加补丁指令。

2. 自动修复 + 分级阈值

# 修复高严重性和严重级别的问题
npx @openai/codex-security scan . --patch --patch-severity high --json

补丁验证后，叠加 --create-pr 自动提交已验证文件并打开 GitHub Pull Request：

npx @openai/codex-security scan . --patch --patch-severity high --create-pr

注意：普通扫描不会改动仓库文件，只有显式指定 --patch 才会动代码。

3. 深度扫描

npx @openai/codex-security scan . --mode deep --workers 2 --subagents 0 \
  --stop-after-no-new 3 --max-discovery-runs 10 --max-time-hours 1.5

深度扫描发现过程默认 96 小时后停止，--max-time-hours 可设置任意正数小时（最大 96）。达到限制时，已完成的发现结果会被保留并返回。

4. 多推理提供商

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

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

# Amazon Bedrock
export AWS_BEARER_TOKEN_BEDROCK="<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 凭据链。

5. 发现结果管理

# 查看仓库未关闭的发现结果
npx @openai/codex-security findings list [repository]

# 修复单个发现结果
npx @openai/codex-security patch OCCURRENCE_ID

# 修复已保存扫描中的选定结果
npx @openai/codex-security patch --scan SCAN_ID --severity high

# 对比两次扫描（按根因匹配，识别新增/持续/重新打开/已解决）
npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

6. Linear 集成

# 导入并修复 Linear Issue
npx @openai/codex-security patch --linear-issue SEC-123

# 发布扫描结果到 Linear 团队
npx @openai/codex-security publish scan /path/to/scan \
  --to linear --linear-team TEAM_ID --linear-project PROJECT_ID

每个发现结果会创建一个新 Issue，包含扫描 ID、受影响的代码位置、源代码片段和修复建议。

7. 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,
  maxTimeHours: 1.5,
});
console.log(result.reportPath);
await security.close();

容器化批量扫描

官方提供镜像和 Docker Compose 配置，可对固定到不可变 Git 修订版的仓库做非交互式、可恢复扫描，支持身份验证、私有结果存储和 Ubuntu AppArmor 加固。

上手建议

1. 先读中文版 README 了解全貌；
2. 在一个小仓库上跑一次基础扫描，观察结果质量；
3. 再逐步开启 --patch 和 --create-pr；
4. 接入 CI 前，确认密钥走环境变量、不落盘。

中文版价值

我已将 README 和核心文档完整中文化，中文版仓库：

https://github.com/yangshun2005/codex-security-cn

文档、命令说明、SDK 用法、容器化部署均可直接以中文阅读，大幅降低评估门槛。

如果这个项目对你有帮助，也欢迎动动小手去原仓库点个 Star，支持作者持续维护。