これにより、`seclab-taskflow-agent` と `seclab-taskflows`（親）が推移的に取り込まれるため、
`seclab_taskflows.taskflows.audit.*`、
`seclab_taskflows.toolboxes.local_file_viewer`、
`seclab_taskflows.toolboxes.gh_file_viewer`、および
`seclab_taskflows.configs.model_config` という形式のすべてのドット参照が、
実行時に親ディストリビューションから解決されます。

---

## 目次

1. [これは何か](#what-this-is)
2. [クイックスタート](#quick-start)
3. [アーキテクチャ](#architecture)
4. [パイプライン、段階ごとに](#the-pipeline-stage-by-stage)
5. [カバレッジフィードバックループ](#the-coverage-feedback-loop)
6. [構造認識ファジング](#structure-aware-fuzzing)
7. [イテレーションとキャンペーンをまたぐ永続コーパス](#persistent-corpus-across-iterations-and-campaigns)
8. [トリアージと脆弱性レポート](#triage-and-vulnerability-reports)
9. [ライブダッシュボード](#live-dashboard)
10. [出力ファイル](#output-files)
11. [データベーススキーマ](#database-schema)
12. [MCP ツール（エージェントの語彙）](#mcp-tools-the-agents-vocabulary)
13. [調整可能なノブ（環境変数）](#tunable-knobs-environment-variables)
14. [パイプラインの拡張](#extending-the-pipeline)
15. [ベンチマークプロジェクトと結果](#benchmark-projects-and-results)
16. [制限事項と注意点](#limitations-and-gotchas)
17. [セキュリティ警告](#security-warning)
18. [開発：テスト、リンティング、コントリビューション](#development-testing-linting-contributing)
19. [用語集](#glossary)

---

## これは何か

このタスクフローは、完全に自律的なファジングパイプラインです。ネイティブ C/C++ プロジェクトの GitHub リポジトリを指定すると、次のことを行います：

1. 不足していれば AFL++ + clang/llvm/lcov + ctags/cscope/graphviz をインストールし、
2. ソースを取得し、
3. 候補となるファズターゲット（パーサー、デコーダー、バリデータなど）を特定し、
4. ビルドシステムを分析し、
5. ターゲットごとに 1 つ以上のハーネス候補を作成し、それぞれを AFL 計装された `.afl` バイナリとカバレッジ計装された `.cov` バイナリの両方としてビルドし、
6. （オプションで）60 秒間のカバレッジで候補を評価し、最良のものを保持し、
7. 時間予算を倍増させながらファズ/カバレッジ/改善ループを実行し、
8. すべてのクラッシュをトリアージし、以前に既知のクラッシュが依然として再現することを確認し、判定、悪用可能性、提案パッチ、回帰テストのスケッチを含むクラッシュごとの markdown 脆弱性レポートを作成し、
9. 次のキャンペーン用に Fuzz-Introspector スタイルのコールグラフ + 未到達 API レポートを構築し、
10. すべてをライブ HTML ダッシュボードに公開します。

このパイプラインは精神において **OSS-Fuzz スタイル**です。同じ手法の多く（フォーマット別ミューテータと辞書、構造認識トークンスプライシング、カバレッジ駆動のハーネス改善、機械可読レポート、重複排除されたスタックハッシュクラッシュ）を使用していますが、はるかに小さく自己完結しています。

---

## クイックスタート```bash
# Inside the codespace (or a host with python + git available):
./scripts/fuzzing/run_fuzzing.sh tukaani-project/xz

---

## アーキテクチャ

上から下へ3つのレイヤー:```
┌────────────────────────────────────────────────────────────────────┐
│  scripts/fuzzing/run_fuzzing.sh                                    │
│      shell driver; chains the taskflow stages with `set +e`        │
└────────────────────┬───────────────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│  src/seclab_taskflows/taskflows/fuzzing/*.yaml                     │
│      LLM agent prompts; one YAML per pipeline stage                │
└────────────────────┬───────────────────────────────────────────────┘
                     │  (calls MCP tools)
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│  src/seclab_taskflows/mcp_servers/                                 │
│   ├ fuzz_context.py    persistence (SQLite via SQLAlchemy)         │
│   └ fuzz_runner.py     subprocess wrappers (AFL, clang, lcov, ...) │
│                                                                    │
│  scripts/fuzzing/dashboard.py                                      │
│   read-only HTML view of fuzz_context.db                           │
└────────────────────────────────────────────────────────────────────┘

イテレーションごと、ハーネスごとに、エージェントは次のことを行います。

1. このハーネスの安定したコーパスディレクトリを取得するために `get_persistent_corpus_dir(harness_id)` を呼び出します。
2. `run_afl_for(afl_binary_path, seed_dir=<persistent corpus>, output_dir=<run dir>, seconds=<budget>, dictionary=<auto.dict>)` を呼び出します。
3. LCOV トレースファイルと HTML レポートを生成するために `run_coverage(cov_binary_path, inputs_dir=<run>/default/queue, output_dir=<run>/coverage)` を呼び出します。
4. `coverage_report` 行と未カバー項目ごとの `coverage_gap` 行を永続化するために `store_coverage_from_lcov(run_id, lcov_path, html_path)` を呼び出します。
5. AFL のイテレーションキューを永続コーパスにマージし、サイズを抑えるために `cmin` を実行するために `fold_queue_into_persistent_corpus(...)` を呼び出します。
6. `get_coverage_summary` と `get_coverage_gaps` を読み取り、次のいずれかを行います：
   - 未カバーの分岐に到達するために新しいシード（`coverage_feedback` タグ付き）を追加する、
   - 追加の API を呼び出すようにハーネスソースを編集する、
   - ガードを満たすために AFL が必要とするマジック定数の辞書エントリを自動追加するために `enrich_dictionary_from_uncovered(...)` を呼び出す、または
   - ギャップをスキップする（コールドエラーパス / ベンダーコード）。
7. ダッシュボードのイテレーションタイムラインが何が変更されたかを追跡できるように `store_iteration_note(repo, iteration_number, harness_id, note=<one line summary>)` を呼び出します。

**プラトー検出。** 2 回連続のイテレーションで行カバレッジの絶対パーセンテージポイントの増加が両方とも `< FUZZ_PLATEAU_THRESHOLD_PCT`（デフォルト `1.0`）未満になると、ループは早期に終了します。

---

## 構造認識ファジング

3 つの相補的なメカニズムが、生のバイト変更よりも強力な入力を生成します。

### 1. フォーマット別辞書 + カスタムミューテータ

`input_kind` が既知のフォーマットに一致するターゲット向けに、タスクフローは事前構築済みの辞書と `LLVMFuzzerCustomMutator` C ソースファイルを提供します：

| フォーマット | 辞書 | ミューテータ | 備考 |
|--------|------------|---------|-------|
| `json` | `json.dict` | `json_mutator.c` | トークンスプライス、バランス括弧の複製/削除、型反転 |
| `xml` | `xml.dict` | `xml_mutator.c` | タグ、エンティティ、DTD、billion-laughs トークン |
| `regex` | `regex.dict` | `regex_mutator.c` | アンカー、クラス、量指定子、実際の ReDoS パターン |
| `binary_tlv` | _(none)_ | `binary_tlv_mutator.c` | 長さプレフィックス付きレコード：長さオーバーフロー / 複製 / 削除 |
| `png` | `png.dict` | _(reuses binary_tlv)_ | PNG 辞書 + binary_tlv ミューテータ |

これらは `write_initial_harnesses`（辞書がシードの隣にコピーされる）と `build_harnesses`（ミューテータが AFL バイナリにリンクされる）によって自動的に取り込まれます。各ミューテータはミューテーションの 50% を AFL のデフォルトバイトミューテータに委譲するため、エンジンのランダム化を失いません。

新しいフォーマットを追加するには：`<name>.dict` および/または `<name>_mutator.c` を `src/seclab_taskflows/dictionaries/` に配置し、`fuzz_runner.py` の下部にある `_FORMAT_ASSETS` マップに登録します。

### 2. ソース認識（プロジェクト固有）スマートミューテータ

馴染みのないフォーマットの場合、またはより強力なプロジェクト固有のトークンが必要な場合は常に、`generate_smart_mutator` がターゲットリポジトリ自身の `.c`/`.h` ファイルをスキャンし、スプライス辞書が以下から抽出された `LLVMFuzzerCustomMutator` C ファイルを出力します：

- 3 文字以上の英字を含む文字列リテラル（コンパイラ/ライセンスノイズ、パス、ヘッダー、asm 制約、フォーマット指定子をフィルタリングした後）、
- `#define`、`case`、`enum` からの 32 ビット数値定数（0、1、256、0xff… のような一般的な小整数ノイズをフィルタリングした後）。

3 つのフォーカスが利用可能です：

| フォーカス | スプライスするもの | 使用する場面 |
|-------|-----------------|-------------|
| `strings` | プロジェクトの文字列リテラルのみ | テキストフォーマット（JSON、XML、YAML、CSV） |
| `constants` | 32 ビット数値マジック値のみ | バイナリプロトコル、マジックナンバーを含むヘッダー |
| `combined` | 両方 | デフォルト；通常は最良 |

`generate_smart_mutators(...)`（複数形）を `HARNESS_CANDIDATES >= 3` と組み合わせて、各フォーカスが予選ラウンドで候補ハーネスになるようにします。

### 3. プロジェクト認識 AFL 辞書 + カバレッジ駆動型エンリッチメント

2 つの相補的なツールが、キャンペーンの進行に合わせて AFL `-x` 辞書を構築・拡張します：

- **`generate_project_dictionary(source_root, output_path)`** — イテレーション 1 の前に 1 回実行され、スマートミューテータが使用するのと同じソーストークンセットを静的に抽出し、AFL 辞書として書き出します。数値定数は両方のエンディアンで出力されるため、ファザーはホストのバイトオーダーに関係なく `memcmp(x, &magic, 4)` を満たすことができます。

- **`enrich_dictionary_from_uncovered(source_root, dictionary_path, uncovered_locations)`** — 各イテレーションのカバレッジステップの後に実行され、未カバー行の周辺のソースを条件付きガード（`strncmp/memcmp/strstr`、`case 0xN:`、`== 0xN`、`== 'X'`）についてスキャンし、新しいトークンを辞書に追加します。冪等：すでに存在するエントリを再追加することはありません。

### 4. コーパススプライス演算

`corpus_dir` が `generate_smart_mutator` に渡されると、生成された C はコーパススプライス演算子も取得します：最初の呼び出しでそのディレクトリから最大 64 ファイル（各 4 KiB に制限）をロードし、それ以降はそれらのファイルのランダムなサブリージョンをミューテーションされた入力にスプライスできます。これにより、AFL の標準 havoc がうまく行わない再結合スタイルの演算子をミューテータに与えます。`get_persistent_corpus_dir(...)` と組み合わせて、スプライスライブラリが「AFL がすでに発見したものをリミックスする」ようにします。

---

## イテレーションとキャンペーンをまたぐ永続コーパス

各ハーネスには次の場所に安定したコーパスディレクトリがあります：```
<workspace>/corpus/harness_<id>/

---

## 出力ファイル

すべて `~/.local/share/seclab-taskflow-agent/seclab-taskflows/` 配下にあります。

| パス | 内容 |
|------|----------|
| `fuzz_context/fuzz_context.db` | SQLite — ターゲット、ハーネス、実行、カバレッジ、クラッシュ、判定、コールグラフ、ハーネス候補、イテレーションノート |
| `fuzz_runner/builds/` | ビルド済みの `.afl` および `.cov` バイナリ |
| `fuzz_runner/runs/` | AFL 出力ディレクトリ + LCOV ファイル + HTML カバレッジレポート |
| `fuzz_runner/corpus/harness_<id>/` | ハーネスごとの永続コーパス（イテレーションとキャンペーンをまたいで引き継がれる） |
| `fuzz_runner/repo/<owner>__<repo>/REPORT.md` | Markdown キャンペーンサマリ、判定別にグループ化されたクラッシュ |
| `fuzz_runner/repo/<owner>__<repo>/vuln_<crash_id>.md` | クラッシュごとの Markdown 脆弱性レポート |
| `fuzz_runner/repo/<owner>__<repo>/call_graph.{dot,svg,md}` | 静的コールグラフ + 到達/未到達のオーバーレイ |

---

## データベーススキーマ

`fuzz_context.db` 内のテーブル（SQLAlchemy 経由の SQLite）：

| テーブル | 注目すべきカラム |
|-------|--------------------|
| `fuzz_target` | `repo, file, function, signature, input_kind` |
| `harness` | `target_id, repo, harness_path, afl_binary_path, cov_binary_path, build_status, version, sanitizers` |
| `seed_corpus` | `target_id, source, path, bytes_count, added_in_iteration` |
| `fuzz_run` | `harness_id, iteration_number, exec_per_sec, paths_total, crashes_count, status, output_dir, started_at, ended_at` |
| `coverage_report` | `run_id, lines_total, lines_hit, line_pct, fns_*, branches_*, lcov_path, html_path` |
| `coverage_gap` | `report_id, file, function, line, kind, reason_hint` |
| `crash` | `run_id, input_blob_path, minimized_path, stack_top_hash, sanitizer_output, verdict, bug_class, cwe, severity, vuln_report_path, reproducer_path, classification, notes` |
| `call_graph` | `repo, target_id, dot_path, svg_path, functions_total, functions_in_graph, functions_reached, functions_unreached, untouched_surface_json` |
| `harness_suggestion` | `repo, function_name, file, rationale, input_kind, priority` |
| `iteration_note` | `repo, harness_id, iteration_number, note, created_at` |

スキーママイグレーションは `fuzz_context.py` の `_migrate()` にあります。新しいテーブルは
`Base.metadata.create_all()` によって自動的に作成されます。PRAGMA ベースの `ALTER TABLE` が
必要なのは新しいカラムのみです。

---

## MCP ツール（エージェントの語彙）

エージェントは AFL や clang を直接呼び出すことはありません — MCP ツールを
呼び出すことでパイプラインを構成します。目的別にグループ化した全ツールセットは以下のとおりです：

### 永続化 (`fuzz_context.py`)

- `store_fuzz_target`, `get_fuzz_targets`
- `store_harness`, `update_harness_build`, `get_harnesses`
- `store_seed`, `start_fuzz_run`, `finish_fuzz_run`, `get_fuzz_runs`
- `store_coverage_from_lcov`, `get_coverage_summary`, `get_coverage_gaps`,
  `coverage_plateau_reached`
- `store_crash`, `update_crash_verdict`, `get_crashes`,
  `get_crashes_grouped`, `suggest_severity`
- `store_call_graph`, `get_call_graphs`, `get_repo_reached_functions`
- `store_harness_suggestion`, `get_harness_suggestions`
- `store_iteration_note`, `get_iteration_notes`

### ビルド / ファズ / カバレッジ (`fuzz_runner.py`)

- `check_tooling`, `workspace_paths`
- `compile_harness` — `.afl` および `.cov` バイナリをビルド
- `run_afl_for`, `cmin`, `tmin`, `replay_under_asan`, `reproduce_crash`
- `run_coverage` — `.cov` バイナリに対して AFL キューをリプレイし、LCOV をエクスポート
- `extract_dictionary` — バイナリから印刷可能な文字列を抽出
- `package_reproducer` — 単一クラッシュの `.tgz` をバンドル

### 永続コーパス (v8)

- `get_persistent_corpus_dir`, `fold_queue_into_persistent_corpus`

### フォーマットアセット (C5)

- `list_format_assets`, `get_format_dictionary`, `write_format_mutator`

### スマートミューテータ + プロジェクト対応辞書

- `generate_smart_mutator`, `generate_smart_mutators`
- `generate_project_dictionary`, `enrich_dictionary_from_uncovered`

ツール関数は `@mcp.tool()` (FastMCP) でデコレートされています。テスト内では、
`.fn` 属性を介して呼び出します。例：
`fr.run_afl_for.fn(afl_binary_path=..., ...)`。

---

## 調整可能なノブ（環境変数）

| 変数 | デフォルト | 目的 |
|----------|---------|---------|
| `HARNESS_CANDIDATES` | `1` | ターゲットごとに書き込まれる候補ハーネスの数。OSS-Fuzz-Gen スタイルの競争には 2 または 3 に設定します。予選ステージでは各候補を `QUALIFIER_SECONDS` の間実行し、行カバレッジ % で最良のものを保持します。 |
| `QUALIFIER_SECONDS` | `60` | 予選ステージにおける候補ごとの実時間予算。 |
| `FUZZ_PLATEAU_THRESHOLD_PCT` | `1.0` | 連続する 2 回のイテレーションがプラトーと見なされ、ループが早期に停止する、行カバレッジの増加量（絶対 pp）のしきい値。 |
| `FUZZ_DASHBOARD_PORT` | `8765` | ライブダッシュボードのポート。 |
| `FUZZ_NO_DASHBOARD` | (未設定) | `1` に設定するとダッシュボードの起動をスキップします。 |
| `FUZZ_RUNNER_TIMEOUT` | `1200` | `fuzz_runner` におけるツールごとのサブプロセスタイムアウト（秒）。 |
| `LOCAL_SHELL_TIMEOUT` | `180` | `local_shell` におけるコマンドごとのタイムアウト（秒）。 |

さらに標準的なエージェント変数（`COPILOT_TOKEN`, `LOG_DIR`,
`FUZZ_CONTEXT_DIR`, …）があります。完全なリストはプロジェクトルートの README を参照してください。

---

## パイプラインの拡張

### 新しいフォーマットの追加（ミューテータ + 辞書）

1. `dictionaries/<name>.dict`（AFL `-x` フォーマット）および/または
   `dictionaries/<name>_mutator.c`（libFuzzer カスタムミューテータ）を配置します。
2. `fuzz_runner.py` の末尾にある `_FORMAT_ASSETS` に登録します：   ```python
   "<name>": {
       "dictionary": "<name>.dict",
       "mutator": "<name>_mutator.c",
       "description": "Short one-liner about the format",
   },

コードベースの規約（これらのキャンペーン履歴版については `benchmark/improvements.md` も参照）：

- `os.environ.get(NAME, "default")` ではなく `os.environ.get(NAME) or "default"` を使用すること。そうしないと、YAML テンプレート置換による空文字列が返されてしまう。
- 新しいアノテーションには `Optional[X]` ではなく `X | None`（PEP 604）を使用すること。
- テストはデコレートされた名前を直接呼び出すのではなく、`.fn(...)` を介して MCP ツールを呼び出すこと。
- テスト内で `/tmp/...` リテラルを避けること — `tmp_path` pytest フィクスチャを使用すること（lint ルール `S108`）。
- テストメソッド内のすべてのインラインインポートは、ファイルの先頭に移動できない場合（例えば `pytest.skip` の後に条件付きでインポートする場合）、`# noqa: PLC0415` が必要。
- 複合的な真偽テストは 1 行につき 1 アサーションとすること（lint ルール `PT018`）。

改善トラッカー（`benchmark/improvements.md`）は、バージョン間でパイプラインに追加された内容の永続的なログです。実質的な機能を追加した際は、何が変更されたか、どこに存在するか、どのテストがそれを保護しているかを記述したセクションをそこに追加してください。

---

## 用語集

- **AFL++** — カバレッジガイド型グレーボックスファザー。ここでの実行エンジン。
- **libAFLDriver** — AFL++ ハーネスが libFuzzer のエントリポイント規約（`LLVMFuzzerTestOneInput`）を使用できるようにする静的ライブラリ。
- **LCOV** — 業界標準のカバレッジトレースファイル形式。`llvm-cov export -format=lcov` を介してエクスポートし、独自に解析します。
- **`stack_top_hash`** — ASan/UBSan スタックトレースの正規化された上位 N フレームの 16 文字ハッシュ。クラッシュの重複排除に使用されます。
- **永続コーパス** — `<workspace>/corpus/harness_<id>/` にあるハーネスごとのディレクトリで、AFL の興味深い入力をイテレーションや同じキャンペーンの再実行をまたいで保持します。
- **スマートミューテータ** — スプライストークンがターゲット自身のソースコードから抽出される `LLVMFuzzerCustomMutator`（`generate_smart_mutator`）。
- **カスタムミューテータ（libFuzzer）** — バッファをどのようにミューテートするかを完全に自由に決定できる、ユーザー提供の C 関数。エンジンから呼び出されます。AFL++ も同じ ABI をサポートしています。
- **MCP ツール** — LLM エージェントが呼び出せる FastMCP でデコレートされた関数。
- **OSS-Fuzz / Fuzz-Introspector** — Google のオープンソースファジングインフラストラクチャと、そのコンパニオンであるコールグラフ/カバレッジ分析ツール。このタスクフローのいくつかの機能（フォーマットごとのミューテータ、スタックによる重複排除、コールグラフ + 未到達 API レポート、マルチ候補ハーネス）は、これらに触発されています。

---

## ライセンス

このプロジェクトは MIT オープンソースライセンスの条件の下でライセンスされています。完全な条件については [LICENSE](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/LICENSE.txt) ファイルを参照してください。

## メンテナ

[CODEOWNERS](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/CODEOWNERS) を参照するか、GitHub Security Lab チームにお問い合わせください。

## サポート

このプロジェクトに関するヘルプの入手方法の詳細については [SUPPORT.md](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/SUPPORT.md) を参照してください。

## 謝辞

このプロジェクトは [AFL++](https://github.com/AFLplusplus/AFLplusplus)、[OSS-Fuzz](https://github.com/google/oss-fuzz)、および [Fuzz-Introspector](https://github.com/ossf/fuzz-introspector) の概念と技術の上に構築されています。