This directory documents the Python service in backend/src. It is written for developers and operators of the inline MITM test system. The source code remains the implementation authority; this documentation records the externally useful contracts, lifecycle, Linux integration, and data semantics that are easy to lose when reading individual modules.

Reading order

Architecture explains the process, responsibilities, and lifecycle.
Sniffing modes gives the complete technical behavior and implications of AF_PACKET and TC/eBPF capture.
Capture pipeline follows a packet from observation to persistence and realtime delivery.
HTTP and WebSocket API lists every router mounted by the application.
Data and analysis describes the packet record, database operations, and derived analysis views.
Host integration covers network, eBPF, nftables, tshark, and systemd side effects.
Configuration and deployment records dependencies and all BACKEND_* settings.
Source reference documents every backend source module, including modules not mounted by the current application.

Scope and conventions

All HTTP paths below include the FastAPI root_path, /api. The interactive schema is available at /api/docs, the alternative reference UI at /api/redoc, and the machine-readable contract at /api/openapi.json.

"Live" means a router is included by src.main. nft_api.py and nftables_api.py contain independent routers but are not included by the current entrypoint; they are documented as available-but-unmounted implementation paths.

Packet capture, firewall changes, bridge changes, and script deployment alter the host system. They must be used only in a controlled environment with explicit operator authorization.