Codex Security CLI 常见问题

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

仓库扫描

谁可以使用 CLI

@openai/codex-security 软件包已公开发布。安装 CLI 和 SDK：

npm install @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 和输出目录运行相同的批量扫描命令。当记录的扫描产物保持完整时，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

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

使用 --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

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

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

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

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

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

匹配两次扫描中共享根本原因的结果：

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比较匹配的结果：

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