> [!TIP]
> Documentación para contribuidores:  lee `docs/gosentry/index.md` para ver un mapa del código, el bucle de desarrollo recomendado, los puntos de entrada de CI y los scripts de benchmark.
> Este fork utiliza la Pull GitHub App para abrir y fusionar automáticamente los PR desde `golang/go:master` hacia `master`, asegurando que nunca nos quedemos atrás de las últimas actualizaciones de la cadena de herramientas de Go.

## Característica 1: Fuzzing consciente de structs (fuzzing de structs como entradas)

#### Resumen

El fuzzing nativo de Go (`go test -fuzz=...`) solo admite un pequeño conjunto de tipos escalares como parámetros de fuzzing (`[]byte`, `string`, números, ...). En gosentry, también puedes someter a fuzzing **tipos compuestos** construidos a partir de esos escalares: structs, arrays, slices y punteros.
Esto es útil cuando tu código acepta de forma natural entradas estructuradas y no quieres construir un codificador/decodificador personalizado solo para sembrar y mutar el corpus. 
Consulta `test/gosentry/examples/multiargs` y `test/gosentry/examples/composite` para ver ejemplos.

#### Ejemplo simple```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 veces esto puede no funcionar, porque Go está integrando la función en línea. Si `// overflow_false_positive` no es suficiente, añade `//go:noinline` antes de la firma de tu función.

## Característica 3: Pánico en funciones seleccionadas

Al hacer fuzzing de objetivos, puede interesarnos provocar un pánico cuando se llama a ciertas funciones. Por ejemplo, algún software puede emitir mensajes `log.error` en lugar de entrar en pánico, aunque tales condiciones suelen indicar estados que los investigadores de seguridad querrían detectar durante el fuzzing.
Sin embargo, estos errores normalmente se manejan internamente (por ejemplo, mediante mecanismos de reintento o pausa, o imprimiendo mensajes en los registros), lo que los hace en gran medida invisibles para los fuzzers. El objetivo de esta característica es abordar este problema.

#### Cómo usarlo

Compila gosentry y luego usa el indicador `--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"

Usa `-fuzztime=1m` para detener una campaña de LibAFL después de un minuto.

La generación de informes de cobertura a partir del corpus de una campaña de LibAFL se documenta en [Característica 8](#feature-8-generate-go-coverage-reports-from-fuzzing-campaign).

El fuzzing basado en gramáticas (Nautilus) se documenta en [Característica 7](#feature-7-grammar-based-fuzzing-nautilus).

<details>
<summary><strong>Cómo se conectan Go y 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     │
└───────────────────────────────────────────────────────────────────────────┘

Los fuzzers de última generación como AFL++ o LibAFL encontrarían el panic al instante en ese caso. Sin embargo, el fuzzer nativo de Go no lo haría. Esa es una brecha enorme que restringe la exploración de cobertura en **gran medida**.

El benchmark a continuación muestra esos límites. Ten en cuenta que esos benchmarks pueden **reproducirse** y mejorarse mediante el [repositorio gosentry-bench-libafl](https://github.com/kevin-valerio/gosentry-bench-libafl/tree/main).

##### Benchmark 1:

El gráfico a continuación muestra la evolución del número de líneas cubiertas al fuzzear el [UUID](https://github.com/google/uuid) de Google usando LibAFL frente al fuzzer nativo de Go.
![BENCH1](https://assets.kitploit.com/production/public/readmes/41918/7b1ea005996846c9ee4d7c0d42fee26731050d10b6b21d59c551e4b1b956923e.png "BENCH1")

##### Benchmark 2:

El gráfico a continuación muestra la evolución del número de líneas cubiertas al fuzzear [go-ethereum](https://github.com/ethereum/go-ethereum) usando LibAFL frente al fuzzer nativo de Go.
![BENCH2](https://assets.kitploit.com/production/public/readmes/41918/61aab8540ab8d339307854de6737a405056c3c8ad83a822df40f74e362b93021.png "BENCH2")



#### Ejemplo
Puedes probarlo en algunos harnesses de fuzzing en `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>` es el nombre del objetivo de fuzzing cuando `-fuzz` es un identificador simple como `FuzzXxx` (o `^FuzzXxx$`); de lo contrario, es `pattern-<hash>`.
- La generación de cobertura (`--generate-coverage`) usa la misma regla para encontrar el corpus `queue/` correcto, por lo que debe ejecutarse desde el mismo paquete con el mismo `-fuzz=...`.

## Característica 5: Fuzzing orientado a git-blame (experimental)

#### Resumen

El fuzzing guiado por cobertura es excelente para explorar nuevas rutas, pero trata todo el código cubierto como igualmente interesante. Al hacer fuzzing en bases de código grandes, es posible que desees sesgar el fuzzer hacia el código modificado recientemente, donde es más probable que se introduzcan regresiones y errores. En el modo LibAFL, gosentry puede usar `git blame` para preferir entradas que ejecuten líneas modificadas recientemente (manteniendo la guía de cobertura como señal principal).

Este trabajo se basa en trabajos previos de [LibAFL-git-aware](https://github.com/kevin-valerio/LibAFL-git-aware). Todos los detalles técnicos en profundidad están documentados allí.

#### Cómo usarlo

Habilita la planificación consciente de git 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