WuppieFuzz v1.7.1

A TNO desenvolveu o WuppieFuzz, um fuzzer de API REST guiado por cobertura, desenvolvido sobre o LibAFL, direcionado a um amplo público de utilizadores finais, com um forte foco em facilidade de utilização, explicabilidade das falhas descobertas e modularidade. O WuppieFuzz suporta todas as três configurações de teste (caixa preta, caixa cinzenta e caixa branca).

[!NOTE]
Para uma orientação rápida e passo a passo, siga o tutorial!

Cobertura mediática

O WuppieFuzz foi apresentado em:

Publicação científica

Se pretender citar o WuppieFuzz em trabalhos académicos, utilize a publicação preferida listada em 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 está licenciado sob Apache-2.0; consulte LICENSE.
Os avisos de licença de terceiros estão listados em THIRD_PARTY_NOTICES.

Instalação rápida

Para instalação rápida do WuppieFuzz em sistemas operativos populares (MacOS, Windows, Linux), consulte releases ou utilize brew install wuppiefuzz

Breve guia de utilização

Pré-requisitos para desenvolvimento

Para compilar o projeto, é necessário instalar as seguintes dependências e ferramentas

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

Executar

Antes de executar o WuppieFuzz, tem de iniciar a sua aplicação alvo (instrumentada).

Além disso, deve fornecer ao WuppieFuzz uma especificação OpenAPI para que ele saiba como gerar e mutar os seus pedidos. Para obter ajuda sobre os argumentos da linha de comandos, utilize o seguinte:

$ cargo run -- --help # mostra ajuda para os parâmetros e flags necessários

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

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

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

Ficheiro de configuração

Se pretender utilizar um ficheiro de configuração em vez de/em combinação com argumentos da linha de comandos, pode utilizar a flag --config <CONFIG_FILE>. Caso utilize argumentos da linha de comandos em combinação com um ficheiro de configuração, os argumentos da linha de comandos têm precedência.

O ficheiro de configuração deve ser um ficheiro yaml e conter uma linha para cada argumento da linha de comandos que pretenda especificar, por exemplo:

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:

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

Esta linha combinaria os argumentos da linha de comandos e do ficheiro de configuração. Uma vez que a flag --timeout é especificada em ambos, o timeout especificado na linha de comandos (10 segundos) terá precedência.

No diretório example_configs/ encontrará dois ficheiros de configuração de exemplo para utilizar na geração de relatórios de cobertura com JaCoCo para código Java e para a geração de relatórios de cobertura com LCOV para código Python.

Relatórios

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

cobertura de endpoints: pode ser sempre gerada, pois apenas requer a especificação OpenAPI.
cobertura de código: atualmente suportada apenas para JaCoCo, mas pretendemos suportar mais. A parte complicada é que isto requer um mapeamento da cobertura para os ficheiros de origem e uma geração robusta de relatórios que utilize esse mapeamento.

Além disso, uma base de dados é preenchida com todas as informações de pedidos relacionadas com a sua campanha de fuzzing. Esta base de dados pode ser visualizada e explorada através do painel Grafana.

Estrutura deste repositório

assets: logótipos, imagens, etc.
coverage_agents: código e instruções para o rastreamento de cobertura a aplicar em vários alvos
example_configs: ficheiros 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 fazer fuzzing de um alvo específico e como interpretar os resultados do fuzzing
dashboard: ferramentas para triagem dos resultados do fuzzing e do desempenho

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

Compilação de desenvolvimento

Por predefinição, o WuppieFuzz inclui as 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, pode desativar todas as dependências incluídas e ligar a bibliotecas instaladas no sistema.

[!NOTE] A crate z3 requer Z3 4.15+, que é mais recente do que a versão fornecida pela maioria dos gestores de pacotes das distribuições Linux. Instale o Z3 via Homebrew (brew install z3) para obter uma versão compatível.

Dependências do sistema

Instale as seguintes bibliotecas no seu sistema:

Debian/Ubuntu:

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 num caminho não padrão. Adicione o seu diretório de bibliotecas ao seu ambiente para que o compilador e o linker em tempo de execução possam encontrar o Z3:

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 as tornar permanentes.

Fedora (42+):

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

macOS (Homebrew):

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, ligando a todas as bibliotecas do sistema:

cargo dev-build          # compilar sem dependências incluídas
cargo dev-run -- <args>  # executar sem dependências incluídas
cargo dev-test           # testar sem dependências incluídas

Gerar 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

Ler mais