Le fuzzer natif de Go ne peut pas fuzzer une valeur struct directement (il ne sait muter qu'une petite liste de types scalaires). gosentry ajoute une petite couche de liaison : lorsque votre cible de fuzzing utilise des types composites (comme Input), gosentry fuzz un simple []byte en coulisses. À chaque exécution, il décode ces octets dans votre struct (champ par champ, récursivement pour les slices/tableaux/pointeurs), puis appelle votre rappel f.Fuzz avec la valeur décodée. Le même encodage est utilisé pour les seeds, de sorte qu'un f.Add(Input{...}) devient une entrée de corpus []byte encodée que le fuzzer peut réutiliser et muter comme n'importe quelle autre seed.

Les fuzzers (y compris LibAFL) mutent des octets bruts, nous voulons donc un décodeur capable de transformer n'importe quelle tranche d'octets en une valeur de struct « quelconque » et de continuer. JSON/gob rejetteraient la plupart des entrées aléatoires (mauvais pour la couverture) et ne rempliraient pas non plus les champs non exportés, alors que le fuzzing bénéficie souvent de la rupture des invariants. Ce format personnalisé est petit, rapide, déterministe et tolérant aux données malformées.

Sous le capot, cela utilise le propre format binaire simple de gosentry (pas gob, pas JSON). Le code se trouve dans src/testing/libafl.go :

• Encodage : libaflMarshalInputs / libaflAppendValue
• Décodage : libaflUnmarshalArgs / libaflDecodeValue

Règles d'encodage (niveau haut) :

• bool : 1 octet (0 ou 1)
• Entiers : octets en little-endian (int/uint font 8 octets)
• Flottants : bits IEEE-754 en little-endian (float32 = 4 octets, float64 = 8 octets)
• string : uvarint(len) puis les octets bruts de la chaîne
• []byte : uvarint(len) puis les octets bruts
• Autres slices : uvarint(len) puis chaque élément encodé
• Structures : champs encodés dans l'ordre de déclaration
• Pointeurs : 1 octet (0 = nil, 1 = présent) puis la valeur pointée

En mode --use-libafl, gosentry compile le harness Go avec l'instrumentation de couverture activée. Cela ajoute de petits compteurs au code qui changent lorsque différentes parties de votre programme s'exécutent. Lorsque le harness démarre dans golibafl, le runtime Go expose ces compteurs à LibAFL. LibAFL les lit après chaque entrée pour voir quel code a été exécuté, et utilise cette couverture pour guider les mutations suivantes.

.go.fuzzcntrs est la section de l'éditeur de liens qui contient les compteurs de couverture 8 bits de style libFuzzer de Go (activés par -gcflags=all=-d=libfuzzer) ; chaque octet indique « combien de fois ce point instrumenté a été atteint ». Lorsque --focus-on-new-code=true, golibafl génère git_recency_map.bin de la manière suivante :

1. Extraire go.o de libharness.a.
2. Lire la taille de la section .go.fuzzcntrs pour obtenir le nombre de compteurs N.
3. Analyser les relocations de .text qui référencent les symboles .go.fuzzcntrs pour retrouver l'adresse de chaque index de compteur.
4. Résoudre chaque adresse en file:line à l'aide de go tool addr2line.
5. Exécuter git blame --line-porcelain pour obtenir committer-time par ligne.
6. Écrire git_recency_map.bin sous la forme u64 head_time + u64 N + N * u64 timestamps (little-endian). Les entrées non mappées utilisent l'horodatage 0.

Exécuté avec misc/gosentry/bench_focus_on_new_code_geth.sh --trials 5 --warmup 600 --timeout 200.```text gitaware_5: crash (7122ms) baseline results: trial 1: crash (107747ms) trial 2: crash (146415ms) trial 3: crash (37902ms) trial 4: crash (154034ms) trial 5: timeout (200000ms) baseline crashes: 4/5 (timeouts=1, errors=0) baseline median (capped to timeout): 146.415s

git-aware results: trial 1: timeout (200000ms) trial 2: crash (87432ms) trial 3: crash (61733ms) trial 4: crash (157540ms) trial 5: crash (7122ms) git-aware crashes: 4/5 (timeouts=1, errors=0) git-aware median (capped to timeout): 87.432s

</details>

## Fonctionnalité 6 : Détecter les courses de données, les fuites de goroutines et les blocages (timeouts) au moment du fuzzing

##### Détection des blocages confirmés (timeouts LibAFL)

Lors du fuzzing avec LibAFL, une exécution de harness peut **expirer** (par exemple à cause d'un deadlock / de goroutines bloquées en attente, ou d'un chemin extrêmement lent).

Pour réduire les faux positifs, gosentry considère un timeout comme un candidat au blocage et le confirme en rejouant l'entrée ayant expiré plusieurs fois avec un timeout plus grand. En cas de blocage confirmé, gosentry écrit l'entrée dans `<libafl output dir>/hangs/` et arrête la campagne de fuzzing (il la traite comme un bug/crash).

Avant de se terminer, `golibafl` tente de minimiser l'entrée qui provoque le crash/blocage (au mieux ; les blocages sont plafonnés à ~60 s au total).

Remarque : la confirmation de blocage s'exécute également lors de l'importation/génération initiale du corpus, de sorte que les cibles qui expirent sur chaque entrée peuvent encore être détectées de manière déterministe.

Ceci est configuré via `--libafl-config` :
- `catch_hangs` (défaut : `true`)
- `hang_timeout_ms` (défaut : `10000`)
- `hang_confirm_runs` (défaut : `3`)

##### Détection des courses de données (`--catch-races`)

gosentry peut exécuter une boucle de rejeu séparée `-race` qui surveille le répertoire `queue/` de LibAFL et rejoue les seeds nouvellement découvertes avec `GORACE=halt_on_error=1`.

La boucle de rejeu construit une archive de harness `-race` séparée, réservée au rejeu (sans instrumentation de couverture de fuzzing).

Lorsqu'une course de données est détectée pendant le rejeu, gosentry affiche le rapport complet du détecteur de courses avant le résumé `catch-races:` et la commande de reproduction.

Remarque : le détecteur de courses de Go ne détecte les courses de données qu'**à l'intérieur d'une seule exécution de harness** (courses entre goroutines du même processus accédant à la même mémoire sans synchronisation appropriée). `--catch-races` manquera les courses si la seed ne déclenche pas la concurrence conflictuelle, et il ne détecte pas les courses entre processus.

<details>
<summary><strong>Comment fonctionne le mode de détection de courses de données</strong></summary>

Ce mode démarre un petit moniteur à l'intérieur de `go test` (même processus parent), et il s'exécute pendant toute la campagne de fuzzing.

- Quand : avant que le processus principal de fuzzing LibAFL ne soit démarré, gosentry construit le harness de rejeu + le runner.
- Surveillance : avant que le fuzzing ne démarre, gosentry enregistre l'état initial du contenu de `<libafl output dir>/queue/` dans un ensemble `seen`. Une goroutine interroge ensuite `<libafl output dir>/queue/` toutes les ~1 s et ne rejoue que les seeds nouvellement créées (ignore les fichiers cachés et `*.metadata`).```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)                          │
└───────────────────────────────────────────────────────────────────────────┘

Ce mode démarre également un petit moniteur dans go test (même processus parent), et il s'exécute pendant toute la campagne de fuzzing.

• Surveillance : une goroutine interroge <libafl output dir>/queue/ toutes les ~1s et rejoue chaque nouvelle seed avec GOSENTRY_LIBAFL_CATCH_LEAKS=1 (active go.uber.org/goleak après chaque exécution).```text Legend: output/... = /...

┌───────────────────────────────────────────────────────────────────────────┐ │ 1) Main LibAFL fuzzing run │ │ - golibafl writes new seeds to output/queue/ │ └───────────────┬───────────────────────────────────────────────────────────┘ v ┌───────────────────────────────────────────────────────────────────────────┐ │ 2) --catch-leaks sidecar setup │ │ - builds replay runner: golibafl-leak (linked against the harness) │ └───────────────┬───────────────────────────────────────────────────────────┘ v ┌───────────────────────────────────────────────────────────────────────────┐ │ 3) Replay loop │ │ - polls output/queue/ for new seeds │ │ - runs: GOSENTRY_LIBAFL_CATCH_LEAKS=1 golibafl-leak run --input <seed>│ │ (enables go.uber.org/goleak checks after each execution) │ └───────────────┬───────────────────────────────────────────────────────────┘ v ┌───────────────────────────────────────────────────────────────────────────┐ │ 4) On "catch-leaks: detected goroutine leak" │ │ - copies seed to output/leaks/ │ │ - stops the fuzz campaign (treat as bug/crash) │ └───────────────────────────────────────────────────────────────────────────┘

</details>


#### Comment utiliser

Activez la détection de fuites de goroutines avec `--catch-leaks=true` ou la détection de courses avec `--catch-races=true````bash
./bin/go test -fuzz=FuzzHarness --use-libafl --focus-on-new-code=false --catch-races=true --catch-leaks=true

Fonctionnalité 7: Fuzzing basé sur la grammaire (Nautilus)

Vue d'ensemble

Le fuzzing au niveau des octets est excellent, mais les parseurs et les formats de fichiers nécessitent souvent des entrées structurées. Avec --use-grammar, gosentry utilise le mutateur de grammaire Nautilus de LibAFL pour générer et muter des entrées conformes à une grammaire fournie par l'utilisateur (format JSON), et les transmet à votre harnais de fuzzing Go habituel (testing.F.Fuzz).

En mode grammaire, LibAFL continue d'exécuter la boucle normale guidée par la couverture (choisir une graine de corpus → muter → exécuter → conserver les entrées qui augmentent la couverture). Le runner ajoute la mutation Nautilus (graine → arbre de grammaire → muter → déparser) ainsi que (par défaut) une étape guidée par CMPLOG, de type I2S, qui réécrit les terminaux feuilles de Nautilus en fonction des comparaisons à l'exécution. Cela garantit que les entrées restent grammaticalement valides (il n'exécute pas les étapes brutes de type havoc/token au niveau des octets en mode grammaire). Vous pouvez désactiver l'étape CMPLOG/I2S dans --libafl-config via nautilus_cmplog_i2s=false (le fuzzing au niveau des octets garde toujours CMPLOG/I2S activé).

[!NOTE] Le mode grammaire est généralement plus lent que le fuzzing au niveau des octets. C'est un compromis : plus de structure vs moins d'exécutions par seconde.

Pour de meilleurs résultats, utilisez un callback de fuzz à un argument qui accepte soit une tranche d'octets ([]byte), soit une string:```go f.Fuzz(func(t testing.T, data []byte) { / parse data */ }) // or: f.Fuzz(func(t testing.T, s string) { / parse s */ })

Le mode grammaire fonctionne mieux avec un seul argument d’entrée (`[]byte` ou `string`). Les callbacks de fuzz multi-arguments amènent gosentry à décoder le tampon d’octets sous-jacent en valeurs séparées, de sorte que le texte généré par la grammaire d’origine ne reste pas intact.

> [!NOTE]
> Le mode grammaire génère toujours des **octets/chaînes**. Si vous avez besoin d’entrées structurées (ou si vous faites du fuzzing différentiel), c’est dans votre harness que vous convertissez `data` en valeurs du domaine (parse/unmarshal). (En dehors du mode grammaire, gosentry peut également fuzzer des types composites Go > en les décodant depuis des octets ; voir [Fonctionnalité 1](#feature-1-struct-aware-fuzzing-fuzz-structs-as-inputs).)

Vous pouvez régler Nautilus via `--libafl-config` (utilisé uniquement avec `--use-grammar`) : `nautilus_max_len` et `nautilus_cmplog_i2s` (voir `misc/gosentry/libafl.config.jsonc`).

<details>
<summary><strong>Benchmark : étape CMPLOG/I2S de la grammaire Nautilus (activée vs désactivée)</strong></summary>

Exécuté le 17 février 2026 avec l’exemple de grammaire JSON du dépôt (`test/gosentry/examples/grammar_json`, `FuzzGrammarJSON`, grammaire `testdata/JSON.json`).

Résultats (LibAFL `UserStats`) :

| mode | `nautilus_cmplog_i2s` | durée | exécutions | exéc/s | arêtes |
|---|---:|---:|---:|---:|---:|
| activé | `true` | 1m-5s | 103818 | 1.586k | 388/8008 (4%) |
| désactivé | `false` | 1m-0s | 256659 | 4.251k | 388/8008 (4%) |

Remarque : `edges` correspond aux arêtes de la carte de couverture de LibAFL, et non aux lignes de source Go.

Définissez `GOSENTRY_VERBOSE_AFL=1` pour afficher quelques entrées générées. Définissez `GOSENTRY_VERBOSE_AFL_ALL_INPUTS=1` pour afficher **chaque** exécution en mode grammaire sous la forme `GOLIBAFL_MUTATED_INPUT "..."` (très bavard).

#### Aides à la création de grammaires

Si vous devez créer une nouvelle grammaire JSON Nautilus pour votre propre format/protocole cible, gosentry fournit :

- Un prompt prêt pour LLM : [misc/gosentry/nautilus/prompt.md](https://github.com/trailofbits/gosentry/blob/HEAD/misc/gosentry/nautilus/prompt.md)
- Un petit ensemble de grammaires d’exemple : [misc/gosentry/nautilus/examples/](https://github.com/trailofbits/gosentry/blob/HEAD/misc/gosentry/nautilus/examples/)

<details>
<summary><strong>Exemple de harness de fuzz Go (JSON)</strong></summary>```go
func FuzzGrammarJSON(f *testing.F) {
	f.Fuzz(func(t *testing.T, data []byte) {
		dec := json.NewDecoder(bytes.NewReader(data))
		dec.UseNumber()

		var v any
		if err := dec.Decode(&v); err != nil {
			t.Fatalf("invalid JSON: %v", err)
		}
		if err := dec.Decode(&struct{}{}); err != io.EOF {
			t.Fatalf("invalid JSON: trailing data")
		}
	})
}

Ébauche de harnais de fuzzing différentiel (deux analyseurs) :```go f.Fuzz(func(t *testing.T, data []byte) { gotA, errA := ParseA(data) gotB, errB := ParseB(data) if (errA == nil) != (errB == nil) { t.Fatalf("parser disagreement: A=%v B=%v", errA, errB) } _ = gotA _ = gotB })

</details>

<details>
<summary><strong>Exemple : fuzzing grammatical d'un « vrai langage d'entrée » (sans encodeur personnalisé)</strong></summary>

Cet exemple fuzze un petit évaluateur d'expressions arithmétiques en générant des **expressions valides** à partir d'une grammaire. Il n'y a pas d'encodage « struct to bytes » ad hoc : le fuzzer produit le même type d'entrée que votre code analyserait normalement.

Harness (une entrée `string` à 1 argument fonctionne le mieux en mode grammaire) :```go
func FuzzExprEval(f *testing.F) {
	f.Add("1+2")
	f.Add("(3*4)-5")

	f.Fuzz(func(t *testing.T, expr string) {
		// Parse+eval your language/protocol.
    // You can be **sure** that `expr` will always be a valid math operation. Just decode/parse/unmarshall it afterwards. 
		_, _ = Eval(expr)
	})
}

Schéma de grammaire (format JSON Nautilus):```json [ ["Expr", "{Term}"], ["Expr", "{Term}+{Expr}"], ["Expr", "{Term}-{Expr}"], ["Term", "{Factor}"], ["Term", "{Factor}*{Term}"], ["Factor", "{Num}"], ["Factor", "({Expr})"], ["Num", "0"], ["Num", "1"], ["Num", "2"], ["Num", "3"] ]

</details>

<details>
<summary><strong>Exemple de grammaire JSON Nautilus (petit sous-ensemble JSON)</strong></summary>

C'est le format de fichier attendu par `--grammar=...` :
- La grammaire est un tableau JSON de règles : `["NonTerm", "RHS"]`.
- Les noms de non-terminaux doivent commencer par une lettre majuscule (`Value`, `Object`, ...).
- Utilisez `{NonTerm}` dans la RHS pour référencer une autre règle.
- `{` et `}` sont réservés aux références de non-terminaux ; pour émettre des accolades littérales, utilisez `\\{` et `\\}` dans la chaîne RHS.```json
[
  ["Json", "{Value}"],
  ["Value", "null"],
  ["Value", "{String}"],
  ["String", "\"{Chars}\""],
  ["Chars", ""],
  ["Chars", "{Char}{Chars}"],
  ["Char", "a"],
  ["Char", "b"]
]

┌───────────────────────────────────────────────────────────────────────────┐ │ 0) gosentry go test -fuzz=FuzzXxx (LibAFL + --use-grammar) │ │ - captures your testing.F.Fuzz callback + its parameter types │ │ - builds libharness.a (libFuzzer-style entrypoints for LibAFL) │ │ - runs golibafl fuzz ... --use-grammar --grammar ... │ └───────────────┬───────────────────────────────────────────────────────────┘ v ┌───────────────────────────────────────────────────────────────────────────┐ │ 1) golibafl (Rust + LibAFL) fuzzes the Go harness in-process │ │ - loads libharness.a via HARNESS_LIB=... │ │ - observers: edges + time (+ cmplog for comparisons) │ │ - feedback/objective: coverage/time/crash (and optional hang handling) │ │ - scheduler selects a corpus seed (coverage-guided) │ └───────────────┬───────────────────────────────────────────────────────────┘ v ┌───────────────────────────────────────────────────────────────────────────┐ │ 2) Nautilus (in-process, per client) │ │ - loads the JSON grammar into a Nautilus context │ │ - fuzz loop stage: parse seed -> mutate tree -> unparse to bytes │ │ - if the seed is not parseable: fall back to generation-from-scratch │ └───────────────┬───────────────────────────────────────────────────────────┘ v ┌───────────────────────────────────────────────────────────────────────────┐ │ 3) Grammar mode stages │ │ - initial corpus: if input dir empty, call generate N times │ │ - fuzz loop: corpus seed -> grammar mutate -> exec harness │ │ - new coverage inputs are added to the on-disk corpus (output/queue/) │ └───────────────────────────────────────────────────────────────────────────┘

</details>

Limitations (glue actuelle) :
- Le mode grammaire fonctionne mieux avec un seul argument d'entrée ; les cibles de fuzzing multi-arguments décodent le tampon d'octets sous-jacent en valeurs séparées.
- Pas encore de recombinaison/croisement de grammaire entre deux graines du corpus (la mutation est à graine unique).

## Fonctionnalité 8 : Générer des rapports de couverture Go à partir de la campagne de fuzzing

Après (ou pendant) l'exécution d'une campagne de fuzzing LibAFL, gosentry peut générer un rapport de couverture Go en rejouant le **corpus de file d'attente** LibAFL actuel (sans fuzzing).```bash
# Same package + same fuzz target as your fuzz campaign:
./bin/go test -fuzz=FuzzHarness --generate-coverage .

Ceci rejoue les entrées de <libafl output dir>/queue/ et écrit cover.out et cover.html.

Trophées

Ces bugs ont été découverts en menant une campagne de fuzzing différentiel utilisant la fonctionnalité de fuzzing par grammaire de gosentry.

Optimism

• Kona et op-node peuvent être en désaccord sur les canaux brotli
• Un type de batch inconnu déclenche une panique et provoque un déni de service dans kona-protocol
• Incohérence d'analyse des trames de Kona par rapport à op-node et aux spécifications OP Stack

REVM

• Un dépôt échoué dans op-revm s'arrêtant avec OutOfFunds n'incrémente pas le nonce, ce qui conduit à une divergence de state root avec les autres clients

Crédits

• golibafl
• Nautilus
• LibAFL
• goleak
• go
• go-panikint