# 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 de WuppieFuzz." src="https://raw.githubusercontent.com/tno-s3/wuppiefuzz/HEAD/assets/WuppieFuzz.svg" width="40%" min-width="250px" align="right">
</picture>

TNO a développé WuppieFuzz, un fuzzer d'API REST guidé par la couverture, construit sur
LibAFL, ciblant un large public d'utilisateurs finaux, avec un fort accent sur
la facilité d'utilisation, l'explicabilité des failles découvertes et la modularité. WuppieFuzz
prend en charge les trois modes de test (boîte noire, boîte grise et boîte blanche).

> [!NOTE]  
> Pour un guide rapide et pas à pas, veuillez suivre le [tutoriel](https://github.com/tno-s3/wuppiefuzz/blob/main/tutorial) !

## Couverture médiatique

WuppieFuzz a été présenté dans :

- [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)


### Publication scientifique

Si vous souhaitez citer WuppieFuzz dans un travail académique, veuillez utiliser la
publication préférée listée dans [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

## Licence

WuppieFuzz est sous licence Apache-2.0 ; voir [LICENSE](https://github.com/tno-s3/wuppiefuzz/blob/main/LICENSE).  
Les mentions de licence tierces sont listées dans [THIRD_PARTY_NOTICES](https://github.com/tno-s3/wuppiefuzz/blob/main/THIRD_PARTY_NOTICES).

## Installation rapide

Pour une installation rapide de WuppieFuzz sur les systèmes d'exploitation populaires (MacOS,
Windows, Linux), voir [releases](https://github.com/TNO-S3/WuppieFuzz/releases/) ou utilisez [`brew install wuppiefuzz`](https://formulae.brew.sh/formula/wuppiefuzz)

### Docker

Vous pouvez construire l'image Docker avec `docker build . -t wuppiefuzz:local`. Pour l'utiliser, vous devez monter un dossier contenant votre spécification OpenAPI. Lorsque vous fuzzuez un service que vous exécutez localement (pas dans Docker), vous devez spécifier le réseau de l'hôte :

``` 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
```



### Guide rapide

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

## Prérequis pour le développement

Pour construire le projet, vous devez installer les dépendances et outils suivants :

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

## Exécution

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

Avant d'exécuter WuppieFuzz, vous devez démarrer votre application cible
(instrumentée).

De plus, vous devez fournir à WuppieFuzz une **spécification OpenAPI** afin qu'il
sache comment générer et muter ses requêtes. Pour obtenir de l'aide sur les arguments
de ligne de commande, utilisez ce qui suit :

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

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

Par exemple, pour exécuter WuppieFuzz contre une cible Java avec l'agent JaCoCo
attaché, vous spécifiez son fichier OpenAPI (contenant l'URL sur laquelle la cible
est exécutée dans la spécification de l'API). De plus, vous spécifiez que le format de
couverture est JaCoCo, et indiquez le répertoire des classes comme suit :

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

## Fichier de configuration

Si vous souhaitez utiliser un fichier de configuration à la place des arguments de
ligne de commande, ou en combinaison avec ceux-ci, vous pouvez utiliser le drapeau `--config <CONFIG_FILE>`. Si vous utilisez
des arguments de ligne de commande en combinaison avec un fichier de configuration, les arguments de ligne de commande
ont la priorité.

Le fichier de configuration doit être un fichier yaml et contenir une ligne pour chaque argument
de ligne de commande que vous souhaitez spécifier, par exemple :

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

Un exemple de commande d'exécution pourrait dans ce cas être :

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

Cette ligne combinerait les arguments de la ligne de commande et du fichier de
configuration. Comme le drapeau `--timeout` est spécifié dans les deux, le timeout spécifié dans
la ligne de commande (10 secondes) aura la priorité.

Dans le répertoire `example_configs/` vous trouverez deux exemples de fichiers de configuration à
utiliser pour générer des rapports de couverture avec JaCoCo pour du code Java et pour générer
des rapports de couverture avec LCOV pour du code Python.

## Rapports

Lorsque vous exécutez WuppieFuzz avec le drapeau `--report`, un sous-répertoire est créé dans
`reports/` avec un horodatage comme nom. Tous les rapports de couverture pris en charge sont
écrits dans ce sous-répertoire. Il existe deux types de rapports de couverture :

1. **couverture des endpoints** : peut toujours être générée puisqu'elle ne nécessite que
   la spécification OpenAPI.
2. **couverture du code** : actuellement prise en charge uniquement pour JaCoCo, mais nous visons à en prendre en charge
   davantage. La partie délicate est que cela nécessite une correspondance entre la couverture et les fichiers sources,
   et une génération de rapport robuste qui l'utilise.

En plus de cela, une base de données est remplie avec toutes les informations de requêtes liées à votre
campagne de fuzzing. Cette base de données peut être visualisée et explorée via le
tableau de bord Grafana.

## Structure de ce dépôt

- **assets** : logos, images, etc.
- **coverage_agents** : code et instructions pour le suivi de couverture à appliquer sur
  diverses cibles
- **example_configs** : exemples de fichiers de configuration pour configurer WuppieFuzz
- **src** : code source de WuppieFuzz
- **tutorial** : un tutoriel approfondi et de bas niveau sur la façon de fuzzer une cible
  spécifique et comment interpréter les résultats de fuzzing
- **dashboard** : outillage pour trier les résultats de fuzzing et les performances

Pour plus d'informations sur chacun de ces éléments, voir les READMEs dans ces répertoires.

## Build de développement

Par défaut, WuppieFuzz embarque ses dépendances C (OpenSSL, SQLite, Z3) afin qu'un
`cargo build` classique fonctionne immédiatement. Pour une compilation plus rapide pendant
le développement, vous pouvez désactiver toutes les dépendances embarquées et lier contre
des bibliothèques installées sur le système à la place.

> [!NOTE]
> Le crate `z3` nécessite Z3 4.15+, qui est plus récent que la version fournie par
> la plupart des gestionnaires de paquets des distributions Linux. Installez Z3 via
> [Homebrew](https://brew.sh/) (`brew install z3`) pour obtenir une version compatible.

### Dépendances système

Installez les bibliothèques suivantes sur votre système :

**Debian/Ubuntu :**

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

Sur Linux, Homebrew s'installe dans un chemin non standard. Ajoutez son répertoire de bibliothèques
à votre environnement afin que le compilateur et l'éditeur de liens à l'exécution puissent trouver 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]
> Ajoutez les lignes ci-dessus à votre `~/.bashrc` ou `~/.zshrc` pour les rendre permanentes.

**Fedora (42+) :**

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

**macOS (Homebrew) :**

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

### Alias Cargo

Le dépôt inclut des alias cargo dans `.cargo/config.toml` qui compilent avec
`--no-default-features`, en liant contre toutes les bibliothèques système :

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

## Génération de la documentation

`cargo doc --no-deps` pour générer la documentation à partir des commentaires dans le code
source. La page principale de la documentation sera
`target/doc/wuppiefuzz/index.html`
WuppieFuzz

Populaires
