tno-s3/wuppiefuzzEin coverage-gesteuerter REST-API-Fuzzer, entwickelt auf Basis von LibAFL
# 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 von WuppieFuzz." src="https://raw.githubusercontent.com/tno-s3/wuppiefuzz/HEAD/assets/WuppieFuzz.svg" width="40%" min-width="250px" align="right"> </picture> TNO hat WuppieFuzz entwickelt, einen coverage-gesteuerten REST-API-Fuzzer, der auf LibAFL aufbaut und sich an eine breite Zielgruppe von Endanwendern richtet, mit starkem Fokus auf Benutzerfreundlichkeit, Erklärbarkeit der entdeckten Fehler und Modularität. WuppieFuzz unterstützt alle drei Test-Szenarien (Black Box, Grey Box und White Box). > [!NOTE] > Für eine schnelle, mitverfolgbare Anleitung folgen Sie bitte dem [Tutorial](https://github.com/tno-s3/wuppiefuzz/blob/main/tutorial)! ## Medienberichterstattung WuppieFuzz wurde vorgestellt in: - [The ONE Conference e-magazine 2024](https://emagazine.one-conference.nl/2024/finally-validate-your-publicly-exposed-interfaces-with-ease/) - [Testen Sie Ihre APIs ganz einfach mit TNOs neuem REST-API-Fuzzer](https://www.tno.nl/en/newsroom/insights/2024/10/application-security-testing/) - [OpenAPI.tools-Eintrag: WuppieFuzz](https://openapi.tools/tools/wuppiefuzz) - [Automatisierte REST-API-Schwachstellenerkennung mit WuppieFuzz (Nordic APIs auf YouTube)](https://www.youtube.com/watch?v=JcV9RUBvb2w) - [Thoughtworks Technology Radar: WuppieFuzz](https://www.thoughtworks.com/radar/tools/wuppiefuzz) ### Wissenschaftliche Veröffentlichung Wenn Sie WuppieFuzz in wissenschaftlichen Arbeiten zitieren möchten, verwenden Sie bitte die bevorzugte Publikation, die in [CITATION.cff](https://github.com/tno-s3/wuppiefuzz/blob/main/CITATION.cff) aufgeführt ist: 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 ## Lizenz WuppieFuzz ist unter Apache-2.0 lizenziert; siehe [LICENSE](https://github.com/tno-s3/wuppiefuzz/blob/main/LICENSE). Lizenzhinweise Dritter sind in [THIRD_PARTY_NOTICES](https://github.com/tno-s3/wuppiefuzz/blob/main/THIRD_PARTY_NOTICES) aufgeführt. ## Schnellinstallation Für eine schnelle Installation von WuppieFuzz auf gängigen Betriebssystemen (MacOS, Windows, Linux) siehe [releases](https://github.com/TNO-S3/WuppieFuzz/releases/) oder verwenden Sie [`brew install wuppiefuzz`](https://formulae.brew.sh/formula/wuppiefuzz) ### Docker Sie können das Docker-Image mit `docker build . -t wuppiefuzz:local` erstellen. Um es zu verwenden, müssen Sie einen Ordner einbinden, der Ihre OpenAPI-Spezifikation enthält. Beim Fuzzing eines Dienstes, den Sie lokal ausführen (nicht in Docker), müssen Sie Host-Netzwerk angeben: ``` 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 ``` ### Kurzanleitung [](https://www.youtube.com/watch?v=-oR4d9aXrqo) ## Voraussetzungen für die Entwicklung Um das Projekt zu bauen, müssen Sie die folgenden Abhängigkeiten und Werkzeuge installieren: ``` sudo apt install -y build-essential pkg-config cmake # General build tools curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Rust ``` ## Ausführen <picture> <img alt="WuppieFuzz in Aktion." src="https://raw.githubusercontent.com/tno-s3/wuppiefuzz/HEAD/assets/WuppieFuzz-action.jfif" width="40%" min-width="250px" align="right"> </picture> Bevor Sie WuppieFuzz ausführen, müssen Sie Ihre (instrumentierte) Zielanwendung starten. Zusätzlich müssen Sie WuppieFuzz eine **OpenAPI-Spezifikation** bereitstellen, damit es weiß, wie es seine Anfragen generieren und mutieren soll. Für Hilfe zu den Kommandozeilenargumenten verwenden Sie Folgendes: ```sh $ cargo run -- --help # shows help for required parameters and flags Usage: wuppiefuzz [OPTIONS] [OPENAPI_SPEC.YAML] ... ``` Um beispielsweise WuppieFuzz gegen ein Java-Ziel mit angehängtem JaCoCo-Agent auszuführen, geben Sie dessen OpenAPI-Datei an (die die URL enthält, unter der das Ziel läuft, in der API-Spezifikation). Zusätzlich geben Sie an, dass das Coverage-Format JaCoCo ist, und geben das Klassenverzeichnis wie folgt an: ```sh cargo run -- fuzz openapi.yaml --coverage-format jacoco --jacoco-class-dir ../Targets/app/target/classes/ ``` ## Konfigurationsdatei Wenn Sie eine Konfigurationsdatei anstelle von bzw. in Kombination mit Kommandozeilenargumenten verwenden möchten, können Sie das Flag `--config <CONFIG_FILE>` verwenden. Falls Sie Kommandozeilenargumente in Kombination mit einer Konfigurationsdatei verwenden, haben die Kommandozeilenargumente Vorrang. Die Konfigurationsdatei sollte eine YAML-Datei sein und für jedes Kommandozeilenargument, das Sie angeben möchten, eine Zeile enthalten, zum Beispiel: ```yaml coverage_format: jacoco output_format: human-readable source_dir: "/swagger-petstore/src/main/java" jacoco_class_dir: "/swagger-petstore/target" timeout: 20 ``` Ein Beispiel-Ausführungsbefehl könnte in diesem Fall sein: ```sh $ cargo run -- fuzz --config=config.yaml --report --coverage-host=localhost:6300 --timeout=10 ./openapi.yaml ``` Diese Zeile würde die Argumente von der Kommandozeile und aus der Konfigurationsdatei kombinieren. Da das Flag `--timeout` in beiden angegeben ist, hat der in der Kommandozeile angegebene Timeout (10 Sekunden) Vorrang. Im Verzeichnis `example_configs/` finden Sie zwei Beispiel-Konfigurationsdateien zur Verwendung für die Generierung von Coverage-Berichten mit JaCoCo für Java-Code und für die Generierung von Coverage-Berichten mit LCOV für Python-Code. ## Berichte Wenn Sie WuppieFuzz mit dem Flag `--report` ausführen, wird ein Unterverzeichnis innerhalb von `reports/` mit einem Zeitstempel als Namen erstellt. Alle unterstützten Coverage-Berichte werden in dieses Unterverzeichnis geschrieben. Es gibt zwei Arten von Coverage-Berichten: 1. **Endpoint-Coverage**: Diese kann immer generiert werden, da sie nur die OpenAPI-Spezifikation erfordert. 2. **Code-Coverage**: Derzeit nur für JaCoCo unterstützt, aber wir streben an, mehr zu unterstützen. Der knifflige Teil ist, dass dies ein Mapping von Coverage zu Quelldateien und eine robuste Berichtsgenerierung erfordert, die dies nutzt. Darüber hinaus wird eine Datenbank mit allen Anfrageinformationen zu Ihrer Fuzzing-Kampagne gefüllt. Diese Datenbank kann über das Grafana-Dashboard visualisiert und erkundet werden. ## Struktur dieses Repositorys - **assets**: Logos, Bilder usw. - **coverage_agents**: Code und Anweisungen zur Coverage-Verfolgung, die auf verschiedene Ziele angewendet werden können - **example_configs**: Beispiel-Konfigurationsdateien zur Konfiguration von WuppieFuzz - **src**: Quellcode von WuppieFuzz - **tutorial**: ein ausführliches und detailliertes Tutorial darüber, wie man ein bestimmtes Ziel fuzzt und wie man Fuzzing-Ergebnisse interpretiert - **dashboard**: Werkzeuge zur Triage der Fuzzing-Ergebnisse und -Performance Weitere Informationen zu jedem dieser Punkte finden Sie in den READMEs in diesen Verzeichnissen. ## Entwicklungs-Build Standardmäßig vendort WuppieFuzz seine C-Abhängigkeiten (OpenSSL, SQLite, Z3), sodass ein regulärer `cargo build` out of the box funktioniert. Für eine schnellere Kompilierung während der Entwicklung können Sie alle vendorten Abhängigkeiten deaktivieren und stattdessen gegen systeminstallierte Bibliotheken linken. > [!NOTE] > Die Crate `z3` erfordert Z3 4.15+, was neuer ist als die Version, die von > den meisten Linux-Distributions-Paketmanagern bereitgestellt wird. Installieren Sie Z3 über > [Homebrew](https://brew.sh/) (`brew install z3`), um eine kompatible Version zu erhalten. ### Systemabhängigkeiten Installieren Sie die folgenden Bibliotheken auf Ihrem System: **Debian/Ubuntu:** ```sh sudo apt install libssl-dev libsqlite3-dev brew install z3 # apt's libz3-dev is too old; use Homebrew instead ``` Unter Linux installiert Homebrew in einen nicht-standardmäßigen Pfad. Fügen Sie sein Bibliotheksverzeichnis zu Ihrer Umgebung hinzu, damit der Compiler und der Runtime-Linker Z3 finden können: ```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] > Fügen Sie die obigen Zeilen zu Ihrer `~/.bashrc` oder `~/.zshrc` hinzu, um sie dauerhaft zu machen. **Fedora (42+):** ```sh sudo dnf install openssl-devel sqlite-devel z3-devel ``` **macOS (Homebrew):** ```sh brew install openssl sqlite z3 ``` ### Cargo-Aliase Das Repository enthält Cargo-Aliase in `.cargo/config.toml`, die mit `--no-default-features` bauen und gegen alle Systembibliotheken linken: ```sh cargo dev-build # build without vendored dependencies cargo dev-run -- <args> # run without vendored dependencies cargo dev-test # test without vendored dependencies ``` ## Dokumentation generieren `cargo doc --no-deps`, um Dokumentation aus Kommentaren im Quellcode zu generieren. Die Hauptseite der Dokumentation wird `target/doc/wuppiefuzz/index.html` sein
