> [!TIP]
> Documentazione per contributori:  leggi `docs/gosentry/index.md` per una mappa del codice, il ciclo di sviluppo consigliato, i punti di ingresso della CI e gli script di benchmark.
> Questo fork utilizza la Pull GitHub App per aprire e unire automaticamente le PR da `golang/go:master` in `master`, assicurandoci di non rimanere mai indietro rispetto agli ultimi aggiornamenti della toolchain Go.

## Funzionalità 1: Fuzzing consapevole delle struct (fuzz di struct come input)

#### Panoramica

Il fuzzing nativo di Go (`go test -fuzz=...`) supporta solo un piccolo insieme di tipi scalari come parametri di fuzz (`[]byte`, `string`, numeri, ...). In gosentry, puoi anche fare fuzz di **tipi compositi** costruiti da quegli scalari: struct, array, slice e puntatori.
Questo è utile quando il tuo codice accetta naturalmente input strutturati e non vuoi costruire un encoder/decoder personalizzato solo per inizializzare e mutare il corpus.
Vedi `test/gosentry/examples/multiargs` e `test/gosentry/examples/composite` per esempi.

#### Esempio semplice```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")
		}
	})
}

A volte questo potrebbe non funzionare, perché Go sta in-lineando la funzione. Se `// overflow_false_positive` non basta, aggiungi `//go:noinline` prima della firma della tua funzione.

## Funzionalità 3: Panico su funzioni selezionate

Quando si eseguono test di fuzzing sui target, potrebbe interessarci innescare un panico quando vengono chiamate determinate funzioni. Ad esempio, alcuni software possono emettere messaggi `log.error` invece di andare in panico, anche se tali condizioni spesso indicano stati che i ricercatori di sicurezza vorrebbero rilevare durante il fuzzing.
Tuttavia, questi errori sono solitamente gestiti internamente (ad esempio tramite meccanismi di retry o pausa, oppure stampando messaggi nei log), il che li rende in gran parte invisibili ai fuzzer. L'obiettivo di questa funzionalità è risolvere questo problema.

#### Come usarlo

Compila gosentry, poi usa il flag `--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"

Use `-fuzztime=1m` per fermare una campagna LibAFL dopo un minuto.

La generazione del report di copertura dal corpus di una campagna LibAFL è documentata nella [Funzione 8](#feature-8-generate-go-coverage-reports-from-fuzzing-campaign).

Il fuzzing basato su grammatiche (Nautilus) è documentato nella [Funzione 7](#feature-7-grammar-based-fuzzing-nautilus).

<details>
<summary><strong>Come Go + LibAFL sono collegati tra loro</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 fuzzers come AFL++ o LibAFL troverebbero il panic istantaneamente in quel caso. Tuttavia, il fuzzer nativo di Go non lo troverebbe. Questo è un divario enorme che limita **molto** l'esplorazione della copertura.

I benchmark qui sotto mostrano questi limiti. Nota che questi benchmark possono essere **riprodotti** e migliorati tramite il [repository gosentry-bench-libafl](https://github.com/kevin-valerio/gosentry-bench-libafl/tree/main).

##### Benchmark 1:

Il grafico seguente mostra l'evoluzione del numero di righe coperte durante il fuzzing di [UUID](https://github.com/google/uuid) di Google con LibAFL rispetto al fuzzer nativo di Go.
![BENCH1](https://assets.kitploit.com/production/public/readmes/41918/7b1ea005996846c9ee4d7c0d42fee26731050d10b6b21d59c551e4b1b956923e.png "BENCH1")

##### Benchmark 2:

Il grafico seguente mostra l'evoluzione del numero di righe coperte durante il fuzzing di [go-ethereum](https://github.com/ethereum/go-ethereum) con LibAFL rispetto al fuzzer nativo di Go.
![BENCH2](https://assets.kitploit.com/production/public/readmes/41918/61aab8540ab8d339307854de6737a405056c3c8ad83a822df40f74e362b93021.png "BENCH2")



#### Esempio
Puoi testarlo su alcuni harness di fuzzing in `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

Note:
- `<harness>` è il nome del target di fuzzing quando `-fuzz` è un semplice identificatore come `FuzzXxx` (o `^FuzzXxx$`), altrimenti è `pattern-<hash>`.
- La generazione della coverage (`--generate-coverage`) usa la stessa regola per trovare il corpus `queue/` giusto, quindi deve essere eseguita dallo stesso package con lo stesso `-fuzz=...`.

## Funzionalità 5: fuzzing orientato a Git blame (sperimentale)

#### Panoramica

Il fuzzing guidato dalla coverage è ottimo per esplorare nuovi percorsi, ma tratta tutto il codice coperto come ugualmente interessante. Quando si esegue il fuzzing su codebase di grandi dimensioni, potrebbe essere utile orientare il fuzzer verso il codice modificato di recente, dove è più probabile che vengano introdotte regressioni e bug. In modalità LibAFL, gosentry può usare `git blame` per preferire input che eseguono righe modificate di recente (mantenendo comunque la guida della coverage come segnale primario).

Questo lavoro si basa su un precedente lavoro di [LibAFL-git-aware](https://github.com/kevin-valerio/LibAFL-git-aware). Tutti i dettagli tecnici approfonditi sono documentati lì.

#### Come usarlo

Abilita la schedulazione git-aware con `--focus-on-new-code=true`:```bash
./bin/go test -fuzz=FuzzHarness --use-libafl --focus-on-new-code=true --catch-races=false --catch-leaks=false