如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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 程式碼庫中,開啟 Settings → Secrets and variables → Actions。
  2. 選取 New repository secret。
  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. 在程式碼庫中選取 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: 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 虛擬機器上,Action 會安裝必要套件,並視需要載入 AppArmor 設定檔。若使用自架執行器或在作業容器內執行,請提供可正常運作的沙盒、x64 版 Linux、Node.js 24 和 Python 3.11 以上版本。

如要手動執行工作流程,請開啟 Actions → Codex Security repository → Run workflow。開啟已完成的執行紀錄,即可檢視摘要、原始碼註解及可下載的報告。

由於 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。在 Checks 分頁開啟 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。省略此參數時,會使用 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 應用程式提供的對應檢查設為必要檢查。例如,將 Codex Security / main 設為 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 參照不明或差異與預期不符: 簽出 PR 的最新提交時,請設定 fetch-depth: 0。
  • 缺少憑證: 確認受信任的工作流程可以存取 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 概覽。