Code Scanningガイド(SAST)

Posted at 2025-12-21

Code Scanningガイド(SAST)

GitHub Code Scanningは、リポジトリ内のコードを静的解析し、セキュリティ脆弱性やコーディングエラーを自動検出する機能です。本記事では、この機能の実装から運用まで、技術的な詳細を含めて解説します。

Code Scanningの基礎
セットアップ方法の選択
対応言語とビルドモード
Copilot Autofixによる修正提案
アラートの管理とワークフロー
クエリスイートとカスタマイズ
外部CI/CDシステムとの統合
トラブルシューティング
組織規模での展開

1. Code Scanningの基礎

1.1. 利用可能なリポジトリ

Code Scanningは以下のリポジトリで利用できます。

GitHub.com上のパブリックリポジトリ
GitHub Code Securityが有効化された組織所有のプライベート/インターナルリポジトリ

1.2. 分析エンジン: CodeQL

CodeQLは、コードをデータとして扱う静的解析エンジンです。以下のプロセスで動作します。

1.3. 料金体系

パブリックリポジトリ: 無料
プライベート/インターナルリポジトリ: GitHub ActionsのランナーMinutesを消費
GitHub Code Securityライセンスが必要

2. セットアップ方法の選択

Code Scanningには、用途に応じた2つのセットアップ方法があります。

2.1. デフォルトセットアップ

推奨される初期設定方法です。最小限の設定で即座に分析を開始できます。

2.1.1. 特徴

リポジトリ内の言語を自動検出
最適なクエリスイートを自動選択
スケジュールされたスキャンを自動設定

2.1.2. 有効化手順

リポジトリの「Settings」→「Code security and analysis」に移動
「CodeQL analysis」で「Set up」→「Default」を選択
必要に応じて言語とクエリスイートをカスタマイズ

2.1.3. トリガータイミング

デフォルトブランチまたは保護ブランチへのプッシュ時
プルリクエスト作成時
週次スケジュール実行

2.2. アドバンスセットアップ

ワークフローファイルを編集して、詳細な制御が必要な場合に使用します。

2.2.1. 使用すべきケース

特定のビルドコマンドが必要な場合
複雑なマトリックスビルドを実行する場合
カスタムクエリを実行する場合
ワークフローのトリガーを細かく制御したい場合

2.2.2. 基本的なワークフロー例

name: "CodeQL分析"

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]
  schedule:
    - cron: '30 1 * * 0'  # 毎週日曜日午前1:30に実行

jobs:
  analyze:
    name: コード解析
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      actions: read
      contents: read

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

    steps:
    - name: リポジトリのチェックアウト
      uses: actions/checkout@v5

    - name: CodeQLの初期化
      uses: github/codeql-action/init@v4
      with:
        languages: ${{ matrix.language }}

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

    - name: CodeQL分析の実行
      uses: github/codeql-action/analyze@v4

3. 対応言語とビルドモード

3.1. 対応言語一覧

言語	識別子	代替識別子
C/C++	`c-cpp`	`c`, `cpp`
C#	`csharp`	-
Go	`go`	-
Java/Kotlin	`java-kotlin`	`java`, `kotlin`
JavaScript/TypeScript	`javascript-typescript`	`javascript`, `typescript`
Python	`python`	-
Ruby	`ruby`	-
Rust	`rust`	-
Swift	`swift`	-
GitHub Actions	`actions`	-

3.2. ビルドモード（コンパイル言語）

コンパイルが必要な言語（C/C++、C#、Go、Java/Kotlin、Rust、Swift）では、3つのビルドモードから選択できます。

3.2.1. noneモード（推奨初期設定）

ソースコードから直接データベースを生成します。ビルドが不要なため、最も高速です。

対応言語: C/C++、C#、Java、Rust

設定例:

- name: CodeQLの初期化
  uses: github/codeql-action/init@v4
  with:
    languages: java-kotlin
    build-mode: none

注意点:

生成コードは解析対象外
Kotlinコードが含まれる場合、Javaのみが分析対象（Kotlinはautobuildが必要）

3.2.2. autobuildモード

CodeQLが自動的にビルド方法を検出して実行します。

設定例:

- name: CodeQLの初期化
  uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    build-mode: autobuild

検出される主なビルドシステム:

Java: Maven、Gradle、Ant
C#: .NET、MSBuild
C/C++: CMake、Make、MSBuild

3.2.3. manualモード

明示的なビルドコマンドを指定します。最も正確な分析結果が得られます。

設定例:

- name: CodeQLの初期化
  uses: github/codeql-action/init@v4
  with:
    languages: c-cpp
    build-mode: manual

- name: ビルド実行
  run: |
    ./configure
    make release

- name: CodeQL分析の実行
  uses: github/codeql-action/analyze@v4

3.3. 複数言語の混在リポジトリ

異なるビルドモードを言語ごとに指定できます。

strategy:
  matrix:
    include:
      - language: c-cpp
        build-mode: manual
      - language: csharp
        build-mode: autobuild
      - language: java-kotlin
        build-mode: none

4. Copilot Autofixによる修正提案

Copilot Autofixは、検出されたアラートに対して自動的に修正候補を生成します。

4.1. 利用可能条件

パブリックリポジトリ: すべてのユーザー
プライベート/インターナルリポジトリ: GitHub Code Securityライセンス保有者

注意: GitHub Copilotのサブスクリプションは不要です。

4.2. 対応範囲

Copilot Autofixは、以下の言語のデフォルト・security-extendedクエリスイート内の多くのクエリに対応しています。

C/C++、C#、Go、Java/Kotlin、Swift
JavaScript/TypeScript、Python、Ruby、Rust

4.3. 使用方法

4.3.1. プルリクエストでの自動生成

デフォルトセットアップまたはアドバンスセットアップで有効化されている場合、プルリクエスト内のアラートに対して自動的に修正候補が生成されます。

4.3.2. 既存アラートへの適用

Security タブからアラートを開き、「Generate fix」ボタンをクリックします。

修正候補が生成された後の操作:

「Create PR with fix」をクリック → 新しいブランチとドラフトプルリクエストが自動作成される
修正内容をレビュー・テスト
必要に応じて編集
コミット・マージ

4.3.3. Copilot Coding Agentへの割り当て

アラートをCopilot Coding Agentに割り当てることで、自動的に修正プルリクエストを作成させることができます。

手順:

アラート詳細ページを開く
右側メニューの「Assignees」をクリック
「Copilot」を選択
30秒以内にプルリクエストが自動作成される

4.4. 修正候補の品質保証

GitHubは2,300以上のテストケースを用いて、生成された修正候補を継続的に検証しています。

テスト項目:

アラートが実際に修正されているか
新しいアラートが発生していないか
構文エラーがないか
既存のテストに影響がないか

4.5. 制約事項と注意点

Copilot Autofixには以下の制約があります。

ハードリミット:

1つのソースから15語以上の引用: 禁止
1つのソースから2回以上の引用: 禁止
歌詞・詩・俳句の再現: 禁止

技術的制限:

複雑なデータフロー問題への対応が困難な場合がある
大規模ファイルではコンテキストが切り詰められる可能性
LLMの非決定性により、同じアラートでも異なる提案が生成される場合がある

推奨事項:

生成された修正は必ずレビューし、テストを実行する
CIテストと依存関係管理を適切に設定する
修正内容が意図したとおりか、セキュリティ要件を満たすか確認する

5. アラートの管理とワークフロー

5.1. アラートの表示とフィルタリング

Security タブの Code scanning セクションで、すべてのアラートを確認できます。

5.1.1. フィルタリングオプション

フィルタ	説明	例
`is:open`	オープンなアラート	`is:open branch:main`
`is:closed`	クローズ済みアラート	`is:closed`
`severity:`	重要度レベル	`severity:high`
`branch:`	特定ブランチ	`branch:develop`
`tag:`	タグによる絞り込み	`tag:security`
`-tag:`	タグの除外	`-tag:style`

5.1.2. 全文検索

アラート名とアラート詳細（折りたたみ部分を含む）を検索できます。

例: sql injection
→ "sql" または "injection" を含むすべてのアラート

5.2. アラートの重要度レベル

5.2.1. Severity（すべてのアラート）

Error: 修正が必須
Warning: 修正を推奨
Note: 情報提供

5.2.2. Security Severity（セキュリティアラート）

CVSS（Common Vulnerability Scoring System）に基づいた評価です。

レベル	CVSS スコア	説明
Critical	9.0超	即座に対処が必要
High	7.0-8.9	優先的に対処
Medium	4.0-6.9	計画的に対処
Low	0.1-3.9	低優先度

5.3. アラートへの対応フロー

5.4. アラートの却下

以下の理由でアラートを却下できます。

却下理由の選択:

False positive: 誤検出
Won't fix: 修正しない（設計上の判断）
Used in tests: テストコードでのみ使用
Risk accepted: リスクを承認済み

重要: 却下理由はクエリの改善に使用されるため、正確に選択してください。

却下操作のAPI例:

PUT /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}
{
  "state": "dismissed",
  "dismissed_reason": "false positive",
  "dismissed_comment": "このライブラリの入力検証機能により保護されています"
}

5.5. プルリクエストでのアラート表示

プルリクエスト内の変更によって発生したアラートは、以下の場所に表示されます。

Conversation タブ: プルリクエストレビューとして
Files changed タブ: コードアノテーションとして
Checks タブ: ステータスチェックとして

表示条件:

アラートの全行がプルリクエストのdiffに含まれている
デフォルトブランチに存在しない新しいアラートである

6. クエリスイートとカスタマイズ

6.1. 組み込みクエリスイート

CodeQLには、各言語に対して2つの主要なクエリスイートが用意されています。

6.1.1. default（デフォルト）

特徴:

高精度・低誤検出率
重要なセキュリティ問題に焦点
デフォルトセットアップで自動的に使用される

推奨用途: 初期設定、継続的なスキャン

6.1.2. security-extended（拡張セキュリティ）

特徴:

defaultのすべてのクエリを含む
追加の低精度クエリを実行
より多くの潜在的な問題を検出

推奨用途: より徹底的な分析が必要な場合

設定方法（デフォルトセットアップ）:

Settings → Code security and analysis
CodeQL analysis → Edit
Query suite で「Extended」を選択

設定方法（アドバンスセットアップ）:

- name: CodeQLの初期化
  uses: github/codeql-action/init@v4
  with:
    queries: security-extended

6.2. カスタムクエリの追加

アドバンスセットアップでは、独自のクエリやサードパーティのクエリを追加できます。

6.2.1. クエリパックの使用

- name: CodeQLの初期化
  uses: github/codeql-action/init@v4
  with:
    packs: |
      yamada-corp/java-security-queries@~1.2.0
      tanaka-repo/custom-rules

6.2.2. 個別クエリファイルの指定

- name: CodeQLの初期化
  uses: github/codeql-action/init@v4
  with:
    queries: |
      ./custom-queries/security-check.ql
      ./custom-queries/performance/
      suzuki-org/query-suite.qls

6.3. カスタム設定ファイルの使用

より複雑な設定には、YAML設定ファイルを使用します。

設定ファイル例（.github/codeql/config.yml）:

name: "カスタムCodeQL設定"

# デフォルトクエリを無効化
disable-default-queries: true

# 実行するクエリ
queries:
  - name: "社内セキュリティルール"
    uses: ./internal-queries
  - name: "外部クエリパック"
    uses: yamada-corp/security-pack@main

# クエリフィルタ（特定のクエリを除外）
query-filters:
  - exclude:
      id: js/unused-local-variable
  - exclude:
      tags:
        - experimental

# 分析対象パス
paths:
  - src
  - lib

# 分析対象外パス
paths-ignore:
  - src/test
  - '**/*.test.js'
  - node_modules

ワークフローでの指定:

- name: CodeQLの初期化
  uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/config.yml

6.4. Model Packsによるカバレッジ拡張

標準ライブラリで認識されないフレームワークや依存関係がある場合、Model Packsを使用してカバレッジを拡張できます。

対応言語: C/C++、C#、Java/Kotlin、Python、Ruby、Rust

6.4.1. デフォルトセットアップでの設定

.github/codeql/extensions/ ディレクトリに Model Pack を配置
自動的に検出・使用される

ディレクトリ構造例:

.github/
└── codeql/
    └── extensions/
        └── custom-framework-models/
            ├── codeql-pack.yml
            └── models/
                └── framework-models.yml

6.4.2. 組織レベルでの設定

Model Packを GitHub Container Registry に公開
Organization Settings → Code security and analysis → Global settings
"Expand CodeQL analysis" で公開済みパックを指定

7. 外部CI/CDシステムとの統合

GitHub Actions以外のCI/CDシステムでCodeQL分析を実行し、結果をGitHubにアップロードできます。

7.1. CodeQL CLIの使用

7.1.1. セットアップ

# CodeQL CLIのダウンロード
wget https://github.com/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz

# 展開
tar -xvzf codeql-bundle-linux64.tar.gz

# PATHに追加
export PATH="$PATH:$(pwd)/codeql"

7.1.2. データベースの作成

# Javaプロジェクトの例
codeql database create java-db \
  --language=java \
  --command="mvn clean compile"

# コンパイル不要な言語（Python）の例
codeql database create python-db \
  --language=python

7.1.3. 分析の実行

codeql database analyze java-db \
  codeql/java-queries:codeql-suites/java-security-extended.qls \
  --format=sarif-latest \
  --output=results.sarif

7.1.4. GitHubへのアップロード

codeql github upload-results \
  --repository=yamada-org/project-repo \
  --ref=refs/heads/main \
  --commit=a1b2c3d4e5f6 \
  --sarif=results.sarif \
  --github-auth-stdin < token.txt

7.2. サードパーティツールの統合

SARIF 2.1.0形式に対応した任意の静的解析ツールを使用できます。

7.2.1. GitHub Actionsでのアップロード例

name: "サードパーティ解析ツール"

on:
  push:
    branches: [ main ]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v5
    
    - name: 解析ツールの実行
      run: |
        # ツール固有のコマンド
        security-scanner --output results.sarif
    
    - name: SARIFファイルのアップロード
      uses: github/codeql-action/upload-sarif@v4
      with:
        sarif_file: results.sarif
        category: security-scanner

7.3. カテゴリによる複数結果の管理

同じツール・コミットに対して複数のSARIFファイルをアップロードする場合、カテゴリを指定します。

- name: Python分析のアップロード
  uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: python-results.sarif
    category: python-analysis

- name: JavaScript分析のアップロード
  uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: js-results.sarif
    category: javascript-analysis

7.4. SARIF形式の要件

7.4.1. 必須プロパティ

$schema: SARIF 2.1.0スキーマURI
version: "2.1.0"
runs[].tool.driver.name: ツール名
runs[].results[].ruleId: ルールID
runs[].results[].message.text: メッセージ
runs[].results[].locations[]: 少なくとも1つの場所

7.4.2. ファイルサイズ制限

圧縮後: 10MB以内
結果数: 25,000件以内（上位5,000件のみ表示）

8. トラブルシューティング

8.1. よくある問題と解決方法

8.1.1. ビルドエラー: "No source code was seen during the build"

原因:

コンパイル言語でビルドが失敗している
ビルドがCodeQLの監視範囲外で実行されている
キャッシュされたコンポーネントのみが使用されている

解決策:

# autobuildを削除し、手動ビルドを指定
- name: CodeQLの初期化
  uses: github/codeql-action/init@v4
  with:
    languages: java-kotlin
    build-mode: manual

- name: 明示的なビルド
  run: |
    ./gradlew clean build

8.1.2. メモリ不足: "Out of memory"

解決策:

1. Larger Runnersの使用:

jobs:
  analyze:
    runs-on: ubuntu-latest-8-cores  # より大きなランナー

2. セルフホストランナーの使用:

推奨スペック:

RAM: 16GB以上（大規模プロジェクトは64GB）
CPU: 4コア以上（大規模プロジェクトは8コア）
SSD: 14GB以上

8.1.3. 分析時間が長すぎる

最適化手順:

1. 分析対象の絞り込み:

paths:
  - src/main
paths-ignore:
  - src/test
  - '**/generated/**'

2. クエリスイートの変更:

# security-extended から default に変更
queries: default

3. 並列実行の活用:

strategy:
  matrix:
    language: [ 'java', 'javascript' ]
# 各言語が並列実行される

8.1.4. Kotlinファイルが分析されない

警告メッセージ:

Warning: Detected X Kotlin files in your project that could not be processed without a build

解決策:

デフォルトセットアップを無効化→再有効化するか、アドバンスセットアップでビルドモードを変更します。

- name: CodeQLの初期化
  uses: github/codeql-action/init@v4
  with:
    languages: java-kotlin
    build-mode: autobuild  # または manual

8.1.5. SARIFファイルが大きすぎる

エラー:

SARIF file is too large (>10MB)

解決策:

1. クエリ数を削減:

query-filters:
  - exclude:
      tags: experimental

2. データフローパスを制限:

- name: CodeQL分析
  uses: github/codeql-action/analyze@v4
  env:
    CODEQL_ACTION_EXTRA_OPTIONS: '{"database":{"interpret-results":["--max-paths", 1]}}'

3. 分析対象を分割:

複数のワークフローに分割し、それぞれ異なるカテゴリで実行します。

8.2. デバッグログの有効化

詳細なログが必要な場合:

- name: CodeQLの初期化
  uses: github/codeql-action/init@v4
  with:
    debug: true

または、ワークフローを再実行する際に「Enable debug logging」を選択します。

8.3. Tool Status Pageの活用

Security タブ → Code scanning → Tool status で以下を確認できます。

最終スキャン日時
スキャン成功率
分析されたファイルの割合
エラーメッセージ

9. 組織規模での展開

9.1. デフォルトセットアップの一括有効化

9.1.1. 対象リポジトリの条件

GitHub Actionsが有効
パブリックリポジトリ、またはGitHub Code Securityが有効
アドバンスセットアップが未設定

9.1.2. 有効化手順

Organization Settings → Code security and analysis
「Configure default setup」を選択
対象リポジトリを選択（フィルタリング可能）
「Apply to selected repositories」をクリック

9.2. Security Configurationsの使用

組織全体で統一された設定を適用できます。

9.2.1. カスタム設定の作成

Organization Settings → Code security and analysis → Configurations
「New configuration」をクリック
以下を設定:
- クエリスイート
- Model packs
- Threat models（Java/Kotlin、C#）
- Delegated alert dismissal（アラート却下の承認フロー）

9.2.2. 設定の適用

リポジトリをフィルタリング
「Apply configuration」を選択
作成したカスタム設定を選択

9.3. セキュリティキャンペーンの実施

組織全体で特定のセキュリティ問題に集中的に取り組むための機能です。

9.3.1. キャンペーンマネージャーの役割

9.3.2. 開発者側のワークフロー

1. キャンペーン通知の受信

メールまたはリポジトリのSecurityタブで確認

2. アラートの確認

Copilot Autofixの修正候補を確認
複数のアラートを選択して一括修正

3. 修正の実装

「Create new branch」で作業ブランチ作成
または「Commit autofix」で自動修正をコミット

4. Copilot Coding Agentへの割り当て

複数のアラートを選択
「Assign to Copilot」をクリック
自動的にプルリクエストが作成される

9.4. Merge Protectionの設定

プルリクエストのマージ条件として、Code Scanningの結果を使用できます。

9.4.1. Rulesetsでの設定

Repository Settings → Rules → Rulesets
「New branch ruleset」を作成
「Require code scanning results」を有効化
ツールとアラート閾値を指定:
- ツール: CodeQL
- Alerts: Errors only
- Security alerts: High or higher

マージ条件の例:

ツール: CodeQL
重要度: Error以上
セキュリティ重要度: High以上
ステータス: 分析完了

効果:

新しいHigh以上のセキュリティアラートがある場合、マージ不可
分析が未完了の場合、マージ不可
設定されたツールが実行されていない場合、マージ不可

9.5. 組織レベルのモニタリング

Security Overview（Organization Settings）で以下を確認できます。

9.5.1. 確認可能なメトリクス

リポジトリ別のアラート数
重要度別の分布
修正までの平均時間
プルリクエストでのアラート検出率

9.5.2. フィルタリング例

severity:high is:open language:java
→ 重要度Highのオープンなアラート（Java）

10. まとめ

10.1. 推奨導入フロー

10.2. 成功のためのポイント

段階的な導入: デフォルトセットアップから始め、徐々にカスタマイズ
チーム教育: セキュアコーディングの知識共有
継続的な改善: Tool Status Pageで分析状況を定期確認
自動化の活用: Copilot AutofixとCoding Agentで修正を効率化
組織的な取り組み: Security Campaignsで重要課題に集中

Code Scanningを活用することで、開発速度を維持しながら、より安全なコードベースを構築できます。まずは小規模なプロジェクトで試し、効果を実感してから組織全体に展開することをお勧めします。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

Code Scanningガイド(SAST)

Code Scanningガイド(SAST)

目次

1. Code Scanningの基礎

1.1. 利用可能なリポジトリ

1.2. 分析エンジン: CodeQL

1.3. 料金体系

2. セットアップ方法の選択

2.1. デフォルトセットアップ

2.1.1. 特徴

2.1.2. 有効化手順

2.1.3. トリガータイミング

2.2. アドバンスセットアップ

2.2.1. 使用すべきケース

2.2.2. 基本的なワークフロー例

3. 対応言語とビルドモード

3.1. 対応言語一覧

3.2. ビルドモード（コンパイル言語）

3.2.1. noneモード（推奨初期設定）

3.2.2. autobuildモード

3.2.3. manualモード

3.3. 複数言語の混在リポジトリ

4. Copilot Autofixによる修正提案

4.1. 利用可能条件

4.2. 対応範囲

4.3. 使用方法

4.3.1. プルリクエストでの自動生成

4.3.2. 既存アラートへの適用

4.3.3. Copilot Coding Agentへの割り当て

4.4. 修正候補の品質保証

4.5. 制約事項と注意点

5. アラートの管理とワークフロー

5.1. アラートの表示とフィルタリング

5.1.1. フィルタリングオプション

5.1.2. 全文検索

5.2. アラートの重要度レベル

5.2.1. Severity（すべてのアラート）

5.2.2. Security Severity（セキュリティアラート）

5.3. アラートへの対応フロー

5.4. アラートの却下

5.5. プルリクエストでのアラート表示

6. クエリスイートとカスタマイズ

6.1. 組み込みクエリスイート

6.1.1. default（デフォルト）

6.1.2. security-extended（拡張セキュリティ）

6.2. カスタムクエリの追加

6.2.1. クエリパックの使用

6.2.2. 個別クエリファイルの指定

6.3. カスタム設定ファイルの使用

6.4. Model Packsによるカバレッジ拡張

6.4.1. デフォルトセットアップでの設定

6.4.2. 組織レベルでの設定

7. 外部CI/CDシステムとの統合

7.1. CodeQL CLIの使用

7.1.1. セットアップ

7.1.2. データベースの作成

7.1.3. 分析の実行

7.1.4. GitHubへのアップロード

7.2. サードパーティツールの統合

7.2.1. GitHub Actionsでのアップロード例

7.3. カテゴリによる複数結果の管理

7.4. SARIF形式の要件

7.4.1. 必須プロパティ

7.4.2. ファイルサイズ制限

8. トラブルシューティング

8.1. よくある問題と解決方法

8.1.1. ビルドエラー: "No source code was seen during the build"

8.1.2. メモリ不足: "Out of memory"

8.1.3. 分析時間が長すぎる

8.1.4. Kotlinファイルが分析されない

8.1.5. SARIFファイルが大きすぎる

8.2. デバッグログの有効化

8.3. Tool Status Pageの活用

9. 組織規模での展開

9.1. デフォルトセットアップの一括有効化

9.1.1. 対象リポジトリの条件

9.1.2. 有効化手順

9.2. Security Configurationsの使用

9.2.1. カスタム設定の作成

9.2.2. 設定の適用