waf-fu

Browser di log e replayer per AWS WAF v2 con una TUI interattiva. Estrae i log da CloudWatch, S3 e dall'API di campionamento WAF (con caching su SQLite), li visualizza in una UI terminale a pannelli divisi con rilevamento dell'autenticazione e filtraggio basato su YAML, e riproduce le richieste tramite Firefox, Chrome o curl con piena fedeltà di header/cookie/body. Supporta l'esportazione batch in curl, JSON e HAR.

Installazione

Da PyPI

uv pip install waf-fu

pipx install waf-fu

Da 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

Da un clone locale

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

uv pip install .

pipx install .

Il file uv.toml incluso configura uv pip per installare nel Python di sistema anziché creare un virtualenv. pipx e uv tool install utilizzano sempre i propri ambienti isolati.

Requisiti

Python >= 3.12

Credenziali AWS configurate tramite profilo, variabili d'ambiente o ruolo dell'istanza. Vedi Permessi IAM per i requisiti di ciascuna sorgente.

Pacchetti Python

Pacchetto	Versione minima	Richiesto per
boto3	qualsiasi	Recupero log AWS
selenium	4.26	Replay Chrome e Firefox
trio	qualsiasi	Interni del replay Chrome CDP

boto3 e selenium sono dichiarati in pyproject.toml e installati automaticamente. trio è una dipendenza transitiva del backend Chrome.

Backend di replay del browser

Il replay del browser è opzionale. Il replay con curl funziona senza dipendenze aggiuntive.

Firefox (consigliato per la fedeltà degli header):

Componente	Versione minima	Installazione
Firefox	120	sudo dnf install firefox / sudo apt install firefox
geckodriver	0.35.0	sudo dnf install geckodriver / sudo apt install firefox-geckodriver o github.com/mozilla/geckodriver/releases (>= 0.35.0)
selenium	4.26	uv pip install 'selenium>=4.26'

Il replay con Firefox utilizza l'intercettazione di rete WebDriver BiDi per iniettare metodo, header, cookie e body della richiesta originale. Il supporto di rete BiDi richiede geckodriver >= 0.35 e selenium >= 4.26. Le versioni precedenti ricadono su un approccio basato su XHR che non può iniettare header personalizzati.

Chrome / Chromium:

Componente	Versione minima	Installazione
Chrome	118	sudo dnf install google-chrome-stable / sudo apt install google-chrome-stable o Chromium
chromedriver	118	sudo dnf install chromedriver / sudo apt install chromium-driver o googlechromelabs.github.io/chrome-for-testing
selenium	4.26	uv pip install 'selenium>=4.26'

Il replay con Chrome utilizza il dominio Fetch di CDP (Chrome DevTools Protocol) per intercettare e modificare le richieste. Metodo, header, body e cookie vengono tutti iniettati tramite CDP.

I percorsi dei driver possono essere sovrascritti con --chromedriver PATH e --geckodriver PATH se il rilevamento automatico non trova il binario corretto.

Avvio rapido

# TUI interattiva -- esplora e riproduci
waf-fu --log-group "aws-waf-logs-my-acl"

# Nessun log group -- seleziona interattivamente tra i gruppi rilevati
waf-fu --profile myprofile --region us-east-1

# Log WAF su S3 invece di CloudWatch
waf-fu --s3-bucket aws-waf-logs-my-bucket

# Rileva ed estrae ogni sorgente di log in tutte le regioni
waf-fu --inventory

# Pre-filtra prima dell'apertura della TUI
waf-fu --start 4h --action BLOCK

# Modalità offline -- solo record in cache, nessuna chiamata AWS
waf-fu --db-only

# Replay attraverso un proxy (Burp, mitmproxy, ecc.)
waf-fu --log-group "aws-waf-logs-my-acl" --proxy 127.0.0.1:8080

# Esportazione batch non interattiva
waf-fu --log-group "aws-waf-logs-my-acl" --mode batch-curl -o replay.sh

# Esporta i record in cache in JSON
waf-fu --export logs.json

# Modalità debug -- registra i dettagli del replay su file (dati client oscurati)
waf-fu --log-group "aws-waf-logs-my-acl" --debug

Sorgenti di log

waf-fu estrae i log WAF da tre sorgenti e li unisce per richiesta:

Sorgente	Flag CLI	Dati
CloudWatch	--log-group (predefinito)	JSON completo del log WAF (header, URI, query, azione)
S3	--s3-bucket	Come CloudWatch, dalla consegna S3
WAF API	--log-location waf	Richieste campionate con campi non oscurati

Usa --log-location cwl|s3|waf per limitare a una singola sorgente, oppure --inventory per rilevare ed estrarre automaticamente tutte le sorgenti in tutte le regioni.

I record provenienti da sorgenti diverse vengono uniti tramite chiave di correlazione, così vedi una singola vista unificata per richiesta, con i dati più ricchi da ciascuna.

Permessi IAM

Ogni sorgente necessita dei propri permessi IAM, limitati ai flag CLI che la attivano.

CloudWatch Logs

Richiesto per: operazione predefinita, --log-location cwl

• logs:FilterLogEvents -- estrae i record di log da CloudWatch
• logs:DescribeLogGroups -- rileva i log group corrispondenti a aws-waf-logs-*

S3

Richiesto per: --s3-bucket, --log-location s3, --inventory

• s3:ListAllMyBuckets -- rileva i bucket di log WAF tramite prefisso del nome
• s3:ListBucket -- elenca gli oggetti di log in un bucket di log WAF
• s3:GetObject -- scarica i file di log compressi con gzip

WAFv2

Richiesto per: --log-location waf, --inventory, arricchimento automatico

• wafv2:ListWebACLs -- rileva le web ACL
• wafv2:GetWebACL -- enumera le regole per le query di richieste campionate
• wafv2:GetLoggingConfiguration -- rileva quali destinazioni di log (CWL, S3) usa una ACL
• wafv2:GetSampledRequests -- recupera campioni di richieste non oscurati (aggira RedactedFields)

Minimo indispensabile: sono richiesti solo i permessi di CloudWatch Logs. I permessi S3 e WAFv2 sono opzionali e abilitano sorgenti di dati aggiuntive. Lo strumento ricade in modo controllato quando i permessi mancano.