Codex Security CLI 常见问题#

Codex 中文站说明： 本页围绕“Codex Security CLI 常见问题”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新，请以当前客户端为准。

解答有关 Codex Security 扫描、安全发现、误报、覆盖范围、成本和 CI 的常见问题。

查找有关从终端扫描仓库和管理安全结果的常见问题的答案。对于安装和首次扫描，请从 CLI 快速入门 开始。

仓库扫描#

谁可以使用 CLI#

@openai/codex-security 软件包是公开的。

运行扫描仍需获得 Codex Security 访问权限。为取得最佳效果，请使用已通过 Trusted Access for Cyber 验证的账号。

为什么登录后扫描仍使用 API key#

当环境中包含 OPENAI_API_KEY 或 CODEX_API_KEY 时，没有交互式终端的扫描以及 JSON 和 JSONL 扫描默认使用环境变量中的 API key，即使你已经成功通过 ChatGPT 或 access token 登录。若 ChatGPT 登录也可用，使用文本输出的交互式扫描会询问要选择哪种凭据。试运行不会提示选择，也不会加载凭据。

如需在扫描中使用已存储的凭据，请显式选择：

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

要强制使用 OPENAI_API_KEY 或 CODEX_API_KEY 中的 API key：

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

如需让已存储的凭据成为自动选择的默认值，请运行 unset OPENAI_API_KEY CODEX_API_KEY。所有支持的认证模式请参阅 CLI 参考。

批量仓库扫描如何工作#

使用 GitHub CLI 登录：

gh auth login

从 GitHub 账号或组织中发现并选择仓库：

npx @openai/codex-security bulk-scan

对于准备好的列表，请提供仓库 CSV 和输出目录：

npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--workers 4

请参阅运行批量安全扫描，了解 GitHub 发现、CSV 格式、批量扫描结果和可用选项。

中断的批量扫描可以恢复吗#

可以。使用原始 CSV 和输出目录运行相同的 bulk-scan 命令。 Codex Security 会跳过已完成的仓库。

添加 --max-attempts 3 以重试临时仓库或扫描错误：

npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--workers 4 \
--max-attempts 3

使用 partial 或 unknown 覆盖范围完成的扫描会保留其结果，并 使活动以代码 2 退出。即使使用 --max-attempts，也不会重试。

扫描如何使用架构和安全策略#

使用 --knowledge-base 传递架构文档、威胁模型或安全策略：

npx @openai/codex-security scan . \
--knowledge-base /path/to/architecture.md \
--knowledge-base /path/to/security-policies

Codex Security 使用这些文档作为当前扫描的上下文。有关支持的文件类型和目录行为，请参阅添加安全上下文。

安全发现与覆盖范围#

团队在哪里可以找到早期的扫描结果#

列出仓库的已保存扫描：

npx @openai/codex-security scans list /path/to/repository

使用结果中的扫描 ID 来检查其结果：

npx @openai/codex-security scans show SCAN_ID

每次完成的扫描都会将其报告、结果、覆盖范围和支持产物保存在一起。有关完整布局，请参阅扫描产物。

要检查已保存的扫描及其 worker 事件，请运行 scans logs SCAN_ID。这些日志不会经过脱敏，可能包含源代码或凭据。

CLI 无法保存扫描历史记录时怎么办#

Codex Security 会把扫描历史记录保存在工作台数据库中。如果默认状态目录不可写，请选择仓库之外的私有目录：

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

扫描如何区分新发现和已知发现#

列出某个仓库所有扫描中仍处于 open 状态的发现：

npx @openai/codex-security findings list /path/to/repository

列表会标明最新扫描中已确认的发现，以及未在该次扫描中确认、但仍为 open 的较早发现。

比较两次扫描中的发现：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比较操作会自动根据根本原因匹配发现、复用已保存的 匹配结果，并识别新增、持续存在、重新出现、已解决和未知的 发现。仅当后一次扫描覆盖了发现的原始目标和受影响路径，且不存在覆盖缺口时， 该发现才会被视为已解决。

误报反馈如何发挥作用#

检查已保存的扫描，找到安全发现的 occurrence ID：

npx @openai/codex-security scans show SCAN_ID

记录为什么该发现不适用：

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
--reason "The framework escapes this input before it reaches the query"

未来对同一仓库的扫描会将该解释作为上下文。这些扫描仍会独立检查当前源代码、控制措施和可达性。将发现标记为误报不会屏蔽规则、路径或漏洞类别。

有关命令的详细信息，请参阅安全发现参考。

为什么重复扫描会返回不同的结果#

即使扫描配置相同，AI 辅助扫描的结果也可能不同。首先重新运行基线扫描：

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

将基准扫描与新扫描进行比较：

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

当缺少上下文可能导致变化时，提供共享架构和安全指导。匹配可以识别运行中相同的潜在发现，但它并不使扫描具有确定性。直接重新检查任何消失的重要发现。

团队如何确认修复是否有效#

应用修复后，重新运行原始扫描：

npx @openai/codex-security scans rerun BEFORE_SCAN_ID

将原始发现与新扫描进行比较：

npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

确认新扫描覆盖了原始目标和受影响的路径，没有覆盖间隙。然后直接根据当前检出内容重新检查原始发现：

npx @openai/codex-security validate /path/to/original/findings.json \
"Recheck the SQL injection in src/orders.ts:42 against the current code"

仅缺少发现或扫描比较并不能证明修复有效。

覆盖不完全是什么意思#

覆盖范围可以是 complete、partial 或 unknown。在将扫描视为评审证据前，请评审 coverage.json 中排除的路径、延后处理的范围和未解决的问题。

即使没有严重性策略，部分或未知覆盖范围的扫描也会返回退出码 2。这些扫描仍然保留任何可用的安全发现和报告。当稍后的扫描未覆盖该结果的原始路径时，无法确定较早的结果不再存在。

自动化和成本#

扫描成本限制如何运作#

在开始扫描之前设置以美元为单位的估计成本限制：

npx @openai/codex-security scan . --max-cost 5

该限制是一个估计，而不是硬性支出上限。已在处理的请求可能会超出限制。Codex Security 在扫描停止时保留可用结果。

能否扫描 commit 和 pull request#

为暂存和未暂存的更改安装预提交安全检查：

npx @openai/codex-security install-hook

对于 pull request 检查，请扫描已提交的更改并设置严重性阈值：

npx @openai/codex-security scan . \
--diff origin/main \
--fail-on-severity high

当完整扫描发现安全问题达到或超过所选严重性时，会返回退出码 1。有关完整的 GitHub Actions 工作流、产物处理和 SARIF 导出，请参阅在 CI 中运行扫描。

其他应用可以直接运行扫描吗#

是的。使用 TypeScript SDK 启动扫描、选择目标、检查结果和覆盖范围、跟踪进度以及从应用或开发工具应用成本控制。

本站实践建议#

应用“Codex Security CLI 常见问题”中的安全设置时，应从最小权限开始，再根据实际任务逐步开放。涉及网络、密钥、生产环境或删除操作时，仍应保留人工确认。

Codex API 与国内使用#

在实践“Codex Security CLI 常见问题”相关功能时，如需为 Codex 配置 OpenAI-compatible API，可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。