对于追求代码安全与合规的开发者而言，利用独立的 Codex Security CLI 在本地环境中进行扫描是一项核心任务。与通过 UI 进行的代码审查不同，CLI 提供了直接在开发工作流中集成安全检查的能力，并允许开发者对扫描结果进行深度离线审查。本文将详细说明从环境就绪、权限管理到报告解读的完整操作流程。
前置环境与安全准备
在执行扫描之前，首先需确保本地环境符合 Codex Security CLI 的依赖要求。官方目前支持的运行环境如下：
- Node.js: 要求版本为 24 或 26；若使用 Node.js 22，则必须为 22.13.0 或更高版本。
- Python: 要求 3.10 或更高版本。若使用 Python 3.10，需额外安装
tomli库。 - 访问权限: 若要使用 OpenAI 推理能力，必须拥有合法的 Codex Security 访问权限。针对特定存储库或账户，若涉及全库扫描，还可能需要启用“Trusted Access for Cyber”权限。
重要安全提醒：该 CLI 在运行时将完全继承您的操作系统权限，且扫描过程不会因交互确认而暂停。为避免潜在的风险，建议在启动扫描前，清理环境中与工作无关的敏感凭据，确保 CLI 的执行空间符合最小权限原则。如果您需要升级账户权限，可参考 Codex 充值入口 进行了解。
配置与登录步骤
通过 npx 可以直接运行官方公共包，无需繁琐的本地安装步骤。首先确认 CLI 版本：
npx @openai/codex-security --version
随后进行账户登录。直接执行以下命令：
npx @openai/codex-security login
在缺乏浏览器环境的服务器或远程开发机上，请添加 --device-auth 参数，并根据终端提示完成验证。如果您的开发环境中同时存在其他 API Key，建议在后续扫描命令中显式添加 --auth chatgpt 以确保使用正确的登录凭证。
关于更多 Codex 工具的上下文与背景信息，可阅读 Codex AI 简介 进一步了解其技术基础，或查阅更多 ChatGPT 编码实践 以优化工作流。
扫描执行流程：从 Dry-Run 到正式扫描
为了避免配置错误导致冗长的扫描任务失败，我们强烈建议先进行“试跑”（Dry-run）。
- 定义路径：指定本地仓库地址（REPOSITORY）以及存储扫描结果的目录（SCAN_DIR）。务必将结果目录设置在 Git 工作树之外，以保证数据的独立性。
- 执行 Dry-Run：
npx @openai/codex-security scan "$REPOSITORY" --auth chatgpt --output-dir "$SCAN_DIR" --dry-run
注意：Dry-run 仅用于验证输入路径是否可访问及 CLI 命令逻辑，它不会启动真实的扫描，也不会加载复杂的运行时凭据，因此无法预判最终的扫描认证是否完全成功。
- 正式扫描：移除
--dry-run即可开始执行。默认情况下，CLI 会在终端展示实时仪表盘。如果您是在 CI/CD 管道或非交互式环境中运行，建议添加--headless参数，以便以日志流形式查看进度，避免界面刷新产生的乱码。
解读报告与扫描状态
扫描结束后，所有的分析结果将存储在您指定的目录中。核心文件包括 report.md、scan-manifest.json、findings.json 和 coverage.json。
- 确认完成状态：检查
scan-manifest.json中的scan.status字段，确保扫描已正常结束。 - 分析覆盖率：通过
coverage.json查看被审阅的代码表面、被排除的路径以及未覆盖的区域。请注意，即使扫描完成，也不代表所有文件都经过了审查，代码覆盖缺口并不直接改变退出码。 - 理解退出码：
0：扫描成功完成。注意：这并不意味着没有漏洞，只是代表扫描执行过程无报错。1：发现了符合配置的严重级别阈值的漏洞。2：发生了错误（如输入错误、执行失败或完整性问题）。
在处理具体发现（Findings）时，应逐一核实受影响的代码、攻击前提及验证证据。请务必记住，基于源代码分析得出的漏洞并不等同于运行时复现，在决定进行修复（Remediation）前，必须确认提供的证据是否足够充分。
Q: 运行 scan 命令时没有交互窗口，如何判断扫描是否正常进行？
A: 如果在非交互式终端运行，CLI 默认会显示进度行。若要强制在交互式终端中查看进度行，请添加 --headless 参数。
Q: 扫描目录中包含了敏感源码和凭据，我该如何处理？ A: 扫描生成的 dashboard 和保存的日志可能包含源码片段或凭据信息，在共享或存档扫描目录之前，请务必进行内容审查。
Q: Dry-run 成功是否代表正式扫描一定能通过？ A: 不一定。Dry-run 仅验证本地输入路径，它不会加载凭据或检查 Python 环境的运行时配置，因此无法确保认证环节在正式扫描时不出错。
Q: coverage.json 显示有代码未覆盖，这算扫描失败吗？
A: 不算。退出码 0 表示扫描程序本身运行成功。覆盖率缺口是正常的审计情况，代表部分代码未被纳入本次审查范围，需手动在 coverage.json 中检查 excluded 路径。
Q: 扫描结果目录中的文件可以移动吗？
A: 建议将扫描目录保持完整，不要拆分。共享或存档时，应确保 scan-manifest.json、findings.json 和 coverage.json 与 report.md 处于同一目录下。
Q: 为什么我的扫描直接返回了退出码 2？
A: 退出码 2 通常表示发生了输入路径错误、运行时环境依赖缺失、结果完整性校验失败或必需的输出配置错误，请检查 scan_dir 的权限及 Python 依赖是否完整。