Verdict Callback HTTP Contract (v1)
When auto_response.verdict_callback.enabled: true, CSM POSTs each
auto-block decision to the configured URL and reads an advisory
response. The endpoint is not a per-tenant nftables enforcement
plane - it lets phpanel observe and label decisions, downgrade them to
audit-only, and attach tenant attribution.
CSM runs its local block validation before calling the endpoint. Malformed IPs, disabled IPv6 targets, infra IPs, and configured block limits are rejected locally and are not sent to the callback.
Callers
Two parts of CSM call the endpoint, told apart by the request source:
auto_response: each automatic block of a single address, after local validation and before theauto_response.dry_rungate.severityis"auto". Anallowverdict skips that block. In dry run with the firewall on outside observe mode, the admission ledger also asks for locally eligible block attempts, so one block can bring an additional request. Its requests carryCSM auto-block: <check>as thereason, run up to four at a time and honourallow_unsignedandrequire_response_signature; anallowends the forecast without an example. Existing effects, protected targets and full capacity need no owner request; retries ask anew and reload discards old policy answers. The v1 request contains no dry-run field, and request totals are not an exact multiple of legacy calls.bpf_enforcement: only whenbpf_enforcement.verdict_callback: trueis also set. CSM asks about the destination of an outbound connection the BPF hook denied, or would have denied in dry-run.reasonisbpf_enforcement:<check>:<port>andseverityis the finding’s severity (WARNING,HIGHorCRITICAL). The answer only annotates findings: the verdict,tenant_idandnoteare added to the finding details. It never changes the kernel decision, which is made before the call. Answers are cached for one minute per destination, reason and severity, and the finding that triggers a lookup is sent without one.
Subnet blocks, promotion of an existing block to permanent, and manual blocks from the CLI, web UI or API do not call the endpoint.
Endpoint
POST <auto_response.verdict_callback.url>
Content-Type: application/json
Accept: application/json
X-CSM-Signature: sha256=<hex> (HMAC-SHA256 over raw body, omitted if no secret configured)
auto_response.verdict_callback.url must be an http:// or https://
URL with a host. CSM POSTs directly to that URL (no path appended).
Authentication
CSM signs the raw request body with HMAC-SHA256 using the configured
secret and sends the digest in X-CSM-Signature: sha256=<hex>. The
secret is resolved once per request/response exchange: if
hmac_secret_env is set and the env var is non-empty, it wins over the
static hmac_secret field. Request and response verification use the same
key for that exchange. The value comes from the running process environment;
editing an environment file requires a daemon restart, even if configuration
is reloaded. See credential rotation.
CSM refuses to enable the callback without a non-empty hmac_secret or
resolved hmac_secret_env value. Operators can set
allow_unsigned: true only for staged rollouts that intentionally send
unsigned requests and accept unsigned responses. Without that explicit
opt-in, CSM rejects an unsigned allow verdict and proceeds with the
default block.
The server MUST verify the signature with constant-time compare and reject unsigned or invalid requests with 401.
Response signing (required by default)
The server MUST sign its response body with the same HMAC-SHA256 scheme
(same secret, same X-CSM-Signature: sha256=<hex> header). CSM verifies
the response signature with constant-time compare before parsing the
verdict; an unsigned or forged response is rejected and CSM falls back
to its default block. Without this check an on-path attacker could
downgrade every “block” decision to “allow”.
If the server cannot sign responses yet (e.g. mid-rollout), operators
can set auto_response.verdict_callback.require_response_signature: false in csm.yaml to temporarily accept unsigned responses. The
default is true and there is no other way to disable the signature
requirement.
When response signing is disabled but a secret is configured, CSM still
checks any nonce or timestamp fields the server echoes. A nonce must
match the request nonce, and a timestamp must stay within the five-minute
skew window. A legacy response that omits both fields keeps working.
Request body
{
"ip": "203.0.113.10",
"reason": "mail_bruteforce",
"severity": "auto",
"source": "auto_response",
"nonce": "9a7e84f0c123ab45e102d4f8b9c1d3e0",
"timestamp": 1748345600
}
ip(required): the address CSM is about to block, or forbpf_enforcementthe connection’s destination.reason(required): short reason string, for exampleCSM auto-block: wp_login_bruteforce.severity(optional):"auto"for auto-response decisions; the finding’s severity forbpf_enforcement.source(optional):"auto_response"or"bpf_enforcement"; see Callers.nonce(always sent): a 128-bit hex random value unique to this call. The panel MUST echo it verbatim when response signing is on. When response signing is disabled, CSM still checks the value if the panel echoes it.timestamp(always sent): unix seconds when CSM produced the request. The panel does not need to validate it but MAY use it to reject stale calls.
Response body (200 OK)
{
"verdict": "block",
"tenant_id": "tenant-42",
"note": "matched dovecot user pattern",
"nonce": "9a7e84f0c123ab45e102d4f8b9c1d3e0",
"timestamp": 1748345600
}
verdict:"block"(default; also returned if field omitted) or"allow"to override. Any other string is rejected by CSM as a protocol error, treated as “no decision” (CSM proceeds with the default block per fail-open semantics).tenant_id(optional): attribution string; CSM logs it alongside the decision.note(optional): free-form note logged for the verdict.nonce(required when response signing is on): MUST equalrequest.nonce. CSM compares with constant-time equality and rejects mismatches as replay attempts. When response signing is disabled, CSM still checks this field if present.timestamp(required when response signing is on): unix seconds when the panel produced the reply. CSM rejects replies whose timestamp drifts more than five minutes from local clock. When response signing is disabled, CSM still checks this field if present.
Failure semantics
- Network error / timeout / non-200 HTTP response: CSM logs a warning and proceeds with the default block. The hook is fail-open at the transport level.
- Local nonce generation failure: CSM does not send the request and proceeds with the default block.
- 200 OK with
verdict: "allow": CSM does not modify nftables; logs the override to stderr. If no HMAC secret is configured, this is accepted only whenallow_unsigned: trueis set. - 200 OK with
verdict: "block"or omitted: standard block path runs (which still honorsauto_response.dry_runif set). - 200 OK with unknown
verdictstring: rejected; treated as fail-open (default block). - 200 OK with
verdict: "allow"and no HMAC secret whileallow_unsignedis false: rejected as an unsigned downgrade; treated as fail-open (default block). - 200 OK with missing or invalid
X-CSM-Signature(andrequire_response_signaturenot turned off): rejected as forged; treated as fail-open (default block). Operators see the rejection in stderr; recurring rejections indicate either a panel-side rollout gap or an active on-path attack. - 200 OK with mismatched
nonceor timestamp drift over five minutes: rejected as replay whenever a secret is configured and the field is present; treated as fail-open (default block). - 200 OK with missing
nonceortimestamp: rejected as replay when response signing is required. Missing replay fields are accepted only whenrequire_response_signature: falseis set for a legacy response shape.
Limits
- CSM caps response body at 64 KB. Larger responses are rejected.
- Default request timeout is 2 seconds (configurable via
timeout_sec, range 1-30).
Sample server stub (Go)
http.HandleFunc("/api/csm/verdict", func(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
if !verifySignature(r.Header.Get("X-CSM-Signature"), body, secret) {
http.Error(w, "bad signature", 401); return
}
var req struct {
IP, Reason, Severity, Source string
Nonce string
}
_ = json.Unmarshal(body, &req)
tenant := lookupTenantOwning(req.IP) // your impl
verdict := "block"
if isPanelInfra(req.IP) { // never block our own infra
verdict = "allow"
}
respBody, _ := json.Marshal(map[string]any{
"verdict": verdict, "tenant_id": tenant,
"nonce": req.Nonce, "timestamp": time.Now().Unix(),
})
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(respBody)
w.Header().Set("X-CSM-Signature", "sha256="+hex.EncodeToString(mac.Sum(nil)))
_, _ = w.Write(respBody)
})
When to graduate this to per-tenant enforcement
This v1 hook surfaces tenant attribution but does not synthesize per-tenant nftables rules. If/when phpanel wants real per-tenant enforcement (block IP X from tenant Y’s mailboxes only, allow elsewhere), that’s a separate plan that will need:
- Multi-set nftables rule generation per tenant
- A way to map an IP+tenant pair to an nftables verdict
- Lock-step config sync between CSM and the panel’s tenant table
Do that work then, against a real call site, not on spec.