mitm-webserver/documentation/backend/configuration.md

Configuration and deployment

Runtime dependencies

The service runs with Python 3.11 in the supplied Dockerfile and starts Uvicorn as src.main:app on port 8000 with reload enabled. Python dependencies include FastAPI/Pydantic, asyncpg, pyroute2, Scapy, pip-nftables, multipart handling, and WebSocket support. The image installs build tools, libpcap development headers, pkg-config, and tshark.

The host also needs facilities that a minimal application container normally does not have: a reachable PostgreSQL database, Linux network namespace permissions, raw-socket capability, access to ip/pyroute2 netlink operations, nftables and appropriate capability, ethtool where profile/reset functions are used, systemd/systemctl for scripts, and BCC/eBPF/tc tooling for tc_ebpf capture.

Environment variables

All settings are loaded once by src.config.load_settings. Empty values use their default. Boolean true values are 1, true, yes, or on (case-insensitive).

Variable	Default	Purpose
BACKEND_DB_DSN	postgresql://mitm_user:mitm_password@localhost:5432/mitm_db	PostgreSQL connection string.
BACKEND_LOG_LEVEL	DEBUG	Python logging level.
BACKEND_DB_POOL_MIN_SIZE / MAX_SIZE	1 / 5	asyncpg pool bounds.
BACKEND_BROADCAST_QUEUE_MAXSIZE	1024	Per-WebSocket broadcast queue size.
BACKEND_PACKET_TRACKER_FINALIZE_DELAY_SECONDS	0.25	Wait for related observations before finalizing.
BACKEND_PACKET_TRACKER_RETENTION_SECONDS	10.0	Pending-entry retention.
BACKEND_PACKET_TRACKER_MIN_FLUSH_INTERVAL_SECONDS	0.05	Minimum persistence flush interval.
BACKEND_PACKET_TRACKER_PERSIST_TIMEOUT_SECONDS	2.0	One persistence attempt timeout.
BACKEND_PACKET_TRACKER_BATCH_PERSIST_TIMEOUT_SECONDS	10.0	Batch persistence timeout.
BACKEND_PACKET_TRACKER_PERSIST_RETRY_BACKOFF_SECONDS / MAX_SECONDS	0.25 / 5.0	Retry backoff bounds.
BACKEND_PACKET_TRACKER_ERROR_LOG_INTERVAL_SECONDS	5.0	Failure-log throttling interval.
BACKEND_PACKET_TRACKER_FLUSH_BATCH_SIZE	500	Maximum batch size; clamped to at least 1.
BACKEND_PACKET_TRACKER_MAX_ENTRIES	50000	Bounded in-memory correlation capacity; clamped to at least 1.
BACKEND_PACKET_TRACKER_MAX_PERSIST_FAILURES	3	Failure threshold; clamped to at least 1.
BACKEND_PACKET_TRACKER_MAX_DIRTY_AGE_SECONDS	60.0	Maximum age before dirty data must be flushed.
BACKEND_PACKET_TRACKER_STOP_JOIN_TIMEOUT_SECONDS	2.0	Tracker thread join timeout.
BACKEND_PACKET_TRACKER_REJECT_CORRELATION_WINDOW_SECONDS	1.0	Rejection-event matching window.
BACKEND_SNIFFER_BUFFER_CAPACITY	20000	Pre-DB capture buffer capacity.
BACKEND_SNIFFER_SOCKET_RCVBUF_BYTES	4194304	Requested raw-socket receive buffer.
BACKEND_SNIFFER_SELECTOR_TIMEOUT_SECONDS	1.0	Reader select timeout.
BACKEND_SNIFFER_RECV_BYTES	65536	Maximum raw receive length.
BACKEND_SNIFFER_BUFFER_DRAIN_INTERVAL_SECONDS	5.0	Buffered-record drain frequency.
BACKEND_SNIFFER_THREAD_JOIN_TIMEOUT_SECONDS	2.0	Session reader join timeout.
BACKEND_BRIDGE_BPF_BUILD_DIR	/tmp/mitm-bpf	eBPF build artifacts directory.
BACKEND_BRIDGE_TELEMETRY_RAW_SAMPLE_EVERY / META_SAMPLE_EVERY	1 / 1	Raw/meta sampling rates; zero is allowed.
BACKEND_BRIDGE_TELEMETRY_INGRESS_PERF_PAGES / META_PERF_PAGES	256 / 128	eBPF perf-buffer page counts.
BACKEND_BRIDGE_TELEMETRY_EVENT_QUEUE_MAXSIZE	20000	Telemetry event queue cap.
BACKEND_BRIDGE_TELEMETRY_QUEUE_RECOVERY_SIZE	1000	Queue recovery threshold.
BACKEND_BRIDGE_TELEMETRY_DROP_LOG_INTERVAL_SECONDS	5.0	Telemetry-drop log throttling.
BACKEND_BRIDGE_LINK_STATE_THREAD_JOIN_TIMEOUT_SECONDS	2.0	Link watcher join timeout.
BACKEND_BRIDGE_LINK_STATE_FAILURE_HOLDOFF_SECONDS / RECOVERY_HOLDOFF_SECONDS	0.75 / 1.0	Delay before propagating failure/recovery.
BACKEND_BRIDGE_LINK_STATE_DEGRADED_RECHECK_SECONDS	0.5	Degraded-link polling period.
BACKEND_TELEMETRY_PROCESS_STOP_TIMEOUT_SECONDS / READER_JOIN_TIMEOUT_SECONDS	3.0 / 2.0	Telemetry subprocess shutdown limits.
BACKEND_TSHARK_ENABLED	true	Enables tshark worker management.
BACKEND_TSHARK_DISPLAY_FILTER	empty	Optional tshark display filter.
BACKEND_TSHARK_TRY_HEURISTIC_FIRST	true	Applies local heuristic before tshark match.
BACKEND_TSHARK_CACHE_TTL_SECONDS	5.0	Enrichment cache lifetime.
BACKEND_TSHARK_MATCH_WINDOW_MS	5000	Capture-to-tshark matching window.
BACKEND_TSHARK_READER_JOIN_TIMEOUT_SECONDS / PROCESS_STOP_TIMEOUT_SECONDS	2.0 / 3.0	tshark shutdown limits.

Operational safeguards

Run the API behind an authenticated, access-controlled boundary. The configured CORS policy currently permits every origin, method, and header; it is convenient for development but should not be treated as an authorization control. Keep DB credentials out of version control and use a production-specific DSN.

Before starting capture, verify target interface/bridge names and ensure recovery access to the host. Before using firewall or script endpoints, snapshot the nft ruleset and understand which systemd units and filesystem paths are in scope.