implementing-github-advanced-security-for-code-scanning

コードスキャン向け GitHub Advanced Security の実装

概要

GitHub Advanced Security（GHAS）は、CodeQL を活用した静的アプリケーションセキュリティテストを GitHub の開発ワークフローに直接統合します。CodeQL はコードをデータとして扱うため、セマンティック分析によって SQL インジェクション、クロスサイトスクリプティング、バッファーオーバーフロー、認証の不備などのセキュリティ脆弱性を、従来のパターンマッチング型スキャナーより大幅に少ない誤検知で特定できます。GHAS はコードスキャン、シークレットスキャン、依存関係レビュー、Dependabot アラートを含み、リポジトリの包括的なセキュリティ態勢を提供します。

使用する場面

• 環境で GitHub Advanced Security のコードスキャン機能を導入、設定、実装する場合
• コンプライアンス要件に沿ったセキュリティ制御を確立する場合
• この分野のセキュリティアーキテクチャを構築または改善する場合
• この実装が必要なセキュリティ評価を実施する場合

前提条件

• GHAS ライセンスを備えた GitHub Enterprise Cloud または GitHub Enterprise Server 3.0+
• リポジトリ管理者または組織オーナーの権限
• GitHub Actions ワークフロー構文（YAML）の知識
• 対応言語：C/C++、C#、Go、Java/Kotlin、JavaScript/TypeScript、Python、Ruby、Swift

主な概念

CodeQL 分析エンジン

CodeQL はソースコードをクエリ可能なデータベースにコンパイルし、そのデータベースに対してセキュリティに特化したクエリを実行します。クエリスイートには CWE 識別子に対応付けられた数百のチェックが含まれ、OWASP Top 10、SANS Top 25、言語固有の脆弱性パターンを対象としています。組織固有のアンチパターンを検出するには、CodeQL クエリ言語（QL）を使ってカスタムクエリを作成できます。

デフォルト設定と高度な設定

デフォルト設定では、リポジトリのコードセキュリティ設定からワンクリックでコードスキャンを有効にできます。GitHub は存在する言語を自動的に判定し、適切なクエリスイートを選択して、スキャンのトリガーを設定します。この方法ではワークフローファイルが不要なため、迅速な導入に最適です。

高度な設定では、カスタマイズ可能な .github/workflows/codeql.yml ワークフローファイルが生成されます。チームはスケジュール、言語マトリックス、コンパイル言語向けのビルドコマンド、追加のクエリパック、サードパーティ製 SARIF 生成ツールとの統合を制御できます。カスタムビルド手順、モノレポ構成、プライベートクエリパックが必要な場合は、高度な設定が必要です。

組織全体への展開

数百のリポジトリを管理する企業向けに、GHAS は組織レベルのセキュリティ概要を使ってコードスキャンを大規模に設定できます。管理者は、対象となるすべてのリポジトリでデフォルト設定を有効にし、カスタムのセキュリティ構成を定義して、セキュリティカバレッジダッシュボードで導入状況を監視できます。

ワークフロー

手順 1 --- 組織で GHAS を有効にする

1. Organization Settings > Code security and analysis に移動します
2. すべてのリポジトリ、または選択したリポジトリで GitHub Advanced Security を有効にします
3. ライセンスシートの割り当てを確認します（GHAS はアクティブなコミッターごとに課金されます）

手順 2 --- 迅速に導入するためにデフォルト設定を構成する

1. Repository Settings > Code security > Code scanning に移動します
2. CodeQL analysis の行にある「Set up」をクリックし、「Default」を選択します
3. 自動検出された言語とクエリスイート（default または extended）を確認します
4. 「Enable CodeQL」をクリックして、プッシュイベントとプルリクエストイベントでのスキャンを有効にします

手順 3 --- カスタムワークフローで高度な設定を行う

.github/workflows/codeql-analysis.yml を作成します：

name: "CodeQL Analysis"

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 2 * * 1'  # Weekly Monday 2:30 AM UTC

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
      actions: read

    strategy:
      fail-fast: false
      matrix:
        language: ['javascript-typescript', 'python', 'java-kotlin']

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}
          queries: +security-extended,security-and-quality
          # For compiled languages, add build commands below

      - name: Autobuild
        uses: github/codeql-action/autobuild@v3

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v3
        with:
          category: "/language:${{ matrix.language }}"

手順 4 --- カスタムクエリパック

ワークフローで参照して、組織固有のクエリパックをインストールします：

- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: java-kotlin
    packs: |
      my-org/[email protected]
      codeql/java-queries:cwe/cwe-089

手順 5 --- ブランチ保護ルールを設定する

1. Repository Settings > Branches > Branch protection rules に移動します
2. 「Require status checks to pass」を有効にし、CodeQL analysis チェックを追加します
3. 「Require code scanning results」を有効にし、重大度のしきい値を設定します（例：High/Critical の場合にブロック）

ステップ 6 --- シークレットスキャンとプッシュ保護

1. コードセキュリティの設定からシークレットスキャンを有効にします
2. プッシュ保護を有効にして、検出されたシークレットを含むコミットをブロックします
3. 組織固有のシークレット（API キー、内部トークンなど）に対応するカスタムパターンを設定します

ステップ 7 --- 依存関係レビューと Dependabot

1. Dependabot アラートとセキュリティアップデートを有効にします
2. .github/dependabot.yml を設定して、依存関係のバージョンを自動更新します
3. プルリクエストに対する依存関係レビューの適用を有効にし、既知の脆弱性を含む依存関係を導入する PR をブロックします

クエリスイートのリファレンス

スイート	説明	用途
default	信頼度の高いセキュリティクエリ	誤検知を最小限に抑えた本番環境のスキャン
security-extended	重大度の低い検出結果も含む、より広範なセキュリティクエリ	包括的なセキュリティ対策
security-and-quality	セキュリティとコード品質のクエリ	セキュリティと保守性の両方を確認したいチーム
カスタムパック	組織が作成したクエリ	内部のアンチパターンやコンプライアンス違反の検出

セキュリティワークフローとの統合

サードパーティツールからの SARIF アップロード

GHAS は外部ツールからの SARIF（Static Analysis Results Interchange Format）アップロードを受け付けます。

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
    category: "semgrep"

セキュリティ概要ダッシュボード

組織レベルのセキュリティ概要では、次の情報を確認できます。

• 重大度別に未解決アラートがあるリポジトリを表示するリスクビュー
• リポジトリ全体での GHAS 機能の有効化状況を表示するカバレッジビュー
• 修正の進捗を追跡するためのアラートの経時的な推移
• チーム、言語、アラートの種類でフィルタリングして、対象を絞ったレビューを実施

モニタリングとメトリクス

• コードスキャンアラートの平均修復時間（MTTR）を追跡します
• 誤検知率をモニタリングし、それに応じてクエリの設定を調整します
• アラートの却下理由を確認して、開発者向けトレーニングが必要な領域を特定します
• API（/repos/{owner}/{repo}/code-scanning/alerts）を使用して、カスタムレポート用ダッシュボードを作成します

よくある落とし穴

1. コンパイル言語のビルド失敗 --- CodeQL で C/C++、Java、C#、Go、Swift を扱うには、コンパイルの成功が必要です。Actions ランナーでビルド依存関係を利用できるようにしてください
2. スケジュールスキャンの無視 --- プッシュや PR のスキャンでは依存関係の脆弱性を検出できません。週次のスケジュールスキャンにより、既存コードに含まれる新たに公表された CVE を検出できます
3. security-and-quality によるアラートの過剰発生 --- 開発者がアラート疲れを起こさないよう、まず default スイートから始め、段階的に拡張してください
4. GHAS ライセンス枠の不足 --- GHAS が有効なリポジトリに対するアクティブなコミッターのみがライセンス枠を使用します。これを考慮して必要数を計画してください

参考資料

• GitHub コードスキャンのドキュメント
• CodeQL のドキュメント
• CodeQL クエリリポジトリ
• SARIF 仕様
• GitHub セキュリティ概要