WuppieFuzz

# WuppieFuzz v1.8.0

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/WuppieFuzz-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="assets/WuppieFuzz.svg">
  <img alt="Logo di WuppieFuzz." src="https://raw.githubusercontent.com/tno-s3/wuppiefuzz/HEAD/assets/WuppieFuzz.svg" width="40%" min-width="250px" align="right">
</picture>

TNO ha sviluppato WuppieFuzz, un fuzzer REST API coverage-guided sviluppato su
LibAFL, rivolto a un'ampia platea di utenti finali, con una forte attenzione
alla facilità d'uso, all'esplicabilità dei difetti individuati e alla modularità. WuppieFuzz
supporta tutte e tre le modalità di testing (black box, grey box e white box).

> [!NOTE]  
> Per una guida rapida e passo-passo, segui il [tutorial](https://github.com/tno-s3/wuppiefuzz/blob/main/tutorial)!

## Copertura mediatica

WuppieFuzz è stato presentato in:

- [The ONE Conference e-magazine 2024](https://emagazine.one-conference.nl/2024/finally-validate-your-publicly-exposed-interfaces-with-ease/)
- [Test your APIs easily with TNO's new REST API fuzzer](https://www.tno.nl/en/newsroom/insights/2024/10/application-security-testing/)
- [OpenAPI.tools listing: WuppieFuzz](https://openapi.tools/tools/wuppiefuzz)
- [Automated REST API Vulnerability Detection with WuppieFuzz (Nordic APIs on YouTube)](https://www.youtube.com/watch?v=JcV9RUBvb2w)
- [Thoughtworks Technology Radar: WuppieFuzz](https://www.thoughtworks.com/radar/tools/wuppiefuzz)


### Pubblicazione scientifica

Se desideri citare WuppieFuzz in un lavoro accademico, utilizza la pubblicazione
preferita elencata in [CITATION.cff](https://github.com/tno-s3/wuppiefuzz/blob/main/CITATION.cff):

Rooijakkers, T., Nijsten, A., Daniele, C., Weitenberg, E., Groenewegen, R., &
Melissen, A. (2026). *WuppieFuzz: Coverage-Guided, Stateful REST API Fuzzing*.
In *Proceedings of the 12th International Conference on Information Systems
Security and Privacy (ICISSP), Volume 2*, 221-231. SciTePress.
https://doi.org/10.5220/0000217100004061

## Licenza

WuppieFuzz è distribuito con licenza Apache-2.0; vedi [LICENSE](https://github.com/tno-s3/wuppiefuzz/blob/main/LICENSE).  
Le note sulle licenze di terze parti sono elencate in [THIRD_PARTY_NOTICES](https://github.com/tno-s3/wuppiefuzz/blob/main/THIRD_PARTY_NOTICES).

## Installazione rapida

Per un'installazione rapida di WuppieFuzz sui sistemi operativi più diffusi (MacOS,
Windows, Linux) vedi [releases](https://github.com/TNO-S3/WuppieFuzz/releases/) oppure usa [`brew install wuppiefuzz`](https://formulae.brew.sh/formula/wuppiefuzz)

### Docker

Puoi creare l'immagine docker con `docker build . -t wuppiefuzz:local`. Per usarla, devi montare una cartella contenente la tua specifica openapi. Quando fai fuzzing su un servizio in esecuzione localmente (non in Docker), devi specificare il networking dell'host:

``` shell
docker run \
  --network host \
  -v ./fuzzing-folder:/fuzzing-folder \  # The folder will be populated with wuppiefuzz outputs
  -w /fuzzing-folder \
  wuppiefuzz:local fuzz --timeout 60 --report openapi.json
```



### Breve guida pratica

[![How to use WuppieFuzz? - YouTube](https://raw.githubusercontent.com/tno-s3/wuppiefuzz/HEAD/assets/demo_video.png)](https://www.youtube.com/watch?v=-oR4d9aXrqo)

## Prerequisiti per lo sviluppo

Per compilare il progetto devi installare le seguenti dipendenze e strumenti:

```
sudo apt install -y build-essential pkg-config cmake  # General build tools
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh  # Rust
```

## Esecuzione

<picture>
  <img alt="WuppieFuzz in azione." src="https://raw.githubusercontent.com/tno-s3/wuppiefuzz/HEAD/assets/WuppieFuzz-action.jfif" width="40%" min-width="250px" align="right">
</picture>

Prima di eseguire WuppieFuzz, devi avviare la tua applicazione target
(strumentata).

Inoltre, devi fornire a WuppieFuzz una **specifica OpenAPI** in modo che
sappia come generare e mutare le sue richieste. Per assistenza sugli argomenti
della riga di comando, usa quanto segue:

```sh
$ cargo run -- --help # shows help for required parameters and flags

Usage: wuppiefuzz [OPTIONS] [OPENAPI_SPEC.YAML]
...
```

Ad esempio, per eseguire WuppieFuzz contro un target Java con l'agente JaCoCo
collegato, specifichi il suo file OpenAPI (contenente l'URL su cui è in esecuzione
il target nella specifica API). Inoltre, specifichi che il formato di
coverage è JaCoCo e indichi la directory delle classi come segue:

```sh
cargo run -- fuzz openapi.yaml --coverage-format jacoco --jacoco-class-dir ../Targets/app/target/classes/
```

## File di configurazione

Se vuoi usare un file di configurazione invece di/in combinazione con gli argomenti
della riga di comando, puoi usare il flag `--config <CONFIG_FILE>`. Nel caso in cui usi
argomenti della riga di comando in combinazione con un file di configurazione, gli argomenti della riga di comando hanno la precedenza.

Il file di configurazione deve essere un file yaml e contenere una riga per ogni argomento
della riga di comando che vuoi specificare, ad esempio:

```yaml
coverage_format: jacoco
output_format: human-readable
source_dir: "/swagger-petstore/src/main/java"
jacoco_class_dir: "/swagger-petstore/target"
timeout: 20
```

Un esempio di comando di esecuzione potrebbe in questo caso essere:

```sh
$ cargo run -- fuzz --config=config.yaml --report --coverage-host=localhost:6300 --timeout=10 ./openapi.yaml
```

Questa riga combinerebbe gli argomenti dalla riga di comando e dal file di
configurazione. Poiché il flag `--timeout` è specificato in entrambi, il timeout specificato nella
riga di comando (10 secondi) avrà la precedenza.

Nella directory `example_configs/` troverai due file di configurazione di esempio da
usare per generare report di coverage con JaCoCo per codice Java e per generare
report di coverage con LCOV per codice Python.

## Report

Quando esegui WuppieFuzz con il flag `--report`, viene creata una sottodirectory all'interno di
`reports/` con un timestamp come nome. Tutti i report di coverage supportati vengono
scritti in questa sottodirectory. Esistono due tipi di report di coverage:

1. **endpoint coverage**: può essere sempre generato poiché richiede solo
   la specifica OpenAPI.
2. **code coverage**: attualmente supportato solo per JaCoCo, ma puntiamo a supportarne
   altri. La parte complicata è che questo richiede una mappatura dal coverage ai file
   sorgente, e una generazione di report robusta che la utilizzi.

Inoltre, un database viene popolato con tutte le informazioni sulle richieste relative alla tua
campagna di fuzzing. Questo database può essere visualizzato ed esplorato tramite la
dashboard Grafana.

## Struttura di questo repository

- **assets**: loghi, immagini, ecc.
- **coverage_agents**: codice e istruzioni per il tracciamento del coverage da applicare a
  vari target
- **example_configs**: file di configurazione di esempio per configurare WuppieFuzz
- **src**: codice sorgente di WuppieFuzz
- **tutorial**: un tutorial approfondito e di basso livello su come fare fuzzing di uno specifico
  target e su come interpretare i risultati del fuzzing
- **dashboard**: strumenti per il triage dei risultati del fuzzing e delle prestazioni

Per maggiori informazioni su ciascuno di questi, vedi i README in queste directory.

## Build di sviluppo

Per impostazione predefinita, WuppieFuzz include le sue dipendenze C (OpenSSL, SQLite, Z3) in modo che
un normale `cargo build` funzioni subito. Per una compilazione più rapida durante
lo sviluppo, puoi disabilitare tutte le dipendenze incluse e collegarti invece alle
librerie installate nel sistema.

> [!NOTE]
> Il crate `z3` richiede Z3 4.15+, che è più recente della versione fornita dalla
> maggior parte dei gestori di pacchetti delle distribuzioni Linux. Installa Z3 tramite
> [Homebrew](https://brew.sh/) (`brew install z3`) per ottenere una versione compatibile.

### Dipendenze di sistema

Installa le seguenti librerie sul tuo sistema:

**Debian/Ubuntu:**

```sh
sudo apt install libssl-dev libsqlite3-dev
brew install z3  # apt's libz3-dev is too old; use Homebrew instead
```

Su Linux, Homebrew installa in un percorso non standard. Aggiungi la sua directory delle librerie
al tuo ambiente in modo che il compilatore e il linker a runtime possano trovare Z3:

```sh
eval "$(brew shellenv)"
export LIBRARY_PATH="$(brew --prefix z3)/lib:$LIBRARY_PATH"
export LD_LIBRARY_PATH="$(brew --prefix z3)/lib:$LD_LIBRARY_PATH"
```

> [!TIP]
> Aggiungi le righe sopra al tuo `~/.bashrc` o `~/.zshrc` per renderle permanenti.

**Fedora (42+):**

```sh
sudo dnf install openssl-devel sqlite-devel z3-devel
```

**macOS (Homebrew):**

```sh
brew install openssl sqlite z3
```

### Alias Cargo

Il repository include alias cargo in `.cargo/config.toml` che compilano con
`--no-default-features`, collegandosi a tutte le librerie di sistema:

```sh
cargo dev-build          # build without vendored dependencies
cargo dev-run -- <args>  # run without vendored dependencies
cargo dev-test           # test without vendored dependencies
```

## Generazione della documentazione

`cargo doc --no-deps` per generare la documentazione dai commenti nel codice
sorgente. La pagina principale della documentazione sarà
`target/doc/wuppiefuzz/index.html`