openai/codex-security

# Codex 安全 Codex Security 是一个开源的 CLI 和 TypeScript SDK，用于查找、验证和审查您拥有或已获授权评估的代码中的安全问题。 ## 要求 SDK 和 CLI 支持 macOS、Linux 和 Windows，并且需要 Node.js 22 或更高版本。扫描和导出结果还需要 Python 3.10 或更高版本。如果您使用 Python 3.10，请安装 `tomli` 包。安装该包或运行 `--help` 和 `--version` 不需要 Python。 在运行扫描之前，请使用您的 OpenAI 账户登录或提供 OpenAI API key。仅扫描您拥有或已获明确授权评估的代码库。 ## 安装并扫描 ``` npm install @openai/codex-security npx codex-security login npx codex-security scan /path/to/repo ``` 运行 `npx codex-security --help` 查看所有命令，运行 `npx codex-security scan --help` 查看扫描选项。 在远程或无头（headless）机器上，请使用 `npx codex-security login --device-auth`。对于 CI 和其他无人值守的扫描，请使用您的 shell、CI secret 或 secret 管理器设置 `OPENAI_API_KEY` 或 `CODEX_API_KEY`。 在 Windows 上，使用 PowerShell 设置 API key： ``` $env:OPENAI_API_KEY = "" npx codex-security scan C:\code\repository ``` 要存储 API key，请通过 stdin 传入： ``` printenv OPENAI_API_KEY | npx codex-security login --with-api-key ``` 使用 `npx codex-security login status` 检查已存储的登录信息，并使用 `npx codex-security logout` 将其移除。Codex Security 会复用现有的基于文件的 Codex 登录信息。如果 Codex 将凭证存储在系统 keyring 中，请在扫描前运行一次 `npx codex-security login`。 环境 API key 优先于已存储的登录信息。取消设置 `OPENAI_API_KEY` 和 `CODEX_API_KEY` 即可使用您的 ChatGPT 登录信息。login status 命令会报告当前生效的凭证来源，但不会打印其具体值，即使不存在已存储的登录信息时也是如此。 扫描代码库的子集或输出机器可读的结果： ``` npx codex-security scan /path/to/repo --model gpt-5.6-terra npx codex-security scan /path/to/repo --path src --path tests npx codex-security scan /path/to/repo --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf npx codex-security scan /path/to/repo --diff origin/main --json npx codex-security scan /path/to/repo --output-dir /path/outside/repo/results npx codex-security scan /path/to/repo --output-dir /path/outside/repo/results --archive-existing npx codex-security scan /path/to/repo --dry-run npx codex-security scan /path/to/repo --fail-on-severity high npx codex-security install-hook npx codex-security bulk-scan npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans npx codex-security scans list /path/to/repo npx codex-security scans list --scan-root /path/outside/repo/results npx codex-security scans show SCAN_ID npx codex-security scans rerun SCAN_ID npx codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID npx codex-security scans match --all npx codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID npx codex-security export /path/outside/repo/results --export-format sarif --output /path/outside/repo/results.sarif npx codex-security export /path/outside/repo/results --export-format csv --output /path/outside/repo/findings.csv npx codex-security export /path/outside/repo/results --export-format json --output /path/outside/repo/findings.json npx codex-security validate /path/outside/repo/findings.json "Possible SQL injection in src/query.ts:42" npx codex-security patch /path/outside/repo/findings.json "Missing authorization check in src/routes.ts:18" ``` `install-hook` 会在每次提交前扫描暂存和未暂存的更改。它遵循 `core.hooksPath`，不会替换已有的 hook，并会阻止高严重性的发现或失败的扫描。设置 `--fail-on-severity` 可更改阈值。 使用 `npx codex-security --version` 查看 CLI 版本，使用 `npx codex-security info --json` 查看包、插件和 runtime 版本、默认 model 和推理强度（reasoning effort）以及下一次扫描命令。添加 `--dry-run` 可检查生效的 model 和推理强度，而无需初始化 Codex 或连接网络。 输出目录必须位于扫描目录及任何包含它的 Git worktree 之外。在 macOS 和 Linux 上，现有的输出目录必须是当前用户私有的（`chmod 700`）。扫描产物可能包含源码片段、漏洞详情和复现步骤。请勿将它们放入代码库、公开的 issue 报告或共享位置中。 生成 SARIF 后，它会被写入 `/exports/results.sarif`。使用 `npx codex-security scan --help` 查看所有关于目标、输出和 runtime 的选项。 对多个文件或目录重复使用 `--knowledge-base PATH`。程序将递归搜索目录中的 Markdown、文本、PDF 和 Word (`.docx`) 文件。 使用 `gh auth login` 登录，然后运行 `npx codex-security bulk-scan` 来发现在过去 90 天内推送的 GitHub 代码库。已归档的代码库和 fork 将被排除在外。搜索代码库列表，选择要扫描的代码库，并在扫描前进行确认。 私有检出会复用您的 GitHub CLI 登录信息，而不会更改您的全局 Git 配置。对于自动化操作或现有的代码库列表，请传入包含 `id`、`repository` 和完整的不可变 `revision` 列的 CSV，并指定 `--output-dir`。使用 `npx codex-security bulk-scan --help` 查看所有选项。 CLI 使用 [Incur](https://github.com/wevm/incur) 实现对 agent 友好的发现和结构化输出。使用 `--llms` 查看 command manifest，使用 `scan --schema --format json` 查看 command schema，通过 `mcp add` 注册 MCP server，通过 `skills add` 同步 agent 技能，并使用 `completions bash|zsh|fish` 获取 shell 补全。扫描结果支持 `--format toon|json|yaml|jsonl` 和 `--full-output`。 使用 `info --json` 获取 SDK 和内置插件的元数据。MCP 仅公开此只读元数据命令；扫描、身份验证、导出、验证和 patching 仍仅限 CLI 使用，因为 MCP 传输无法取消正在进行的扫描。 如果输出目录已包含结果，请添加 `--archive-existing`。CLI 会将它们移动到 `.previous--`，并在原始路径下的一个全新空目录中启动扫描。添加 `--dry-run` 可查看目标位置而不移动文件。 默认情况下，扫描仅生成报告。在 CI 中使用 `--fail-on-severity`，以便在完成的扫描中包含达到或超过所选严重级别的发现时以状态码 1 退出。覆盖不完整以及 CLI/runtime 错误会以状态码 2 退出。覆盖不完整的扫描仍会将可用的人类可读或 JSON 结果写入 stdout，并将覆盖警告写入 stderr，在仅报告模式下也是如此。 对于 CI，请将机器可读的输出保存在检出的代码库之外，并应用严重性策略。覆盖不完整和 runtime 错误仍会以非零状态码退出： ``` SCAN_ROOT="$(mktemp -d)" npx codex-security scan . \ --diff origin/main \ --output-dir "$SCAN_ROOT/results" \ --json \ --fail-on-severity high > "$SCAN_ROOT/findings.json" ``` JSON 扫描保持非交互模式，即使 stderr 是终端也是如此。以交互方式运行 Codex 的命令（`validate`、`patch`、`login` 和 `logout`）会拒绝 `--json`。当选择 JSON 输出时，请将 CSV 导出内容写入文件。 扫描默认使用 `gpt-5.6-sol` 以及超高（extra-high）的推理强度。使用 `--model` 切换模型。使用 `--codex` 进行其他 Codex 设置： ``` npx codex-security scan . --model gpt-5.6-terra --codex 'model_reasoning_effort="high"' ``` 扫描会报告其请求的路径以及实际的排序、文件审查、验证和攻击路径阶段。完成扫描后会显示发现严重性、覆盖率、耗时、可用 token 数和 worker 数量、结果目录以及下一个有用的命令。进度信息保留在 stderr 中；JSON 结果保留在 stdout 中。 ## 使用 TypeScript SDK 创建一个 client，选择一个位于代码库之外的私有输出目录，并在扫描完成后关闭 client： ``` import { CodexSecurity } from "@openai/codex-security"; const security = new CodexSecurity(); try { const result = await security.run("/path/to/repository", { outputDir: "/path/outside/repository/results", }); console.log(result.reportPath); console.log(result.findings.findings.length); } finally { await security.close(); } ``` SDK 还支持路径和 diff 目标、preflight、进度回调、取消、安全知识库以及带类型的扫描结果。 ## 在 Docker 中运行批量扫描 包含的 Docker 镜像可在 Linux Docker 主机上根据提供的 CSV 运行非交互式的批量扫描。包含的 `compose.yaml` 配置了镜像、持久化文件以及经过强化的 Codex 命令沙箱。

配置 Docker 批量扫描

创建一个 `repositories.csv`，其中包含每个代码库的一个完整的、不可变的 Git 提交： ``` id,repository,revision payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567 ``` 创建私有的、持久化的结果和身份验证目录，并允许容器以您当前用户的身份写入文件： ``` mkdir -p results state chmod 700 results state export CODEX_SECURITY_USER="$(id -u):$(id -g)" docker compose build codex-security ``` 要从远程或无头（headless）的 Docker 主机进行一次性登录，请运行： ``` docker compose run --rm codex-security login --device-auth ``` 在浏览器中打开显示的验证 URL，并输入一次性代码。容器退出后，登录信息将保留在 `state/` 中。 或者，通过您的主机环境或 secret 管理器提供 `OPENAI_API_KEY` 或 `CODEX_API_KEY`。对于私有代码库，以相同方式提供 `GH_TOKEN` 或 `GITHUB_TOKEN`。Compose 仅将指定的、已配置的凭证传递给容器。 使用默认命令启动一个可恢复的四 worker 扫描： ``` docker compose run --rm codex-security ``` 在默认的超高（extra-high）推理设置下，全代码库扫描每个代码库可能需要数十分钟。请将大型活动作为异步批处理作业运行，并在整个运行过程中保持结果和身份验证目录处于挂载状态。 完成的报告、每个代码库的发现以及扫描 manifest 将显示在主机的 `results/` 目录中。该活动的工作台状态保留在 `results/.codex-security-state/` 中；可复用的 Codex 登录信息单独保留在 `state/` 中。这样便允许一个新的结果目录使用相同的登录信息启动单独的活动，而不会与之前的扫描发生冲突。使用原始 CSV 以及相同的 `results/` 和 `state/` 目录重新运行相同的命令，即可恢复被中断的扫描。 要选择不同数量的并行 worker 或重试失败的代码库，请覆盖默认的扫描命令： ``` docker compose run --rm codex-security \ bulk-scan /input/repositories.csv \ --output-dir /output \ --workers 8 \ --max-attempts 2 ``` 设置 `CODEX_SECURITY_CSV`、`CODEX_SECURITY_RESULTS` 或 `CODEX_SECURITY_STATE` 以使用 Compose 项目之外的现有文件或目录。设置 `CODEX_SECURITY_IMAGE` 以使用已批准且已构建好的镜像。访问 GitHub Enterprise Server 时设置 `CODEX_SECURITY_GIT_HOST`。请将凭证、代码库列表和结果排除在镜像和 Git 之外；包含的 ignore 文件会将它们排除在镜像构建和提交之外。 所有 CSV 文件，包括自定义名称的代码库清单，都将被排除在 Docker 构建上下文之外。Compose 会在运行时挂载选定的 CSV。 包含的 Compose 配置会丢弃所有 Linux capabilities，阻止获取新特权，以非 root 用户身份运行，并应用提供的默认拒绝 seccomp profile。Codex Security 在单独的非特权 Linux 沙箱中运行每个扫描命令。Docker 的默认 seccomp profile 会阻止该沙箱所需的 user 和 mount namespace；提供的 profile 仅允许必要的 namespace 操作。Linux 主机必须允许非特权 user namespace。某些 Docker Desktop 虚拟机还会额外限制嵌套的 mount namespace，因此请使用 Linux 主机进行生产级扫描。 对于没有 Docker Compose 的环境，等效的底层调用方式是： ``` docker run --rm --init \ --user "$(id -u):$(id -g)" \ --cap-drop ALL \ --security-opt no-new-privileges \ --security-opt "seccomp=$PWD/docker/codex-security-seccomp.json" \ --env OPENAI_API_KEY \ --env CODEX_API_KEY \ --env GH_TOKEN \ --env GITHUB_TOKEN \ --env CODEX_SECURITY_GIT_HOST \ --mount "type=bind,source=$PWD/repositories.csv,target=/input/repositories.csv,readonly" \ --mount "type=bind,source=$PWD/results,target=/output" \ --mount "type=bind,source=$PWD/state,target=/state" \ codex-security:local \ bulk-scan /input/repositories.csv \ --output-dir /output ``` 提供 GitHub token 时，镜像会为 `github.com` 配置非交互式的 Git credential helper。该 token 既适用于 HTTPS 代码库 URL，也适用于 `git@github.com:` 代码库 URL，而无需挂载 SSH agent。该镜像绝不会将该 token 放入代码库 URL 中，也不会将其写入镜像层，或发送给另一个 Git 主机。需要时，请将 `CODEX_SECURITY_GIT_HOST` 设置为 GitHub Enterprise Server 实例的主机名。 使用 `--workers` 控制并发代码库扫描，使用 `--max-attempts` 重试失败项目。只要任何代码库失败，该命令就会返回非零状态。

## 扫描历史和重新运行 `npx codex-security scans list` 列出当前代码库的扫描记录。传入代码库路径可检查另一个检出，使用 `--scan-root DIR` 可按扫描产物目录进行过滤。`scans show SCAN_ID` 包含已保存的配置、发现和覆盖率。 历史记录保存在 `$CODEX_HOME/state/plugins/codex-security` 下现有的 Codex Security 工作台数据库中。设置 `CODEX_SECURITY_STATE_DIR` 可选择其他位置。 `scans rerun SCAN_ID` 会针对当前检出重复相同的配置。`scans match BEFORE_SCAN_ID AFTER_SCAN_ID` 会链接具有相同根本原因的发现；`scans match --all` 包含当前代码库的每一个可用的已完成扫描，包括其他 worktree 和克隆。使用 `--force` 可重新计算已保存的匹配项。 `scans compare BEFORE_SCAN_ID AFTER_SCAN_ID` 会读取已保存的匹配项，并识别出新增、持续存在、重新开启、已解决或未知的发现。当覆盖率不完整或未审查其原始位置时，缺失的发现仍为未知。 使用 `export` 可从已完成且已封存（sealed）的扫描创建 CSV、JSON 或 SARIF，而无需启动 Codex 或加载凭证。JSON 会保留已封存的发现文档。CSV 使用通用的发现列，将发现标记为 open，并且不包含本地工作台的分类（triage）状态。导出器在写入前会验证封存（seal），接受 `--output -` 用于 stdout，并且可以与 SARIF 一起使用 `--source-root /path/to/repo` 以添加源代码行指纹。运行 `npx codex-security export --help` 获取所有导出选项。 使用 `validate` 对候选发现运行内置的验证技能，并使用 `patch` 对安全问题运行内置的修复发现技能。每个位置输入都可以是一个文件（其内容将被读取到请求中）或文本字面量。这两个命令均在当前目录下运行。 对于 manifest，规范的扫描文档限制为 16 MiB，发现限制为 128 MiB，覆盖率限制为 32 MiB。过大的扫描会在封存（sealing）前被拒绝。 退出代码如下：`0` 表示完成的仅报告扫描或通过的策略，`1` 表示完成的策略违规，`2` 表示输入无效、覆盖不完整或 runtime/导出错误，`130` 表示中断，`143` 表示终止。 使用 `--dry-run` 或 `await security.preflight(...)` 可验证本地扫描输入并报告所选的凭证来源，而无需初始化 Codex加载凭证或启动扫描。Dry run 不会检查插件、探测 Python 或连接网络；其身份验证元数据也不会被验证。 ## 文档、支持与安全 - [Codex Security 概述](https://developers.openai.com/codex/security) - [CLI 快速入门和参考](https://developers.openai.com/codex/security/cli) - [TypeScript SDK 指南](https://developers.openai.com/codex/security/sdk) - [GitHub issues](https://github.com/openai/codex-security/issues) 用于报告 bug 和功能请求 - [安全策略](SECURITY.md) 用于私下报告漏洞和进行安全操作 - [贡献指南](CONTRIBUTING.md) 本项目基于 [Apache-2.0 License](LICENSE) 获得许可。

标签：MITM代理, OpenAI, TypeScript SDK, 内存规避, 自动化攻击, 请求拦截, 逆向工具, 错误基检测, 静态代码分析