Fleet Correlation Contract (v1)
CSM is a per-host sensor. It does not correlate findings across hosts itself; cross-host (“fleet”) correlation is owned by phpanel, which already receives every deduplicated finding through the per-finding webhook. This document defines the contract phpanel implements to turn that stream into one fleet incident per attacker instead of N identical per-host incidents.
This is the phpanel-side correlation design: CSM stays a sensor with no new inbound network surface on hosts. A peer-to-peer ingest endpoint inside CSM was considered and rejected for v1 (it would add an inbound auth plane and key distribution to every host).
What CSM already provides
With alerts.webhook.type: phpanel, CSM POSTs one HMAC-signed
message per deduplicated finding that reaches alert.Dispatch (see
the per-finding webhook in internal/alert/webhook.go). This sink runs
before operator alert suppression and the operator alert rate limit, so
phpanel receives the correlation stream even when local notifications
are muted:
POST <alerts.webhook.url>
Content-Type: application/json
X-CSM-Signature: sha256=<hex> (HMAC-SHA256 over the raw body)
X-CSM-Hostname: <hostname>
{
"hostname": "host-7.example",
"timestamp": "2026-05-29T10:00:00Z",
"finding": {
"check": "ssh_bruteforce",
"severity": 2,
"source_ip": "203.0.113.10",
"message": "...",
"timestamp": "2026-05-29T10:00:00Z",
"tenant_id": "...", // when known
"domain": "...", // when known
...
}
}
CSM keeps each finding in a durable queue and delivers them in order. A 2xx answer acknowledges a finding. HTTP 400, 413 or 422 refuses the record itself: CSM moves it to a bounded local archive, counts it as lost and sends the next finding. Use these codes only for a problem with that one record. After a long run of refusals with nothing accepted, CSM stops archiving and retries instead, so a panel that refuses every request does not lose the queue. The hold survives config reloads and daemon restarts and ends after an accepted delivery. Redirects are not followed and do not acknowledge findings. Any other failure is retried with backoff, and later findings wait behind it.
Every field phpanel needs to correlate across hosts is present:
hostname identifies the reporting sensor, and finding.source_ip
identifies the attacker when the detector has a remote source. For
mail_subnet_spray and smtp_subnet_spray, use source_ip when present
(older findings); otherwise use the single subnet in finding.cidrs.
Other checks’ cidrs, including http_asn_crawl, are response targets
and must not become an attacker key. Severity is the CSM numeric enum
(0 warning, 1 high, 2 critical). No extra
CSM API or peer transport is required; fleet correlation is a matter of
phpanel aggregating the stream it already receives.
Correlation rule (phpanel side)
- Verify
X-CSM-Signature(HMAC-SHA256 over the raw body) with the shared secret before trusting any field. Reject unsigned or mismatched messages. - Group incoming findings by the attacker address described above within a sliding window (recommend matching CSM’s 15-minute incident merge window).
- When the same attacker address appears in findings from two or more
distinct
hostnamevalues inside the window, open one fleet incident keyed on that address rather than per-host incidents. - Attach each contributing
(hostname, finding)to the fleet incident’s timeline so an operator sees the spread across the fleet. - Account/mailbox/domain identifiers are host-local; do not use them as the cross-host key (they collide across tenants). Use only the attacker address as the cross-host key.
Severity and de-duplication
- A fleet incident’s severity is the max of its contributing findings.
- Findings carrying no attacker address (host-integrity events, config drift) are not fleet-correlated; they stay per-host.
- The same
(hostname, attacker address, check)arriving repeatedly is the normal heartbeat of an ongoing attack; collapse on the attacker address and count contributions rather than opening a new incident per message.
Out of scope (v1)
- Peer-to-peer ingest between CSM hosts.
- A CSM-side fleet incident store. CSM remains stateless with respect to other hosts; the fleet view lives in phpanel.
- Cross-host auto-block orchestration. phpanel may drive per-host blocks through each host’s existing control surface; CSM does not coordinate blocks across the fleet.