# バッチ設計書 41-CodeQL Analysis（codeql-analysis.yml）

## 概要

本ドキュメントは、GitHub Actionsワークフロー「CodeQL Analysis」（codeql-analysis.yml）のバッチ設計書である。masterブランチへのpushおよびPull Request時に、GitHubのCodeQL静的解析エンジンを使用してセキュリティ脆弱性を検出する自動化ワークフローについて記載する。

### 本バッチの処理概要

本ワークフローは、mrubyリポジトリのソースコードに対してCodeQLによるセキュリティ静的解析を自動実行し、潜在的な脆弱性やセキュリティ上の問題を早期に検出する。

**業務上の目的・背景**：mrubyはOSSの組み込み向けRuby実装であり、多数の外部コントリビューターからのコード変更が発生する。セキュリティ脆弱性（バッファオーバーフロー、メモリリーク、インジェクション等）を人手で全てレビューすることは困難であるため、GitHub CodeQLを活用した自動静的解析によって、マージ前にセキュリティリスクを検出し、コードベースの安全性を継続的に維持する必要がある。

**バッチの実行タイミング**：masterブランチへのpush時、およびmasterブランチ向けのPull Request作成・更新時に自動実行される。

**主要な処理内容**：
1. リポジトリのソースコードをチェックアウトする
2. CodeQLの解析エンジンを対象言語（actions）で初期化する
3. Autobuildでプロジェクトを自動ビルドする
4. CodeQL解析を実行し、セキュリティカテゴリで結果を分類する

**前後の処理との関連**：本ワークフローは独立して実行され、他のCIワークフロー（Build & Test、Super-Linter等）と並行動作する。解析結果はGitHubのSecurity Alertsタブに反映され、Pull Requestのチェックステータスとして表示される。

**影響範囲**：GitHubリポジトリのSecurity Alertsダッシュボード、Pull Requestのステータスチェック。解析対象はGitHub Actionsの定義ファイルである。

## バッチ種別

セキュリティ静的解析 / CI（継続的インテグレーション）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（イベント駆動） |
| 実行時刻 | 該当なし（イベントトリガー） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | masterブランチへのpush / masterブランチ向けPull Request |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHubリポジトリ | mrubyリポジトリがGitHub上に存在すること |
| CodeQL有効化 | リポジトリでGitHub Advanced Securityが有効化されていること |
| ブランチ条件 | push先またはPR先がmasterブランチであること |

### 実行可否判定

GitHub Actionsのイベントトリガーにより自動判定される。masterブランチへのpushイベント、またはmasterブランチを対象とするpull_requestイベントが発生した場合に実行される。`fail-fast: false`が設定されているため、マトリクス内の一部が失敗しても他のジョブは継続する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| language | string[] | Yes | ["actions"] | CodeQL解析対象言語のリスト |
| category | string | Yes | "Security" | 解析結果のカテゴリ分類 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| リポジトリソースコード | ファイルシステム | actions/checkout@v6でチェックアウトされたソースコード全体 |
| CodeQLデータベース | CodeQL DB | Autobuildステップで生成されるCodeQL解析用データベース |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Security Alerts | SARIF | CodeQL解析結果（脆弱性情報） |
| Pull Requestステータス | GitHub Check | ワークフローの成功/失敗ステータス |

### 出力ファイル仕様

本ワークフローはファイル出力を行わない。解析結果はSARIF形式でGitHubのCode Scanning APIにアップロードされ、Security AlertsおよびPull Requestのチェック結果として表示される。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし（GitHub API経由でアップロード） |
| 出力先 | GitHub Security Alerts |
| 文字コード | 該当なし |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ actions/checkout@v6でソースコードを取得
2. CodeQL初期化
   └─ github/codeql-action/init@v4で解析エンジンを初期化（言語: actions）
3. Autobuild
   └─ github/codeql-action/autobuild@v4でプロジェクトを自動ビルドしCodeQLデータベースを生成
4. CodeQL解析実行
   └─ github/codeql-action/analyze@v4で静的解析を実行し結果をアップロード（カテゴリ: Security）
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始<br>push/PR to master] --> B[リポジトリチェックアウト<br>actions/checkout@v6]
    B --> C[CodeQL初期化<br>言語: actions]
    C --> D[Autobuild<br>プロジェクト自動ビルド]
    D --> E[CodeQL解析実行<br>カテゴリ: Security]
    E --> F{解析結果}
    F -->|脆弱性なし| G[ワークフロー成功]
    F -->|脆弱性あり| H[Security Alertsに報告]
    H --> G
```

## データベース操作仕様

### 操作別データベース影響一覧

本ワークフローはデータベース操作を行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ビルドエラー | Autobuildステップでビルドに失敗した場合 | ビルドエラーの原因を修正し、再度pushまたはPRを更新する |
| - | CodeQL初期化エラー | CodeQLエンジンの初期化に失敗した場合 | GitHub Actionsのランナー状態を確認し、再実行する |
| - | 解析タイムアウト | CodeQL解析がタイムアウトした場合 | 解析対象の言語やスコープを見直す |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 手動で再実行（GitHub Actions UIから） |
| リトライ間隔 | 該当なし（手動） |
| リトライ対象エラー | 一時的なインフラエラー |

### 障害時対応

ワークフロー失敗時は、GitHub Actionsのログからエラーステップとエラーメッセージを確認し、原因に応じて対処する。`fail-fast: false`設定のため、マトリクスの一部ジョブが失敗しても他のジョブは影響を受けない。

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（CI/CDパイプライン） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | リポジトリ全体のActionsファイル |
| 目標処理時間 | 明示的な規定なし（GitHub Actionsのデフォルトタイムアウト6時間） |
| メモリ使用量上限 | ubuntu-latestランナーのデフォルト（7GB RAM） |

## 排他制御

GitHub Actionsの標準動作により、同一ワークフローの複数インスタンスが並行実行される可能性がある。concurrencyの設定は定義されていないため、同時実行が許可されている。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actionsの標準ログ（トリガーイベント情報） |
| 進捗ログ | 各ステップ実行時 | チェックアウト結果、CodeQL初期化状態、ビルドログ、解析進捗 |
| 終了ログ | ワークフロー終了時 | 解析結果サマリー、検出された脆弱性件数 |
| エラーログ | エラー発生時 | エラースタックトレース、失敗ステップ情報 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHubリポジトリの通知設定に従う |
| セキュリティアラート検出 | 1件以上 | GitHub Security Alerts / リポジトリ管理者 |

## 備考

- 解析対象言語は現在`actions`のみが設定されている。C/C++等の言語を追加する場合はmatrix.languageを拡張する必要がある
- CodeQLアクションはv4を使用している
- `fail-fast: false`設定により、マトリクスの一部失敗時も他のジョブを継続する
- 権限設定として`actions: read`、`contents: read`、`security-events: write`が必要
