GitHub Actions で Codex Security を実行すると、Pull Request の変更内容をレビューしたり、リポジトリを定期的にスキャンしたりできます。アクションは CLI をインストールし、構造化レポートを保存して、ジョブのサマリーとソースコードへの注釈を追加します。まずはスキャン結果を参考情報として確認し、スキャンの対象範囲と品質を評価してから、マージをブロックする条件を設定します。
ワークフローの準備
スキャンを実行するには、Codex Security へのアクセス権が必要です。次の手順で OpenAI API キーを追加します。
- GitHub リポジトリで Settings → Secrets and variables → Actions を開きます。
- New repository secret を選択します。
- 名前に
CODEX_SECURITY_API_KEYと入力し、値に OpenAI API キーを貼り付けて、シークレットを保存します。
以下のワークフロー例では、このシークレットが Codex Security Action に自動的に渡されます。ワークフローファイルに API キーを記述する必要はありません。
ワークフローは、信頼できるリポジトリと Pull Request に対してのみ実行してください。スキャンはランナーのローカル権限で実行され、承認を待たずに進みます。スキャンに関係のない認証情報やデプロイ手順は、別のジョブに分けてください。
GitHub Actions ワークフローの追加
スキャン料金：これらのワークフローは API キーを使用するため、料金が発生する場合があります。どちらの例でも max-cost を省略しているため、推定料金に基づいてスキャンを停止するしきい値は設定されていません。スキャン 1 回あたりのしきい値を 5 米ドルにするには、max-cost: "5" を Codex Security Action の with 設定に追加します。このしきい値は支出の厳密な上限ではありません。すでに処理中のリクエストによって、実際の料金がしきい値を超えることがあります。料金計算に関する要件は「スキャン予算の設定（任意）」を参照してください。
リポジトリの定期スキャン
以下のワークフローは、毎週月曜日の 07:23（UTC）にデフォルトブランチをスキャンします。GitHub の Actions タブから手動で実行することもできます。GitHub がホストする x64 の Ubuntu 24.04 ランナーを使用し、必要なサンドボックスを自動的にセットアップします。
- リポジトリで Add file → Create new file を選択します。
- ファイル名を
.github/workflows/codex-security-repository.ymlにします。 - 以下のワークフローを貼り付け、デフォルトブランチにコミットします。
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 }}バージョンについて：どちらの例でも、Codex Security Action をコミット 3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 に固定しています。これは action-v0.3.0 リリースに対応し、CLI 0.3.0 をインストールします。固定するコミットを更新する前に、新しいアクションのリリース内容を確認してください。
ランナーの要件：このアクションに必要な Node.js 24 と Python 3.11 以降は、このランナーに用意されています。サンドボックスのセットアップでは、スキャン前に bubblewrap パッケージをインストールし、付属の AppArmor プロファイルを読み込みます。このランナーでは、パッケージをインストールするだけでは不十分です。
ワークフローを手動で実行するには、Actions → Codex Security repository → Run workflow を開きます。完了したワークフローの実行結果を開くと、サマリー、注釈、ダウンロード可能なレポートを確認できます。
fail-on-severity が none のため、検出結果は報告のみで、ジョブの失敗条件にはなりません。ただし、スキャナーでエラーが発生した場合や、必須のレポート処理に失敗した場合は、ジョブが失敗します。
特定のフォルダーをスキャンするには、スキャンステップの with ブロックに各フォルダーのパスを 1 行ずつ、そのまま記述します。
paths: |
src/api
src/authパスの指定には scope: repository が必要です。glob パターンは展開されません。差分をスキャンする場合は paths を省略します。persist-credentials: false の設定を維持し、チェックアウトの直後にスキャンを実行してください。
Pull Request の変更内容のスキャン
同じシークレットを使用して、.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 を作成するか、そのブランチの既存の PR を更新します。アクションはコミット履歴全体を使って正確なマージベースを特定し、そこからチェックアウトした PR の先頭コミットまでの変更をスキャンします。Codex Security チェックの結果は、PR の Checks タブで確認できます。まずは検出結果を参考情報として確認し、マージの可否を判定する準備が整ったら、重大度ポリシーを選択します。
この例では、フォークからの PR と dependabot[bot] が作成した PR をスキップします。ジョブがスキップされた場合、セキュリティレビューを実施したことにはなりません。このボットが作成した PR も対象にするには、ボットを除外する条件を削除し、CODEX_SECURITY_API_KEY を Dependabot 用のシークレットとして dependabot[bot] にも設定してください。このアクションは pull_request_target と workflow_run に対応していません。
スキャナーは、チェックアウトしたコードに適用される SECURITY.md の指示を読み込みます。PR にポリシーの変更が含まれていれば、その変更も反映されます。コードと併せてポリシーの変更内容もレビューしてください。
Daybreak アクセスの設定（任意）
Daybreak の利用は任意です。どちらのワークフロー例も gpt-6-sol を使用します。組織が Trusted Access for Cyber の承認を受けている場合は、コメント記号 # を cyber-access-program の行頭から削除します。この行はスキャンステップの with ブロックにあります。
model: gpt-6-sol
cyber-access-program: daybreak_blueDaybreak Blue が有効で、gpt-6-sol にアクセスできるプロジェクトの API キーを使用してください。
プログラムの指定には standard も使用できます。Daybreak へのアクセス権がない場合は、標準の安全対策のもとで API キーからアクセスできるモデルを使用し、cyber-access-program を省略するか standard に設定します。モデルやプログラムを選択するだけでは、アクセス権は付与されません。アクションの「Daybreak アクセスに関するガイド」を参照してください。
リクエストの拒否や安全対策によるブロックでスキャンが中止されると、fail-on-severity が none でもアクションは失敗します。この入力で指定するのは検出結果の扱いです。スキャナーのエラーには適用されません。
スキャン予算の設定（任意）
どちらのワークフロー例も max-cost を省略しているため、推定料金に基づく停止しきい値は設定されていません。しきい値を設定するには、max-cost に正の金額を米ドルで指定します。CLI から直接スキャンする場合は --max-cost を使用します。
料金を制限するには、選択したモデルの料金計算に CLI が対応している必要があります。しきい値は推定料金に基づくため、支出の厳密な上限にはなりません。処理中のリクエストによって料金がしきい値を超えることがあります。しきい値に達してスキャンが停止した場合は、検出結果と coverage.json を確認してください。料金制限の動作については「出力とポリシーのオプション」を参照してください。
レポートの保存と SARIF のアップロード
これらの例では upload-artifacts: "true" を設定し、ダウンロード可能なレポートを 7 日間保存します。レポートにはソースコードの抜粋、脆弱性を示す証拠、修正方法の詳細が含まれる場合があります。コードの内容に応じて、保存期間とリポジトリのアクセス権を設定してください。アクションがアップロードするのは、許可リストにある検証済みのレポートだけです。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-repositoryPR 用ワークフローでは category: codex-security-pr を使用し、スキャンの対象範囲ごとにカテゴリを分けます。スキャンステップの id: security はそのままにしてください。検出結果が重大度ポリシーに抵触した場合でも、生成と検証が完了したレポートはアップロードできます。スキャンが失敗または中断した場合、差分が空の場合、ドライランの場合は、SARIF はアップロードされません。
設定項目、ステータスフィールド、レポートのパスの一覧は、アクションの「入出力リファレンス」を参照してください。
重大度ポリシーの選択
GitHub ワークフローの初期設定は fail-on-severity: none です。完了したスキャンで重大度が高（high）または緊急（critical）の問題を検出したときにジョブを失敗させるには、スキャンステップの入力を次のように変更します。
fail-on-severity: highPR のジョブが失敗したときにマージをブロックするには、リポジトリのルールで Codex Security を必須のステータスチェックに設定します。GitHub は、必須のチェックでも、実行条件を満たさずスキップされたジョブを成功として扱います。そのため、フォークからの PR と dependabot[bot] が作成した PR は、スキャンを実行せずにこのチェックを通過します。スキップされた場合もマージをブロックするには、スキャンの成功と完了を必須にします。
アクションは 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 である必要があります。両方を確認することで、スキャン自体が完了していても、重大度ポリシー、レポート処理、クリーンアップによる失敗を判定に反映できます。
この例の除外条件では、判定用ジョブはフォークからの PR と dependabot[bot] が作成した PR のマージをブロックします。差分が空の場合やドライランの場合も、アクションが skipped と判定するため、マージがブロックされます。判定用ジョブは、対象から除外された PR をスキャンしません。これらの場合にマージを禁止したいときだけ、このポリシーを選択してください。
スキャンのトラブルシューティング
- 不明な Git ref または想定外の差分：PR の先頭コミットを
fetch-depth: 0でチェックアウトしてください。 - サンドボックスの起動エラー：Ubuntu 24.04 では、アクションを実行する前に
bubblewrapパッケージをインストールし、AppArmor プロファイルを読み込んでください。パッケージをインストールするだけでは、必要なプロファイルは読み込まれません。 - 認証情報の不足：
CODEX_SECURITY_API_KEYが信頼できるワークフローで利用可能であり、スキャンステップの環境変数OPENAI_API_KEYに割り当てられていることを確認してください。 - Python のセットアップエラー：このアクションには Python 3.11 以降が必要です。
- スキャン範囲に関する注記：対象範囲から除外された項目や保留された調査を
coverage.jsonで確認してください。これらの注記が原因で実行が失敗したり、重大度ポリシーの適用が免除されたりすることはありません。 - SARIF の欠落：
scan-status、report-status、sarif-upload-readyを確認してください。任意の SARIF が見つからない場合、アクションは警告を出しますが、スキャン結果は変わりません。一方、指定したアーティファクトのアップロードに失敗すると、ジョブは失敗します。 - SARIF のアップロードエラー：組織が対象リポジトリで GitHub Code Security を有効にしており、ワークフローに
actions: read、contents: read、security-events: writeの各権限が付与されていることを確認してください。
すべてのコマンド、フラグ、アーティファクト、出力フィールドについては「CLI リファレンス」を参照してください。その他のプロバイダーについては「CI/CD の概要」を参照してください。