WuppieFuzz v1.6.0

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

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

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

ظهرت WuppieFuzz في:

• مجلة ONE Conference الإلكترونية 2024
• اختبر واجهات برمجة التطبيقات بسهولة باستخدام أداة TNO الجديدة لتشويب REST API
• قائمة OpenAPI.tools: WuppieFuzz
• الكشف التلقائي عن ثغرات REST API باستخدام WuppieFuzz (Nordic APIs على يوتيوب)
• الرادار التقني من Thoughtworks: 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)، انظر الإصدارات أو استخدم brew install wuppiefuzz

دليل استخدام مختصر

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

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

• 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

التشغيل

قبل تشغيل 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، وتعطي مسار مجلد الفئات كما يلي:

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

1. تغطية نقاط النهاية: يمكن توليدها دائمًا لأنها تتطلب فقط مواصفة OpenAPI.
2. تغطية الكود: مدعومة حاليًا فقط لـ JaCoCo، لكننا نهدف إلى دعم المزيد. الجزء الصعب هو أنها تتطلب تخطيطًا من التغطية إلى الملفات المصدرية، وتوليد تقارير متين يستخدم هذا التخطيط.

علاوة على ذلك، يتم ملء قاعدة بيانات بجميع معلومات الطلبات المتعلقة بحملة التشويب (fuzzing) الخاصة بك. يمكن عرض قاعدة البيانات هذه واستكشافها عبر لوحة معلومات 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 (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، وتُربط مع جميع مكتبات النظام:

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.