ChatGPT 中文教程
中文
联系我 goolvyouyou@gmail.com

Codex Security CLI 常见问题

解答有关 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 . --mode deep --max-time-hours 1.5

默认值为 96 小时。可以使用不超过 96 的任意正数，包括 小数。到达截止时间时，Codex Security 会停止尚未完成的工作进程，保留 已完成的标准扫描结果，并将其汇总到最终报告中。如果 没有任何工作进程完成源代码审查，报告会记录部分覆盖范围，且 CLI 会返回退出代码 2。

对于持久化设置或批量扫描活动，请在深度扫描 配置的 [deep_scan] 下设置 max_time_hours。

扫描成本限制如何运作

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

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

该限制是估算值，并非严格的支出上限。已经在 进行中的请求可能会在超过限制后完成。如果深度扫描在 Codex Security 汇总已完成的工作进程结果后达到限制，CLI 会保存覆盖范围不完整的已完成 报告，并以代码 2 退出。否则，它会保留 所有可用的部分输出。

能否扫描 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 启动扫描、选择目标、检查结果和覆盖范围、跟踪进度以及从应用或开发工具应用成本控制。