WuppieFuzz v1.8.0

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

[!NOTE]
للحصول على إرشاد سريع يمكن اتباعه خطوة بخطوة، يُرجى اتباع البرنامج التعليمي!

التغطية الإعلامية

ظهرت WuppieFuzz في:

المنشور العلمي

إذا كنت ترغب في الاستشهاد بـ WuppieFuzz في عمل أكاديمي، فيُرجى استخدام المنشور المفضّل المدرج في 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.
إشعارات تراخيص الأطراف الثالثة مدرجة في THIRD_PARTY_NOTICES.

التثبيت السريع

للتثبيت السريع لـ WuppieFuzz على أنظمة التشغيل الشائعة (MacOS، وWindows، وLinux) انظر releases أو استخدم brew install wuppiefuzz

Docker

يمكنك بناء صورة docker باستخدام docker build . -t wuppiefuzz:local. لاستخدامها، يجب عليك تركيب مجلد يحتوي على مواصفة openapi الخاصة بك. عند إجراء fuzzing لخدمة تعمل محليًا (وليس في Docker)، تحتاج إلى تحديد host networking:

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

دليل مختصر

المتطلبات الأساسية للتطوير

لبناء المشروع تحتاج إلى تثبيت التبعيات والأدوات التالية:

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

التشغيل

قبل تشغيل WuppieFuzz، يجب عليك تشغيل تطبيقك الهدف (المُجهّز بأدوات القياس).

بالإضافة إلى ذلك، يجب عليك تزويد WuppieFuzz بـ مواصفة OpenAPI حتى يعرف كيفية توليد طلباته وتعديلها. للحصول على مساعدة بشأن وسائط سطر الأوامر، استخدم ما يلي:

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

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

على سبيل المثال، لتشغيل WuppieFuzz ضد هدف Java مع وكيل JaCoCo مُرفق، تُحدّد ملف OpenAPI الخاص به (الذي يحتوي على عنوان URL الذي يعمل عليه الهدف في مواصفة API). بالإضافة إلى ذلك، تُحدّد أن صيغة التغطية هي JaCoCo، وتعطي دليل الفئات (classes) كما يلي:

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

ملف الإعدادات

إذا كنت ترغب في استخدام ملف إعدادات بدلاً من وسائط سطر الأوامر أو بالاشتراك معها، يمكنك استخدام العلامة --config <CONFIG_FILE>. في حال استخدامك لوسائط سطر الأوامر بالاشتراك مع ملف إعدادات، فإن وسائط سطر الأوامر لها الأولوية.

يجب أن يكون ملف الإعدادات ملف yaml ويحتوي على سطر لكل وسيط من وسائط سطر الأوامر الذي تريد تحديده، على سبيل المثال:

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

قد يكون أمر تشغيل نموذجي في هذه الحالة كالتالي:

$ 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/ باسم يمثل طابعًا زمنيًا. تُكتب جميع تقارير التغطية المدعومة في هذا الدليل الفرعي. هناك نوعان من تقارير التغطية:

تغطية نقاط النهاية (endpoint coverage): يمكن توليدها دائمًا لأنها تتطلب فقط مواصفة OpenAPI.
تغطية الكود (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 (brew install z3) للحصول على إصدار متوافق.

تبعيات النظام

ثبّت المكتبات التالية على نظامك:

Debian/Ubuntu:

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

على Linux، يثبّت Homebrew في مسار غير قياسي. أضف دليل مكتباته إلى بيئتك حتى يتمكن المترجم والرابط وقت التشغيل من العثور على 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] أضف الأسطر أعلاه إلى ملف ~/.bashrc أو ~/.zshrc لجعلها دائمة.

Fedora (42+):

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

macOS (Homebrew):

brew install openssl sqlite z3

أسماء Cargo المستعارة

يتضمن المستودع أسماء cargo مستعارة في .cargo/config.toml تبني باستخدام --no-default-features، مع الربط بجميع مكتبات النظام:

WuppieFuzz

الأكثر شعبية