Codex Security CLI 快速入门
Codex Security CLI 快速入门
了解如何安装并登录 Codex Security CLI，选择 OpenAI 或 Amazon Bedrock，对已获授权的仓库运行本地安全扫描并查看报告、发现结果与覆盖范围。
Codex Security CLI 快速入门#
Codex 中文站说明： 本页围绕“Codex Security CLI 快速入门”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新，请以当前客户端为准。
设置 Codex Security、运行本地扫描，并查看报告、发现结果和覆盖范围。
Codex Security 可帮助安全和工程团队查找、确认并修复漏洞。使用其命令行界面 (CLI) 扫描您拥有或获准评估的仓库、持续查看发现结果，并在变更合入前进行检查。
@openai/codex-security软件包是公开的。运行扫描需要 Codex Security 访问权限。要在 Codex 中进行交互式扫描，请从 Codex Security 插件快速入门开始。有关已连接的 GitHub 仓库，请参阅 Codex Security 云端设置。
检查先决条件#
CLI 需要 Node.js 22.13.0 或更高版本。运行扫描或导出发现结果还需要 Python 3.10 或更高版本。有关更多详细信息，请参阅身份验证和先决条件。
设置并验证 CLI#
使用 npx 运行 CLI 并检查其版本：
npx @openai/codex-security --version列出可用命令：
npx @openai/codex-security --help另请参阅 CLI 参考。
登录#
在本地使用时，请使用 ChatGPT 账户登录：
npx @openai/codex-security login在远程或无头机器上，请使用设备身份验证：
npx @openai/codex-security login --device-auth对于 CI 和其他自动化工作流，请设置 OpenAI API key：
export OPENAI_API_KEY="<your-api-key>"有关 AWS 凭据，请参阅 Amazon Bedrock 设置。对于 OpenRouter 或 Fireworks，请设置提供商的 API key，并使用 --provider 和 --model 选择模型。
如果同时设置了 API key，但希望使用 ChatGPT 登录，请明确选择该方式：
npx @openai/codex-security scan . --auth chatgpt要强制使用环境中的 API key，请选择 API key 身份验证：
npx @openai/codex-security scan . --auth api-key根据您的账户和仓库，扫描完整仓库可能还需要 Trusted Access for Cyber。
准备扫描#
选择要扫描的仓库以及用于写入结果的目录。
REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results如果省略 --output-dir，Codex Security 会将结果保存在自己的持久状态目录中。结果可能包含源代码摘录和漏洞详细信息，因此请选择私有位置并采用适当的保留策略。
如果默认状态目录不可写，请在所扫描仓库之外选择一个可写目录：
export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state开始扫描前，请检查仓库、目标和输出目录：
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run试运行会检查本地输入，包括所有 --knowledge-base 路径，但不会启动 Codex、加载凭据或探测插件的 Python 解释器。
运行首次扫描#
运行标准扫描，并将结果保存在所选目录中：
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"交互式终端会显示实时扫描面板。添加 --headless 可改为显示纯文本进度行。CI 和没有交互式会话的终端会自动使用纯文本进度。
默认情况下，CLI 会将扫描进度和完成摘要写入 stderr。它不会将完整扫描结果输出到 stdout。扫描完成后会输出类似以下内容的摘要：
REPORT /path/outside/repository/codex-security-results/report.md
FINDINGS 2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
COVERAGE complete
ELAPSED 42s
RESULTS /path/outside/repository/codex-security-results如果相关信息可用，还会显示 token 用量和预估成本。要输出完整的机器可读 JSON 结果，请明确请求结构化输出：
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json扫描默认仅生成报告，因此发现结果会保留供本地审查。当您准备好在 CI 中运行扫描时，可以添加严重性阈值。
选择模型和推理强度#
扫描默认使用 gpt-5.6-sol，推理强度为 xhigh。任务有需要时，可选择其他模型和强度：
npx @openai/codex-security scan "$REPOSITORY" \
--model gpt-5.6-terra \
--effort high支持的强度级别包括 minimal、low、medium、high 和 xhigh。
查看结果#
打开 report.md 查看易读的结果。扫描目录还包含供自动化使用的结构化文件：
codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
└── results.sarif # when producedscan-manifest.json记录目标、范围、生成方和密封制品。findings.json记录每个发现结果的严重性、置信度、位置、证据和修复措施。coverage.json记录已审查的界面、排除项、延期工作、待解决问题和覆盖完整性。
覆盖范围可以是 complete、partial 或 unknown。在将扫描视为审查证据之前，请阅读所有延期区域或待解决问题。 CLI 参考介绍了完整的制品和输出契约。
选择下一次扫描#
当仓库包含独立的服务或软件包时，请使用路径扫描：
npx @openai/codex-security scan "$REPOSITORY" \
--path services/billing \
--path packages/auth审查基础修订版本与 HEAD 之间已提交的变更：
npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD审查相对于 HEAD 的暂存和未暂存变更：
npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD差异和工作树扫描要求仓库参数为 Git 工作树根目录。开始差异扫描前，请获取所选修订版本。
当仓库或路径需要更广泛的审查时，请使用深度模式：
npx @openai/codex-security scan "$REPOSITORY" --mode deep要控制发现工作进程、子智能体以及扫描停止时机：
npx @openai/codex-security scan "$REPOSITORY" \
--mode deep \
--workers 2 \
--subagents 0 \
--stop-after-no-new 3 \
--max-discovery-runs 10这些选项需要深度模式。该模式支持仓库和路径目标，但不支持差异或工作树扫描。在这里，--workers 控制单次扫描内的发现工作进程；bulk-scan --workers 控制并发仓库扫描。
添加架构和安全上下文#
提供架构文档、威胁模型或安全策略作为扫描上下文。这有助于 Codex Security 根据系统的实际工作方式评估发现结果：
npx @openai/codex-security scan "$REPOSITORY" \
--knowledge-base /path/to/architecture.md \
--knowledge-base /path/to/security-policies添加自定义扫描说明#
添加说明，让扫描聚焦于你的安全优先事项。可以使用第二个文件提供后续指令：
npx @openai/codex-security scan "$REPOSITORY" \
--scan-prompt-file /path/to/scan.md \
--post-scan-prompt-file /path/to/follow-up.md后续指令会在同一个已验证身份的 session 中运行，适用于成功完成的扫描，也适用于覆盖范围不完整或出错的扫描；扫描被取消或达到成本上限后不会运行。这两个选项也适用于 bulk-scan；CSV 的 prompt 列可添加仓库专用说明。
设置扫描预算#
使用 --max-cost 在预估模型成本超过以 USD 计价的限额时停止扫描：
npx @openai/codex-security scan "$REPOSITORY" --max-cost 5已在进行的请求可能会在略微超过限额后完成。如果扫描因成本限制而中止，部分扫描结果仍会保留在磁盘上。
在每次提交前扫描变更#
为仓库安装 Git pre-commit 安全检查：
npx @openai/codex-security install-hook该检查会在每次提交前扫描暂存和未暂存的变更。它会阻止高严重性发现结果和扫描错误，但不会替换现有的 pre-commit 脚本。
批量扫描仓库#
发现仓库前，请登录 GitHub：
gh auth login从您的 GitHub 账户或组织中发现并选择仓库：
npx @openai/codex-security bulk-scan交互式流程会排除已归档仓库和 fork。扫描前，它会要求您确认所选仓库。
要扫描准备好的仓库列表，请提供 CSV 和输出目录：
npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--workers 4再次运行相同命令即可恢复现有批量扫描。Codex Security 会跳过已完成的仓库。需要重试临时仓库错误或扫描错误时，请添加 --max-attempts 3。
有关 GitHub 发现、CSV 准备、活动结果和 Docker 设置，请参阅运行批量安全扫描。
在 Docker 中运行批量扫描#
如果您的访问权限包含 Codex Security Docker 镜像，请在 Linux Docker 主机上使用随附的强化 Compose 配置和安全配置文件。主机必须支持创建非特权用户命名空间。请提供仓库 CSV，将结果和登录状态保存在持久挂载目录中，并通过环境或密钥管理器提供凭据：
docker compose run --rm codex-security \
bulk-scan /input/repositories.csv \
--output-dir /output \
--workers 4容器会以无交互提示的方式运行批量扫描。如果希望以交互方式发现仓库，请在 Docker 外部使用 CLI。对于私有仓库，请通过环境或密钥管理器提供 GH_TOKEN 或 GITHUB_TOKEN。登录要求（包括账户和仓库访问权限）同样适用于容器化扫描。
重新查看已保存的扫描#
列出仓库中保存的扫描：
npx @openai/codex-security scans list "$REPOSITORY"从结果中复制扫描 ID，以检查其发现结果和配置：
npx @openai/codex-security scans show SCAN_ID要检查某次扫描及其 workers 保存的事件：
npx @openai/codex-security scans logs SCAN_ID保存的日志不会经过脱敏，可能包含源代码或凭据。分享前请先检查。
列出该仓库历次扫描中仍处于 open 状态的发现：
npx @openai/codex-security findings list "$REPOSITORY"如果最新扫描没有确认某项较早的发现，该发现仍会保持 open 状态。
要将已审查的发现结果标记为误报，请说明该发现不适用的原因：
npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
--reason "The route already checks permissions"后续扫描会考虑该说明，但仍会重新检查当前代码。
使用原始配置对当前检出内容重新运行同一扫描：
npx @openai/codex-security scans rerun SCAN_ID比较两次扫描，以查找新增、持续存在、重新出现、已解决或状态未知的发现结果：
npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID比较会自动按根本原因匹配发现结果，并复用已保存的匹配项。
有关批量扫描 CSV 格式、扫描历史筛选器和命令选项，请参阅 CLI 参考。
请继续选择符合您目标的工作流：
- 运行批量安全扫描，以发现 GitHub 仓库或扫描固定的 CSV 清单。
- 阅读 CLI 常见问题解答，了解扫描历史、误报反馈、覆盖范围和修复验证方面的答案。
- 在 CI 中运行扫描，以审查拉取请求、保留结果并设置严重性策略。
- 使用 CLI 参考，检查所有标志、输出格式、制品和退出代码。
- 集成 TypeScript SDK，从应用或开发者工具运行扫描。
本站实践建议#
应用“Codex Security CLI 快速入门”中的安全设置时，应从最小权限开始，再根据实际任务逐步开放。涉及网络、密钥、生产环境或删除操作时，仍应保留人工确认。
Codex API 与国内使用#
在实践“Codex Security CLI 快速入门”相关功能时，如需为 Codex 配置 OpenAI-compatible API，可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。