# バッチ設計書 45-CIFuzz（oss-fuzz.yml）

## 概要

本ドキュメントは、GitHub Actionsワークフロー「CIFuzz」（oss-fuzz.yml）のバッチ設計書である。Pull Request時にGoogleのOSS-Fuzz基盤を使用してmrubyのファジングテストをビルドおよび実行し、メモリ安全性やクラッシュバグを検出するワークフローについて記載する。

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

本ワークフローは、Pull Request時にOSS-Fuzzのファジングインフラストラクチャを使用して、mrubyに対するファジングテストを600秒間実行し、潜在的なクラッシュバグやメモリ安全性の問題を検出する。

**業務上の目的・背景**：mrubyはC言語で実装された組み込み向けRuby処理系であり、メモリ管理に関するバグ（バッファオーバーフロー、use-after-free、ヒープオーバーフロー等）が発生するリスクがある。ファジングテストはランダムな入力データを用いてプログラムの堅牢性を検証する手法であり、人手のテストでは発見困難な不具合を自動的に検出できる。GoogleのOSS-Fuzzプロジェクトとの連携により、Pull Requestの段階で回帰テストとしてファジングを実行し、セキュリティ脆弱性の混入を防止する。

**バッチの実行タイミング**：Pull Request作成時および更新時に自動実行される。

**主要な処理内容**：
1. OSS-Fuzzのファザー（Fuzzer）をmrubyプロジェクト向けにビルドする
2. ビルドされたファザーを600秒間実行し、クラッシュを検出する
3. クラッシュが検出された場合、クラッシュアーティファクトをアップロードする

**前後の処理との関連**：本ワークフローは独立して実行され、Build & Test（No.38）等のビルドワークフローと並行動作する。OSS-Fuzzプロジェクトとして登録されている「mruby」の設定に依存する。

**影響範囲**：Pull Requestのマージ可否判定。ファジングテスト結果がPull Requestのステータスチェックとして表示される。クラッシュが検出された場合はアーティファクトとして再現データがアップロードされる。

## バッチ種別

セキュリティテスト / ファジング / CI（継続的インテグレーション）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（イベント駆動） |
| 実行時刻 | 該当なし（イベントトリガー） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | Pull Request作成・更新時 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHubリポジトリ | mrubyリポジトリがGitHub上に存在すること |
| Pull Request | Pull Requestイベントが発生していること |
| OSS-Fuzz登録 | mrubyがOSS-Fuzzプロジェクトとして登録されていること |

### 実行可否判定

GitHub Actionsのpull_requestイベントトリガーにより自動判定される。全てのPull Requestに対して実行され、ブランチのフィルタリングは行われない。`dry-run: false`のため、実際のファジングが実行される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| oss-fuzz-project-name | string | Yes | mruby | OSS-Fuzzプロジェクト名 |
| dry-run | boolean | No | false | ドライラン実行の有無 |
| fuzz-seconds | integer | No | 600 | ファジング実行時間（秒） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| リポジトリソースコード | ファイルシステム | ファジングビルド対象のmrubyソースコード |
| OSS-Fuzzプロジェクト設定 | OSS-Fuzz | google/oss-fuzzリポジトリ内のmrubyプロジェクト設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Pull Requestステータス | GitHub Check | ワークフローの成功/失敗ステータス |
| クラッシュアーティファクト | ファイル | クラッシュ再現データ（失敗時のみ） |
| GitHub Actionsログ | テキスト | ファジング実行結果の詳細ログ |

### 出力ファイル仕様

クラッシュが検出された場合のみアーティファクトがアップロードされる。

| 項目 | 内容 |
|-----|------|
| ファイル名 | artifacts（アーティファクト名） |
| 出力先 | ./out/artifacts（ランナー上のパス） |
| 文字コード | バイナリ |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. ファザービルド
   └─ google/oss-fuzz/infra/cifuzz/actions/build_fuzzers@masterでmrubyプロジェクトのファザーをビルド
2. ファザー実行
   └─ google/oss-fuzz/infra/cifuzz/actions/run_fuzzers@masterで600秒間ファジングを実行
3. クラッシュアーティファクトアップロード（失敗時のみ）
   └─ actions/upload-artifact@v6でクラッシュ再現データをアップロード
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始<br>Pull Request] --> B[ファザービルド<br>oss-fuzz-project: mruby]
    B --> C[ファザー実行<br>fuzz-seconds: 600]
    C --> D{クラッシュ検出}
    D -->|クラッシュなし| E[ワークフロー成功]
    D -->|クラッシュあり| F[クラッシュアーティファクトアップロード]
    F --> G[ワークフロー失敗]
```

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

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

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

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

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | クラッシュ検出 | ファジングによりクラッシュが発生した場合 | アーティファクトからクラッシュ入力を取得し、原因を解析・修正する |
| - | ファザービルド失敗 | ファザーのコンパイルに失敗した場合 | ビルドエラーの原因を修正してPRを更新する |
| - | タイムアウト | 600秒のファジング時間内に完了しない場合 | 正常動作であり、600秒経過後に自動的に停止する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 手動で再実行（GitHub Actions UIまたはPR更新） |
| リトライ間隔 | 該当なし（手動） |
| リトライ対象エラー | 一時的なインフラエラー（ファザービルド失敗等） |

### 障害時対応

クラッシュが検出された場合は、アップロードされたクラッシュアーティファクト（./out/artifacts）を取得し、クラッシュ入力を使用してローカル環境で再現・デバッグを行う。ファザービルド失敗の場合は、OSS-Fuzzのビルド設定とmrubyのソースコード変更との互換性を確認する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ランダムな入力データ（件数は実行時間に依存） |
| 目標処理時間 | 600秒（ファジング実行時間）+ ビルド時間 |
| メモリ使用量上限 | ubuntu-latestランナーのデフォルト（7GB RAM） |

## 排他制御

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

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actionsの標準ログ（PRイベント情報） |
| 進捗ログ | ファジング実行中 | ファザービルド結果、ファジング進捗、テストケース実行数 |
| 終了ログ | ワークフロー終了時 | ファジング結果サマリー |
| エラーログ | クラッシュ検出時 | クラッシュスタックトレース、クラッシュ入力情報 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗（クラッシュ検出） | 1回 | GitHubリポジトリの通知設定に従う |
| ファザービルド失敗 | 1回 | Pull Requestのステータスチェック |

## 備考

- google/oss-fuzz/infra/cifuzz/actionsのmasterブランチを使用している（バージョン固定なし）
- ファジング実行時間は600秒（10分）に設定されている
- `dry-run: false`のため、実際のファジングが実行される
- クラッシュアーティファクトはactions/upload-artifact@v6を使用してアップロードされる
- アーティファクトのアップロードは`if: failure()`条件により、ワークフロー失敗時（クラッシュ検出時）のみ実行される
- 権限設定は`contents: read`のみ
- OSS-Fuzzプロジェクト名は「mruby」
