> [!TIP]
> コントリビューター向けドキュメント: コードマップ、推奨される開発ループ、CI エントリポイント、ベンチマークスクリプトについては、`docs/gosentry/index.md` をお読みください。
> このフォークは Pull GitHub App を使用して、`golang/go:master` から `master` への PR を開き自動マージすることで、Go ツールチェーンの最新アップデートから遅れないようにしています。

## 機能 1: 構造体を意識したファジング（構造体を入力としてファズ）

#### 概要

Go のネイティブなファジング (`go test -fuzz=...`) は、ファズパラメータとして少数のスカラー型 (`[]byte`, `string`, 数値, ...) のみをサポートしています。gosentry では、それらのスカラーから構築された**複合型**（構造体、配列、スライス、ポインタ）もファズできます。
これは、コードが自然に構造化入力を受け取り、コーパスをシードしてミューテーションするためだけに独自のエンコーダ/デコーダを構築したくない場合に便利です。
例については、`test/gosentry/examples/multiargs` と `test/gosentry/examples/composite` を参照してください。

#### 簡単な例```go
type Input struct {
	Data []byte
	S    string
	N    int
	OK   bool
}

func FuzzStructInput(f *testing.F) {
	// Seed the initial corpus with a Go struct (gosentry feature).
	f.Add(Input{Data: []byte("A"), S: "B", N: 7, OK: true})

	f.Fuzz(func(t *testing.T, in Input) {
		if in.OK && in.N == 1337 && in.S == "BOOMMOOB" && bytes.Equal(in.Data, []byte("A")) {
			t.Fatalf("boom")
		}
	})
}

これが機能しない場合がありますが、それはGoが関数をインライン化しているためです。`// overflow_false_positive` で不十分な場合は、関数シグネチャの前に `//go:noinline` を追加してください。

## Feature 3: Panic on selected functions

ファジングの対象を調査する際、特定の関数が呼び出されたときにパニックを発生させたい場合があります。例えば、一部のソフトウェアはパニックを起こさずに `log.error` メッセージを出力する場合がありますが、そのような状況は、セキュリティ研究者がファジング中に検出したい状態を示していることがよくあります。
しかし、これらのエラーは通常、内部的に処理されるため（再試行や一時停止のメカニズム、またはログへのメッセージ出力など）、ファザーからはほぼ見えません。この機能の目的は、この問題に対処することです。

#### 使い方

gosentry をコンパイルし、`--panic-on` フラグを使用します。```bash
./bin/go test -fuzz=FuzzHarness --use-libafl --focus-on-new-code=false --catch-races=false --catch-leaks=false --panic-on="test_go_panicon.(*Logger).Warning,test_go_panicon.(*Logger).Error"

`-fuzztime=1m` を使用すると、LibAFL キャンペーンを 1 分後に停止できます。

LibAFL キャンペーンのコーパスからのカバレッジレポート生成については、[機能 8](#feature-8-generate-go-coverage-reports-from-fuzzing-campaign) に記載されています。

文法ベースのファジング (Nautilus) については、[機能 7](#feature-7-grammar-based-fuzzing-nautilus) に記載されています。

<details>
<summary><strong>Go + LibAFL の連携方法</strong></summary>```text
┌───────────────────────────────────────────────────────────────────────────┐
│ 1) gosentry `go test`                                                      │
│    - captures  `testing.F.Fuzz(...)` callback                             │
│    - generates  extra source file: `_libaflmain.go`                       │
└───────────────┬───────────────────────────────────────────────────────────┘
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 2) Generated bridge: `_libaflmain.go`                                     │
│    - provides libFuzzer-style C ABI entrypoints:                          │
│        LLVMFuzzerInitialize                                               │
│        LLVMFuzzerTestOneInput                                             │
│    - adapts bytes -> Go types -> calls the captured fuzz callback         │
└───────────────┬───────────────────────────────────────────────────────────┘ 
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 3) `libharness.a` (static archive on disk) contains:                      │
│      - compiled objects for all test package (+ dependencies)             │
│      - generated `_testmain.go` + `_libaflmain.go`                        │
│      - LLVMFuzzerInitialize                                               │
│      - LLVMFuzzerTestOneInput                                             │
└───────────────┬───────────────────────────────────────────────────────────┘
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 4) `golibafl/` (Rust + LibAFL)                                            │
│    env: HARNESS_LIB=/path/to/libharness.a                                 │
│    fuzz loop: mutate input -> LLVMFuzzerTestOneInput(data) -> observe     │
└───────────────────────────────────────────────────────────────────────────┘

SOTAファザー（AFL++やLibAFLなど）は、その場合パニックを即座に検出するでしょう。しかし、Goネイティブファザーはそうではありません。これは、カバレッジ探索を**大幅に**制限する大きなギャップです。

以下のベンチマークは、これらの限界を示しています。これらのベンチマークは、[gosentry-bench-libafl リポジトリ](https://github.com/kevin-valerio/gosentry-bench-libafl/tree/main)で**再現**および改善できることに注意してください。

##### ベンチマーク1:

下のチャートは、LibAFLとGoネイティブファザーを使用してGoogleの[UUID](https://github.com/google/uuid)をファジングした際にカバーされた行数の推移です。
![BENCH1](https://assets.kitploit.com/production/public/readmes/41918/7b1ea005996846c9ee4d7c0d42fee26731050d10b6b21d59c551e4b1b956923e.png "BENCH1")

##### ベンチマーク2:

下のチャートは、LibAFLとGoネイティブファザーを使用して[go-ethereum](https://github.com/ethereum/go-ethereum)をファジングした際にカバーされた行数の推移です。
![BENCH2](https://assets.kitploit.com/production/public/readmes/41918/61aab8540ab8d339307854de6737a405056c3c8ad83a822df40f74e362b93021.png "BENCH2")



#### 例
`test/gosentry/examples/` にあるいくつかのファジングハーネスでテストできます。```bash
cd test/gosentry/examples/reverse
../../../../bin/go test -fuzz=FuzzReverse --focus-on-new-code=false --catch-races=false --catch-leaks=false

Notes:
- `<harness>` は、`-fuzz` が `FuzzXxx`（または `^FuzzXxx$`）のような単純な識別子である場合のファズターゲット名です。それ以外の場合は `pattern-<hash>` です。
- カバレッジ生成（`--generate-coverage`）は、正しい `queue/` コーパスを見つけるために同じルールを使用するため、同じパッケージから同じ `-fuzz=...` で実行する必要があります。

## 機能5: Git-blame指向ファジング（実験的）

#### 概要

カバレッジ誘導ファジングは新しいパスを探索するのに優れていますが、カバーされたすべてのコードを同等に興味深いものとして扱います。大規模なコードベースをファジングする際には、リグレッションやバグが発生しやすい最近変更されたコードにファザーを偏らせたい場合があります。LibAFLモードでは、gosentryは`git blame`を使用して、最近変更された行を実行する入力を優先できます（カバレッジガイダンスを主要なシグナルとして維持しつつ）。

この作業は、[LibAFL-git-aware](https://github.com/kevin-valerio/LibAFL-git-aware) の以前の作業に基づいています。技術的な詳細はすべてそこに文書化されています。

#### 使用方法

`--focus-on-new-code=true` でgit対応スケジューリングを有効にします：```bash
./bin/go test -fuzz=FuzzHarness --use-libafl --focus-on-new-code=true --catch-races=false --catch-leaks=false

</details>

## 機能 6: ファズ時に競合状態、goroutine リーク、ハング（タイムアウト）を検出する

##### 確認済みハングの捕捉（LibAFL タイムアウト）

LibAFL でファジングを行うと、ハーネスの実行が **タイムアウト** することがあります（例: デッドロック、待機中にスタックした goroutine、または非常に遅いパス）。

誤検知を減らすため、gosentry はタイムアウトをハングの候補として扱い、タイムアウトした入力をより大きなタイムアウトで数回リプレイして確認します。ハングが確認された場合、gosentry は入力を `<libafl output dir>/hangs/` に書き込み、ファズキャンペーンを停止します（バグ/クラッシュとして扱います）。

終了前に、`golibafl` はクラッシュ/ハングする入力を最小化しようとします（ベストエフォート。ハングは合計で最大約60秒に制限されます）。

注: ハング確認は初期コーパスのインポート/生成中にも実行されるため、すべての入力でタイムアウトするターゲットでも決定的に検出できます。

これは `--libafl-config` で設定します:
- `catch_hangs` (デフォルト: `true`)
- `hang_timeout_ms` (デフォルト: `10000`)
- `hang_confirm_runs` (デフォルト: `3`)

##### データ競合の捕捉（`--catch-races`）

gosentry は、LibAFL の `queue/` ディレクトリを監視し、`GORACE=halt_on_error=1` を設定して新たに発見されたシードをリプレイする、独立した `-race` リプレイループを実行できます。

リプレイループは、リプレイ専用（ファズカバレッジ計測なし）の別の `-race` ハーネスアーカイブを構築します。

リプレイ中にデータ競合が検出されると、gosentry は `catch-races:` の要約と再現コマンドの前に、完全なレース検出レポートを出力します。

注: Go のレース検出器は、**単一のハーネス実行内** のデータ競合のみを検出します（同じプロセス内の goroutine が適切な同期なしに同じメモリにアクセスする競合）。`--catch-races` は、シードが競合する並行処理をトリガーしない場合、競合を見逃します。また、プロセス間の競合も検出しません。

<details>
<summary><strong>データ競合モードの仕組み</strong></summary>

このモードは、`go test` 内（同じ親プロセス）に小さなモニターを起動し、ファズキャンペーン全体を通じて実行します。

- タイミング: メインの LibAFL ファジングプロセスが開始される前に、gosentry はリプレイハーネス + ランナーを構築します。
- 監視: ファジング開始前に、gosentry は `<libafl output dir>/queue/` の初期内容を `seen` セットにスナップショットします。その後、goroutine が `<libafl output dir>/queue/` を約1秒ごとにポーリングし、新しく作成されたシードのみをリプレイします（ドットファイルと `*.metadata` はスキップします）。

</details>```text
Legend: output/... = <libafl output dir>/...

┌───────────────────────────────────────────────────────────────────────────┐
│ 1) Main LibAFL fuzzing run                                                 │
│    - `golibafl` writes new seeds to `output/queue/`                        │
└───────────────┬───────────────────────────────────────────────────────────┘
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 2) `--catch-races` sidecar setup                                           │
│    - builds replay harness: `libharness_race.a` (`go test -race ...`)      │
│    - builds replay runner: `golibafl-race` (linked against race harness)   │
└───────────────┬───────────────────────────────────────────────────────────┘
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 3) Replay loop                                                             │
│    - polls `output/queue/` for new seeds                                   │
│    - runs: `GORACE=halt_on_error=1 golibafl-race run --input <seed>`       │
│      (2 workers × 3 repeats per seed)                                      │
└───────────────┬───────────────────────────────────────────────────────────┘
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 4) On "DATA RACE"                                                          │
│    - prints the race detector report                                       │
│    - copies seed to `output/races/`                                        │
│    - stops the fuzz campaign (treat as bug/crash)                          │
└───────────────────────────────────────────────────────────────────────────┘