TCP State Monitor

Небольшой локальный dashboard для наблюдения за TCP-трафиком. Он показывает темп пакетов, распределение TCP-флагов, активные адреса и последние переходы — без сохранения содержимого пакетов на диск.

Проект вырос из эксперимента со Scapy. Я переделал его так, чтобы монитор можно было безопасно запустить без доступа к сети, быстро понять по интерфейсу и использовать как основу для локальной диагностики.

Что умеет

• считает SYN, SYN-ACK, ACK и FIN в реальном времени;
• показывает packets/sec, uptime, top source/destination IP и последние 20 потоков;
• фильтрует статистику по source/destination IP или оставляет только handshake;
• ставит сбор на паузу, сбрасывает счётчики и экспортирует снимок в JSON;
• отдаёт машинные endpoints /api/stats, /api/export и /healthz;
• работает с реальным захватом Scapy или с синтетическим demo-трафиком;
• хранит только ограниченные агрегаты в RAM — payload не читается и не сохраняется.

Важно: это монитор, а не firewall. Фильтры исключают пакеты из статистики, но не блокируют и не изменяют сетевой трафик.

Быстрый запуск

Нужен Python 3.10+.

git clone https://github.com/ivanpukhov/ip.git
cd ip
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py --demo

Dashboard откроется на http://127.0.0.1:5000. Demo использует только адреса из TEST-NET диапазонов RFC 5737 и не обращается к ним по сети.

Для настоящего захвата:

python app.py --interface en0 --bpf "tcp port 443"

Имя интерфейса можно узнать через ifconfig или ip link. Захват пакетов требует прав, которые зависят от операционной системы и capture backend. Не запускайте web-интерфейс на публичном адресе без дополнительной аутентификации; по умолчанию он слушает только localhost.

Настройка

Скопируйте пример и измените нужные значения:

cp .env.example .env

Переменная	По умолчанию	Назначение
MONITOR_HOST	127.0.0.1	Адрес Flask-сервера
MONITOR_PORT	5000	Порт dashboard
MONITOR_INTERFACE	системный	Сетевой интерфейс Scapy
MONITOR_BPF	tcp	BPF-фильтр до обработки пакетов
MONITOR_CAPTURE	true	Включить реальный захват
MONITOR_DEMO	false	Генерировать безопасный demo-трафик
MONITOR_DEBUG	false	Flask debug только для разработки

CLI-параметры имеют приоритет над .env. Полный список доступен по python app.py --help.

Как устроено

Scapy capture / demo generator
             │
             ▼
       PacketMonitor
  thread-safe bounded counters
             │
       ┌─────┴─────┐
       ▼           ▼
  Flask JSON API   HTML dashboard

PacketMonitor отделён от Flask и Scapy: классификацию пакетов и состояние можно тестировать без capture socket. Очереди ограничены по размеру, а snapshot API возвращает уже готовые агрегаты.

Разработка

pip install -r requirements-dev.txt
ruff check .
python -m unittest discover -s tests -v

CI выполняет те же проверки на каждом push и pull request.

Ограничения

• TCP-состояния определяются по флагам отдельных пакетов, это не полноценный stateful connection tracker операционной системы;
• NAT, offloading и место захвата влияют на наблюдаемую картину;
• данные живут только в памяти и пропадают после перезапуска;
• проект предназначен для локальной диагностики и учебных лабораторий.

Лицензия: MIT.