diff --git a/Service-Bus.md b/Service-Bus.md index 4b8aeab..7573ec1 100644 --- a/Service-Bus.md +++ b/Service-Bus.md @@ -196,6 +196,46 @@ Adding a new family is safe. --- +## Caddy fingerprint socket (`/run/decnet/fp.sock`) + +The `http` and `https` decky templates run a Caddy build that includes the +`decnet_fp` listener-wrapper module. The module writes newline-delimited JSON +records to a UNIX datagram socket at `$DECNET_FP_SOCK` +(default `/run/decnet/fp.sock`). `syslog_bridge.py` binds the socket, +deserialises each record, and re-emits it as a standard syslog line that the +collector tails and the ingester processes. + +This socket is **not** the service bus. It is a loopback-only, single-host +IPC channel internal to a decky container. Records never leave the host; +only the syslog lines they produce are forwarded to master. + +### Record kinds + +| `kind` | Emitted by | Fields | Syslog `event_type` | +|---|---|---|---| +| `h1_headers` | `decnet_fp` listener wrapper (h1 path) | `remote_addr`, `method`, `path`, `proto_tag="h1"`, `headers_ordered` (list of `[name, value]` pairs in wire order), `cookie`, `accept_language` | (consumed internally — see `http_request_headers` below) | +| `h2_settings` | `decnet_fp` listener wrapper (h2 path) | `remote_addr`, `settings` (map), `frame_order` (list of setting IDs in wire order) | `http2_settings` | +| `http_request_headers` | `decnet_fp` `FPHandler` (h1 + h2) | `remote_addr`, `proto_tag`, `method`, `path`, `headers_ordered`, `cookie`, `accept_language` — canonical wire-order header list used to compute JA4H | `http_request_fingerprint` (with `ja4h` field populated by `syslog_bridge._compute_ja4h`) | +| `h3_settings` | `decnet_fp` `FPHandler` (h3 path via `http3.Settingser`) | `remote_addr`, `settings` (map: `EnableDatagrams`, `EnableExtendedConnect`, plus any `Other` entries keyed by spec name or `GREASE_`) | `http3_settings` | +| `access_log` | `decnet_fp` `DecnetJSONLEncoder` Caddy access-log encoder | `remote_addr`, `method`, `path`, `proto_tag`, `status`, `bytes` | `http_access` | + +**`remote_addr` format**: Go's `net.http` and quic-go expose remote addresses as +`host:port` strings. `syslog_bridge` forwards them verbatim. The collector's +`parse_rfc5424` strips the port before assigning `attacker_ip`, and writes the +port as `fields["remote_port"]` so persistent source-port patterns are +preserved as fingerprint signal in the bounty payload. + +### Ingester handling + +The ingester's `_extract_bounty` stores: +- A `fingerprint` bounty of type `ja4h` for every `http_request_fingerprint` + event (payload includes `ja4h`, `protocol`, `method`, `path`, `remote_port`). +- A `fingerprint` bounty of type `http2_settings` or `http3_settings` for the + corresponding SETTINGS events (payload includes `settings`, `frame_order`, + `protocol`, `remote_port`). + +--- + ## Environment variables | Variable | Default | Meaning |