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.