documentation md files

documentation/backend/api.md

@@ -0,0 +1,112 @@
+# 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.