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

TNO desarrolló WuppieFuzz, un fuzzer de API REST guiado por cobertura construido sobre
LibAFL, dirigido a un amplio público de usuarios finales, con un fuerte enfoque en
la facilidad de uso, la explicabilidad de los fallos descubiertos y la modularidad. WuppieFuzz
admite los tres modos de pruebas (caja negra, caja gris y caja blanca).

> [!NOTE]  
> Para una guía rápida y paso a paso, ¡sigue el [tutorial](https://github.com/tno-s3/wuppiefuzz/blob/main/tutorial)!

## Cobertura mediática

WuppieFuzz ha aparecido en:

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


### Publicación científica

Si deseas citar WuppieFuzz en un trabajo académico, utiliza la publicación
preferida que figura en [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

## Licencia

WuppieFuzz está licenciado bajo Apache-2.0; consulta [LICENSE](https://github.com/tno-s3/wuppiefuzz/blob/main/LICENSE).  
Los avisos de licencias de terceros se enumeran en [THIRD_PARTY_NOTICES](https://github.com/tno-s3/wuppiefuzz/blob/main/THIRD_PARTY_NOTICES).

## Instalación rápida

Para una instalación rápida de WuppieFuzz en los sistemas operativos más populares (MacOS,
Windows, Linux), consulta [releases](https://github.com/TNO-S3/WuppieFuzz/releases/) o usa [`brew install wuppiefuzz`](https://formulae.brew.sh/formula/wuppiefuzz)

### Docker

Puedes construir la imagen de Docker con `docker build . -t wuppiefuzz:local`. Para usarla, debes montar una carpeta que contenga tu especificación OpenAPI. Al hacer fuzzing de un servicio que se ejecuta localmente (no en Docker), debes especificar el modo de red del 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
```



### Guía rápida

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

## Requisitos previos para el desarrollo

Para construir el proyecto necesitas instalar las siguientes dependencias y herramientas:

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

## Ejecución

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

Antes de ejecutar WuppieFuzz, debes iniciar tu aplicación objetivo
(instrumentada).

Además, debes proporcionar a WuppieFuzz una **especificación OpenAPI** para que
sepa cómo generar y mutar sus peticiones. Para obtener ayuda sobre los argumentos
de línea de comandos, usa lo siguiente:

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

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

Por ejemplo, para ejecutar WuppieFuzz contra un objetivo Java con el agente JaCoCo
adjunto, especificas su archivo OpenAPI (que contiene la URL en la que se ejecuta
el objetivo en la especificación de la API). Además, especificas que el formato de
cobertura es JaCoCo y proporcionas el directorio de clases de la siguiente manera:

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

## Archivo de configuración

Si deseas usar un archivo de configuración en lugar de (o en combinación con) los argumentos
de línea de comandos, puedes usar el flag `--config <CONFIG_FILE>`. En caso de que uses
argumentos de línea de comandos junto con un archivo de configuración, los argumentos de línea
de comandos tienen prioridad.

El archivo de configuración debe ser un archivo yaml y contener una línea por cada argumento
de línea de comandos que desees especificar, por ejemplo:

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

Un comando de ejecución de ejemplo podría ser en este caso:

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

Esta línea combinaría los argumentos de la línea de comandos y del archivo de
configuración. Dado que el flag `--timeout` se especifica en ambos, el timeout especificado en
la línea de comandos (10 segundos) tendrá prioridad.

En el directorio `example_configs/` encontrarás dos archivos de configuración de ejemplo para
usar al generar informes de cobertura con JaCoCo para código Java y para generar
informes de cobertura con LCOV para código Python.

## Informes

Cuando ejecutas WuppieFuzz con el flag `--report`, se crea un subdirectorio dentro de
`reports/` con una marca de tiempo como nombre. Todos los informes de cobertura admitidos se
escriben en este subdirectorio. Hay dos tipos de informes de cobertura:

1. **cobertura de endpoints**: esto siempre se puede generar, ya que solo requiere
   la especificación OpenAPI.
2. **cobertura de código**: actualmente solo se admite para JaCoCo, pero nuestro objetivo es admitir
   más. La parte complicada es que esto requiere un mapeo de la cobertura a los archivos
   fuente, y una generación robusta de informes que lo utilice.

Además de esto, se llena una base de datos con toda la información de las peticiones relacionada con tu
campaña de fuzzing. Esta base de datos se puede visualizar y explorar a través del
panel de Grafana.

## Estructura de este repositorio

- **assets**: logos, imágenes, etc.
- **coverage_agents**: código e instrucciones para el seguimiento de cobertura que se aplica a
  varios objetivos
- **example_configs**: archivos de configuración de ejemplo para configurar WuppieFuzz
- **src**: código fuente de WuppieFuzz
- **tutorial**: un tutorial detallado y de bajo nivel sobre cómo hacer fuzzing de un objetivo
  específico y cómo interpretar los resultados del fuzzing
- **dashboard**: herramientas para clasificar los resultados y el rendimiento del fuzzing

Para más información sobre cada uno de estos, consulta los README en estos directorios.

## Compilación de desarrollo

Por defecto, WuppieFuzz incluye sus dependencias de C (OpenSSL, SQLite, Z3) para que
un `cargo build` normal funcione sin configuración adicional. Para una compilación más rápida durante
el desarrollo, puedes deshabilitar todas las dependencias incluidas y enlazar contra
bibliotecas instaladas en el sistema en su lugar.

> [!NOTE]
> El crate `z3` requiere Z3 4.15+, que es más reciente que la versión distribuida por
> la mayoría de los gestores de paquetes de distribuciones Linux. Instala Z3 a través de
> [Homebrew](https://brew.sh/) (`brew install z3`) para obtener una versión compatible.

### Dependencias del sistema

Instala las siguientes bibliotecas en tu sistema:

**Debian/Ubuntu:**

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

En Linux, Homebrew instala en una ruta no estándar. Añade su directorio de bibliotecas
a tu entorno para que el compilador y el enlazador en tiempo de ejecución puedan encontrar 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]
> Añade las líneas anteriores a tu `~/.bashrc` o `~/.zshrc` para hacerlas permanentes.

**Fedora (42+):**

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

**macOS (Homebrew):**

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

### Alias de Cargo

El repositorio incluye alias de cargo en `.cargo/config.toml` que compilan con
`--no-default-features`, enlazando contra todas las bibliotecas del sistema:

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

## Generación de documentación

`cargo doc --no-deps` para generar documentación a partir de los comentarios en el código
fuente. La página principal de la documentación será
`target/doc/wuppiefuzz/index.html`