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

طوّرت TNO أداة WuppieFuzz، وهي أداة fuzzing لواجهات REST API موجّهة بالتغطية (coverage-guided) مبنية فوق LibAFL، وتستهدف جمهورًا واسعًا من المستخدمين النهائيين، مع تركيز قوي على سهولة الاستخدام، وقابلية تفسير العيوب المكتشفة، والتصميم المعياري (modularity). تدعم WuppieFuzz جميع أنماط الاختبار الثلاثة (الصندوق الأسود، والصندوق الرمادي، والصندوق الأبيض).

> [!NOTE]  
> للحصول على إرشاد سريع يمكن اتباعه خطوة بخطوة، يُرجى اتباع [البرنامج التعليمي](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 الخاصة بك. عند إجراء fuzzing لخدمة تعمل محليًا (وليس في 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 أثناء العمل." 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، وتعطي دليل الفئات (classes) كما يلي:

```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. **تغطية نقاط النهاية (endpoint coverage)**: يمكن توليدها دائمًا لأنها تتطلب فقط مواصفة OpenAPI.
2. **تغطية الكود (code coverage)**: مدعومة حاليًا لـ JaCoCo فقط، لكننا نهدف إلى دعم المزيد. الجزء الصعب هو أنها تتطلب ربطًا من التغطية إلى ملفات المصدر، وتوليد تقارير قوي يستخدم ذلك.

علاوة على ذلك، تُملأ قاعدة بيانات بجميع معلومات الطلبات المتعلقة بحملة الـ fuzzing الخاصة بك. يمكن تصوّر قاعدة البيانات هذه واستكشافها من خلال لوحة تحكم Grafana.

## بنية هذا المستودع

- **assets**: الشعارات والصور وغيرها.
- **coverage_agents**: الكود والتعليمات لتتبع التغطية لإرفاقها بأهداف متنوعة
- **example_configs**: ملفات إعدادات نموذجية لإعداد WuppieFuzz
- **src**: الكود المصدري لـ WuppieFuzz
- **tutorial**: برنامج تعليمي متعمّق ومنخفض المستوى حول كيفية إجراء fuzzing لهدف محدد وكيفية تفسير نتائج الـ fuzzing
- **dashboard**: أدوات لفرز نتائج الـ fuzzing والأداء

لمزيد من المعلومات حول كل من هذه، انظر ملفات 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`