在 GitHub Actions 中執行 Codex Security

在 GitHub Actions 中執行 Codex Security，審查拉取請求中的變更，或定時掃描儲存庫。該 Action 會安裝 CLI，儲存結構化報告，並新增作業摘要和源程式碼註解。先將結果僅用作參考，審查覆蓋範圍和掃描品質後，再設定強制執行。

準備工作流程

執行掃描需要 Codex Security 存取權限。按以下步驟新增 OpenAI API key：

1. 在 GitHub 儲存庫中，開啟 Settings → Secrets and variables → Actions。
2. 選擇 New repository secret。
3. 輸入名稱 CODEX_SECURITY_API_KEY，並將 OpenAI API key 貼上為值。儲存該機密。

下方的工作流程範例會自動將此機密傳遞給 Codex Security Action。你無需將 API key 寫入工作流程檔案。

僅對你信任的儲存庫和拉取請求執行工作流程。掃描會使用執行器的本機權限，且不會暫停以等待核准。將無關的憑據和部署步驟放在單獨的作業中。

新增 GitHub Actions 工作流程

定時掃描儲存庫

以下工作流程會在每週一 UTC 時間 07:23 掃描預設分支。你也可以從 GitHub 的 Actions 選項卡手動執行它。它使用 x64 GitHub 託管的 Ubuntu 24.04 執行器，並自動設定所需的沙箱。

1. 在儲存庫中，選擇 Add file → Create new file。
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: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

      - 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@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
        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 需要 Node.js 24 和 Python 3.11 或更高版本，此執行器已提供這些環境。沙箱設定會安裝 bubblewrap 包，並在掃描前載入隨附的 AppArmor 設定檔。在此執行器上，僅安裝該包還不夠。

如需手動執行工作流程，請開啟 Actions → Codex Security repository → Run workflow。開啟一次已完成的執行，檢視摘要、註解和可下載的報告。

由於 fail-on-severity 為 none，發現的問題只會記錄在報告中。掃描器錯誤和必需的報告生成錯誤仍會導致作業失敗。

如需掃描指定資料夾，請在掃描步驟的 with 塊中新增以換行分隔的字面路徑：

paths: |
  src/api
  src/auth

路徑要求使用 scope: repository，且不會展開 glob 模式。對於差異掃描，請省略 paths。保留 persist-credentials: false，並在檢出程式碼後立即執行掃描。

掃描拉取請求中的變更

使用同一個機密，建立 .github/workflows/codex-security-pr.yml：

name: Codex Security PR

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read

concurrency:
  group: codex-security-pr-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  security:
    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
    name: Codex Security
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    steps:
      - name: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

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

      - name: Scan PR changes
        id: security
        uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
        with:
          scope: diff
          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 }}

從同一儲存庫中的分支發起或更新 PR。該 Action 使用完整歷史記錄尋找確切的合併基點，並掃描截至已檢出的 PR 頭部提交的變更。在 PR 的 Checks 下檢視 Codex Security 檢查。先將發現的問題僅用作參考，準備好將其作為變更准入條件後，再選擇嚴重性策略。

此範例會跳過來自 fork 的 PR 和由 dependabot[bot] 發起的 PR。作業被跳過並不表示已完成安全審查。如需包含這些機器人 PR，請移除發起者排除條件，並且將 CODEX_SECURITY_API_KEY 設定為供 dependabot[bot] 使用的機密。該 Action 不支援 pull_request_target 或 workflow_run。

掃描器會讀取檢出程式碼中適用的 SECURITY.md 指導說明，包括 PR 中的策略變更。請將這些變更與程式碼一並審查。

設定可選的 Daybreak 存取權限

Daybreak 為可選項。兩個工作流程範例均使用 gpt-6-sol。如果你的組織已獲准使用 Trusted Access for Cyber，請在掃描步驟的 with 塊中移除 cyber-access-program 前的 #：

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

使用已啟用 Daybreak Blue 且有權存取 gpt-6-sol 的專案中的 API key。

該存取計劃的輸入也接受 standard。如果沒有 Daybreak 存取權限，請使用你的 API key 在標準安全防護措施下有權存取的模型，並省略 cyber-access-program 或將其設為 standard。選擇模型或存取計劃並不會授予存取權限。請參閱該 Action 的 Daybreak 存取權限指南。

導致掃描中止的拒絕響應或安全攔截會使 Action 失敗，即使 fail-on-severity 為 none 也是如此。該輸入控制的是問題處理策略，而非掃描器錯誤。

設定可選的掃描預算

兩個工作流程範例均省略了 max-cost，因此未設定預估費用停止閾值。如需設定，請通過 max-cost 輸入新增一個以美元計的正數金額。對於直接使用 CLI 的掃描，請使用 --max-cost。

費用限制要求 CLI 支援所選模型的定價。預估閾值並非硬性支出上限：正在進行的請求所產生的費用可能使總費用超出閾值。如果掃描因達到閾值而停止，請審查發現的問題和 coverage.json。有關費用限制行為，請參閱輸出和策略選項。

儲存報告並上傳 SARIF

範例設定了 upload-artifacts: "true"，以儲存可下載的報告，保留期為七天。報告可能包含源程式碼片段、漏洞證據和修復細節。請根據程式碼的需要選擇合適的保留期和儲存庫存取權限。該 Action 僅上傳其允許列表中經過驗證的報告；請勿遞迴上傳其 results-directory 輸出。

SARIF 上傳為可選項。對於私有或內部儲存庫，請在上傳前啟用 GitHub Code Security。將工作流程的 permissions 塊替換為：

permissions:
  contents: read
  security-events: write
  actions: read # Required for private repositories

然後在任一工作流程的掃描步驟之後新增以下步驟：

- 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 的輸入和輸出參考。

選擇嚴重性策略

GitHub 工作流程最初使用 fail-on-severity: none。如需在已完成的掃描發現高危或嚴重問題時使作業失敗，請更改掃描步驟的輸入：

fail-on-severity: high

在儲存庫規則中將 Codex Security 設為必需的狀態檢查，以便在 PR 作業失敗時阻止合併。GitHub 會將因條件而跳過的作業視為成功，即使它是必需的檢查也是如此。來自 fork 的 PR 和來自 dependabot[bot] 的 PR 會在未經掃描的情況下通過此檢查。如需阻止這些跳過情況，請要求掃描成功完成。

該 Action 遵循 CLI 的執行結果：

• 退出碼 0 會設定 scan-status: completed 和 policy-status: passed。
• 退出碼 1 會設定 scan-status: completed 和 policy-status: failed；當發現的問題達到或超過所設定的嚴重性級別時，該步驟會失敗。
• 退出碼 2 或程序中斷會設定 scan-status: failed 和 policy-status: not-evaluated；該步驟會失敗。
• 必需報告無效或缺失、檢出的程式碼發生變化、請求的產物上傳失敗以及執行時清理失敗，也會導致該步驟失敗。

掃描完成表示所設定的分析生成了有效結果。coverage.json 中的範圍排除項、暫緩調查項及其他說明不會產生單獨的掃描結果狀態，也不會繞過嚴重性策略。掃描完成並不保證已發現所有漏洞。評估結果時請檢視 coverage.json。

要求掃描成功完成

如需更嚴格的策略，請新增一個單獨的門禁，即使掃描作業失敗或被 GitHub 跳過，它也會執行。掃描作業中的步驟無法檢查被跳過的作業，因為該作業的所有步驟都不會執行。

在 PR 工作流程中，將此 outputs 對映新增到現有的 security 作業，使其與 runs-on 和 steps 保持相同縮排：

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

然後在 jobs 下新增此作業，與現有的 security 作業並列：

security-gate:
  name: Codex Security gate
  needs: security
  if: ${{ always() }}
  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

將 Codex Security gate 設為此策略的必需狀態檢查。它要求掃描作業成功，且滿足 scan-status: completed。同時檢查這兩個條件，可以保留嚴重性策略、報告生成和清理造成的失敗，即使掃描本身已完成也是如此。

按照範例中的排除條件，此門禁會阻止來自 fork 的 PR 和來自 dependabot[bot] 的 PR。它也會阻止空差異和試執行，Action 會將這些情況標記為 skipped。該門禁不會掃描被排除的 PR。僅當這些情況應阻止合併時，才選擇此策略。

排查掃描問題

• 未知的 Git 引用或意外的差異： 使用 fetch-depth: 0 檢出 PR 頭部提交。
• 沙箱啟動錯誤： 在 Ubuntu 24.04 上，安裝 bubblewrap 包，並在 Action 執行前載入 AppArmor 設定檔。僅安裝該包不會載入所需的設定檔。
• 缺少憑據： 確認受信任的工作流程可以使用 CODEX_SECURITY_API_KEY，且它已對映到掃描步驟的 OPENAI_API_KEY 環境變數。
• Python 設定錯誤： 該 Action 需要 Python 3.11 或更高版本。
• 覆蓋範圍說明： 檢視 coverage.json 中的範圍排除項和暫緩調查項。這些說明不會導致執行失敗，也不會繞過嚴重性策略。
• 缺少 SARIF： 檢查 scan-status、report-status 和 sarif-upload-ready。如果缺少可選的 SARIF，Action 會發出警告，但不會更改掃描結果狀態；請求的產物上傳失敗仍會導致作業失敗。
• SARIF 上傳錯誤： 確認你的組織已為儲存庫啟用 GitHub Code Security，且工作流程已授予 actions: read、contents: read 和 security-events: write。

有關所有命令、標誌、產物和輸出欄位，請參閱 CLI 參考。有關其他供應商，請參閱 CI/CD 概述。