Codex 安全 CLI FAQ

身份非官方简体中文镜像

翻译状态 AI 翻译

来源版本官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

查找有关扫描仓库和管理终端中的安全发现的常见问题解答。关于安装和首次扫描，请从以下内容开始： CLI 快速入门。

仓库扫描

谁可以使用 CLI

该 @openai/codex-security 软件包是公开的。安装 CLI 和 SDK：

npm install @openai/codex-security

运行扫描需要 Codex Security 访问权限。为获得最佳结果，请使用一个已通过 Trusted Access for Cyber验证的账户。

为什么登录后扫描会使用 API 密钥

当你的环境包含 OPENAI_API_KEY 或 CODEX_API_KEY时，扫描在没有交互式终端的情况下，以及 JSON 和 JSONL 扫描默认使用环境 API 密钥，即使已经成功 ChatGPT 或使用访问令牌登录。带文本输出的交互式扫描会在 ChatGPT 登录也可用时要求你选择。试运行不会提示，也不会加载凭据。

若要在扫描中使用已存储的凭据，请显式选择它们：

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

若要要求使用来自 API 的 OPENAI_API_KEY 或 CODEX_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 会将扫描历史保存在 workbench 数据库中。如果默认状态目录不可写，请在仓库外选择一个私有目录：：

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

比较会识别新的、持续存在的、重新打开的、已解决的和未知的发现。只有当后一次扫描覆盖其原始目标和受影响路径且没有覆盖缺口时，某项发现才算已解决。

误报反馈如何工作

检查保存的扫描以找到该出现项 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，即使没有严重性策略。它们仍会保留任何可用的发现和覆盖范围。后续扫描如果未覆盖某项发现的原始路径，就无法证明该早先发现不再存在。

自动化和成本

扫描成本限制如何工作

在开始扫描前，在 USD 中设置估算成本限制：

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

该限制是估算值，并非严格的支出上限。已经进行中的请求可能会在超出限制后完成。 Codex 当扫描停止时，Security 会保留可用结果。

扫描可以检查提交和拉取请求吗

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

npx @openai/codex-security install-hook

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

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

完整扫描在发现严重性达到或超过 1 所选严重性的 issue 时，会返回退出代码。请参阅在 CI 中运行扫描，了解完整 GitHub Actions 工作流、工件处理和 SARIF 导出。

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

可以。使用 TypeScript SDK 从应用程序或开发者工具启动扫描、选择目标、检查发现和覆盖范围、跟踪进度并应用成本控制。