mitm-webserver/documentation/backend/api.md

HTTP and WebSocket API

The application is served below /api. FastAPI validates request models and publishes the complete JSON Schema at /api/openapi.json; use it for exact field types and the current response schema. This page documents semantics and all mounted operations.

General endpoints

Method/path	Meaning
GET /api/hello	Simple application health response.
GET /api/versions	Returns the Python runtime version.

Network: /api/network

Method/path	Parameters/body	Behaviour
GET /interfaces	none	Lists interfaces, addresses, flags, MTU, MAC, state and Ethernet profile.
GET /routes	none	Lists kernel route entries and resolved output-interface names.
GET /links	none	Lists raw link information.
GET /bridges	none	Lists Linux bridges, STP state and current member details.
GET /full-state	none	Combines interfaces, routes, links and bridges into one snapshot.
POST /interfaces/reset-defaults	{ interfaces: string[] }	Resets each requested interface to MTU 1500 and attempts to restore an automatic Ethernet profile through ethtool.
POST /bridge/create	{ name, interfaces }	Creates a Linux bridge and attaches listed interfaces.
POST /bridge/remove	{ name }	Removes an existing bridge.
GET /bridge/link-state-watchers	none	Returns all watcher states.
GET /bridge/{bridge_name}/link-state-watcher	path name	Returns one bridge watcher state.
POST /bridge/{bridge_name}/link-state-watcher/enable	optional recovery holdoff	Enables member failure/recovery propagation.
POST /bridge/{bridge_name}/link-state-watcher/disable	path name	Stops and removes that watcher.
WS /ws/state	none	Receives full network-state update payloads after network mutations.

An interface object includes its kernel index, name, state, MAC, MTU, decoded flags, assigned IPv4/IPv6 addresses, and, where available, speed/duplex/autoneg data.

Sniffer: /api/sniffer

Method/path	Parameters/body	Behaviour
POST /start	exactly one of bridge or interface; optional bridge_capture_mode, benchmark_mode	Creates a capture session. Bridge modes are tc_ebpf and af_packet.
POST /stop	optional session ID or bridge/interface selector	Stops an identified session, target sessions, or all sessions according to the request.
GET /status	none	Returns status keyed by captured interface: running/existing/up state, owner session, mode, and benchmark mode.
GET /debug	none	Returns internal session, buffered-record, tshark, telemetry, and tracker state. Treat as diagnostic output, not a stable client contract.

The start endpoint rejects requests containing both a bridge and an interface, or neither. A bridge defaults to tc_ebpf; an interface always captures using AF_PACKET.

Packets: /api/packets

Method/path	Parameters/body	Behaviour
GET /packets?limit=100	limit 1–10,000	Fetches most-recent normalized packet rows.
DELETE /packets?reset_id=true	optional boolean	Clears packet history; can reset database identity state.
WS /ws/packets	none	Receives packet updates from the in-process broadcaster.

REST history is authoritative. WebSocket clients must expect connection loss and dropped messages for a slow subscriber, then refill missed state with GET.

Analysis: /api/analysis

Every analysis endpoint accepts since_minutes when shown; its valid range is 1 minute to 30 days. Results are derived from the stored packet history and do not claim ground truth about a physical topology or attack.

Method/path	Main query controls	Result
GET /interface-hosts	since_minutes, limit_per_interface	Likely hosts attached to each MITM-side interface.
GET /interface-host-protocols	plus limit_protocols_per_host	Attachment inference with per-host protocol evidence.
GET /interface-protocol-paths	limit_paths	Directional aggregated paths for a Sankey-style view.
GET /conversations	limit	Aggregated directional endpoint conversations.
GET /conversation-flow-detail	flow_id or directional endpoint/port fields; protocol, limit_packets	Ordered packets, subflows, and derived request/response events.
GET /host-intelligence	limit_hosts	Host-centric peers, service and hostname hints.
GET /discovery	limit	Discovery, naming and service-advertisement activity.
GET /anomalies	limit	Heuristic scan, beacon, rare service, reset-heavy and drop-heavy candidates.

conversation-flow-detail requires a flow_id or enough directional fields to identify a conversation. All analysis endpoints return 503 while the database is unavailable and 500 when their underlying query fails.

Firewall: /api/firewall

Method/path	Body/query	Behaviour
GET /rules	none	Lists nftables ruleset in a predictable structured representation, enriched with textual rule data where possible.
DELETE /rules/{handle}	optional family/table/chain defaults	Deletes the rule identified by its nft handle.
POST /raw	{ cmd: string }	Executes an arbitrary textual nft command and returns stdout/stderr/return code.

The raw endpoint is intentionally powerful and must not be exposed to untrusted clients. It changes the host firewall, not an application-local simulation.

Scripts: /api/scripts/scripts

The doubled path is produced by the current combination of router and application prefixes. Scripts are Python NFQUEUE workers installed under /srv/fw-scripts and can have systemd units and isolated virtual environments.

Method/path	Behaviour
GET /	Lists scripts and their unit mappings/status.
POST /	Uploads a script multipart payload; accepts a script, optional requirements file and required name form field.
GET /{name}	Downloads script source.
GET /{name}/requirements	Downloads its requirements file.
PUT /{name}/requirements	Replaces requirements and runs pip install in the script venv.
DELETE /{name}/requirements	Deletes requirements and removes the venv.
POST /{name}/enable	Creates/starts an NFQUEUE systemd service for a requested queue number.
POST /{name}/disable	Stops/disables the service for a queue number.
DELETE /{name}	Removes all, or one requested queue-number unit, then cleans script-related files as appropriate.

Names allow letters, digits, ., _, and -; . and .. are prohibited. Repository example scripts are protected from API modification. Enabling/uploading requirements has code-execution and host-service consequences.