运行 Codex 中的安全性 CI

身份 非官方简体中文镜像

翻译状态 AI 翻译

来源版本 官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

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

运行 Codex 安全性 CLI 在 CI 以审查拉取请求中的确切更改， 保留发现和覆盖范围，并可选择在指定 严重性级别使检查失败。先从建议性结果开始，审查扫描质量和运行时间，然后 添加适合你的仓库的严重性策略。

安装公开的 @openai/codex-security 包。运行扫描仍然 需要 Codex Security 访问权限。

本指南使用 GitHub Actions。相同的扫描和导出命令也适用于其他 CI 系统。

准备工作流

将一个 OpenAI API 密钥存储为名为 CODEX_SECURITY_API_KEY的仓库或组织密钥。

将此密钥直接映射到扫描步骤的 OPENAI_API_KEY 环境 变量。将凭据限定在扫描进程范围内，并使用 --auth api-key 显式选择它。

运行器需要：

• Node.js 22 或更高版本。
• Python 3.10 或更高版本。
• 已发布的 @openai/codex-security 包，安装在 仓库检出目录之外。
• 拉取请求的 head 和 base 历史记录，以便 Git 可以计算合并基点。
• GitHub Code Security 在上传 SARIF时，需为私有或内部仓库启用。

添加 GitHub Actions 工作流

创建 .github/workflows/codex-security.yml。在检出拉取 请求之前，将 @openai/codex-security@0.1.3 安装到 $RUNNER_TEMP/codex-security 下，使可信可执行文件可在 $RUNNER_TEMP/codex-security/node_modules/.bin/codex-security使用：

name: Codex Security scan

on:
  pull_request:

jobs:
  codex-security:
    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
      - name: Set up Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: "26"

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
        with:
          python-version: "3.14"

      - name: Install Codex Security
        run: |
          set -euo pipefail
          npm install \
            --prefix "$RUNNER_TEMP/codex-security" \
            --ignore-scripts \
            --no-audit \
            --no-fund \
            @openai/codex-security@0.1.3

      - name: Verify Codex Security
        env:
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
        run: |
          set -euo pipefail
          test -x "$CODEX_SECURITY_BIN"
          "$CODEX_SECURITY_BIN" --version

      - name: Check out the pull request
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Scan the pull request
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
          CODEX_SECURITY_STATE_DIR: ${{ runner.temp }}/codex-security-state
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          SCAN_DIR: ${{ runner.temp }}/codex-security-results
        run: |
          set -euo pipefail
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_SHA")"
          "$CODEX_SECURITY_BIN" scan . \
            --diff "$BASE_REVISION" \
            --head "$HEAD_SHA" \
            --auth api-key \
            --output-dir "$SCAN_DIR" \
            --json > "$RUNNER_TEMP/codex-security.json"

      - name: Export SARIF
        id: export-sarif
        if: always()
        env:
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
          SCAN_DIR: ${{ runner.temp }}/codex-security-results
          SARIF_FILE: ${{ runner.temp }}/codex-security.sarif
        run: |
          set -euo pipefail
          if test -f "$SCAN_DIR/scan-manifest.json"; then
            "$CODEX_SECURITY_BIN" export "$SCAN_DIR" \
              --export-format sarif \
              --source-root "$GITHUB_WORKSPACE" \
              --output "$SARIF_FILE"
            echo "available=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Upload SARIF
        if: always() && steps.export-sarif.outputs.available == 'true'
        uses: github/codeql-action/upload-sarif@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4
        with:
          sarif_file: ${{ runner.temp }}/codex-security.sarif
          ref: refs/pull/${{ github.event.pull_request.number }}/head
          sha: ${{ github.event.pull_request.head.sha }}
          category: codex-security

      - name: Preserve scan results
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: codex-security-results
          path: |
            ${{ runner.temp }}/codex-security-results
            ${{ runner.temp }}/codex-security.json
          if-no-files-found: warn
          retention-days: 7

该工作流会检出拉取请求 head，计算其合并基点，并 扫描这些修订版本之间已提交的更改。完整历史记录可保持 目标精确。 persist-credentials: false 会使仓库令牌不进入 已检出的 Git 配置。在检出前安装 CLI 并 运行其绝对路径，可避免仓库控制的可执行文件接触 扫描凭据。 --auth api-key 会显式选择作用域限定的 API 密钥。 扫描会将其历史记录保存在仓库之外的可写状态目录中。 。

--json 会向 stdout 写入一个完整的 JSON 文档，因此工作流可以直接保存 它。进度、完成摘要和错误仍保留在 stderr。这 不同于 codex exec --json，后者会发出 JSON Lines 事件流。

导出步骤会读取已完成且已封存的扫描，并写入 SARIF。它不会改动 Codex 运行时和凭据。扫描工件可能包含有漏洞的 源代码片段、证据和修复详情。请为你的仓库选择合适的访问控制和 较短的保留期限。

选择严重性策略

上述工作流仅生成报告，因为它省略了 --fail-on-severity。 准备好让发现影响检查后，请向 扫描命令添加阈值：

"$CODEX_SECURITY_BIN" scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --fail-on-severity high

支持的阈值包括 critical、 high、 medium和 low。一个 阈值会包含该严重性及以上级别的发现。

扫描步骤使用以下退出码：

退出	含义
0	扫描已完成且覆盖范围完整，任何已配置策略均已通过。
1	已完成的扫描包含达到或超过阈值的发现。
2	该 CLI 发现输入或运行时错误，或已完成的扫描覆盖范围不完整。
130	Ctrl-C 中断了扫描。
143	SIGTERM 终止了扫描。

覆盖范围为 partial 或 unknown 的扫描会返回 2，即使没有严重性 策略也是如此。 CLI 仍会写入其可用发现和覆盖范围。请先审查 中的延期区域 coverage.json 再将检查视为结论性结果。

使用现有结果目录重试

为每个 CI 作业使用新的运行器目录。对于持久化或自托管的 运行器，请使用 --archive-existing保留较早的结果：

"$CODEX_SECURITY_BIN" scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --archive-existing

该命令会归档较早的结果，并从空的扫描目录开始。

排查 CI 扫描问题

• 未知 Git 引用或意外 diff： 获取 base 和 head 历史记录， 计算合并基点，并显式传入两个修订版本。
• 受保护或非空的输出目录： 选择一个位于 外围 Git 工作树之外的私有目录。当 --archive-existing 目录已包含结果时，使用 。
• 缺少凭据： 确认 CODEX_SECURITY_API_KEY 仓库 密钥可供可信工作流使用，并直接映射到扫描 步骤的 OPENAI_API_KEY 环境变量。
• 扫描历史记录错误： 将 CODEX_SECURITY_STATE_DIR 设置为仓库之外的可写 目录。
• Python 设置错误： 确认运行器使用 Python 3.10 或更高版本。
• 覆盖范围不完整： 审查 coverage.json，包括延期的表面 和未解决的问题，然后使用合适的目标或环境重新运行。
• SARIF 导出错误： 确认扫描已完成且完整扫描 目录可用。导出会在写入 SARIF前验证已封存的工件。
• SARIF 上传错误： 对于私有或内部仓库，请确认 你的组织已为该仓库启用 GitHub Code Security，并且 工作流授予 actions: read、 contents: read和 security-events: write。

有关每个命令、标志、工件和输出字段，请参阅 CLI 参考。有关基于插件的交互式 CI 审查，请参阅 审查代码更改的安全性。