github-actions-hardening

GitHub Actions の堅牢化

GitHub Actions のワークフローに特化したセキュリティレビュー担当です。一般的なセキュリティスキャナーが探すアプリケーションコードの脆弱性ではなく、トリガーの種類、トークンのスコープ、文字列の補間など、Actions 固有の脅威モデルについて分析します。危険なコードは YAML 自体と、スクリプトの実行前に GitHub が ${{ }} 式をシェルへ展開する仕組みにあるため、ほとんどのワークフローのリスクは言語リンターでは検出できません。

このスキルを使用する場面

次のような依頼で、このスキルを使用してください。

• .github/workflows/ 配下のファイルのレビュー、監査、または堅牢化
• 新しいワークフローを作成し、安全な設定をデフォルトにしたい場合
• pull_request_target、workflow_run、または issue_comment トリガーを使用するワークフロー
• GITHUB_TOKEN の権限や permissions: キーに関する質問
• アクションをタグやブランチではなくコミット SHA に固定する方法
• run: ステップで信頼できない入力（Issue のタイトル、PR の本文、ブランチ名、コミットメッセージ）を処理する方法
• Actions からの OIDC／クラウド認証、または CI でのシークレットの取り扱い
• パブリックリポジトリでのセルフホストランナー
• 「このワークフローは安全ですか？」「CI を安全にしてください」「この GitHub Action をレビューしてください」などの依頼

核心となる考え方

ワークフローでは、${{ <expr> }} はシェルの実行前にランナーによってスクリプトへ展開されます。 したがって、次のようなステップは、

- run: echo "Title: ${{ github.event.issue.title }}"

変数を渡しているのではなく、攻撃者が制御できるテキストをシェルコマンドへ直接貼り付けています。"; <attacker-command> # というタイトルの Issue はスクリプトに連結され、実行されます。この仕組みは、実際の Actions の脆弱性で最もよく見られるものであり、モデルも日常的に生成してしまいます。外部のコントリビューターが影響を与えられるデータを含むすべての ${{ }} を、コードインジェクションの侵入口として扱ってください。

実行ワークフロー

レビューするすべてのワークフローについて、次の手順を順番どおりに実行してください。

手順 1 — トリガーと信頼レベルを把握する

すべての on: トリガーを読み、ワークフローの権限を分類します。

• push、pull_request（同じリポジトリから）→ コントリビューター自身の信頼レベルで実行
• フォークからの pull_request → 読み取り専用トークンで実行され、シークレットなし（設計上安全）
• pull_request_target、workflow_run、issue_comment、issues → ベースリポジトリのコンテキストで、読み取り／書き込みトークンとシークレットへの完全なアクセス権を使用して実行されますが、外部のコントリビューターからトリガーされる可能性があります。これらは危険なトリガーです。

信頼レベルの全一覧については、references/triggers-and-privilege.md を参照してください。

手順 2 — スクリプトインジェクションを探す

すべての run: ブロック、actions/github-script のすべての script:、カスタムアクションへのすべての入力について、${{ }} 式を列挙し、攻撃者が制御できるデータに解決されるものがないか確認します。リスクの高いコンテキストは次のとおりです。

• github.event.issue.title、github.event.issue.body
• github.event.pull_request.title、github.event.pull_request.body、.head.ref、.head.label
• github.event.comment.body、github.event.review.body
• github.event.pages.*.page_name、github.event.commits.*.message、github.event.head_commit.*
• github.head_ref およびフォークの作成者が設定できるすべての github.event.* フィールド

侵入口の完全な一覧と安全なパターンへの修正方法については、references/injection.md を参照してください。

手順 3 — 特権トリガーで信頼できないコードを実行しないことを確認する

pull_request_target または workflow_run ワークフローが PR／フォークのコードをチェックアウトし（ref: ${{ github.event.pull_request.head.sha }}）、その後に実行している（ビルド、テスト、スクリプトのインストール、ライフサイクルスクリプトを実行する npm install など）場合、特権トークンに対するリモートコード実行です。重大度「CRITICAL」として報告してください。安全なパターンは、ワークフローを2つに分けることです。信頼できないコードを実行する権限のない pull_request ワークフローと、その結果のみを使用する特権付きの workflow_run ワークフローです。

ステップ 4 — permissions: を監査する

• permissions: ブロックがない場合、ワークフローはリポジトリのデフォルト設定を継承します。この設定では、すべてに読み取り／書き込みできる可能性があります。その旨を指摘してください。
• 最上位に permissions: {}（すべて拒否）または contents: read を設定し、そのうえでジョブごとに必要最小限の権限を付与するよう提案してください（例：コメントを投稿するジョブにのみ pull-requests: write を設定）。
• ステップで実際には必要のない permissions: write-all や広範な write スコープがあれば指摘してください。

スコープごとのガイダンスと OIDC の設定については、references/permissions-and-tokens.md を参照してください。

ステップ 5 — アクション参照を監査する（サプライチェーン）

すべての uses: について：

• サードパーティのアクション（actions/* または github/* 以外）は、タグやブランチではなく、40 文字の完全なコミット SHA に固定する必要があります。タグやブランチは変更可能です。侵害された上流のアクションによって v1 が悪意のあるコードに書き換えられ、トークンやシークレットを使って実行されるおそれがあります。
• ファーストパーティの actions/* はリスクが低いものの、SHA に固定することを引き続き推奨します。
• @main、@master、またはブランチ参照があれば、HIGH として指摘してください。これらは「最新」を示し、いつでも変更される可能性があります。
• 人が読めるバージョンを末尾のコメントに記載してください：uses: foo/bar@<sha> # v2.1.0

固定方法、アクション向け Dependabot、アーティファクト／キャッシュのリスクについては、references/supply-chain.md を参照してください。

ステップ 6 — シークレットと出力の取り扱いを確認する

• シークレットをエコー、出力、ログへの書き込みによって露出させないでください。シークレットを扱うステップでは set -x や bash -x を使わないでください。
• 信頼できないコードを実行するステップや、信頼できないサードパーティアクションにシークレットを渡さないでください。
• $GITHUB_ENV または $GITHUB_OUTPUT に書き込まれる信頼できない複数行データは、環境変数やステップ出力をインジェクションするおそれがあります。ランダムな区切り文字を使うヒアドキュメント形式を使用し、ユーザー入力をそのまま書き込まないでください。
• actions/checkout はデフォルトでトークンをディスク上に残します。その後のジョブで信頼できないコードを実行する場合は、persist-credentials: false を設定してください。

ステップ 7 — レポートを作成する

references/report-format.md の形式で指摘事項を出力してください。まず重大度の概要表を示し、その後、ファイル名、該当する YAML の正確な記述、平易な言葉でのリスク説明、具体的な修正前／修正後を種類ごとにまとめてください。変更を自動適用せず、レビュー用に提示してください。

重大度ガイド

重大度	意味	例
🔴 CRITICAL	外部コントリビューターがトークン／シークレットを窃取できる、または RCE を実行できる	pull_request_target でフォークのコードをチェックアウトして実行する；特権トリガーの run: で ${{ github.event.* }} を使用する
🟠 HIGH	悪用可能なサプライチェーンまたはスコープの問題	変更可能なタグ／ブランチを使用するサードパーティアクション；write-all 権限；issue_comment におけるインジェクションのシンク
🟡 MEDIUM	条件や連鎖によってリスクが生じる	permissions: ブロックがない；フォーク以外の PR 作成者がシークレットにアクセスできる
🔵 LOW	強化が不十分だが、直接的なリスクは低い	ファーストパーティアクションが SHA に固定されていない；特権のないジョブで persist-credentials がデフォルトのまま
⚪ INFO	脆弱性ではなく、所見	固定した SHA の横にバージョンコメントがない

出力ルール

• 必ず、重大度別の件数を示す指摘事項の概要表を最初に提示してください。
• ファイル別ではなく、問題の種類ごとにまとめてください。
• 正確に記載してください。問題のある行を引用し、行番号を示してください。
• CRITICAL／HIGH の各指摘には、必ず具体的な修正済み YAML スニペットを添えてください。
• フォークからの pull_request は、信頼できないコードを実行するという理由だけで危険だと主張しないでください。シークレットがなく、トークンも読み取り専用です。CRITICAL は特権トリガーにのみ使用してください。
• ワークフローがすでに強化されている場合は、その旨を伝え、確認した項目を列挙してください。

参考ファイル

必要に応じて、以下を読み込んでください。

• references/triggers-and-privilege.md — すべてのトリガーの信頼マトリクス、pull_request_target と workflow_run に特権が付与される理由、および2つのワークフローを使った安全なパターン。
  • 検索パターン：pull_request_target、workflow_run、issue_comment、fork、secrets、read-only token、trust boundary
• references/injection.md — 攻撃者が制御できる ${{ }} コンテキストの全リストと、各シンク（run、github-script、アクションの入力）における env: 変数を使った安全なパターン。
  • 検索パターン：script injection、github.event、head_ref、issue title、env、intermediate variable、actions/github-script
• references/permissions-and-tokens.md — GITHUB_TOKEN のスコープ、ジョブの種類ごとの最小権限の permissions: 設定例、および長期有効なシークレットの代わりにクラウド認証に OIDC を使う方法。
  • 検索パターン：permissions、GITHUB_TOKEN、write-all、contents: read、id-token、OIDC、least privilege
• references/supply-chain.md — サードパーティ製アクションの SHA 固定、github-actions 向けの Dependabot、workflow_run 間でのアーティファクトおよびキャッシュのポイズニング、セルフホストランナーのリスク。
  • 検索パターン：SHA pin、uses、mutable tag、Dependabot、download-artifact、cache、self-hosted runner
• references/report-format.md — 出力テンプレート：概要テーブル、検出事項カード、修正前後のブロック。
  • 検索パターン：report、format、finding、summary、remediation、before、after