Codex Security 实战：用 AI 给项目做全面安全扫描
15 分钟掌握 OpenAI 官方安全扫描工具，从零配置 CLI、运行代码漏洞检测、在 TypeScript 项目中集成 SDK 自动化检查，导出威胁报告并生成 SECURITY.md，快速建立项目安全基线。
Codex Security 实战：用 AI 给项目做全面安全扫描
上周我把一个跑了两年的内部工具项目推到 GitHub，不到半天就收到了一个 issue：有人指出项目里硬编码了一段测试用的 AWS 密钥。虽然权限极小，但确实不太专业。日常开发节奏太快，安全扫描这种事总被往后排，直到有人提醒才意识到风险。
如果你也遇到过类似情况：项目越做越大，依赖越来越多，手动 review 安全漏洞根本顾不过来，那这篇教程就是为你准备的。我会带你用 OpenAI 官方推出的 Codex Security 工具，从零配置、跑一次完整的代码安全扫描、在 TypeScript 项目中集成 SDK 实现自动化检查，最后生成一份专业安全报告。整个过程大约 15-20 分钟，跑完你就能对项目安全状况心里有底。
环境准备
开始前确认环境满足要求：
- Node.js：22.13.0+（22.x 分支）、24.x 或 26.x
- Python：3.10+（3.10 需额外安装
tomli） - OpenAI API Key：需要 OpenAI 账号生成 API Key。申请过 Daybreak Blue 权限的教程中会涉及相关参数；没有的话用默认的
standard模式即可 - 一个待扫描的项目目录
bash
## 检查环境版本
node -v
python3 --version安装与登录
Codex Security 同时提供 CLI 和 TypeScript SDK，先从 CLI 快速跑通扫描流程。
bash
## 安装到当前项目（全局安装加 -g）
npm install @openai/codex-security
## 登录获取访问凭证
npx @openai/codex-security loginlogin 命令会打开浏览器引导完成 OAuth 授权。远程服务器或无图形界面环境下，用设备认证模式：
bash
npx @openai/codex-security login --device-auth终端会输出验证码，让你在另一台有浏览器的设备上打开指定 URL 完成授权，不用在服务器上折腾浏览器。
底层扫描依赖 AI 模型分析代码上下文，登录是为了获取 API 凭证。CI 环境中不需要走登录流程，在环境变量设置
OPENAI_API_KEY或CODEX_API_KEY即可。
运行第一次扫描
登录完成后，对目标项目执行扫描（. 表示当前目录）：
bash
## 扫描当前项目，使用标准模式
npx @openai/codex-security scan . \
--cyber-access-program standard扫描完成后，终端会列出发现的安全问题。指定扫描范围用 --path 过滤：
bash
## 只扫描 src 和 tests 目录
npx @openai/codex-security scan . --path src --path tests
## 扫描从 main 分支到当前 HEAD 的变更（提交前检查）
npx @openai/codex-security scan . --diff origin/main
## 深度扫描模式，更全面但耗时较长
npx @openai/codex-security scan . --mode deep日常开发不想每次提交都跑全量扫描，--diff 模式只检查变更部分，速度快、成本低。--mode deep 适合发版前或接手老项目时做深度体检。根据场景选模式，别盲目用最强的，省 token 也省时间。
生成 SECURITTY.md
很多开源项目根目录下有 SECURITY.md，告诉外部如何报告漏洞。Codex Security 可以帮你自动起草：
bash
## 为整个项目生成安全策略草稿
npx @openai/codex-security policy .
## 为特定服务组件生成，提供架构文档作为参考
npx @openai/codex-security policy . --path services/api --knowledge-base architecture.md生成的草稿保存在项目外部，需要审查后再决定是否放进仓库。不要直接当最终文件使用，AI 生成的内容需根据项目实际情况调整。这一步的价值在于搭好框架，省去从零搜索模板的麻烦。
实战：给 Express API 项目做安全扫描
假设你有一个 Express 编写的 REST API 项目：
my-api/
├── src/
│ ├── routes/
│ ├── middleware/
│ └── db.js
├── tests/
├── package.json
└── .env想在每次提交 PR 前自动做安全扫描：
1. 安装依赖
bash
cd my-api
npm install @openai/codex-security2. 添加扫描脚本
json
{
"scripts": {
"security-scan": "npx @openai/codex-security scan . --path src"
}
}团队成员只需 npm run security-scan 就能触发扫描，不用记一长串参数。
3. TypeScript 项目集成 SDK
希望嵌入构建流程或自定义脚本，SDK 更合适：
ts
import { CodexSecurity } from "@openai/codex-security";
const security = new CodexSecurity();
try {
const result = await security.run("./src");
console.log("扫描完成，报告路径：", result.reportPath);
// 可检查是否有严重级别漏洞，决定是否阻断构建
} finally {
await security.close();
}finally 块中的 close() 释放扫描过程占用的资源，别漏掉。
4. 导出报告
扫描完成后，结果可导出为 SARIF、JSON 或 CSV：
bash
## 导出威胁模型
npx @openai/codex-security export --artifact threat-model --output threatmodel.md
## 指定某次扫描 ID
npx @openai/codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md不指定 --scan 默认使用当前仓库最近一次完成的扫描结果。导出文件可直接附在 PR 描述或团队内共享。
常见踩坑提醒
Q1：提示需要 Daybreak Blue 权限但我没有？
去掉 --cyber-access-program daybreak_blue 参数，或显式设置为 --cyber-access-program standard。标准模式对大多数项目足够。
Q2：CI 环境中怎么配置认证？
在 CI job 环境变量设置 OPENAI_API_KEY 或 CODEX_API_KEY，跳过 login 步骤。GitHub Action 用 ${{ secrets.CODEX_SECURITY_API_KEY }} 引用。
Q3：扫描很慢或卡住？
深度模式会启动多个并行工作线程，大仓库耗时较长。CI 中用 --diff 做增量扫描，定期（如每周）跑一次全量。确认 Node.js 版本在要求范围内，版本不对可能导致扫描引擎异常退出。
Q4：支持其他 AI 提供商吗？
支持。除 OpenAI 外，还可用 Amazon Bedrock、OpenRouter 和 Fireworks AI。Bedrock 直接用 AWS 认证，无需单独登录 OpenAI。具体配置参考项目 provider 文档。
建立持续安全机制
回顾完整流程：安装 Codex Security 并通过 login 获取凭证 → 用 scan 命令扫描项目，按需选择 --path、--diff 或 --mode deep → 用 policy 生成 SECURITY.md 草稿，export 导出报告 → 在 TypeScript 项目中集成 SDK，嵌入自动化流程。
安全扫描不是一次性工作。建议先在本地跑全量扫描了解安全基线；CI 中配置 --diff 增量扫描确保每次修改不引入新问题；定期（每月或每季度）跑深度扫描，结合导出的威胁模型做代码 review。
项目仓库 openai/codex-security 的文档包含 GitHub Action 配置、批量扫描容器部署、Findings Service 详细指南。花 15 分钟跑一次扫描，可能帮你避免一次线上事故。