Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 the auto_response.dry_run gate. severity is "auto". An allow verdict 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 carry CSM auto-block: <check> as the reason, run up to four at a time and honour allow_unsigned and require_response_signature; an allow ends 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 when bpf_enforcement.verdict_callback: true is also set. CSM asks about the destination of an outbound connection the BPF hook denied, or would have denied in dry-run. reason is bpf_enforcement:<check>:<port> and severity is the finding’s severity (WARNING, HIGH or CRITICAL). The answer only annotates findings: the verdict, tenant_id and note are 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 for bpf_enforcement the connection’s destination.
  • reason (required): short reason string, for example CSM auto-block: wp_login_bruteforce.
  • severity (optional): "auto" for auto-response decisions; the finding’s severity for bpf_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 equal request.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 when allow_unsigned: true is set.
  • 200 OK with verdict: "block" or omitted: standard block path runs (which still honors auto_response.dry_run if set).
  • 200 OK with unknown verdict string: rejected; treated as fail-open (default block).
  • 200 OK with verdict: "allow" and no HMAC secret while allow_unsigned is false: rejected as an unsigned downgrade; treated as fail-open (default block).
  • 200 OK with missing or invalid X-CSM-Signature (and require_response_signature not 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 nonce or 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 nonce or timestamp: rejected as replay when response signing is required. Missing replay fields are accepted only when require_response_signature: false is 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.