waf-fu

متصفح ومُعيد تشغيل سجلات AWS WAF v2 مع واجهة TUI تفاعلية. يسحب السجلات من CloudWatch وS3 وواجهة WAF sampling API (مع تخزين مؤقت SQLite)، ويعرضها في واجهة طرفية مقسّمة إلى أجزاء مع كشف المصادقة وتصفية قائمة على YAML، ويعيد تشغيل الطلبات عبر Firefox أو Chrome أو curl مع الحفاظ الكامل على الترويسات والكوكيز والجسم. يدعم التصدير الدفعي إلى curl وJSON وHAR.

التثبيت

من PyPI

uv pip install waf-fu

pipx install waf-fu

من git

uv pip install git+https://gitrdun.trustedsec.net/cloud/aws/waf-fu.git

pipx install git+https://gitrdun.trustedsec.net/cloud/aws/waf-fu.git

من نسخة محلية

git clone https://gitrdun.trustedsec.net/cloud/aws/waf-fu.git
cd waf-fu

uv pip install .

pipx install .

ملف uv.toml المضمّن يضبط uv pip ليتم التثبيت في Python النظام بدلاً من إنشاء بيئة افتراضية. أما pipx وuv tool install فيستخدمان دائماً بيئاتهما المعزولة الخاصة.

المتطلبات

Python >= 3.12

بيانات اعتماد AWS مُهيّأة عبر profile أو متغيرات البيئة أو دور المثيل (instance role). راجع أذونات IAM لمتطلبات كل مصدر.

حزم Python

الحزمة	الحد الأدنى للإصدار	مطلوبة لـ
boto3	أي إصدار	جلب سجلات AWS
selenium	4.26	إعادة التشغيل عبر Chrome وFirefox
trio	أي إصدار	مكونات إعادة التشغيل الداخلية لـ Chrome CDP

يُعلَن عن boto3 وselenium في pyproject.toml ويُثبَّتان تلقائياً. أما trio فهو تبعية انتقالية لواجهة Chrome الخلفية.

واجهات إعادة تشغيل المتصفح الخلفية

إعادة التشغيل عبر المتصفح اختيارية. إعادة التشغيل عبر Curl تعمل دون أي تبعيات إضافية.

Firefox (موصى به لدقة الترويسات):

المكوّن	الحد الأدنى للإصدار	التثبيت
Firefox	120	sudo dnf install firefox / sudo apt install firefox
geckodriver	0.35.0	sudo dnf install geckodriver / sudo apt install firefox-geckodriver أو github.com/mozilla/geckodriver/releases (>= 0.35.0)
selenium	4.26	uv pip install 'selenium>=4.26'

تستخدم إعادة التشغيل عبر Firefox اعتراض الشبكة WebDriver BiDi لحقن طريقة الطلب الأصلي وترويساته وكوكيزه وجسمه. يتطلب دعم شبكة BiDi إصدار geckodriver >= 0.35 وselenium >= 4.26. الإصدارات الأقدم تتراجع إلى نهج قائم على XHR لا يمكنه حقن ترويسات مخصصة.

Chrome / Chromium:

المكوّن	الحد الأدنى للإصدار	التثبيت
Chrome	118	sudo dnf install google-chrome-stable / sudo apt install google-chrome-stable أو Chromium
chromedriver	118	sudo dnf install chromedriver / sudo apt install chromium-driver أو googlechromelabs.github.io/chrome-for-testing
selenium	4.26	uv pip install 'selenium>=4.26'

تستخدم إعادة التشغيل عبر Chrome بروتوكول CDP (Chrome DevTools Protocol) ونطاق Fetch لاعتراض الطلبات وتعديلها. يتم حقن الطريقة والترويسات والجسم والكوكيز جميعها عبر CDP.

يمكن تجاوز مسارات المشغّلات (drivers) باستخدام --chromedriver PATH و --geckodriver PATH إذا لم يجد الاكتشاف التلقائي الملف التنفيذي الصحيح.

البدء السريع

# Interactive TUI -- browse and replay
waf-fu --log-group "aws-waf-logs-my-acl"

# No log group -- interactively select from discovered groups
waf-fu --profile myprofile --region us-east-1

# S3 WAF logs instead of CloudWatch
waf-fu --s3-bucket aws-waf-logs-my-bucket

# Discover and fetch every log source across all regions
waf-fu --inventory

# Pre-filter before the TUI opens
waf-fu --start 4h --action BLOCK

# Offline mode -- cached records only, no AWS calls
waf-fu --db-only

# Replay through a proxy (Burp, mitmproxy, etc.)
waf-fu --log-group "aws-waf-logs-my-acl" --proxy 127.0.0.1:8080

# Non-interactive batch export
waf-fu --log-group "aws-waf-logs-my-acl" --mode batch-curl -o replay.sh

# Export cached records to JSON
waf-fu --export logs.json

# Debug mode -- log replay details to file (client data redacted)
waf-fu --log-group "aws-waf-logs-my-acl" --debug

مصادر السجلات

يسحب waf-fu سجلات WAF من ثلاثة مصادر ويدمجها لكل طلب:

المصدر	خيار CLI	البيانات
CloudWatch	--log-group (افتراضي)	JSON كامل لسجل WAF (الترويسات، URI، الاستعلام، الإجراء)
S3	--s3-bucket	نفس CloudWatch، من تسليم S3
WAF API	--log-location waf	طلبات مُعيّنة بحقول غير محجوبة

استخدم --log-location cwl|s3|waf لتقييد العمل بمصدر واحد، أو --inventory لاكتشاف وجلب جميع المصادر عبر كل المناطق تلقائياً.

تُدمج السجلات من مصادر مختلفة عبر مفتاح الربط بحيث ترى عرضاً موحّداً واحداً لكل طلب، مع أغنى البيانات من كل مصدر.

أذونات IAM

يحتاج كل مصدر إلى أذونات IAM الخاصة به، مقيّدة بخيارات CLI التي تُفعّله.

CloudWatch Logs

مطلوبة لـ: التشغيل الافتراضي، --log-location cwl

• logs:FilterLogEvents -- جلب سجلات السجلات من CloudWatch
• logs:DescribeLogGroups -- اكتشاف مجموعات السجلات المطابقة لـ aws-waf-logs-*

S3

مطلوبة لـ: --s3-bucket، --log-location s3، --inventory

• s3:ListAllMyBuckets -- اكتشاف حاويات سجلات WAF عبر بادئة الاسم
• s3:ListBucket -- سرد كائنات السجلات في حاوية سجلات WAF
• s3:GetObject -- تنزيل ملفات السجلات المضغوطة بصيغة gzip

WAFv2

مطلوبة لـ: --log-location waf، --inventory، الإثراء التلقائي

• wafv2:ListWebACLs -- اكتشاف قوائم ACL للويب
• wafv2:GetWebACL -- تعداد القواعد لاستعلامات الطلبات المُعيّنة
• wafv2:GetLoggingConfiguration -- اكتشاف وجهات السجلات (CWL، S3) التي تستخدمها قائمة ACL
• wafv2:GetSampledRequests -- استرداد عينات الطلبات غير المحجوبة (يتجاوز RedactedFields)

الحد الأدنى القابل للتطبيق: أذونات CloudWatch Logs فقط مطلوبة. أذونات S3 و WAFv2 اختيارية وتُفعّل مصادر بيانات إضافية. تتراجع الأداة بأمان عند غياب الأذونات.