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

TNO разработала WuppieFuzz — REST API-фаззер с покрытием на основе LibAFL, ориентированный на широкую аудиторию конечных пользователей, с сильным акцентом на простоту использования, объяснимость обнаруженных уязвимостей и модульность. WuppieFuzz поддерживает все три режима тестирования (чёрный ящик, серый ящик и белый ящик).

> [!NOTE]  
> Для быстрого пошагового руководства перейдите к [tutorial](https://github.com/tno-s3/wuppiefuzz/blob/main/tutorial)!

## Освещение в СМИ

WuppieFuzz был представлен в:

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


### Научная публикация

Если вы хотите сослаться на WuppieFuzz в академической работе, пожалуйста, используйте предпочтительную публикацию, указанную в [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

## Лицензия

WuppieFuzz распространяется под лицензией Apache-2.0; см. [LICENSE](https://github.com/tno-s3/wuppiefuzz/blob/main/LICENSE).  
Уведомления о лицензиях третьих сторон перечислены в [THIRD_PARTY_NOTICES](https://github.com/tno-s3/wuppiefuzz/blob/main/THIRD_PARTY_NOTICES).

## Быстрая установка

Для быстрой установки WuppieFuzz для популярных операционных систем (MacOS,
Windows, Linux) см. [releases](https://github.com/TNO-S3/WuppieFuzz/releases/) или используйте [`brew install wuppiefuzz`](https://formulae.brew.sh/formula/wuppiefuzz)

### Docker

Вы можете собрать docker-образ командой `docker build . -t wuppiefuzz:local`. Чтобы использовать его, необходимо смонтировать папку, содержащую вашу openapi-спецификацию. При фаззинге сервиса, запущенного локально (не в Docker), необходимо указать 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
```



### Краткое руководство

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

## Предварительные требования для разработки

Для сборки проекта необходимо установить следующие зависимости и инструменты:

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

## Запуск

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

Перед запуском WuppieFuzz необходимо запустить ваше (инструментированное) целевое
приложение.

Кроме того, необходимо предоставить WuppieFuzz **OpenAPI-спецификацию**, чтобы он
знал, как генерировать и мутировать свои запросы. Для справки по аргументам
командной строки используйте следующее:

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

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

Например, чтобы запустить WuppieFuzz против Java-цели с подключённым агентом
JaCoCo, вы указываете его OpenAPI-файл (содержащий URL, по которому запущена
цель, в спецификации API). Кроме того, вы указываете, что формат покрытия —
JaCoCo, и задаёте каталог классов следующим образом:

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

## Файл конфигурации

Если вы хотите использовать файл конфигурации вместо аргументов командной
строки или в сочетании с ними, вы можете использовать флаг `--config <CONFIG_FILE>`. Если вы используете аргументы командной строки в сочетании с файлом конфигурации, аргументы командной строки имеют приоритет.

Файл конфигурации должен быть yaml-файлом и содержать строку для каждого
аргумента командной строки, который вы хотите указать, например:

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

Пример команды запуска в этом случае может быть таким:

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

Эта строка объединила бы аргументы из командной строки и из файла
конфигурации. Поскольку флаг `--timeout` указан в обоих, таймаут, указанный в
командной строке (10 секунд), будет иметь приоритет.

В каталоге `example_configs/` вы найдёте два примера файлов конфигурации для
использования при генерации отчётов о покрытии с помощью JaCoCo для Java-кода и для генерации
отчётов о покрытии с помощью LCOV для Python-кода.

## Отчёты

Когда вы запускаете WuppieFuzz с флагом `--report`, внутри
`reports/` создаётся подкаталог с именем в виде временной метки. Все поддерживаемые отчёты о покрытии
записываются в этот подкаталог. Существует два типа отчётов о покрытии:

1. **покрытие эндпоинтов**: это можно сгенерировать всегда, поскольку требуется только
   OpenAPI-спецификация.
2. **покрытие кода**: в настоящее время поддерживается только для JaCoCo, но мы стремимся поддерживать
   больше. Сложность в том, что это требует сопоставления покрытия с исходными
   файлами и надёжной генерации отчётов, использующей это.

Вдобавок к этому база данных заполняется всей информацией о запросах, связанной с вашей
кампанией фаззинга. Эту базу данных можно визуализировать и исследовать через
панель Grafana.

## Структура этого репозитория

- **assets**: логотипы, изображения и т. д.
- **coverage_agents**: код и инструкции для отслеживания покрытия, которые можно применить к
  различным целям
- **example_configs**: примеры файлов конфигурации для настройки WuppieFuzz
- **src**: исходный код WuppieFuzz
- **tutorial**: подробное и низкоуровневое руководство о том, как фаззить конкретную
  цель и как интерпретировать результаты фаззинга
- **dashboard**: инструменты для триажа результатов фаззинга и производительности

Для получения дополнительной информации о каждом из них см. README в этих каталогах.

## Сборка для разработки

По умолчанию WuppieFuzz включает свои C-зависимости (OpenSSL, SQLite, Z3), так что
обычная команда `cargo build` работает из коробки. Для более быстрой компиляции во время
разработки вы можете отключить все встроенные зависимости и вместо этого слинковаться с
установленными в системе библиотеками.

> [!NOTE]
> Крейт `z3` требует Z3 4.15+, что новее версии, поставляемой
> большинством менеджеров пакетов дистрибутивов Linux. Установите Z3 через
> [Homebrew](https://brew.sh/) (`brew install z3`), чтобы получить совместимую версию.

### Системные зависимости

Установите следующие библиотеки в вашей системе:

**Debian/Ubuntu:**

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

В Linux Homebrew устанавливается в нестандартный путь. Добавьте его каталог библиотек
в ваше окружение, чтобы компилятор и компоновщик времени выполнения могли найти 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]
> Добавьте строки выше в ваш `~/.bashrc` или `~/.zshrc`, чтобы сделать их постоянными.

**Fedora (42+):**

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

**macOS (Homebrew):**

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

### Псевдонимы Cargo

Репозиторий включает псевдонимы cargo в `.cargo/config.toml`, которые собирают с
`--no-default-features`, линкуясь со всеми системными библиотеками:

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

## Генерация документации

`cargo doc --no-deps` для генерации документации из комментариев в исходном
коде. Главная страница документации будет
`target/doc/wuppiefuzz/index.html`
WuppieFuzz

Популярное
