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

A TNO desenvolveu o WuppieFuzz, um fuzzer de API REST guiado por cobertura, construído sobre o
LibAFL, direcionado a um amplo público de usuários finais, com forte foco em
facilidade de uso, explicabilidade das falhas descobertas e modularidade. O WuppieFuzz
suporta os três modos de teste (caixa preta, caixa cinza e caixa branca).

> [!NOTE]  
> Para um guia rápido e passo a passo, siga o [tutorial](https://github.com/tno-s3/wuppiefuzz/blob/main/tutorial)!

## Cobertura na mídia

O WuppieFuzz foi destaque em:

- [The ONE Conference e-magazine 2024](https://emagazine.one-conference.nl/2024/finally-validate-your-publicly-exposed-interfaces-with-ease/)
- [Teste suas APIs facilmente com o novo fuzzer de API REST da TNO](https://www.tno.nl/en/newsroom/insights/2024/10/application-security-testing/)
- [Listagem no OpenAPI.tools: WuppieFuzz](https://openapi.tools/tools/wuppiefuzz)
- [Detecção automatizada de vulnerabilidades em APIs REST com WuppieFuzz (Nordic APIs no YouTube)](https://www.youtube.com/watch?v=JcV9RUBvb2w)
- [Thoughtworks Technology Radar: WuppieFuzz](https://www.thoughtworks.com/radar/tools/wuppiefuzz)


### Publicação científica

Se você quiser citar o WuppieFuzz em trabalhos acadêmicos, use a publicação
preferencial listada em [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

## Licença

O WuppieFuzz é licenciado sob Apache-2.0; consulte [LICENSE](https://github.com/tno-s3/wuppiefuzz/blob/main/LICENSE).  
Os avisos de licenças de terceiros estão listados em [THIRD_PARTY_NOTICES](https://github.com/tno-s3/wuppiefuzz/blob/main/THIRD_PARTY_NOTICES).

## Instalação rápida

Para uma instalação rápida do WuppieFuzz nos principais sistemas operacionais (MacOS,
Windows, Linux), consulte as [releases](https://github.com/TNO-S3/WuppieFuzz/releases/) ou use [`brew install wuppiefuzz`](https://formulae.brew.sh/formula/wuppiefuzz)

### Docker

Você pode construir a imagem Docker com `docker build . -t wuppiefuzz:local`. Para usá-la, você deve montar uma pasta contendo sua especificação OpenAPI. Ao fuzzear um serviço que você está executando localmente (não no Docker), você precisa especificar o host networking:

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



### Guia rápido

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

## Pré-requisitos para desenvolvimento

Para construir o projeto, você precisa instalar as seguintes dependências e ferramentas:

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

## Execução

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

Antes de executar o WuppieFuzz, você precisa iniciar sua aplicação alvo
(instrumentada).

Além disso, você deve fornecer ao WuppieFuzz uma **especificação OpenAPI** para que ele
saiba como gerar e mutar suas requisições. Para obter ajuda sobre os argumentos
de linha de comando, use o seguinte:

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

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

Por exemplo, para executar o WuppieFuzz contra um alvo Java com o agente JaCoCo
anexado, você especifica seu arquivo OpenAPI (contendo a URL em que o alvo está sendo executado
na especificação da API). Além disso, você especifica que o formato de cobertura
é JaCoCo e fornece o diretório de classes da seguinte forma:

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

## Arquivo de configuração

Se você quiser usar um arquivo de configuração em vez de/em combinação com argumentos
de linha de comando, você pode usar a flag `--config <CONFIG_FILE>`. Caso você use
argumentos de linha de comando em combinação com um arquivo de configuração, os argumentos
de linha de comando têm precedência.

O arquivo de configuração deve ser um arquivo yaml e conter uma linha para cada argumento
de linha de comando que você deseja especificar, por exemplo:

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

Um exemplo de comando de execução poderia, neste caso, ser:

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

Esta linha combinaria os argumentos da linha de comando e do arquivo de
configuração. Como a flag `--timeout` é especificada em ambos, o timeout especificado na
linha de comando (10 segundos) terá precedência.

No diretório `example_configs/` você encontrará dois arquivos de configuração de exemplo para
usar na geração de relatórios de cobertura com JaCoCo para código Java e para geração de
relatórios de cobertura com LCOV para código Python.

## Relatórios

Quando você executa o WuppieFuzz com a flag `--report`, um subdiretório é criado dentro de
`reports/` com um timestamp como nome. Todos os relatórios de cobertura suportados são
escritos neste subdiretório. Existem dois tipos de relatórios de cobertura:

1. **cobertura de endpoints**: isto pode sempre ser gerado, pois requer apenas
   a especificação OpenAPI.
2. **cobertura de código**: atualmente suportado apenas para JaCoCo, mas pretendemos suportar
   mais. A parte complicada é que isto requer um mapeamento de cobertura para arquivos
   de código-fonte, e uma geração robusta de relatórios que use isso.

Além disso, um banco de dados é preenchido com todas as informações de requisições relacionadas à sua
campanha de fuzzing. Este banco de dados pode ser visualizado e explorado através do
dashboard Grafana.

## Estrutura deste repositório

- **assets**: logos, imagens, etc.
- **coverage_agents**: código e instruções para rastreamento de cobertura a serem aplicados em
  vários alvos
- **example_configs**: arquivos de configuração de exemplo para configurar o WuppieFuzz
- **src**: código-fonte do WuppieFuzz
- **tutorial**: um tutorial aprofundado e de baixo nível sobre como fuzzear um alvo
  específico e como interpretar os resultados do fuzzing
- **dashboard**: ferramentas para triagem dos resultados e desempenho do fuzzing

Para mais informações sobre cada um destes, consulte os READMEs nesses diretórios.

## Build de desenvolvimento

Por padrão, o WuppieFuzz inclui suas dependências C (OpenSSL, SQLite, Z3) para que
um `cargo build` normal funcione imediatamente. Para uma compilação mais rápida durante
o desenvolvimento, você pode desabilitar todas as dependências incluídas e linkar contra
bibliotecas instaladas no sistema.

> [!NOTE]
> O crate `z3` requer Z3 4.15+, que é mais recente que a versão fornecida pela
> maioria dos gerenciadores de pacotes de distribuições Linux. Instale o Z3 via
> [Homebrew](https://brew.sh/) (`brew install z3`) para obter uma versão compatível.

### Dependências do sistema

Instale as seguintes bibliotecas no seu sistema:

**Debian/Ubuntu:**

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

No Linux, o Homebrew instala em um caminho não padrão. Adicione seu diretório de bibliotecas
ao seu ambiente para que o compilador e o linker de runtime possam encontrar o 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]
> Adicione as linhas acima ao seu `~/.bashrc` ou `~/.zshrc` para torná-las permanentes.

**Fedora (42+):**

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

**macOS (Homebrew):**

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

### Aliases do Cargo

O repositório inclui aliases do cargo em `.cargo/config.toml` que compilam com
`--no-default-features`, linkando contra todas as bibliotecas do sistema:

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

## Gerando documentação

`cargo doc --no-deps` para gerar documentação a partir dos comentários no código-
fonte. A página principal da documentação será
`target/doc/wuppiefuzz/index.html`