waf-fu

Navegador e reprodutor de logs do AWS WAF v2 com uma TUI interativa. Extrai logs do CloudWatch, S3 e da API de amostragem do WAF (com cache em SQLite), exibe-os em uma interface de terminal de painéis divididos com detecção de autenticação e filtragem baseada em YAML, e reproduz requisições através do Firefox, Chrome ou curl com fidelidade total de cabeçalhos/cookies/corpo. Suporta exportação em lote para curl, JSON e HAR.

Instalação

Do PyPI

uv pip install waf-fu

pipx install waf-fu

Do 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

De um clone local

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

uv pip install .

pipx install .

O uv.toml incluído configura o uv pip para instalar no Python do sistema em vez de criar um virtualenv. O pipx e o uv tool install sempre usam seus próprios ambientes isolados.

Requisitos

Python >= 3.12

Credenciais AWS configuradas via profile, variáveis de ambiente ou instance role. Consulte Permissões IAM para os requisitos por fonte.

Pacotes Python

Pacote	Versão mínima	Necessário para
boto3	qualquer	Busca de logs da AWS
selenium	4.26	Reprodução no Chrome e Firefox
trio	qualquer	Internos de reprodução via Chrome CDP

boto3 e selenium estão declarados em pyproject.toml e são instalados automaticamente. trio é uma dependência transitiva do backend do Chrome.

Backends de reprodução em navegador

A reprodução em navegador é opcional. A reprodução via curl funciona sem dependências extras.

Firefox (recomendado para fidelidade de cabeçalhos):

Componente	Versão mínima	Instalação
Firefox	120	sudo dnf install firefox / sudo apt install firefox
geckodriver	0.35.0	sudo dnf install geckodriver / sudo apt install firefox-geckodriver ou github.com/mozilla/geckodriver/releases (>= 0.35.0)
selenium	4.26	uv pip install 'selenium>=4.26'

A reprodução no Firefox usa interceptação de rede WebDriver BiDi para injetar o método, cabeçalhos, cookies e corpo da requisição original. O suporte a rede BiDi requer geckodriver >= 0.35 e selenium >= 4.26. Versões mais antigas recorrem a uma abordagem baseada em XHR que não consegue injetar cabeçalhos personalizados.

Chrome / Chromium:

Componente	Versão mínima	Instalação
Chrome	118	sudo dnf install google-chrome-stable / sudo apt install google-chrome-stable ou Chromium
chromedriver	118	sudo dnf install chromedriver / sudo apt install chromium-driver ou googlechromelabs.github.io/chrome-for-testing
selenium	4.26	uv pip install 'selenium>=4.26'

A reprodução no Chrome usa o domínio Fetch do CDP (Chrome DevTools Protocol) para interceptar e modificar requisições. Método, cabeçalhos, corpo e cookies são todos injetados via CDP.

Os caminhos dos drivers podem ser sobrescritos com --chromedriver PATH e --geckodriver PATH caso a detecção automática não encontre o binário correto.

Início rápido

# TUI interativa -- navegar e reproduzir
waf-fu --log-group "aws-waf-logs-my-acl"

# Sem log group -- selecionar interativamente entre os grupos descobertos
waf-fu --profile myprofile --region us-east-1

# Logs do WAF no S3 em vez do CloudWatch
waf-fu --s3-bucket aws-waf-logs-my-bucket

# Descobrir e buscar todas as fontes de log em todas as regiões
waf-fu --inventory

# Pré-filtrar antes da TUI abrir
waf-fu --start 4h --action BLOCK

# Modo offline -- apenas registros em cache, sem chamadas à AWS
waf-fu --db-only

# Reproduzir através de um proxy (Burp, mitmproxy, etc.)
waf-fu --log-group "aws-waf-logs-my-acl" --proxy 127.0.0.1:8080

# Exportação em lote não interativa
waf-fu --log-group "aws-waf-logs-my-acl" --mode batch-curl -o replay.sh

# Exportar registros em cache para JSON
waf-fu --export logs.json

# Modo de depuração -- registrar detalhes de reprodução em arquivo (dados do cliente censurados)
waf-fu --log-group "aws-waf-logs-my-acl" --debug

Fontes de log

O waf-fu extrai logs do WAF de três fontes e os mescla por requisição:

Fonte	Flag da CLI	Dados
CloudWatch	--log-group (padrão)	JSON completo do log do WAF (cabeçalhos, URI, query, ação)
S3	--s3-bucket	Igual ao CloudWatch, a partir da entrega via S3
WAF API	--log-location waf	Requisições amostradas com campos não censurados

Use --log-location cwl|s3|waf para restringir a uma única fonte, ou --inventory para descobrir e buscar todas as fontes em todas as regiões automaticamente.

Registros de fontes diferentes são mesclados por chave de correlação para que você veja uma única visão unificada por requisição, com os dados mais ricos de cada uma.

Permissões IAM

Cada fonte precisa de suas próprias permissões IAM, limitadas às flags da CLI que a acionam.

CloudWatch Logs

Necessário para: operação padrão, --log-location cwl

• logs:FilterLogEvents -- buscar registros de log do CloudWatch
• logs:DescribeLogGroups -- descobrir log groups que correspondem a aws-waf-logs-*

S3

Necessário para: --s3-bucket, --log-location s3, --inventory

• s3:ListAllMyBuckets -- descobrir buckets de log do WAF por prefixo de nome
• s3:ListBucket -- listar objetos de log em um bucket de log do WAF
• s3:GetObject -- baixar arquivos de log compactados em gzip

WAFv2

Necessário para: --log-location waf, --inventory, enriquecimento automático

• wafv2:ListWebACLs -- descobrir web ACLs
• wafv2:GetWebACL -- enumerar regras para consultas de requisições amostradas
• wafv2:GetLoggingConfiguration -- descobrir quais destinos de log (CWL, S3) uma ACL usa
• wafv2:GetSampledRequests -- recuperar amostras de requisições não censuradas (contorna RedactedFields)

Mínimo viável: apenas as permissões do CloudWatch Logs são necessárias. As permissões de S3 e WAFv2 são opcionais e habilitam fontes de dados adicionais. A ferramenta recorre graciosamente quando faltam permissões.