waf-fu

Браузер и реплеер логов AWS WAF v2 с интерактивным TUI. Извлекает логи из CloudWatch, S3 и WAF sampling API (с кэшированием в SQLite), отображает их в терминальном интерфейсе с разделёнными панелями, с определением аутентификации и фильтрацией на основе YAML, и воспроизводит запросы через Firefox, Chrome или curl с полной точностью заголовков, cookie и тела. Поддерживает пакетный экспорт в 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 вместо создания virtualenv. pipx и uv tool install всегда используют собственные изолированные окружения.

Требования

Python >= 3.12

Учётные данные AWS, настроенные через профиль, переменные окружения или роль экземпляра. См. Разрешения 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 для внедрения метода, заголовков, cookie и тела исходного запроса. Поддержка сети 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 использует домен Fetch протокола CDP (Chrome DevTools Protocol) для перехвата и модификации запросов. Метод, заголовки, тело и cookie внедряются через CDP.

Пути к драйверам можно переопределить с помощью --chromedriver PATH и --geckodriver PATH, если автоопределение не находит нужный бинарный файл.

Быстрый старт

# Интерактивный TUI -- просмотр и воспроизведение
waf-fu --log-group "aws-waf-logs-my-acl"

# Без log group -- интерактивный выбор из обнаруженных групп
waf-fu --profile myprofile --region us-east-1

# Логи WAF из S3 вместо CloudWatch
waf-fu --s3-bucket aws-waf-logs-my-bucket

# Обнаружить и получить все источники логов во всех регионах
waf-fu --inventory

# Предварительная фильтрация до открытия TUI
waf-fu --start 4h --action BLOCK

# Офлайн-режим -- только кэшированные записи, без обращений к AWS
waf-fu --db-only

# Воспроизведение через прокси (Burp, mitmproxy и т. д.)
waf-fu --log-group "aws-waf-logs-my-acl" --proxy 127.0.0.1:8080

# Неинтерактивный пакетный экспорт
waf-fu --log-group "aws-waf-logs-my-acl" --mode batch-curl -o replay.sh

# Экспорт кэшированных записей в JSON
waf-fu --export logs.json

# Режим отладки -- запись деталей воспроизведения в файл (данные клиента скрыты)
waf-fu --log-group "aws-waf-logs-my-acl" --debug

Источники логов

waf-fu извлекает логи WAF из трёх источников и объединяет их по каждому запросу:

Источник	Флаг CLI	Данные
CloudWatch	--log-group (по умолчанию)	Полный JSON лога WAF (заголовки, URI, query, действие)
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 -- обнаружение log groups, соответствующих 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 -- обнаружение web ACL
• wafv2:GetWebACL -- перечисление правил для запросов сэмплированных запросов
• wafv2:GetLoggingConfiguration -- обнаружение того, какие назначения логов (CWL, S3) использует ACL
• wafv2:GetSampledRequests -- получение неотредактированных сэмплов запросов (обходит RedactedFields)

Минимально необходимое: требуются только разрешения CloudWatch Logs. Разрешения S3 и WAFv2 опциональны и включают дополнительные источники данных. Инструмент корректно деградирует при отсутствии разрешений.