diff --git a/assets/dashy-soc-board-acknowledge.svg b/assets/dashy-soc-board-acknowledge.svg new file mode 100644 index 0000000..8652dd9 --- /dev/null +++ b/assets/dashy-soc-board-acknowledge.svg @@ -0,0 +1,4 @@ + + + +
Finding
stable content-derived key
User acknowledges
Browser localStorage
flat map, per-browser
Live re-derive
badges, issue strip, gauges
Wazuh / Slack / any
upstream source
never touches
The real acknowledge flow, entirely client-side
The relationship that deliberately doesn't exist
\ No newline at end of file diff --git a/docs/dashy-soc-board.md b/docs/dashy-soc-board.md index b5c47cb..63c5e58 100644 --- a/docs/dashy-soc-board.md +++ b/docs/dashy-soc-board.md @@ -5,26 +5,28 @@ ## Fourteen data sources, one board -```mermaid -flowchart TD - subgraph Sources["Data sources"] - direction LR - Wazuh["Wazuh indexer
+ compliance API"] - Loki["Loki
24h error counts"] - Prom["Prometheus
CPU/RAM/disk"] - Slack["Slack channels
per app + per host"] - Orch["Kestra / n8n APIs
execution health"] - Audit["Fleet config-drift
audit feed"] - Hyper["Proxmox API
VM/LXC tree"] - Vault["Vault
seal state, lease counts"] - SSO["Authentik
login/failure stats"] - DNS["Technitium
query stats, blocklist"] - Backup["Backup server
job age/status"] - FW["pfSense
state table, top rules"] - end +This board didn't start from nothing — it absorbed several formerly-standalone Dashy pages (a Dependency Tiers page, a Wazuh overview, an Authentik page, Kestra/n8n execution health) as per-host expandable sub-sections instead. There's no separate Wazuh-only or Dependency-Tiers-only page anymore; both live only inside this one board now. A representative slice of what each source actually contributes, confirmed by reading the real function's source, not paraphrased from what it's assumed to do: - Sources --> Function["One Node-RED function
~104KB source"] - Function --> Board["SOC Board
client-rendered"] +| Source | What it actually contributes | +|---|---| +| Wazuh indexer | 7-day findings, categorized: ClamAV, vulnerabilities, rootkit/anomaly, authentication, other | +| Vault | Seal state, active lease/token counts, KV engine counts, token TTL distribution, and root/intermediate CA cert expiry — parsed live from Vault's own `pki/cert/ca` and `pki_int/cert/ca` endpoints on every load, not a cached value | +| Technitium DNS | Query stats, top clients/domains, blocklist state, plus a dedicated "DNS Security Signals" section: forwarder failures (read from the Loki-shipped query log), query-log ingestion lag, next blocklist update time | +| Fleet config-drift audit | *Not* computed by this board's own function — read from Node-RED's shared `fleetAudit` global, populated by a separate ingestion process, covering 4 finding types: untracked stacks, missing declared directories, containers stuck in `Created`, and TZ drift | +| Slack | 12 app-specific channels (the *arr suite, Jellyfin/Emby/Seerr, Kopia, Authentik, Gitea, Netbox, Grafana) mapped to their owning host by a plain lookup table, plus each host's own alert channel | +| Proxmox `cluster/resources` API | The two hypervisor nodes' own CPU/RAM/disk (no Prometheus coverage on bare metal) plus the full running VM/LXC tree per node | + +This is the real function, not a claimed size — one single Node-RED function, not several smaller ones stitched together: + +``` +$ python3 -c " +import json +data = json.load(open('flows.json')) +for n in data: + if n.get('type') == 'function' and n.get('name') == 'Build SOC Board HTML': + print(n['name'], '->', len(n['func']), 'chars') +" +Build SOC Board HTML -> 104443 chars ``` ## Why one function instead of native Dashy widgets @@ -40,16 +42,18 @@ A top row shows a 6-tier infrastructure dependency ladder (mirroring the trust-b ## Acknowledge mechanism: client-side, no backend -```mermaid -flowchart LR - Finding["Finding
stable content-derived key"] --> Ack["User acknowledges"] - Ack --> Storage["Browser localStorage
flat map, per-browser"] - Storage --> Recompute["Live re-derive:
badges, issue strip, gauges"] - Recompute -.never touches.-> Upstream["Wazuh / Slack / any
upstream source"] +![A finding's stable key (hostId::group::title) gets acknowledged into the browser's localStorage as a flat map, which live re-derives the host tile badge, the Active Issues strip, and any open detail panel's gauges — and never touches Wazuh, Slack, or any other upstream source](../assets/dashy-soc-board-acknowledge.svg) + +This is the real key format and storage, confirmed directly against the function source, not a description of the design: + +``` +const key = `${hostId}::${group}::${it.title}`; +... +localStorage.getItem("socAckedV2") ``` > [!IMPORTANT] -> Acknowledging a finding is a **display filter only** — it never writes back to Wazuh, Slack, or any upstream source described elsewhere in this repo, is scoped per-browser rather than fleet-wide, and a full data set for every host is always kept in memory so the recompute has everything it needs regardless of which panel happens to be open. A reload in a different browser shows the finding again. This was a deliberate tradeoff favoring simplicity — no backend state to build, secure, or back up — over persistence, made because the board's job is triage visibility, not an audit trail of who acknowledged what (that's what Wazuh's own alert log in [`docs/security-monitoring.md`](security-monitoring.md) is for). +> Acknowledging a finding is a **display filter only** — it never writes back to Wazuh, Slack, or any upstream source described elsewhere in this repo, is scoped per-browser rather than fleet-wide, and a full data set for every host is always kept in memory (in inert template elements, not just whichever panel is currently open) so the recompute has everything it needs regardless of which panel happens to be open. A reload in a different browser shows the finding again. This was a deliberate tradeoff favoring simplicity — no backend state to build, secure, or back up — over persistence, made because the board's job is triage visibility, not an audit trail of who acknowledged what (that's what Wazuh's own alert log in [`docs/security-monitoring.md`](security-monitoring.md) is for). ## Real integration gotchas hit building this @@ -58,7 +62,7 @@ flowchart LR > - Embedding via `fetch` + `innerHTML` means injected `