如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

在 GitHub Actions 中运行 Codex Security

使用 Codex Security Action 扫描 Pull Request 和代码仓库,保存报告,上传 SARIF,并配置阻止合并的规则。

在 GitHub Actions 中运行 Codex Security,可以审查 Pull Request 中的更改,也可以定期扫描代码仓库。该 Action 会安装 CLI、保存结构化报告,并添加作业摘要和源码注释。建议先让工作流只报告发现的问题,评估扫描覆盖范围和质量后,再配置阻止合并的规则。

准备工作流

运行扫描需要具备 Codex Security 访问权限。请按以下步骤添加您的 OpenAI API 密钥:

  1. 在 GitHub 代码仓库中,打开设置 → 机密和变量 → Actions。
  2. 选择新建代码仓库机密。
  3. 输入 CODEX_SECURITY_API_KEY 作为名称,将您的 OpenAI API 密钥粘贴到值字段中,然后保存机密。

下方的工作流示例会自动将此机密传递给 Codex Security Action。您无需在工作流文件中写入 API 密钥。

仅对您信任的代码仓库和 Pull Request 运行此工作流。扫描使用运行器的本地权限,不会暂停以等待审批。请将无关的凭据和部署步骤放在其他作业中。

添加 GitHub Actions 工作流

扫描费用: 这些工作流使用您的 API 密钥,可能会产生费用。定期扫描示例省略了 max-cost。Pull Request 工作流将每次扫描的预估费用阈值设为 5 美元。正在处理的请求可能会使费用超过该阈值。请参阅设置可选的扫描预算。

定期扫描代码仓库

以下工作流在每周一 UTC 时间 07:23 扫描默认分支。您也可以从 GitHub 的 Actions 选项卡手动运行它。工作流使用由 GitHub 托管的 x64 Ubuntu 24.04 运行器,并自动配置所需的沙盒。

  1. 在代码仓库中选择添加文件 → 创建新文件。
  2. 将文件命名为 .github/workflows/codex-security-repository.yml。
  3. 粘贴以下工作流,并将文件提交到默认分支。
name: Codex Security repository

on:
  workflow_dispatch:
  schedule:
    - cron: "23 7 * * 1" # Mondays at 07:23 UTC

permissions:
  contents: read

jobs:
  security:
    runs-on: ubuntu-24.04
    timeout-minutes: 120
    steps:
      - name: Check out the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Scan the repository
        id: security
        uses: openai/codex-security@a98b35d7eef9f85c298c86229445bb64ac427aaf # action-v0.9.1
        with:
          scope: repository
          model: gpt-6-sol
          # For approved Daybreak Blue access, uncomment the next input.
          # cyber-access-program: daybreak_blue
          effort: high
          fail-on-severity: none
          upload-artifacts: "true"
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

该 Action 会在使用扫描凭据前检查 Codex 沙盒。在 GitHub 托管的 Ubuntu 24.04 虚拟机上,它会安装所需的软件包,并在需要时加载 AppArmor 配置文件。如果使用自托管运行器或在作业容器中运行扫描,请提供可用的沙盒、Linux x64 环境、Node.js 24 以及 Python 3.11 或更高版本。

要手动运行工作流,请打开 Actions → Codex Security repository → 运行工作流。打开一条已完成的运行记录,即可查看摘要、注释和可下载的报告。

由于 fail-on-severity 设为 none,扫描只报告发现的问题,不会因此判定作业失败。扫描器出错或处理必需报告时出错,仍会导致作业失败。

要扫描指定文件夹,请在扫描步骤的 with 块中逐行填写确切路径:

paths: |
  src/api
  src/auth

指定路径时必须设置 scope: repository,路径中的通配符不会展开。扫描差异时,请省略 paths。请保留 persist-credentials: false,并在检出代码后立即运行扫描。

扫描 Pull Request 中的更改

  1. 将 Pull Request 工作流复制到 .github/workflows/codex-security-pr.yml。将 REPLACE_WITH_REVIEWED_COMMIT 替换为 a98b35d7eef9f85c298c86229445bb64ac427aaf,这是 action-v0.9.1 对应的发布提交。
  2. 选择您的 API 密钥有权访问的模型。模板将每次扫描的预估费用阈值设为 5 美元,并在发现高危或严重问题时将扫描步骤判定为失败。如果只需报告发现的问题,请设置 fail-on-severity: none。
  3. 从同一代码仓库中的分支创建 PR。在检查选项卡下打开 Scan changes 查看结果。工作流还会报告一项以目标分支命名的检查,例如 Codex Security / main。

工作流会在扫描前核对 PR 的头提交、目标分支以及目标分支当前指向的提交,并在接受扫描结果前再次核对。如果目标分支已前移,请更新 PR 分支以触发新的扫描。要在合并时强制执行此要求,请遵循关于分支保护和确保扫描结果为最新的要求。

扫描作业会跳过来自派生代码仓库的 PR,因此这些 PR 无法通过此工作流的必需检查。要扫描 Dependabot 创建的 PR,还需将 CODEX_SECURITY_API_KEY 保存为 Dependabot 机密。

扫描器会从已检出的代码中读取适用的 SECURITY.md 指南,包括 PR 中对策略所做的更改。请在审查代码时一并审查这些更改。

配置可选的 Daybreak 访问权限

如果您的组织已获准使用网络安全可信访问计划,请在扫描步骤的 with 块中选择相应的访问计划和兼容的模型:

model: gpt-6-sol
cyber-access-program: daybreak_blue

请使用已启用 Daybreak Blue 且有权访问 gpt-6-sol 的项目的 API 密钥。

如果项目拥有 Red 访问权限,此参数也可设为 daybreak_red。要使用标准安全防护,请将 cyber-access-program 设为 standard。省略该参数时,Action 会使用 CLI 的默认设置。请参阅该 Action 的 Daybreak 访问指南。

如果模型拒绝请求或安全机制拦截请求,导致扫描中止,该 Action 就会失败,即使 fail-on-severity 设为 none 也是如此。此参数只决定如何处理扫描发现的问题,不影响对扫描器错误的处理。

设置可选的扫描预算

定期扫描工作流省略了 max-cost。要设置停止阈值,请将 max-cost 参数设为一个大于零的美元金额。如果直接通过 CLI 扫描,请使用 --max-cost。

要设置费用限制,CLI 必须支持所选模型的定价。正在处理的请求可能会使费用超过预估阈值。如果扫描因达到阈值而停止,请查看已发现的问题和 scan-manifest.json。有关费用限制的具体行为,请参阅输出和策略选项。

保存报告并上传 SARIF

设置 upload-artifacts: "true" 即可保存可下载的报告。默认保留期为七天。报告可能包含源码片段、漏洞证据和修复细节。请根据代码的实际情况设置报告保留期和代码仓库访问权限。该 Action 只上传允许列表中已通过验证的报告。请勿递归上传 results-directory 输出所指向的整个目录。

您可以选择是否上传 SARIF。对于私有或内部代码仓库,请在上传前启用 GitHub Code Security。扫描作业需要以下权限才能上传 SARIF:

permissions:
  contents: read
  security-events: write
  actions: read # Required for private repositories
  pull-requests: read # Required only in the PR workflow

然后,在任一工作流的扫描步骤之后添加以下步骤:

- name: Upload security findings
  if: ${{ always() && steps.security.outputs.sarif-upload-ready == 'true' }}
  uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
  with:
    sarif_file: ${{ steps.security.outputs.sarif-path }}
    sha: ${{ steps.security.outputs.scanned-sha }}
    ref: ${{ steps.security.outputs.analysis-ref }}
    category: codex-security-repository

对于 PR 工作流,请使用 category: codex-security-pr,以便按类别区分不同扫描范围的报告。请在扫描步骤中保留 id: security。即使发现的问题导致严重性策略检查失败,仍可上传完整且已通过验证的报告。如果扫描失败或中断、差异为空,或执行的是试运行,则不会上传 SARIF。

有关所有设置、状态字段和报告路径,请参阅该 Action 的输入和输出参考。

选择严重性策略

定期扫描工作流最初使用 fail-on-severity: none。如果希望在已完成的扫描发现高危或严重问题时将扫描步骤判定为失败,请使用 PR 工作流中的设置:

fail-on-severity: high

对于每个受保护的目标分支,请将 GitHub Actions 应用提供的对应检查设为必需检查。例如,对于 main 分支,应要求通过 Codex Security / main。GitHub 会将根据条件跳过的作业视为成功。工作流的必需检查还会验证扫描作业是否已运行。它接受已完成的扫描,也接受经核实为空的差异。如果差异为空时也要阻止合并,请要求扫描成功且已完成。

该 Action 根据 CLI 的执行结果确定状态:

  • 退出码为 0 时,设置 scan-status: completed 和 policy-status: passed。
  • 退出码为 1 时,设置 scan-status: completed 和 policy-status: failed。扫描发现的问题达到或超过配置的严重性级别,导致该步骤失败。
  • 退出码为 2 或进程中断时,设置 scan-status: failed 和 policy-status: not-evaluated,该步骤失败。
  • 必需的报告无效或缺失、已检出的代码发生变化、指定的构件上传失败,或运行时清理失败,也会导致该步骤失败。

要求扫描成功且已完成

要实施更严格的策略,请添加独立的合并检查,即使扫描作业失败或被 GitHub 跳过,这项检查也会运行。扫描作业被跳过时,其中的所有步骤都不会运行,因此无法在该作业内部检查它是否被跳过。

PR 工作流通过 security 作业输出扫描状态:

outputs:
  scan-status: ${{ steps.security.outputs.scan-status }}

然后在 jobs 下添加以下作业,与现有的 security 作业并列:

security-gate:
  name: ${{ github.event.action == 'edited' && github.event.changes.base == null && 'metadata / ' || '' }}Codex Security gate / ${{ github.event.pull_request.base.ref }}
  needs: security
  if: always() && (github.event.action != 'edited' || github.event.changes.base != null)
  runs-on: ubuntu-24.04
  steps:
    - name: Require a successful, completed scan
      env:
        SCAN_RESULT: ${{ needs.security.result }}
        SCAN_STATUS: ${{ needs.security.outputs.scan-status }}
      run: test "$SCAN_RESULT" = success && test "$SCAN_STATUS" = completed

对于每个受保护的分支,请将对应的合并检查和扫描检查都设为必需检查。对于 main 分支,应要求同时通过 Codex Security gate / main 和 Codex Security / main。要通过合并检查,扫描作业必须成功,且扫描状态必须为 scan-status: completed。同时检查这两个条件,可以确保即使扫描本身已完成,严重性策略检查、报告处理或清理环节的失败仍会阻止合并。

按照示例中的排除条件,这项检查会阻止合并来自派生代码仓库的 PR。差异为空或仅执行试运行时,该 Action 会将扫描标记为 skipped,此时这项检查也会阻止合并。这项检查不会扫描已排除的 PR。只有在上述情况都应阻止合并时,才选择此策略。

排查扫描问题

  • Git 引用未知或差异与预期不符: 使用 fetch-depth: 0 检出 PR 的头提交。
  • 缺少凭据: 确认受信任的工作流可以访问 CODEX_SECURITY_API_KEY,且该机密已映射到扫描步骤的 OPENAI_API_KEY 环境变量。
  • Python 配置错误: 该 Action 需要 Python 3.11 或更高版本。
  • 缺少 SARIF: 检查 scan-status、report-status 和 sarif-upload-ready。如果缺少可选的 SARIF 报告,该 Action 会发出警告,但不会改变扫描结果。如果指定的构件上传失败,作业仍会失败。
  • SARIF 上传错误: 确认您的组织已为该代码仓库启用 GitHub Code Security,并且工作流已授予 actions: read、contents: read 和 security-events: write 权限。

有关所有命令、标志、构件和输出字段,请参阅 CLI 参考。有关其他 CI/CD 提供商,请参阅 CI/CD 概览。