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

API Reference

Machine-readable HTTPS API. All endpoints require token authentication. State-changing POST, PUT, PATCH, and DELETE requests require CSRF protection for browser cookie sessions.

Authentication

# Bearer token (header)
curl -H "Authorization: Bearer YOUR_TOKEN" https://server:9443/api/v1/status

# Cookie-based (after login)
curl -b "csm_auth=SESSION_COOKIE_FROM_LOGIN" https://server:9443/api/v1/status

Cookie-authenticated state-changing requests require the X-CSRF-Token header (obtained from the authenticated page meta tag). The token belongs to the browser session that loaded the page; another session’s token is refused, and a form field is read from the request body only. Admin-scope Bearer requests are CSRF-exempt because the Authorization header is the write credential.

Browser session management

A successful browser login exchanges an admin token for an opaque session cookie. API tokens are never valid cookies. Sessions expire on idle or absolute deadlines and all end on daemon restart. The header’s Sessions page provides the same management operations as these admin-only endpoints:

MethodPathResult
GET/api/v1/sessionsitems list of sessions with id, name, created, last_seen, expires, remote_ip, user_agent, current
DELETE/api/v1/sessions/<id>Revoke that session; an unknown ID answers 404
DELETE/api/v1/sessionsRevoke all browser sessions, including the caller’s

Revocation returns {"ok":true} only after committing to the store. Failure returns 503; invalid session IDs return 404. Lists contain no credential hashes or session verifiers. Cookie-authenticated DELETE requests require CSRF; admin bearer callers are exempt. Read-scope bearers cannot list or revoke sessions. POST /logout requires authentication and CSRF for browser callers; it revokes the current session and clears the cookie. GET /logout cannot log users out.

Token scopes

Configure tokens under webui.tokens: with a scope of admin, read or unban:

webui:
  tokens:
    - name: "operator"
      token: "..."
      scope: admin       # full read+write
      issued_at: "<UTC RFC3339 time when this token was generated>"
    - name: "panel-readonly"
      token: "..."
      issued_at: "<UTC RFC3339 time when this token was generated>"
      scope: read        # status, findings, history, stats, challenge stats, blocked IPs, scan jobs, health, components, capabilities, SSE
    - name: "panel-unban"
      token: "..."
      scope: unban       # GET /api/v1/firewall/check and POST /api/v1/firewall/unban only
      issued_at: "<UTC RFC3339 time when this token was generated>"
      expires_at: "<UTC RFC3339 time when this token stops working>"
      allowed_ips: ["203.0.113.10", "198.51.100.0/24"]

A credential expires at its expires_at and never expires without one. The optional issued_at records when the token was generated. Replace the placeholders above with fresh random tokens and real times. A malformed or future issued_at, an expires_at that is malformed or not after issued_at, and a past expires_at refuse authentication. See credential rotation.

allowed_ips limits a token to the listed addresses and CIDR ranges, for API calls, browser login and the browser sessions it starts. CSM matches the TCP peer address and ignores forwarded headers. A token without allowed_ips is accepted from any address. An entry that is not an address or CIDR fails configuration loading.

IPv4-mapped addresses and CIDRs within the mapped range match IPv4 peers: ::ffff:192.0.2.0/120 matches the same peers as 192.0.2.0/24. CIDR host bits are masked. Entries with interface zones, such as 2001:db8::1%eth0, fail configuration loading; use an address without a zone. A peer’s interface zone does not affect address matching.

Unban-scope tokens are meant for hosting panels that let customers lift their own blocks. They cannot log in to the dashboard, read status or reach any other route, and they are exempt from CSRF only on those two routes.

On POST /api/v1/firewall/unban, an unban-scope token removes the address’s block and its mail spray re-block marker. Spray failure history and SMTP, IMAP and POP failure counts remain, including shared IPv6 /64 evidence and other addresses’ markers. Renewed spraying can still trigger a block. An admin token or browser session on the same route performs a full operator release, clearing the address’s mail failure history and counts as described in automatic blocking. Either credential also removes subnet blocks CSM added automatically that cover the address (subnet_removed in the response). A subnet an operator blocked is kept and named in subnet_kept: the address stays dropped until that subnet is unblocked. Operator descriptions do not grant automatic-unban eligibility. If a subnet changes during the request, CSM leaves the replacement intact and returns HTTP 500 with a retry message. Older subnet entries without recorded automatic ownership are also kept, even if their source label says automatic; they expire normally or can be removed explicitly through the admin-only subnet removal endpoint. The credential accepted at authorization selects the release mode; expiry while reading the request body cannot change it. A valid browser session takes precedence over a bearer token and still needs CSRF with an unban bearer.

A failed individual-IP removal returns HTTP 500 without clearing threat state or reporting a successful unban. A failed subnet removal also returns HTTP 500; the individual-IP release and any earlier subnet removals have already taken effect. A firewall backend without self-service unban support returns HTTP 501 for an unban-scope caller; it never falls back to an operator release. A backend without conditional subnet removal returns HTTP 501 when a covering automatic subnet needs removal. The cPHulk flush remains best effort and runs only after the firewall removals succeed.

The legacy single-token webui.auth_token:, with its optional webui.auth_token_issued_at and webui.auth_token_expires_at, is loaded into a legacy-auth-token admin entry. Read-scope tokens are intended for orchestrators and dashboards that consume status, findings, history, stats, challenge stats, blocked-IP summaries, scan jobs, health, components, capabilities, and SSE events. Admin scope is still required for write routes and for sensitive reads such as quarantine, settings, firewall internals, threat-intel detail, rules, account detail, exports, incident timelines, and audit history. (ModSecurity stats/blocks/events are read scope; only the ModSecurity rules and escalation routes need admin.) metrics_token: is a separate, read-only credential for /metrics only.

Read-only MCP endpoint

Support agents that speak the Model Context Protocol get these reads at /mcp on the same listener, with their own credentials; see MCP endpoint. It cannot reach any route that changes state.

Errors

Every failure answers a non-2xx status with a JSON body that has an error message. That includes CSRF, origin, rate-limit and wrong-method refusals. Some failures add detail next to it; a settings save that fails validation adds errors, a list of fields and messages. An unknown path under /api/ answers 404. No 2xx response reports a failure.

{"error": "invalid IP address"}

Actions

A request that changes state answers "ok": true with the action’s own fields, such as undo_token or warning. Work that continues after the answer, such as a daemon restart, a firewall rollback or a scan job, answers 202. A batch where some items failed answers 200 and lists the failures; a batch where nothing changed answers an error status. A read-only route answers 405 to any method but GET.

An empty fix batch is rejected. Threat actions report firewall failures, and bulk actions list invalid addresses as well as failed changes. A failed action can have applied some steps before the error; inspect the current state before retrying it. A response that cannot be encoded answers 500 with an error body.

/api/v1/firewall/check and /api/v1/firewall/unban also send "success": true for callers written against the older API. It will be removed; use the status code and ok.

Lists

Every GET route that returns a list answers a JSON object, never a bare array. The list is under items. An empty list anywhere in a response is [] and an empty map {}, never null; null means a value is not known.

  • total is the number of matches the server counted. It is larger than the length of items when the route pages or cuts the list.
  • offset and limit come with routes that page or cap the list. Capped routes that do not support paging report offset: 0.
  • truncated is true when matches were left out: past the page, past the limit, or past a scan cap. When a scan cap stopped the count, total counts only what was scanned. Incident groups also send scan_truncated to distinguish a scan cap from a page limit; their total is exact when scan_truncated is false.
  • Other keys next to items describe the whole list, such as check_types on /findings/enriched or summary on /email/forwarders.

/audit, /threat/top-attackers and /threat/events do not count every match. They send limit and truncated without total.

{"items": [{"ip": "203.0.113.9", "reason": "wp_login_bruteforce"}], "total": 1}

Times and durations

Every time is an RFC 3339 instant in UTC with sub-second precision, such as 2026-09-22T10:04:05.123456Z. The same applies to the event stream. A time that is not set is left out, never sent as 0001-01-01T00:00:00Z.

The API does not send times it formatted for reading, such as “5m ago”, “1h2m” or a clock time without a date. Clients format instants in their own time zone and count down to an expires_at themselves.

Durations are numbers of seconds in keys that end in _seconds, such as uptime_seconds, elapsed_seconds, duration_seconds, oldest_age_seconds and update_interval_seconds. Temporary whitelist responses use duration_seconds, rollback status uses remaining_seconds, and incident timelines use window_seconds. Request parameters such as hours and editable configuration values retain their documented units.

Two values keep a text form. started_at_token is an opaque token for restart polling. The temporary reason on /api/v1/firewall/check keeps its “(expires in …)” text for existing callers; expires_at carries the instant.

Severity

A severity is its label: CRITICAL, HIGH or WARNING. That covers severity, severity_max, demoted_from and the attack event sev. Clients derive colours and sort order from the label. A severity filter takes the label in any case, or the older 0, 1 or 2 level. The findings inside an email quarantine entry keep the scanning engine’s own rating.

Status & Data

GET  /api/v1/status              Full health snapshot: version, uptime, watchers, severity counts,
                                 store health, blocklist size, capabilities[], config_hash, binary_hash,
                                 automation rollout state, challenge pending count, rollback state.
                                 `started_at_token` changes after a daemon restart and is suitable
                                 for restart polling.
                                 `security_posture` is `healthy`, `warning`, or `critical` after
                                 combining daemon faults with active high/critical incidents.
                                 `incidents_open_by_severity` breaks open and contained incidents
                                 down by `critical`, `high`, and `warning`.
                                 `correlation_attribution` (present after the first active-set
                                 merge) lists per check the findings correlation could not
                                 attribute to an account: `current` for the active set now,
                                 `cumulative` since daemon start.
                                 `queues` reports named protection queues, including depth,
                                 capacity, running work, recent and cumulative drops, and lag.
                                 A degraded queue changes `status` and `security_posture`.
                                 `backends` names the backend each started live monitor
                                 selected (`af_alg`, `connection_tracker`, `exec_monitor`,
                                 `sensitive_files`, `placement`): `bpf`, `legacy` or `none`.
                                 `latest_scan` is the canonical last-scan timestamp; `last_scan_time`
                                 is a legacy alias kept for older clients and will be removed.
                                 `uptime_seconds` is the time since the daemon started.
GET  /api/v1/challenge/stats     Challenge-routing activity for the UI: `pending`, `escalated`
                                 (timeouts that became hard blocks), `passed` (challenges solved
                                 or bypassed, since restart), `routed_by_check` (per source
                                 check, since restart), and `recent` routes. Read scope.
GET  /api/v1/capabilities        Static feature list (e.g. `confd.dropins.v1`, `events.sse.v1`,
                                 `webhook.phpanel.v1`, `webui.prefs.v1`, `webui.undo.v1`,
                                 `mail.queue.composition.v1`, `mail.forwarders.delete.v1`,
                                 `detect.http_scanner_profile.v1`, `challenge.stats.v1`,
                                 `firewall.rollback.v1`, `firewall.dos_exempt.v1` on Linux builds).
                                 Use for orchestrator feature-detect. `csm capabilities` prints
                                 the same build tokens without a running daemon.
GET  /api/v1/components          Watcher/component matrix with attachment, event, and upstream freshness state.
GET  /api/v1/events              Server-Sent Events stream of findings as they dispatch.
                                 Read-scope token sufficient. One JSON event per `data:` line.
                                 Writes and flushes have a three-second deadline. A failed
                                 write or flush closes the stream and frees its subscriber slot.
GET  /api/v1/health              Daemon health (fanotify, watchers, engines)
GET  /api/v1/findings            Current active findings
GET  /api/v1/findings/enriched   Enriched findings with GeoIP, accounts, fix info, and a list version.
                                 ?limit=N orders by severity, then newest, even when all rows fit;
                                 returns at most N rows with limit and truncated, while total and
                                 the severity counts cover all.
                                 ?fields=version returns only {version, total}, for change polling.
                                 block_ip is set only for checks that report an attacker address,
                                 the same evidence auto-block acts on
GET  /api/v1/finding-detail      Finding detail with action history (?check=&message=)
GET  /api/v1/history             Paginated history (?limit=&offset=&from=&to=&severity=&search=&checks=&scope=).
                                 checks is a comma-separated list of check names to include.
                                 scope=email limits results to the /api/v1/email/checks list when checks is absent.
                                 total counts every match; truncated is true when matches exist past the page
GET  /api/v1/history/csv         CSV export of the newest 5,000 entries matching the /history filters
GET  /api/v1/stats               24h severity counts and auto-response summary, accounts with active high or critical findings
GET  /api/v1/stats/trend         30-day daily severity counts; each `date` is a calendar day in the server's time zone
GET  /api/v1/stats/timeline      Hourly severity counts for the last 24 hours; each bucket names its `start` instant
GET  /api/v1/quarantine          Quarantined files with metadata (incl. htaccess pre_clean backups)
GET  /api/v1/quarantine-preview  Preview quarantined file content (?id=)
GET  /api/v1/db-object-backups   db_object_backups bucket (MySQL trigger/event/procedure/function drops)
GET  /api/v1/db-object-backup-preview Preview captured CREATE SQL (?key=)
GET  /api/v1/blocked-ips         Blocked IPs with reason and expiry
GET  /api/v1/accounts            Accounts a server-wide scan covers
GET  /api/v1/account             Per-account findings, quarantine, history (?name=)
GET  /api/v1/audit               Newest 200 UI audit log entries; truncated marks older ones. Each entry names the credential that acted (actor) and whether it came as an API token or a browser login (via)
GET  /api/v1/export              Export state (suppressions, whitelist)
GET  /api/v1/incident            Incident timeline (?ip=&account=&hours=)
GET  /api/v1/performance         Performance metrics snapshot (admin scope)
POST /api/v1/perf/fix-error-log  Truncate a fixed-row error_log finding (admin scope, CSRF)
POST /api/v1/perf/fix-display-errors
                                  Disable display_errors for a fixed-row config finding (admin scope, CSRF)
POST /api/v1/perf/fix-wp-cron    Disable WP-Cron and install a system cron for a perf_wp_cron finding (admin scope, CSRF)
GET  /api/v1/hardening           Last stored hardening audit report (admin scope)

Performance telemetry

GET /api/v1/performance returns metrics and findings. In metrics, mysql_mem_mb, mysql_conns, redis_mem_mb, redis_maxmem_mb and redis_keys are null when csm could not read them; zero is a measured zero. The two Redis memory fields are read together, redis_keys separately. A redis_maxmem_mb of 0 means Redis has no memory limit. The csm_performance MCP tool returns the same response.

Accounts at risk

accounts_at_risk in GET /api/v1/stats lists accounts with a current high or critical finding, whatever its age. Suppressed findings and internal records are left out. findings counts all of the account’s current findings, warnings included, and severity is the highest. At most 50 accounts, ordered by severity, then finding count, then name. An empty list is [].

Date ranges

/api/v1/history, /api/v1/email/groups, /api/v1/email/overview, /api/v1/email/rejects, /api/v1/email/senders and /api/v1/email/relay-abuse take from and to as a calendar date (YYYY-MM-DD) or an RFC 3339 time. A date is a day in the server’s time zone, and to includes the whole day. An RFC 3339 to is exclusive. The web UI sends RFC 3339 times so a day follows the operator’s time zone preference. A value in neither form is rejected with 400. An empty or whitespace-only bound is treated as absent. Calendar days start at their first valid local time, including when midnight is skipped or repeated; a skipped calendar date covers an empty range. Fractional seconds are preserved when filtering RFC 3339 bounds. On the /api/v1/email/ endpoints a to without from covers the 24 hours before to.

WordPress verification coverage

wordpress_verification contains core and plugins coverage when installation history is available. The same fields appear in csm status --json; human status shows the counts. Each entry reports verified, modified, unverified, unknown, not_wordpress and last_attempt. unknown means discovery found a directory but no completed attempt is recorded. modified means core verification completed with integrity differences, including missing core files. A verified plugin inventory can still contain vulnerable versions. The timestamp is the latest recorded attempt in that group. Counts retain the last observed results across restarts and cached scan cycles. Overlapping scans retain the latest attempt and its consecutive failure history in scan order. Discovery without an attempt does not replace verification evidence. An absent group means there is no retained installation history, not proof of coverage. An error field reports unreadable history instead of clean counts.

The first failed attempt increases unverified; repeated failures also produce an installation-specific Warning. In host scans, when one cause stops more installations than the per-cause limit, the warnings collapse into a single finding that names the cause, the total and a sample, so a host-wide fault cannot spend the whole alerts.max_per_hour budget. The limit applies across accounts for each kind of verification and cause. Account scans keep installation-specific warnings. A summary has no installation path and names an account only when all affected installations share it. These findings are separate from queue health: a command that completed with a refusal did not lose queue work. Existing queue loss accounting remains responsible for interrupted or missing command work.

Firewall confirmation

automation.firewall_confirmation describes a pending CLI apply-confirmed window, also when the firewall is disabled or its engine failed to start; it is absent when none is pending. deadline is the saved deadline in UTC when it can be read, and error says why the window cannot settle without csm firewall confirm or repair of the reported recovery problem. It is separate from the Web UI configuration rollback timer.

Automatic response admission

status.admission.v1 advertises the admission object on status responses. The same view appears under admission in csm status --json and as admission rows in csm doctor. The daemon reads it on a timer, so checked_at says how old it is. Every automatic response the blocking paths select is also handed to the ledger, which refuses disabled responses. With auto_response.dry_run false, the firewall on and outside observe mode, the ledger applies the automatic IP blocks it is handed (owner.executing) and the blocking paths leave those blocks to it. Otherwise it previews or forecasts eligible work and never applies it, and the view is not an enforcement record.

  • ledger holds the stored admission time, queue, lifetime queue counters (including newly checkpointed ingress drops), hourly and daily outcomes, ingress generations, the hourly ceiling with its general and reserved lanes, storage, the outbox, notice records and unresolved outcomes (running and unknown counts and when the next unknown one can retire), and effects: the temporary set slots the ledger’s own automatic blocks hold, pending and verified, in general and reserved, with next when the first of them expires. The effects section reports an error if its records, tally or schema disagree, including damage beyond the first expiry. Each section carries its own error, so one damaged record does not hide the rest. Ingress drops checkpointed before this accounting change are not added retroactively to lifetime counters. On an upgraded host, retained outcome windows can therefore exceed the corresponding lifetime totals. A restart does not fill that historical gap. Once the ledger has started live, a preview ends as a dry run does: the outcome windows and the candidate’s state show it as dry_run, while the hourly comparison counts it as observe.
  • ingress says whether automatic responses are admitted and, while they are not, since when and how many Critical arrivals were refused.
  • owner says whether admission runs automatic blocks (executing), whether it has completed a turn since the daemon started (settled), and names why the ledger owner is not running (error), why its last turn failed while it runs (turn_error), the last fault met while retiring uncertain blocks (retirement_error, kept until none is left faulted), what keeps unknown outcomes from retiring while the ledger holds some (retirement_held_by: engine for an owner without the firewall engine, as with the firewall disabled or in observe mode, policy for a refused execution policy; their addresses stay held). It is omitted otherwise, including while a configured firewall engine has not started. Policy refusals and recovery update this cause with the execution hold, without waiting for the next ledger sample. Once the cause is gone, each block still retires only after it has expired and the firewall shows nothing of it. While the owner has the firewall engine, block_entries names the entries whose automatic IP blocks the live configuration lets admission run on this host (scan, challenge_timeout, incident, incident_spray, central); the comparison gate expects each to be seen. The owner also reports why the last clock reading or its live start failed (tick_error), whether the clock is degraded, where the ceiling came from (ceiling_source: default, configured or clamped), the legacy hourly count imported at the first start (import, which counts at least until an hour after at, or names why the count could not be read at the first start or when execution began; a committed read error survives startup retries), the last inventory read and why responses naming a damaged record were discarded (damage_error). The first completed turn publishes settled: true with any earlier turn_error cleared. Later failed turns and policy reloads do not reset settled; a daemon restart does. preview_replacements, preview_replacements_last_hour, preview_rotations and preview_rotations_last_hour remain in the API for compatibility and read zero in this build. Live blocks execute and dry-run blocks forecast; neither increments these preview counters.
  • An owner that runs on the firewall engine, with the firewall on and outside observe mode, adds execution_held with execution_held_by (policy for a refused execution policy, firewall for the firewall engine), a verdict object for the panel verdict callback, whose counters count this process and restart at zero, a dry_run object for its dry-run forecast and a set object for the temporary block set outside a dry run, both described below, with set_error when the last turn could not read the set. verdict.enabled is true while the owner itself asks the panel: with the callback configured, during a dry-run forecast and while it runs automatic blocks itself (executing). This staging route does not advertise admission.dry_run_verdict.v1; that capability requires the complete admission-gates contract and activation evidence.

owner.set combines the non-admission occupants from the last scheduling turn with the current ledger holds, divided as automatic admission divides it: limit, unlimited, capacity, unclaimed, imported and drain_seconds as in the forecast’s occupancy below, and general and reserved with each partition’s size, the legacy and admission blocks it holds (used) and its free slots. A schedule serves block work, previewed or run, into free slots of the partition its lane occupies, or into the slot of a lower-priority automatic block it may replace, including a legacy automatic block that recorded its origin; other block work waits as set_full and is checked again when a held slot expires or after a minute. The object is absent when the last scheduling turn found no ready block work, in dry run and when the set could not be read. A maintenance-only turn keeps the last non-admission snapshot unless the owner enters dry run; status still refreshes the ledger holds. Entering dry run, including through a reload, clears both set and set_error before the next clock reading or forecast is attempted. Engine admission counts are not added again when the ledger holds their slots. Any excess counts as unclaimed and makes drain_seconds unknown (-1), since the engine’s drain estimate excludes admission rows. This view is not a fresh kernel inventory.

owner.dry_run is a capacity forecast, not a record of blocks. active is true while the owner forecasts instead of blocking. session_id, since and reset_reason (startup, mode_change or model_error) name the forecast session and are null while none has started, including after a failed start; a session starts at startup, on entry into dry run or after its model failed, and leaving dry run keeps the last session’s identity. modelled_kinds and prediction_scope say what the model covers: block_ip against the hourly ceiling and the temporary block capacity. occupancy gives the real temporary occupancy (actual, addresses plus two elements per timed subnet), the forecast addresses the real sets do not hold (shadow_only), the listed legacy automatic blocks the forecast replaced (replaced), their sum minus replaced (predicted), the limit, whether the set is unlimited and whether retained forecast state fills its modelling bound (limited); it is null while no snapshot is available. actual and imported count at least the listed imports, matching the partition counts. A replaced import is subtracted only while listed, until its own expiry, even if its replacing forecast block expires or is replaced first. Unlisted imports count again; a renewal with a new name is a new import. capacity is the finite capacity automatic admission is modelled within: a positive limit, or 10000 for an unlimited set. Until validation rejects negative limits, they use the same fallback as zero and retain their configured value in limit. unclaimed counts the real timed entries it never evicts (operator blocks, blocks of unknown origin, two per timed subnet and admission blocks no ledger record holds), imported the real verified stamped legacy automatic blocks, and drain_seconds estimates how long the last of them has left at the snapshot, or -1 when a kernel expiry is unavailable. Zero means no remaining known whole seconds. Treat -1 as unknown, not as expired; a combined horizon is unknown if any contributing horizon is unknown. New blocks, renewals and subnet wall-clock changes can extend that estimate; it is not an automatic removal deadline. general and reserved divide the slots the unclaimed entries leave, a fifth rounded up reserved for direct or corroborated work, each with its size, the real and forecast automatic blocks it holds (used; after a live period the slots the ledger’s records still hold count in their own partition, read each turn) and its free slots, also bounded by total remaining capacity. The drain is unknown while admission blocks have no ledger record. Real blocks are never forecast replacement victims and their scopes do not share a partition, so a forecast scope may be due more than live admission would give it. shares gives, for general and reserved, the scopes that share the partition (those holding its forecast blocks the real sets do not hold and those the last turn’s picks wait in) and the fewest slots each is due (share, the size divided among them; the remainder goes one each to the scopes after the session’s cursor), both zero without a scope. All share keys remain present, including zeros; without a snapshot, occupancy is null instead of an object with missing share keys. Existing occupants keep their partition when limits change. In a full set, a forecast block may replace a strictly lower-priority automatic block: a forecast block of a lower class or severity, or a listed legacy automatic block that recorded its origin, which the forecast counts as gone while still listed, until the import’s own expiry. A pick of a new attack may instead rotate out a forecast block of exactly its class and severity in the partition of its own lane once that block’s 30-minute hold has passed on both the admission clock and the session’s elapsed time (capacity_rotate). The set’s scopes share each partition: a pick at or over its share rotates only its own scope’s blocks, one below it only the scope that borrows most, and one without a share waits. A pick that waits while such a block holds its partition predicts equal_tier_wait, not set_full. A rotated or replaced forecast block’s address cannot rotate again until that block would have expired. An overfull set admits none, and entries counted in unclaimed are never replaced. Real coverage replaces forecast occupancy: a manual timed block reduces available capacity, an automatic block counts in general until ledger partitions are wired, and permanent coverage takes no temporary slot. ceiling is the forecast’s own copy of the hourly ceiling: limit, general_used, reserved_used, general_budget and reserved_budget, null while no forecast runs. picks counts the session’s predictions by name and last_hour the last sixty one-minute buckets of process monotonic time, an approximation that a wall-clock change cannot age; every prediction name is present, and both are zero while no forecast runs. examples_lost, summaries_lost and record_errors count this process’s losses and failed writes, examples_stale is true while a purge of earlier sessions’ examples is pending, and comparison_incomplete is true after any loss in this process; a restart alone does not set it, since each run’s hourly summaries carry its epoch. forecast_error names why forecasting last failed (engine_unavailable, clock_degraded, ledger_unavailable, snapshot_mismatch, session_id_unavailable, invalid_policy or model_error) until a turn succeeds, and last_error_at keeps its time until the next session starts. Absent values are null, never missing keys. The durable outcome windows in ledger keep counting dry-run endings across sessions and restarts.

The hourly ceiling follows auto_response.max_blocks_per_hour, capped at 20000. An omitted or zero value selects 2000 for the ledger and 50 for the shared scan-driven block budget. An explicit value is used by both, and csm doctor warns when it puts the ceiling below 2000. After editing the configuration, run systemctl reload csm; web UI settings saves apply at the next ledger tick. See automatic response for the scope of the current budget.

While admission previews or forecasts, existing blocking paths still decide every block. Admission rows say existing blocking is unaffected, and admission execution warns while execution is held. While the owner executes, the rows say admission decides automatic blocks, and the outages that stop automatic blocks, held execution included, fail. The dry-run rows of an owner that forecasts (admission dry run, admission dry-run capacity and admission dry-run examples) show the forecast’s session, real against predicted capacity and lost examples. The capacity row also shows the automatic slots of each partition and how long the entries automatic admission never evicts take to drain, the legacy automatic blocks the forecast counts as replaced, the forecast blocks of the last hour that would have replaced a lower-priority automatic block and how many scopes share each partition; a replacement is an admission, not a wait. A dry run alone is not a failure; a held forecast, model limits, waits the model predicts (equal_tier_wait among them), forecast blocks of the last hour that would have rotated out an equal-priority block, a set those entries fill, no free automatic slot, an unknown drain time and lost or stale examples warn. Recent rotation and wait warnings remain visible when the forecast has no current capacity snapshot; current occupancy and scope shares are then unavailable. These warnings clear when they leave the last-hour window or the forecast session ends. Outside a dry run, admission set shows the slots the last turn budgeted block work by. It warns about unavailable capacity or an unreadable set. The retained preview replacement and rotation counters remain zero in this build and do not describe live replacements or rotations. Rows warn when the ledger owner is not running, its clock reading is refused, an owner turn fails (admission turns), retiring an uncertain block fails (admission retirement), the ledger is damaged, admission has stopped or a Critical finding would not have received its response in the last hour; a partial-containment notice, whose block ran, does not count. They also show a degraded clock, a clamped ceiling, a ceiling of 1 (only the reserved lane runs), a legacy hourly count that could not be read, a failed inventory read and automatic blocks with an unproven outcome, which hold their addresses until they expire and the firewall shows nothing of them. Once owner.executing is set, rows say admission decides automatic blocks, and held execution, a stopped owner, a refused clock reading, a failing turn, a damaged ledger, stopped admission, discarded responses, a Critical gap in the last hour and a ledger the firewall could not read at startup fail. Until owner.settled is set, and for at most two minutes after the daemon starts, those rows warn and say so: the check that follows an upgrade runs before the first turn, and its failure would roll the upgrade back. A Critical gap recorded before the daemon started only warns, and says so: a flood of the hourly ceiling could otherwise fail every check after a restart for an hour. The admission execution fix names the configuration for a refused policy and the firewall otherwise.

admission.audit and admission.notices in queues report the delivery of admission records to the action log and of admission notices. admission.owner.audit_error names the last failed audit delivery, including an applied-block consumer’s state read or threat-store write. The batch stays pending and later rows can wait behind it; queues["admission.audit"] reports no-progress stalls. Successful delivery clears the error. Keep the database and pending rows; repair the reported storage failure before retrying.

A ledger that cannot start, or admission that stops, raises one auto_response_withheld alert through the same path as protection queue alerts, a Warning while admission previews or forecasts and Critical while it executes; it follows the notification channel settings but bypasses alerts.max_per_hour. Ledger notices (withheld responses, exhausted capacity, partial containment of an outbound destination and their summaries) raised while the owner previews or forecasts describe what the ledger would have done, so they are recorded in findings history as Warnings starting with “Admission preview:” and sent to no alert channel. Those raised while it executes go to the alert channels with their kind’s severity and no prefix. The ledger paces them per notice key and summary. A preview is acknowledged only after its history write succeeds. Delivery errors leave notices pending for retry: the next two cycles retry at once, then each attempt waits twice as long as the one before, up to an hour. Ledger notices and the stopped-admission alert retry independently, so a failing path does not defer the other; a successful delivery resets only its path’s wait.

Protection queue health

status.queue_health.v1 advertises the queues map on status responses. The same measurements appear under snapshot.queues in csm status --json and as named checks in csm doctor.

findings.ingest, fanotify.analyzer, fanotify.staged_packages, fanotify.dropper, fanotify.dropper_findings and spool.scanner report waiting work, capacity, running work, cumulative losses, losses during the last minute, the oldest waiting item’s age and the oldest running item’s processing time. Waiting work includes producers blocked on admission. Ingest work remains running while the dispatcher holds or processes its batch, including startup. Ages pause while the startup hold is in place and resume from its release, so a long baseline scan is not reported as a stall; work lost during the hold still counts. Releasing a hold preserves any future eligibility time for deliberately deferred work. Loss totals include the undelivered tail of a batch canceled during shutdown; scan warnings intentionally excluded from alerts do not count as lost work. Recovered file and spool scanner panics count as lost scan work. The workers continue processing later events, but repeated failures still degrade health. fanotify.reconcile reports the recovery queue in directory tasks, with 1,024 waiting slots. Repeated drops in a directory retain its original queue age. A detached scan batch remains running while new drops queue separately, including new work for a directory that is already being scanned. Eviction, work older than the recovery scan window, unreadable directories or candidate files, interrupted batches and unfinished shutdown work count as failed recovery tasks. An incomplete task may still have scanned some files; each directory task counts at most once. Directories and files that no longer exist when recovery runs hold nothing left to scan and complete the task, which keeps bulk extraction and package restores out of the loss counters. The recovery window includes its cutoff; work completed exactly at that boundary does not count as expired. Staged package verification reserves capacity for its whole running batch. Its full-queue timer starts when admission fills the queue and continues while the verifier retains those slots, including between retries. Files awaiting another attempt retain their original waiting age; retrying does not reset lag. Shutdown counts files still awaiting verification after the analyzer workers have stopped. Package metadata I/O cannot block health polling for this queue. Dropper candidates and held findings each have 16,384 waiting slots. Their lag starts after the configured unlink TTL or the finding’s 45-second grace period, respectively; intentional waiting does not count as overdue work. Detached probes and emission batches remain visible as running work. Processing time starts when each batch leaves its waiting queue, independently of the timestamp used to decide which work is eligible. Retries and refreshed observations retain earlier eligibility, and exhausted probes, capacity refusals and unfinished shutdown work count as losses. mail.delivery reports the selected mail-log reader’s 64-slot delivery queue. Its running time includes parsing and delivery of resulting findings. Losses include oversized complete file records, unreadable journal entries, canceled admission, consumer failure and buffered records abandoned on shutdown. Counters survive reader replacement and changes between file and journal sources. They count records already read, including complete records abandoned in file read-ahead, not unread source history or partial file records that have not reached a newline.

mail.file_source reports sampled untransferred bytes after the first file attachment, with depth_unit: bytes and capacity_unavailable: true. This includes disk backlog, buffered read-ahead and raw partial-line bytes, even when the reader retains only a bounded prefix of an oversized line. Transfer to mail.delivery removes the source bytes before output admission can block. These byte and record measurements are separate stages and must not be added.

A reader-owned sampler checks the current descriptor every two seconds, so appends remain visible while delivery is blocked. Health reads memory only. lag_basis: consumer_progress measures time without consumption while unread work remains. Sampling or new arrivals do not reset this clock. A partial line at EOF waits for more input and does not report a stalled consumer. Reader and sampler operations also report processing_lag after one minute without progress, including blocked reads, metadata calls and cleanup.

File I/O failures report source_io. A successful read cannot clear a failed cursor check; each operation must recover. Failed metadata sampling makes depth unavailable until a successful sample. Rotation and observed truncation retire the old generation, and late samples cannot overwrite its replacement. The initial attachment still starts at EOF; replacements start at the beginning. Copytruncate detection retains its existing limit: truncation followed by growth past the old descriptor offset between checks may be indistinguishable from an append.

Complete records already held in read-ahead count once in delivery loss when discarded. Unread disk data and unterminated fragments have no measured record count; generation changes, source failures and shutdown preserve dropped_lower_bound in the source row. A working file or journal replacement clears the retired source’s current error while retaining that history. Source path disappearance still follows the watcher’s existing grace period.

mail.journal_source reports the journal reader after its first successful attachment. The cursor exposes no exact unread-record count or queue capacity, so depth_unavailable and capacity_unavailable are always set, and lag_basis: unavailable marks the missing backlog age rather than reporting a waiting time of zero. The row measures the current operation instead. A selected entry remains in flight until delivery acquires it; known unreadable or abandoned selected entries count once in mail.delivery. The two stages must not be added together.

Journal progress follows cursor advancement, entry reads, bounded idle waits, output admission and close. One minute without operation progress reports processing_lag, including a stuck cursor with no known selected entry. Cursor, entry, wait and close failures report source_io; known abnormal exits remain visible through actual cleanup. An unknown cursor outcome or unread shutdown sets dropped_lower_bound without inventing a record count. Successful reads restore current health; historical uncertainty survives reader replacement. Successful attachment of a file source clears the retired journal’s current error. Failed attachment leaves it visible. Health reads memory only and does not call the journal or change its tail positioning, retry or delivery policy.

When their BPF backends are active, bpf.af_alg.output, bpf.connection.output, bpf.execution.output and bpf.sensitive_files.output report the 256-slot userspace delivery queues. Their losses include decoding failures, admission refusals, consumer panics and buffered output left after the reader stops. A received event remains running until evaluation and delivery to the finding queue finish, including events intentionally filtered during evaluation. Kernel ring occupancy and reservation failures are separate from these userspace measurements. bpf.placement.output, bpf.placement.kernel and bpf.placement.unresolved report whichever placement backend runs: placements waiting for a worker, placements the kernel lost, and placements whose path could not be resolved. The legacy backend adds bpf.placement.create_settle for new files waiting for their own close-write. When this queue fills, its oldest entry is sent for early analysis and counted as a drop from the settle queue. Pending entries discarded at shutdown also count as drops. A full output queue counts the placements it refuses as drops and hands them to overflow recovery, which rescans the directory a file landed in and walks a moved-in directory. placement.dir_walk reports directories moved into a watched tree that wait for their walk, counted in directories. Evicted directories and walks cut short count as lost and raise placed_dir_incomplete_realtime. bpf.execution.docroot reports up to 1,024 non-root process starts waiting for a check of a program in a document root. One worker resolves the running image before reading and scanning it. All non-root starts enter this queue because a launch path outside a document root can be an alias into one. Starts refused by a full queue, starts left waiting at shutdown, and findings suppressed during shutdown count as lost. The scheduled deep scan still reads programs in its scope, and the periodic process check judges running programs. bpf.connection.verdict reports the advisory annotation pool’s 256 waiting slots and up to four running callbacks. Repeated findings for a pending destination, reason and severity share one request and retain its original age. Capacity refusal, callback failure and abandoned shutdown work count as lost annotations, separately from lost findings. Callback errors release the pending key and allow a later finding to retry; a successful retry preserves earlier loss totals. Shutdown closes admission, waits for running callbacks and counts the queued requests left behind. Cached answers remain available without new work. Findings continue immediately when an annotation is unavailable. processctx.enrichment reports 1,024 waiting requests and up to two running process-context workers. It appears only after a BPF consumer initializes the shared pool; reading health does not start workers. Overflow replaces the oldest queued request and preserves the waiting age of the remaining requests. Running time includes the process read, latency observer, account resolution and cache write. Read errors and interrupted processing count as lost enrichment; vanished processes and stale or unverified identities are completed filtering. The queue dropped metric counts refused, evicted and abandoned requests; queue health also includes failures after a worker receives the request. The daemon stops the pool after BPF producers have joined, lets running reads finish and counts buffered requests discarded at shutdown. Final loss evidence remains available. This row measures enrichment requests, not each individual deadline-based file read inside a request. processctx.proc_reads reports the 64 shared slots for deadline-limited process file and symlink reads, including process-start captures on the BPF path. Waiting and running reads share this capacity. A slot remains occupied until both the underlying read and its caller have finished; an undelivered result still occupies its slot. A timeout counts the lost result immediately and keeps a blocked syscall visible as running work until it returns. Timeout and a later read failure count as one loss. Refusals at capacity and read failures count as losses; missing process files are expected churn. Synchronous reads without a deadline consume no slots. The initial process-directory check and the cached boot-time read are synchronous and are not measured by this row. smtp_rdns.resolves reports the 64 reverse-DNS lookup slots used by direct SMTP egress detection. A slot remains occupied until its resolver and caller finish. The one-second caller deadline also bounds healthy processing age; timing out counts a lost result once while keeping a resolver still running visible. Capacity refusals and resolver failures count as losses, while NXDOMAIN and successful empty responses are normal negative results. Cache hits perform no queued work. The bounded result cache is retained data, not waiting lookups. Status can initialize the empty cache but never performs DNS or waits for its cache lock. Synchronous lookups without a deadline use no slots or queue row. email_password.mailboxes reports waiting mailboxes and the five concurrent audits per scan, retaining each audit through finding collection and cache writes. Concurrent scans have no fixed combined waiting capacity. A busy pool uses each audit’s five-minute budget or shorter scan deadline; an idle slot with no dispatch progress for one minute reports backlog lag. Admission and post-audit work have their own one-minute budgets. Cancellation removes waiting demand without adding losses, while actual audits remain visible until they return. Expired work, failed verification, cache write failures and abnormal exits count once per mailbox. Unsupported, malformed and over-budget hashes remain normal incomplete-audit outcomes. Health retains loss counts after the batch drains and reads only memory. Deadline losses are recorded where an audit actually stops unfinished. A deadline arriving after a successful cache write does not turn that mailbox into a loss, and context evaluation during drain never holds the health lock. email_password.hashes reports the three shared password-verification slots. Each slot remains occupied until its KDF and caller have both finished, including after scan cancellation. email_password.waiting reports callers awaiting a slot; it sets capacity_unavailable because concurrent scans have no fixed global waiting limit. Both rows use the password audit’s five-minute check budget for lag. The occupied pool also reports sustained full capacity. A deadline while waiting counts one admission loss; a deadline after admission counts one lost verification result. A later KDF error or abnormal exit cannot count it twice. Explicit cancellation withdraws demand without loss; actual verification errors still count. Successful matches and nonmatches are normal results. Rejected input and already canceled callers start no queued work. These rows contain no password, hash, mailbox or account data, and status never runs a verification. The outer mailbox scan’s discovery, network enrichment and persistence are separate work from these hash slots. checks.executions reports dispatched check functions across host and account scans. An execution remains present until both its function and caller finish, including while its result awaits consumption or its function outlives a timeout. Lag is evaluated against each call’s original deadline, including a shorter parent deadline; a delayed function start does not reset it. Timeouts, panics and abandoned results count once per execution. Explicit cancellation withdraws demand without counting a loss, but a later function failure still counts. This aggregate sets capacity_unavailable: separate scans have their own wrapper limits, and timed-out functions can outlive those slots. It does not measure checks awaiting dispatch, scan-job persistence or later automatic actions. Status reads memory without waiting for a check or accessing the state database. checks.plugin_inventory reports sites waiting for the five inventory workers per refresh, retaining each site through command execution, result collection and cache storage or failed-result cleanup. Concurrent refreshes have no fixed combined capacity. Inventory uses a four-minute budget for its two bounded commands, or the shorter check deadline; admission and result handling each have one minute. A full pool stays healthy within those budgets. A free slot with no dispatch progress for one minute reports backlog lag. Command, decoding and storage failures count once per site, including when cleanup also fails. A command that ran and returned output (on stdout or stderr) with an error, such as a tree wp-cli will not inventory, answered the check and counts no loss. Missing command output still counts as lost work, including when the command exited with an error. Cancellation adds no losses; deadline withdrawal counts unfinished sites. Buffered sites stay visible until the original workers stop consuming and the refresh joins them. Actual commands remain in flight until they return. Health reads memory only and retains loss evidence after recovery. Shared-refresh waiters remain owned by checks.executions; they do not create another set of site jobs. Optional domain lookup fallback and plugin metadata enrichment keep their existing behavior. checks.wordpress_core reports installations waiting for the five checksum workers per scan, retaining each through its command, integrity findings and verified-file caching. The unit is installations; concurrent scans have no fixed combined capacity. Command lag uses the two-minute command budget or a shorter parent deadline. Result and cache work use one minute without progress. A full finite batch stays healthy within those budgets; a free worker with no dispatch progress for one minute reports backlog lag. Returned operational failures and abandoned work count once per installation. A command killed by a signal counts as failed work while retaining any partial integrity findings. Recognized integrity results from a completed command, including deliberately filtered output, complete without a queue loss. So does a command that ran and refused the tree, such as a directory that is not a WordPress installation or one whose configuration fails to load. Missing command output still counts as lost work. Cancellation withdraws unfinished demand without loss, while deadline withdrawal counts unfinished installations. Commands ignoring cancellation remain in flight until they return. A deadline during caching cannot undo completed verification, and an ordinary cache read failure does not turn a verified site into lost work. Health reads only metadata, including while result or cache locks are occupied, and retains confirmed losses after recovery. Discovery is separate check work. auto_block.waiting reports scan, direct-block, firewall-flush and startup observation calls waiting for shared state, with no fixed waiting capacity. auto_block.active reports the single state owner through firewall operations, state writes and cleanup. lag_basis: operation_progress times the current operation within a batch; advancing batches do not degrade solely because their total duration exceeds a minute. One minute without progress degrades the active row and any waiting callers. A free state slot with no admission for one minute also reports lag. Returned direct-block or flush errors, failed state reads and writes, and abnormal exits count once per call; protected-address refusals do not. Known write failures are recorded before readback and diagnostic output. Known errors remain visible during later cleanup, and the common loss threshold and recovery policy apply. These rows count state-lock callers, independently of persisted per-IP retry records. Health snapshots use memory only and cannot wait for the state lock or I/O.

auto_block.pending reports durable retry records, including records loaded at startup when automatic blocking is disabled. Its capacity is the retry admission limit of 1,000 records. Records selected for a cycle remain in flight until their state-file outcome is known; newly requeued records also remain in flight until persistence finishes. auto_block.candidates reports distinct IPs admitted to the current cycle, with no fixed capacity. Candidate and record counts describe different stages and must not be added together. A candidate remains visible through its firewall callback, subsequent bookkeeping and durable requeue.

Pending age uses its original queue timestamp, or first observation when that timestamp is absent. An eligible record receives a timestamp on its first requeue; records without check identity are withdrawn under the current block policy. Refreshing the reason, check or severity does not reset the original queue age. Normal quota waits stay healthy within the existing two-hour retry lifetime; older waiting records report backlog_lag. Active record and candidate work use one minute without operation progress, so advancing batches can run longer without a false warning. These measurements add no retry scheduler and do not change the hourly quota, expiry or overflow policy.

An unsuccessful attempt whose retry survives reports retry_failed without a loss. Successful blocks, dry runs and expected refusals remain completed even if later bookkeeping fails. Withdrawal under the current check policy or login-blocking setting is an expected refusal and adds no loss. Persisted record identities include check and severity, so a refused record cannot acknowledge a different eligible retry after a failed write. Confirmed removal of expired, invalid or overflowed records counts as pending loss; a fresh candidate that neither completes nor survives on disk counts as candidate loss. Existing duplicate coalescence adds no loss while a retry survives. The common loss threshold and recovery policy apply.

State read or write failures report state_io. Failed writes are read back because an error after rename can leave the new state in place. If that read also fails, depth_unavailable and dropped_lower_bound expose the uncertainty. A later successful read restores measured depth; lifetime loss totals remain lower bounds when earlier outcomes could not be established. New work with known outcomes still contributes exact losses. Completed candidate history is released after settlement, and health snapshots never read files or wait for firewall callbacks.

auto_block.cleanup reports distinct IPs awaiting bookkeeping cleanup after a successful firewall flush. It observes saved cleanup retries at startup and admits the flushed engine entries before reading the tracker. Cleanup also includes tracked blocks, with duplicate IPs counted once. Work remains in flight through store removal, threat-record cleanup and the final state-file outcome. This row has no fixed capacity and is independent of the block-candidate stages.

Cleanup waiting age starts at first observation with lag_basis: deferred_checkpoint. Age alone does not degrade health: cleanup retries run on the next explicit flush, without a background retry deadline. One minute without active operation progress reports processing_lag. Failed cleanup whose retry survives reports retry_failed; an old tracker block can retain a retry even when saving its cleanup marker failed. Completed cleanup stays acknowledged across failed saves, while a newly blocked IP creates fresh cleanup demand. Recovery first establishes the known block baseline. Cleanup of a later block has an exact outcome even when older cleanup history remains uncertain.

Cleanup state and snapshot failures report state_io. An unreadable tracker sets depth_unavailable and dropped_lower_bound; speculative waiting records are not reported as measured depth. The last bounded batch retains its identity for later read recovery. A subsequent unreadable flush replaces that history with its own batch. A readable state restores measured depth and counts confirmed unfinished work that no longer has a retry source. An incomplete pre-flush engine snapshot marks lifetime losses as a lower bound without inventing a missing count. Health reads memory only. These measurements preserve the existing flush policy, returned errors and cleanup retry behavior.

attackdb.events reports events awaiting persistence, including historical imports. The buffer has no fixed capacity. Waiting age starts at admission, independently of an event’s timestamp. A detached batch remains in flight through writes, close and error logging; newly arriving events stay in the waiting count. Processing age uses lag_basis: operation_progress and resets when a write returns, so a progressing batch does not appear stalled solely because of its total duration. Waiting age or absent write progress of one minute degrades health. Completed JSONL records accepted by the file writer and successful database writes count as persisted. Buffered data alone does not. Confirmed unwritten events count as losses, including interrupted work left buffered or unencoded, and returned encoding failures. These losses are visible before cleanup; close errors or abnormal I/O exits preserve uncertainty with dropped_lower_bound and report persistence_uncertain for one minute, ahead of a backlog or a stalled write, as the record queue already does. The common loss threshold and recovery policy apply to confirmed losses. These measurements preserve the existing write, retention and shutdown policy; they do not add retries or promise storage durability beyond the writer’s result. Memory-only databases have no persistence backlog. Health reads queue memory, independently of database state locks and I/O.

attackdb.records reports distinct IP records awaiting a saved update or deletion. Repeated changes to one IP coalesce before the snapshot; a mutation during an active write remains separate pending work. A successful deletion can also satisfy a repeated deletion. Loaded records needing normalization and expired records needing removal enter the same queue. Retained scoring records are not counted as pending persistence. There is no fixed capacity.

Waiting age starts at the first pending change. The active snapshot stays in flight through writes, error logging and retry bookkeeping. Processing age uses lag_basis: operation_progress and resets at each returned store write or delete, at the commit of their batch, or at the complete flat-file write result. The store commits one flush as one batch, so a failed commit retries every record and deletion in it. A refusal affects only that operation; a successful save cannot clear a failed deletion for the same address, or vice versa. A returned commit refreshes processing age even if every operation was refused. One minute without progress or with waiting work degrades health. Returned failures report retry_failed while the retry remains queued, preserving its original age without counting it as lost. Successful retries clear that condition. A failed shutdown flush retains the in-memory retry; the stopped background saver does not schedule another attempt.

An interrupted operation counts confirmed abandoned demand only when no pending update or deletion survives. Unreturned write outcomes report persistence_uncertain for one minute and retain dropped_lower_bound afterward. This includes a transaction interrupted before its callback starts or after all its operations were refused. Known losses remain counted through recovery. Health reads queue metadata only, without waiting for database state or storage locks. These measurements preserve the existing persistence, retry and shutdown behavior; they do not make retained in-memory retry state durable across process exit.

block_digest.records reports the actual buffer of watched-country block records, bounded to 5,000 with drop-oldest overflow. The buffer folds into the daily summary at each configured interval, before each summary send and at shutdown. Age starts when a record enters the buffer, independently of the block timestamp. Normal batching and a full buffer alone do not report a stall: waiting becomes overdue one minute after the configured interval. A detached fold remains in flight; one minute without progress reports processing_lag. The row uses lag_basis: operation_progress. Records arriving during a fold belong to the next one. Expected per-IP coalescing is successful completion, while an abandoned fold counts its discarded records as losses.

block_digest.email and block_digest.webhook report configured destinations in notifications, with capacity_unavailable. Each eligible destination owns one notification before delivery starts, including live alerts and the daily summary, which is sent even when empty. Default delivery follows current alert settings at admission, attempt and interrupted cleanup. Disabled destinations add no new waiting work or loss; destinations enabled during an earlier send are still handled. Explicit destination selection applies only to live alerts and keeps its error when that alert channel is disabled. Daily summaries use all enabled alert channels except phpanel. One minute waiting or active reports lag. A returned sink error counts one lost notification and stays in flight through error logging. A daily summary sink, or the summary rendering, that panics fails the same way and is logged with the panic, so it cannot stop the daemon. If an operation exits without returning, its attempted delivery reports delivery_uncertain for one minute and retains dropped_lower_bound; a remaining destination that was never attempted counts one confirmed loss. Known losses use the common warning threshold and survive recovery in lifetime totals.

Live delivery remains best effort. Daily summaries save their window before delivery and retry failed destinations; successful destinations are saved separately. A failed destination retries after one minute, doubling up to one hour, and counts one lost notification for that summary however often it is retried. Between attempts that destination keeps one waiting notification, so its row reports backlog_lag while the outage lasts; switching that destination off releases it within a minute. When the next summary is due, a still unfinished one is dropped, logged once and counted once, and the new one goes to every destination. A crash between remote acceptance and saving success can repeat a delivery. Records retained after the collector stops report consumer_stopped. Health reads metadata independently of collector state locks, country lookups and delivery callbacks. The rows are always present: every daemon runs the collector for the daily summary, and without alerts.block_digest.enabled the records buffer stays empty. The summary and customer block payloads are described under Summary and customer block webhooks.

state.pending reports findings parked for the next startup, bounded to the newest 10,000 findings. The store observes existing parked work when opened. Depth is the last confirmed file contents; in-flight findings include incoming appends and cleared batches still in replay. The bound applies to the stored batch, not concurrent callers or an already detached replay. Overflow and new findings that fail to reach storage count as losses. Duplicate occurrences remain separate findings.

Waiting age starts at admission or startup observation, independently of the finding timestamp. Surviving findings keep their age through later appends; evicted findings no longer determine it. Waiting uses lag_basis: deferred_checkpoint: a parked or full batch awaiting restart does not itself report a stall. state.pending_operations measures callers waiting for the state lock and active persistence or replay, in operations with no fixed bound. One minute waiting or without operation progress reports lag. Actual read, write and clear results advance progress; replay stays active through dispatch.

Read, write and clear errors report state_io. Failed mutations are read back: a returned error after replacement does not imply the new findings were lost. Readback compares the recovered JSON payload, including internal subnet and spray-target data and its normal repair of invalid UTF-8, so repaired log text does not invent uncertainty or hide overflow. Unreadable outcomes set depth_unavailable and dropped_lower_bound. A later read restores measured depth, while lifetime losses remain lower bounds. Known encoding failures and overflow are counted even when other outcomes are unknown. Indistinguishable retained payloads keep the earlier age after a failed write. An interrupted write or clear marks disk state unknown before releasing the state lock. Interrupted replay retains measured disk depth but cannot claim an exact loss for a partially dispatched batch; uncertainty reports persistence_uncertain for one minute. Confirmed losses use the common warning threshold and remain in lifetime totals after recovery.

Parked findings add optional storage-only keys to the public finding fields so subnet response and credential spray correlation keep their inputs at restart. Subnets are in the public cidrs field and also keep their storage-only copy, so a daemon rolled back after a restart still replays them. Older parked records still replay, and older daemons ignore the added keys. Process-local delivery markers are cleared on read, so stored findings receive a fresh evaluation.

Append order, returned errors and clear-before-replay policy are unchanged. These observations add no retry or extra replay. Health snapshots read metadata only and do not wait for state locks, files or dispatch callbacks.

incident.persist.waiting reports immutable incident snapshots waiting for the ordered writer, with no fixed waiting capacity. incident.persist.active reports the single occupied writer. A writer or free-slot admission stalled for one minute reports lag. Failed writes and abnormal callback exits count once; abandoned bulk snapshots count as waiting losses and release their ordering slots for later writes. Callbacks remain owned through cleanup and error logging. Store failures retain in-memory transitions and the existing warning log. incident.persist.deferred reports coalesced bookkeeping waiting for a later mutation or explicit flush, including shutdown. Its oldest age uses lag_basis: deferred_checkpoint; age alone does not degrade health because there is no periodic flush deadline. Full snapshots supersede earlier bookkeeping; restoration and retention discard the affected markers. Memory-only correlators have no persistence work. All three rows read memory independently of state locks and database I/O. The common loss threshold and recovery policy apply to writes.

checks.file_index.waiting reports live scans waiting for the shared baseline slot, with no fixed waiting capacity. Each wait keeps its shorter parent deadline or the file-index check budget; a free slot with no admission for one minute also reports backlog lag. checks.file_index.active reports the single occupied slot. Walking and file analysis use the check’s original execution deadline (normally 15 minutes) or the shorter parent deadline. Setup, persistence and cleanup each have a separate one-minute budget. A healthy long scan alone does not report a full queue. Actual filesystem work remains visible after cancellation until it returns. Deadline withdrawal, incomplete walks, unreadable PHP content, failed executable metadata or state reads and writes, and abnormal exits count once per live scan. Executable entries disappearing during enumeration and explicit cancellation alone add no loss. The common three-loss warning threshold applies, and recovery retains total losses. A successful late baseline commit adds no loss. Findings and shrink protection keep their existing behavior. Force-file-index audits bypass this stateful slot and remain owned by the check execution row. Snapshots read memory only. checks.reputation_queries publishes accepted lookups immediately after quota reservation, including while refused lookups receive fallback scoring. It follows the accepted work through HTTP, response cleanup, buffered results, supplemental scoring and cache or quota-backoff storage. Each scan has at most five requests; concurrent scans have no fixed combined capacity. HTTP uses the client’s timeout, while cleanup, local result handling and persistence have separate one-minute budgets. Supplemental scoring uses the combined timeout of its enabled sources or the shorter parent deadline. Buffered results follow their own active consumer’s deadline; another scan cannot hide their delay. Query failures, failed storage and abnormal exits count once per result. Quota responses and refusal before dispatch remain expected outcomes with the existing quota health warning. Parent cancellation does not cancel the existing HTTP requests; they remain visible until response handling and storage finish. Successful late results add no loss. Health reads memory only and retains losses after recovery. Local feed matches, cache hits and serial pre-query discovery do not create query jobs. A failed cache write retains the findings already produced. checks.dispatch reports pending checks and occupied runner wrappers across host and account scan batches. Concurrent batches have no fixed global waiting limit, so capacity is unavailable. Lag uses consumer_progress within each batch: pending work degrades after one minute without progress when that batch has a free worker slot. A busy pool may keep working within each check’s own deadline. Setup and result handling have a separate one-minute budget; they cannot borrow a heavy check’s longer deadline. A wrapper panic or abnormal exit counts a loss, as does a parent deadline before a check can start. Explicit cancellation withdraws queued demand without loss. Execution failures belong to checks.executions; dispatch tracks the surrounding scheduling operation. Reading status never takes a scan, context or database lock. scans.jobs reports eight waiting full-scan jobs and one worker. Work remains visible through enumeration, scanning, remediation, persistence and cleanup. Its consumer_progress lag follows that worker and its own check batches: healthy check deadlines allow long scans to proceed, while an overdue child cannot be hidden by another child’s progress. Enumeration, result handling, individual file actions and database operations each have a one-minute progress budget. Thirty seconds at full waiting capacity also degrades health. scans.admission separately reports callers waiting for admission and writing their initial job record, with a one-minute lag budget and unavailable capacity. Status reads only memory; operator polling does not advance the worker’s clock. Queue refusal, failed job operations and abandoned work count once per job. Configured finding-history truncation, explicit cancellation and successful shutdown draining do not count as loss. A terminated worker refuses new jobs. At startup, both queued and running records from the previous process become errors with reason daemon_restarted; their lost requests count in job health. email_av.scans reports antivirus engine work through execution and both result handoffs. Timed-out engines remain in flight until they return; buffered results remain queued until the message scan consumes them. Execution lag uses the original per-part deadline, while result waiting and processing each have a one-minute budget. Moving a result between buffers preserves its waiting age. Concurrent messages and engines outliving timeouts have no fixed global limit, so capacity is unavailable. Timeouts, errors and abandoned work count once per engine scan; later failures cannot count the same scan twice. Detections and unavailable engines are normal outcomes, and mail verdict behavior is unchanged. Status reads only memory, and watcher restarts reuse the same engine health. php_taint.requests follows callers waiting for the worker lock, active requests and pipe operations that outlive their callers. Waiting, setup, reply handling and cleanup each have a one-minute lag budget. Active worker communication uses its configured timeout or the shorter caller deadline; a buffered reply cannot borrow a long worker timeout. The request stays in flight through reply decoding and cleanup, and until any outstanding pipe operation finishes. Capacity is unavailable because callers have no fixed global waiting limit. Worker failures, timeouts, breaker refusals and abnormal exits count once per request; known failures are recorded before cleanup. Oversize input, caller cancellation and refusal after an intentional stop do not add losses. Status reads memory without the worker lock, and shutdown retains the supervisor’s health evidence. Recovered analyzer panics also count as failed work when delivered in a valid worker reply. The report and worker reuse policy remain unchanged. yara.requests follows scans waiting for the single YARA scan worker, the active scan and the rules load of a freshly started worker. Capacity is unavailable because callers have no fixed global waiting limit. Worker failures and breaker refusals count once per request. central.actions reports 1,024 waiting central-intelligence actions and one running action. Backlog remains visible while the signed feed refreshes; processing time includes the action handler and its evidence delivery. Overflow, action failure and abandoned shutdown work count as losses. A protected-address refusal or absent firewall engine completes the queue task without claiming that a block happened. Challenge tasks measure delivery to the challenge list; they do not measure its later file or firewall writes. Shutdown cancels feed refreshes, waits for an already-running action and discards the remaining queue. Captured dispatch hooks refuse later work and preserve its loss count after shutdown. Logging does not reset loss totals. bot_verification.requests reports 256 waiting bot-identity requests and one running verification. Duplicate requests share their original waiting age. Running time includes DNS lookups and the cache write. Queue overflow, DNS timeouts or transient failures, failed cache or missing-PTR record writes and abandoned shutdown requests count as losses. Missing PTR records, unknown bot identities and definitive positive or negative answers remain expected outcomes. A source with a recorded missing PTR is not queued again until its one-hour suppression lapses; suppressed requests do not count as losses. For a day after the lookup, lapsed records prevent renewed pending grace without blocking DNS retries. Queue health does not turn a resolver failure into a spoof finding. Shutdown cancels DNS, waits for any active cache write and discards waiting work. Late submissions are refused, pending keys are released and loss totals remain available. abuse_reporting.ingress measures reports awaiting durable storage, with a capacity of 10,000 or the configured spool limit when smaller. Running time includes persistence to every configured target. Memory overflow, incomplete persistence and work abandoned by a worker failure count as losses; one source report counts once even when several targets fail. Outbound delivery can delay memory work, and that backlog remains visible. The queue stays open through the daemon’s final finding flush. Reporter shutdown then closes admission and persists every accepted report before closing the spool; a failed write does not discard unrelated waiting reports. Captured hooks refuse later reports. This row measures the memory queue, not reports already retained on disk for retry; normal shutdown does not count those durable reports as lost. abuse_reporting.spool measures durable reports per destination, with the configured spool capacity. Reports already being sent remain in flight through the database acknowledgment. Failed admission, discarded records and reports the collector refuses as invalid count as losses; a delivery retry, failed acknowledgment or normal shutdown retains the report and does not count it as lost. A failing destination pauses only its own reports for the rest of a pass. An evicted or refused record counts as lost only if no send was acknowledged during this process. An active send settles that count when it finishes; a failed retry cannot undo a prior acknowledgment. lag_basis: observed_age means waiting age starts when this process first sees the record. Existing records start at spool open; retries keep that age. Doctor labels this as observed_lag, since time spent waiting before restart is unknown. Waiting or running work degrades after two minutes, allowing for the normal one-minute delivery interval. The common full-queue and recent-loss thresholds also apply. spool_io names failed admission, read or acknowledgment operations; delivery_failed names a failed or panicking sender and stays set while any destination failed in the last pass or is waiting for its retry deadline. Throttling without progress remains visible here even between log warnings. These states clear when the affected operation recovers. Health reads remain independent of database writes and outbound requests. Reopening with a smaller cap preserves existing records until the next admission applies the configured overflow policy. phpanel.spool measures the durable panel webhook queue, capped at 100,000 records per state directory. In-flight work includes writes waiting to commit and deliveries awaiting database acknowledgment. Retried findings keep their original waiting age; a failed attempt is not a lost finding while its record remains durable. An overflowed record counts as lost only when no send was acknowledged during this process; an active send settles that count when it finishes. Malformed findings, and findings the panel refuses with HTTP 400, 413 or 422, count once when removed from delivery, and the next record is sent at once. Their bounded diagnostic archive is retained history, not pending work. A long run of refusals with nothing accepted between them looks like a panel refusing every request, so from then on refused findings stay queued and are retried as a delivery failure until the panel accepts one. This hold survives config reloads and daemon restarts. Only a 2xx response from the configured endpoint acknowledges a finding; redirects are not followed. Every other failure is retried in order with backoff. Waiting age uses the persisted enqueue timestamp after restart. Boundary records absent from the accounting rebuilt at open are adopted with the same timestamp, so retrying them does not reset their age. Missing, damaged or future timestamps are timed from queue open or adoption. A minute of waiting or processing degrades the row; delivery and database errors remain visible until the affected operation succeeds. Health reads use memory only, so a stalled database or collector cannot block status. Disabling delivery preserves the durable backlog and cumulative loss; enabling it resumes the stored work. Stopped queue instances refuse late admissions. actionlog.writes measures the 64 process-wide action-log write slots. A sink write that outlives the caller’s 250ms wait budget stays in flight until the sink and any panic reporting finish; a batch of actions serialising behind one file lock is normal, and only a minute without the write returning degrades the row. A caller deadline after admission does not count as loss, since the sink may still record the action. Refused admission, sink errors and panics count as lost records, once per record. Changing or disabling the sink preserves outstanding work and cumulative loss. Health reads do not wait for the sink. Normal writes still complete before the caller returns; saturated or stalled recording keeps the existing caller budget. events.deliveries aggregates live event-stream subscribers in one row without client identities. Capacity sums their buffers (64 findings per daemon stream); depth counts waiting deliveries and in-flight work includes encoding, writing and flushing. One full subscriber can degrade this row even while others drain. The common one-minute lag, 30-second fullness and recent-loss thresholds apply. Overflow, encoding errors and failed streams count as losses; a failed stream also counts its abandoned buffered events. Normal request cancellation and server shutdown withdraw pending demand without adding losses. Cumulative loss survives subscriber removal, and an outstanding write remains visible until it returns. Closing the bus preserves buffered work for consumers still draining it. HTTP writes retain their three-second deadline; successful delivery here means the write and flush returned, not that the remote application acknowledged it. Each active BPF backend also exposes a .kernel row. depth_unit: bytes labels ring occupancy and capacity. lag_basis: consumer_progress means lag_seconds measures time without observed consumption while data remains, starting at the first sample that sees pending data. It is not an event age. One minute without progress degrades the row; recently observed reservation failures use the same loss threshold as userspace queues. Kernel loss counters are separate from decode failures and userspace admission loss. After a reader unmaps its ring, depth_unavailable: true and lag_basis: unavailable prevent zero fields from claiming an empty live ring. The last counter sample adds submitted records the reader never consumed. Submission accounting precedes publication, so a fast reader cannot consume an event before it has been counted. dropped_lower_bound: true marks this final shutdown total: kernel detachment can leave callbacks finishing after the sample. Doctor prints dropped>=... for that bound. A counter lookup failure or an incoherent occupancy reading marks the measurement unavailable and degrades the row as measurement_unavailable once it lasts half a minute, so one artefact of reading a live ring raises nothing; a failed final sample degrades at once and remains degraded. A stopped reader is reported instead of the measurement artefacts it causes. Invalid occupancy cannot inherit fullness or consumer stall alarms from an earlier sample; independently counted losses remain visible. The required kernel suite fills the shipped connection program’s ring with real non-root connect calls and checks reservation loss and retained output. fanotify.kernel and spool.kernel report pending notification records and use the same consumer-progress lag measurement. Their group capacity is not exposed by the kernel: capacity_unavailable: true marks it as unknown, and doctor prints depth=N/unknown records. The current system queue limit may differ from the limit captured when the watcher was created. Their loss totals are lower bounds: each overflow record proves at least one loss, and shutdown adds the records known to be unread before closing the descriptor. Events can still arrive between that sample and close. An unavailable pending-record measurement degrades the row once it lasts half a minute; the reading taken at close degrades at once and remains degraded. Records the kernel has already dropped are reported ahead of an unreadable depth. Closing a descriptor leaves known zero occupancy. fanotify.reader and spool.reader track batches after a kernel read, until all records have been dispatched or filtered. A stalled batch remains visible even when the kernel queue is empty. Reader losses count batches interrupted by consumer failure, separately from kernel-record losses. Spool replacements retain loss and running-batch evidence, while the new descriptor starts its own occupancy and progress measurements. Health reads, event reads and permission responses cannot use a descriptor after close. The required kernel suite verifies pending records, stalls, drain recovery and unread shutdown loss using real fanotify events.

forwarder.kernel and phprelay.kernel report inotify backlog in bytes, because records include variable-length filenames. Capacity is unknown and lag follows observed consumer progress. Overflow markers each prove at least one lost event. Closing with unread bytes adds one further known loss; the byte count does not reveal the number of discarded events. These totals use dropped_lower_bound: true. forwarder.reader and phprelay.reader track the running read batch, including synchronous callbacks. Failed callbacks count as interrupted batches. PHP relay replacements retain earlier losses with fresh occupancy measurements. Descriptor reads, watch changes, polling and close share one lifetime guard.

phprelay.index.persistence reports the message attribution writer’s 4,096 waiting slots. Writes remain running from channel receipt through the pending batch and its database transaction. Batches contain at most 256 writes, also during an explicit flush. Each flush covers the backlog present when the writer accepts it; concurrent arrivals cannot extend that flush indefinitely. Refused submissions, encoding failures and writes in a failed transaction count as losses. Failed writes are settled before emitting their error finding, so a blocked reporter cannot hide the loss. A failed transaction counts each of its writes once and does not prevent subsequent batches from committing. Shutdown closes admission and drains accepted writes; later submissions count as refused work. The existing persistence dropped metric counts refused submissions, while queue health also includes writes that fail after admission.

Some rows carry advisory. Their work is best effort: a client that stops reading its event stream, an unreachable panel asked for an optional annotation, and expired process context reads all lose detail around findings that are still detected, stored and delivered. An advisory row reports its own degradation with the same evidence, but leaves the host status and security posture unchanged, warns instead of failing csm doctor, and raises no notification.

php_shield.eval_sites is advisory grading work. It reports running ownership walks and completed results still held for callers. A timeout or refused lookup counts as a lost proof, while the finding stays High. A completed walk releases its single admission slot before publishing, so later events do not wait for that caller. Concurrent callers can hold completed results, making the aggregate capacity unavailable. Health reads perform no filesystem lookup.

Each degraded row names its condition: backlog_lag for the oldest waiting item past its budget, processing_lag for the oldest running item, queue_full for capacity held continuously, dropped_work for recent losses, consumer_stalled for a sampled queue whose consumer stopped advancing, reader_stopped for a released kernel descriptor, measurement_unavailable for a reading that stayed unavailable, and persistence_uncertain for a write whose outcome is unknown. The owner-specific conditions retry_failed, source_io, spool_io, state_io, delivery_failed, delivery_uncertain and consumer_stopped are described with their rows above.

Doctor names each age by what it measures: observed_lag for an age taken at observation, consumer_stall for consumer progress, operation_stall for the current operation, deferred_age for work parked until a restart, and lag=unavailable where no age exists.

A queue becomes degraded after three losses in a minute, thirty seconds continuously full, or a minute waiting or processing. These are operational alert budgets, not measured throughput guarantees. Health is computed directly from the counters, independently of finding delivery. The daemon records and dispatches protection_queue_degraded at most once per queue every five minutes while pressure remains, then one protection_queue_recovered event. The five-minute bound spans recoveries, so a queue that clears and degrades again inside the window stays degraded in status without a second event, and no recovery event follows a degradation the bound suppressed. These are CSM health events and do not feed account-compromise correlation or automatic response. Recovery preserves cumulative loss evidence; restarting a spool watcher also preserves it. Restarting the daemon resets the counters.

Inspect worker errors and CPU, memory and I/O pressure when a queue degrades. Reduce competing bulk work and confirm the queue drains and recent losses stop. This surface currently covers finding delivery, file and spool kernel readers and scanners, recovery scans, staged package verification, dropper processing, BPF queues, process context enrichment and deadline reads, mail-log delivery, forwarder and PHP relay notification queues, and PHP relay index persistence; other bounded queues remain in the roadmap.

Summary and customer block webhooks

The generic alert webhook gets two events of CSM’s own: the daily summary and the known-customer block alert. A phpanel webhook gets neither. Each is one JSON object: text holds the email body, for chat tools, and csm holds the data.

{
  "text": "[CSM] host.example.com - daily summary 2026-06-10\n...",
  "csm": {
    "event": "daily_summary",
    "host": "host.example.com",
    "version": "X.Y.Z",
    "summary": {
      "since": "2026-06-10T08:00:00Z",
      "due": "2026-06-11T08:00:00Z",
      "checks": {"wp_login_bruteforce": {"CRITICAL": 12}},
      "blocks": 3,
      "block_kinds": {"wp-bruteforce": 2, "netblock": 1},
      "muted": 4,
      "sources": [{"ip": "203.0.113.5", "count": 9, "country": "NL"}],
      "watched": {"total": 0, "by_country": {}, "by_category": {}}
    }
  }
}

daily_summary fields:

  • csm.event is daily_summary; csm.host and csm.version name the host and the CSM version.
  • summary.since is the start of the window and summary.due its scheduled send time, both RFC 3339.
  • summary.checks counts summary findings per check, then per severity (CRITICAL, HIGH, WARNING).
  • summary.blocks counts applied blocks; summary.block_kinds counts them by kind, such as wp-bruteforce, mail-bruteforce, netblock, permanent or other.
  • summary.muted counts summary findings of checks in alerts.email.disabled_checks.
  • summary.sources lists the 10 addresses with the most summary findings: ip, count, and country when GeoIP knows it.
  • summary.watched counts watched-country blocks: total, by_country and by_category. It stays empty without alerts.block_digest.enabled.
  • summary.customer_blocks lists the applied blocks that hit known customers, as customer block objects (below), at most 50; summary.customer_blocks_more counts further blocks. Both are left out when empty.
  • summary.would_block lists dry-run and observe-mode verdicts that would have blocked known customers, as customer block objects, at most 50; summary.would_block_more counts further verdicts. Both are left out when empty.

Each count map holds at most 512 keys; later keys count under other.

{
  "text": "[CSM] host.example.com - automatic block hit a known customer: 203.0.113.5\n...",
  "csm": {
    "event": "customer_block",
    "host": "host.example.com",
    "version": "X.Y.Z",
    "customer_blocks": [{
      "target": "203.0.113.5",
      "reason": "SMTP brute force from 203.0.113.5",
      "check": "smtp_bruteforce",
      "customers": [{"ip": "203.0.113.5", "kind": "cpanel", "account": "alice", "at": "2026-06-10T08:15:00Z"}]
    }]
  }
}

customer_block fields:

  • csm.event is customer_block; csm.host and csm.version as above.
  • csm.customer_blocks lists the blocks of the alert. Each has target, the blocked address or network; reason, the block reason or, for a notice without one, its message; check, the check that caused the block, left out when unknown; customers; and more, the covered customers not listed, left out when 0.
  • Each customers entry is one known customer, the most recent first: ip (an IPv6 customer as its /64), kind (cpanel, webmail, smtp, imap, pop or ftp), account (left out when the login named none) and at, the last successful login in RFC 3339.

The watched-country live alert, event block_live, keeps its own shape: there csm.blocks lists blocked addresses.

GeoIP

GET  /api/v1/geoip               IP geolocation (?ip=&detail=1)
POST /api/v1/geoip/batch         Batch GeoIP lookup (body: {"ips":["192.0.2.1"]}, maximum 500)

Threat Intelligence

GET  /api/v1/threat/stats        Attack stats, type breakdown, hourly trend
GET  /api/v1/threat/top-attackers Top attacking IPs with GeoIP (?limit=&spam_only=1)
GET  /api/v1/threat/ip           IP threat lookup (?ip=)
GET  /api/v1/threat/events       IP event history (?ip=&limit=)
GET  /api/v1/threat/whitelist    Whitelisted IPs
GET  /api/v1/threat/db-stats     Attack database statistics
POST /api/v1/threat/block-ip     Block IP for 24 hours
POST /api/v1/threat/block-ip-permanent Block IP with no expiry
POST /api/v1/threat/whitelist-ip       Permanent whitelist
POST /api/v1/threat/temp-whitelist-ip  Temporary whitelist (with expiry)
POST /api/v1/threat/clear-ip           Clear IP from attack database
POST /api/v1/threat/unwhitelist-ip     Remove from whitelist
POST /api/v1/threat/bulk-action        Bulk block (24h or permanent) / whitelist across many IPs

/api/v1/threat/stats includes mail_only_ips, the attack database records that hold only spam evidence, mail_only_new_24h, those first seen in the last 24 hours, and mail_evicted, those dropped to keep the spam evidence budget since the daemon started.

In /api/v1/threat/top-attackers, ip is an IPv6 /64 in CIDR form, such as 2001:db8:1:2::/64, for a record that holds the spam evidence of a network. /api/v1/threat/ip takes an address only. Its attack_record.spam_network names the /64 when the spam evidence shown was recorded for the network. Equivalent IPv6 spellings use the same address record and return the canonical address. The stronger spam evidence wins; ties use the network.

The 24 hour endpoint returns 409 Conflict when the address already has a permanent or longer firewall block. Unblock it explicitly before shortening its lifetime. Bulk actions use action: "block", "block_permanent", or "whitelist"; refused blocks are excluded from count and explained in warnings. Repeated canonical IPs count once. Permanence cannot be selected through an extra request field.

Bulk undo restores the original per-IP firewall deadlines. A later change to any target invalidates that undo action; it cannot restore dismissed evidence or replace the later decision.

Firewall

GET  /api/v1/firewall/status         Config, blocked/allowed counts
GET  /api/v1/firewall/allowed        Whitelisted IPs
GET  /api/v1/firewall/subnets        Blocked subnets
GET  /api/v1/firewall/audit          Firewall audit log
GET  /api/v1/firewall/check          Check if IP is blocked (?ip=); admin or unban scope
POST /api/v1/block-ip                Block an IP
POST /api/v1/unblock-ip              Unblock an IP
POST /api/v1/unblock-bulk            Bulk unblock IPs
POST /api/v1/firewall/allow-ip       Allow an IP
POST /api/v1/firewall/remove-allow   Remove IP from allow list
POST /api/v1/firewall/deny-subnet    Block subnet
POST /api/v1/firewall/remove-subnet  Remove subnet block
POST /api/v1/firewall/flush          Clear all blocks
POST /api/v1/firewall/unban          Unblock IP + flush cphulk; admin or unban scope
POST /api/v1/firewall/cphulk-clear   Flush cphulk bans only

The audit log reports each timestamp as an RFC 3339 instant in UTC and the block or allow lifetime as duration_seconds. Blocked addresses, subnets and allow rules carry expires_at, left out for a permanent entry.

ModSecurity

GET  /api/v1/modsec/stats              WAF statistics (read scope). Accepts ?window=1h|6h|24h, ?severity=warning|high|critical.
GET  /api/v1/modsec/blocks             Blocked requests log, aggregated per IP, with resolved source country (read scope). Accepts ?window=1h|6h|24h, ?severity=warning|high|critical.
GET  /api/v1/modsec/events             WAF event details with resolved source country (read scope). Accepts ?window=1h|6h|24h, ?severity=warning|high|critical.
GET  /api/v1/modsec/rules              Loaded rules list
POST /api/v1/modsec/rules/apply        Apply the set of disabled rules and reload
GET  /api/v1/modsec/rules/escalation   Rule IDs excluded from firewall escalation, sorted
POST /api/v1/modsec/rules/escalation   Exclude one rule from escalation or turn it back on

POST /api/v1/modsec/rules/escalation takes {"rule_id": 900112, "escalate": false}. The rule ID must be a CSM rule (900000-900999). escalate: false adds the exclusion and escalate: true removes it; other excluded rules are left as they are.

A failed rules reload reports rolled_back: true only when restoring the previous overrides succeeds. A rollback failure is reported in the response and audit log; inspect the overrides before trying another reload.

Rules & Suppressions

GET  /api/v1/rules/status        YAML/YARA rule counts, version
GET  /api/v1/rules/list          Rule files
GET    /api/v1/suppressions      Suppression rules
POST   /api/v1/rules/reload      Reload signature rules from disk
POST   /api/v1/suppressions      Add a suppression rule
DELETE /api/v1/suppressions      Delete a suppression rule by id

POST /api/v1/suppressions takes {"check", "path_pattern", "reason"}. The path pattern is a glob and must be valid. A rule that covers every path of a check, hiding all its findings and stopping their remediation, needs "all_paths": true and no path_pattern; an empty pattern without it returns 400. check must be a check name, not a pattern: letters, digits, _, ., : and -. A name that is neither a known check nor the check of a current finding is saved, and the response carries a warning saying the rule matches nothing yet.

Email

GET  /api/v1/email/stats         Email scanning statistics
GET  /api/v1/email/forwarders    Mail forwarder inventory with destination providers and local-copy flags (read scope)
POST /api/v1/email/forwarders/delete  Delete one destination of a forwarder on cPanel hosts through uapi, as the account that owns it; takes {"source", "destination"} as the inventory lists them; 404 when the inventory has no such pair, 500 when cPanel or command execution fails, 503 when unavailable (admin scope, CSRF)
GET  /api/v1/email/deferrals     Outbound deferral rollup by provider and sending IP with reason codes and last_seen, parsed from exim_mainlog; each provider has a sample error text; lines is the number of log lines read and window_start/window_end the times of the first and last of them; one read is reused for 60 s (read scope)
GET  /api/v1/email/queue-composition  Mail queue makeup: real vs null-sender bounce backscatter, frozen count, unreadable count, oldest age, top stuck recipients; 500 when exim could not list the queue, rather than an empty queue (read scope)
POST /api/v1/email/queue/flush-backscatter  Request removal of frozen null-sender messages from the exim queue on cPanel hosts; returns the count of targeted messages no longer queued, reports incomplete verification as 500, or returns 503 when unavailable (admin scope, CSRF)
GET  /api/v1/email/queue         One page of the exim queue on cPanel hosts, oldest first, each message with why it is stuck; page (default 1), limit (default 25, max 100), filter=all|frozen|backscatter, q (a substring of the sender or of one of its first 50 undelivered recipients) (admin scope)
GET  /api/v1/email/queue/{id}    One queued message with all undelivered recipients (up to 1,000), why it is stuck and the last 20 lines of its msglog; 404 when it is not queued (admin scope)
POST /api/v1/email/queue/{id}/{action}  retry, bounce (return to sender), delete or thaw one queued message; answers the outcome the queue shows afterwards (admin scope, CSRF)
GET  /api/v1/email/held          Forward copies held by the forward guard, each with its decoded subject and size (admin scope)
POST /api/v1/email/held/{id}/release   Re-inject a held forward copy to its external recipient (admin scope, CSRF)
DELETE /api/v1/email/held/{id}   Discard a held forward copy (admin scope, CSRF)
GET  /api/v1/email/checks        Email checks the Email page shows, each with its group kind ("" = never grouped) (read scope)
GET  /api/v1/email/groups        Server-grouped action rows (kind=compromised_account|spam_outbreak|auth_failure|queue_alert|malware) with from/to/limit (read scope)
GET  /api/v1/email/overview      Mail decision totals and 15-minute chart series for from/to (default the last 24 h), antispam mode, live queue and mail-related block counts, and Stalwart's filter verdicts: totals delivered, junk, filter_rejected, discarded and unmatched, series delivered, junk, filter_rejected and discarded, and filter_rejects_seen (read scope)
GET  /api/v1/email/rejects       Recent rejected mail (time, class, sender, recipient, source IP, detail), newest first, kept 7 days; class=content (spam and malware, default)|all|<class>[,<class>...], from/to (default the last 24 h), limit (default 50, max 200); totals has the permanent rejects of every class in the range (admin scope)
GET  /api/v1/email/senders       Messages each hosting account sent in from/to (default the last 24 h), busiest first, up to 100 rows, with total, unresolved and abuse_events, the outbound abuse events relay-abuse lists for the range, counted up to 5,000 like relay-abuse, with abuse_events_truncated true when that cap cut the count, and abuse_by_account, those events counted per account they name and per kind, before any list limit (admin scope)
GET  /api/v1/email/relay-abuse   Outbound PHP-mail abuse detections (spam outbreaks, high-volume scripts/accounts) with per-site script breakdown; from/to/limit; total counts up to 5,000 and total_truncated is true when that cap cut it, while truncated is also set when only limit cut the list (read scope)
GET  /api/v1/email/rspamd       rspamd status (up|down|off), antispam mode, version and rspamd's counters since it started (scanned, learned, actions, top 8 rules), read from its controller without a password and cached 60 s; available false with a reason when they cannot be read (read scope)
GET  /api/v1/email/quarantine    Quarantined email list, each with the size of its spooled body and its subject, decoded and cleaned as on held forward copies
GET  /api/v1/email/av/status     Email AV watcher status
GET  /api/v1/email/quarantine/{id}          One quarantined message
POST /api/v1/email/quarantine/{id}/release  Release a quarantined message (admin scope, CSRF)
DELETE /api/v1/email/quarantine/{id}        Delete a quarantined message (admin scope, CSRF)

For Stalwart, the overview’s totals.delivered, totals.junk, totals.filter_rejected, totals.discarded and totals.unmatched count its own filter verdicts in the selected range. unmatched counts messages whose verdict CSM could not tie to a sending address. Chart points use delivered, junk, filter_rejected and discarded, omitting these keys when zero. totals.rejected and the chart’s rejected key count rspamd decisions, not Stalwart filter rejects.

The top-level filter_rejects_seen is true when any retained bucket contains a Stalwart filter rejection or discard, even outside the selected range. False means no such event is retained, not that the filter rejected no mail. The Email page shows a dash and “none logged yet” for rejected mail until this flag is true. Older responses may omit the flag or verdict counts; the page treats the flag as false and missing counts as zero.

The mail.forwarders.delete.v1 capability advertises the forwarder delete endpoint. A 500 can follow a delete that partly ran, so read the inventory again before retrying. A domain’s default address (*@domain) is changed in cPanel.

The senders abuse count and relay abuse list apply the exact from and to bounds, including fractional seconds, even when requests share cached history. from is inclusive and to is exclusive. A cached history limit cannot let findings outside those bounds hide matching findings.

Email groups report handled: true only for auth failures whose complete, current history is answered by active blocks on every attacker address or covering subnet. Missing addresses, truncated or stale history, successful logins, and account sprays stay unhandled. Unreadable firewall state sets blocks_unavailable: true and leaves every group unhandled.

The overview’s counting_since begins when mail counting starts and survives restarts. Stops appear in gaps, ending when counting resumes even if loading saved counts needs a retry. Gap bounds round outward to whole seconds so short stops remain visible. uncounted_minutes rounds the total gap duration to the nearest minute, with a minimum of one for any positive duration.

The overview reads queue depth on every request. Queue detail is refreshed at most once per minute, even if the queue empties and refills. An empty queue discards its previous detail; new mail has detail_unavailable: true until the next listing. Failed listings can reuse detail for at most ten minutes.

The queue list and the overview share one queue listing, refreshed at most once per minute and after any queue action. total counts the messages that match filter and q; queued, frozen, backscatter (null-sender messages) and oldest_seconds describe the whole queue. listed_at is when that listing ran, so these counts can trail the overview’s live queue size. When no listing has succeeded in the last ten minutes the list answers unavailable: true with no items and no counts. A failed refresh cannot reuse an empty listing, and a positive queue count invalidates any earlier empty result. The next list request then lists the queue at once rather than waiting out the minute, once for each such refill. A message exim cannot read is listed with unreadable holding exim’s error and reason class unreadable; without its envelope it has no sender, recipients, size or frozen state, and only delete runs on it. An exim spool error without an immediately preceding message line makes the listing unavailable, including a missing-file error. Truncated entries and unrecognized output also fail instead of reporting an empty queue. The composition counts messages without envelopes only in total and unreadable, not in real or bounce. Backscatter flushing excludes every unreadable message and validates the whole listing before and after removal; a targeted message that becomes unreadable still counts as queued. Quoted recipient local parts remain intact, including spaces. Each message’s reason (class, text, raw) comes from its msglog tail; a partial first line is discarded. Up to 100 reasons are cached for a minute. The current page takes priority when older entries must be evicted. A message thawed since it froze shows retry_wait until its next delivery attempt.

Message reads and actions run exim as a systemd transient unit and never inside the daemon’s sandbox: without systemd-run the message route and the actions answer 503 and exim does not run. Each action first checks that the message is still queued; a missing-file reply must name the requested message. When it is not queued, the answer is 409 with outcome: "gone". Nothing ran, unless the message left during the action. retry answers attempt_started as soon as the delivery attempt has started. bounce and delete answer bounced and removed when the message left the queue and exim reported no error. When exim reported an error and the message left anyway, as when exim -Mrm finds it locked by a delivery that then completes, the answer is 409 with outcome: "gone". An unreadable message answers removed despite an error exit only when exim confirms its removal and the message is no longer queued. A failed or interrupted delete without that confirmation answers gone when another caller takes the message. thaw answers thawed when the queue shows the change, even if exim reported an error. Otherwise the answer is unchanged with an error. A thaw on a message that is not frozen answers unchanged without running exim -Mt. Every attempt is written to the UI audit log as email_queue_<action> with the message ID, the outcome and any error exim reported.

Held forward release requires a recorded sender and recipient, each a single mailbox without commas, whitespace or a leading dash. An explicitly empty sender is allowed for bounces. Ambiguous or missing envelope metadata causes a release error and leaves the message held without invoking sendmail. Release runs sendmail as a systemd transient unit with the message on its stdin, never inside the daemon’s sandbox: without systemd-run the release fails and the message stays held. The unit uses KillMode=process, so the delivery exim forks before it exits is not stopped with the unit and the message leaves at once. A release or delete first claims the held copy, so of concurrent requests one acts and the others answer that the copy is not held; a failed release puts the copy back. A copy whose release or delete the daemon never finished, as when it stopped mid-release, is held again on the next 15-minute refresh once the claim is at least five minutes old; such a release may already have been delivered. Recovery never replaces another held copy in either Maildir folder and makes each claim visible only once.

Deferrals are grouped under the provider whose MX host deferred them (Google, Microsoft and Yahoo hosts), so a business domain those providers host counts under them. The recipient’s domain decides when the log line names no MX or an unknown one.

The rspamd status follows live health probes. Dismissing an outage finding does not change it to up. Version display strings are bounded whether they come from the controller or the installed program. A read of rspamd’s controller finishes even when the request that started it goes away, so its result is cached for the other requests; a failed read is logged once per cache period.

Hardening

GET  /api/v1/hardening           Load last hardening audit report (admin scope)
POST /api/v1/hardening/run       Run hardening audit and save report (admin scope, CSRF)
POST /api/v1/hardening/apply     Apply automatic fixes for one section, then re-run the audit (admin scope, CSRF)

Scan Jobs

csm scan --full enqueues full-scan jobs that run inside the daemon and persist to the store. Jobs are report-only unless an account-scope request sets quarantine: true; server-wide jobs reject quarantine.

GET  /api/v1/scan-jobs              List full-scan jobs (read scope)
GET  /api/v1/scan-jobs/{id}         Job status and stored report (read scope)
GET  /api/v1/scan-jobs/{id}/findings
                                      Paginated findings for one job (?offset=&limit=, limit 500 by
                                      default and at most 5000; truncated marks more pages) (read scope)
POST /api/v1/scan-jobs              Enqueue a full-scan job (admin scope, CSRF)
POST /api/v1/scan-jobs/{id}/cancel  Cancel a queued or running job (admin scope, CSRF)

Verified Bots

GET  /api/v1/verified-bots        Configured verified-crawler allowlist plus live verification state (admin scope)
POST /api/v1/verified-bots/apply  Validate, apply, and reload an edited verified-bots list (admin scope, CSRF)

Actions

POST /api/v1/fix                      Apply fix for a finding
POST /api/v1/fix-bulk                 Bulk fix multiple findings
POST /api/v1/dismiss                  Dismiss one finding {key} or up to 500 {keys}, optional {contents}; returns undo_token if any were dismissed
POST /api/v1/scan-account             On-demand account scan
POST /api/v1/verify-finding           Re-check a single finding on demand (admin scope, CSRF)
POST /api/v1/quarantine-restore       Restore quarantined file
POST /api/v1/quarantine/bulk-delete   Bulk-delete quarantined files; returns count and the ids it could not delete
POST /api/v1/db-object-backup-restore Restore a dropped MySQL object from its db_object_backups record
POST /api/v1/test-alert               Send test alert through all channels
POST /api/v1/import                   Import state bundle (suppressions, whitelist)

fix and fix-bulk act on the file the stored finding names. A request may repeat that path in file_path, but a different path is refused, and a target is never a remediation root itself (/home, /tmp, /var/tmp, /dev/shm) or an account’s home directory.

verify-finding returns the verifier verdict in checked, resolved, demote, and detail. When that verdict also changes the stored finding, severity_change is demoted or restored. A demote verdict without severity_change means no stored severity changed; for example, the finding was already demoted or a scan replaced its snapshot while verification was running. Callers must not report a state change from the verdict alone.

Settings

GET  /api/v1/settings             List editable config sections
GET  /api/v1/settings/<section>   Read a config section (secrets redacted)
POST /api/v1/settings/<section>   Update a config section (safe fields reload, restart fields queue)
POST /api/v1/settings/restart     Request a daemon restart. Returns 202 with `started_at_token`
                                  for polling until the restarted daemon reports a new marker.
POST /api/v1/settings/firewall/tentative-apply  Save firewall config, restart, and arm rollback timer
GET  /api/v1/settings/firewall/rollback         Read pending rollback state
POST /api/v1/settings/firewall/confirm          Confirm tentative firewall changes
POST /api/v1/settings/firewall/revert           Revert tentative firewall changes now

Sections map to top-level config keys: alerts, auto_response, challenge, reputation, performance, infra_ips, sentry, etc. Writes persist to csm.yaml, re-record the integrity hash, and hot-reload where possible; restart-required changes are queued for /api/v1/settings/restart. Invalid field values return 422 and do not touch disk.

Fields marked file_only in the schema are shown but refused on write with a 422: anything that names a command, an executable, a file path, a socket or an environment variable the daemon acts on as root can only be changed in csm.yaml. Changing reputation.upstream.url or reputation.rspamd.url also returns 422 unless the same request enters the effective credential for that address again, and is refused outright when the credential comes from an environment variable. A credential entered in the request must match the resulting configuration after conf.d merging; an overridden replacement cannot authorize sending the stored credential to another address. Firewall tentative apply is restart-class by design: it snapshots the previous config, writes the new one, restarts the daemon, and auto-reverts unless the operator confirms before the timer expires.

Operator preferences

Per-operator state (UI density, timestamp display, default auto-refresh, saved filter views) is keyed server-side by SHA-256 of the auth token, so preferences follow the operator across browsers and devices without the daemon ever storing the raw credential. Capability flag: webui.prefs.v1. These endpoints require admin scope because they read or mutate operator-private UI state.

GET    /api/v1/prefs/user        Read this operator's UI preferences
PUT    /api/v1/prefs/user        Replace the prefs blob (CSRF on cookie sessions)
GET    /api/v1/prefs/views       List saved views; `?page=findings` filters by page
PUT    /api/v1/prefs/views       Upsert one view {page, name, params} (CSRF on cookie sessions)
DELETE /api/v1/prefs/views       Delete one view {page, name} (CSRF on cookie sessions)

Response shape for GET /api/v1/prefs/user:

{
  "density":       "comfortable",
  "timezone":      "local",
  "auto_refresh":  "on",
  "table_columns": { "findings-table": ["check","severity","when"] }
}

density is comfortable or compact. timezone is server, local, or an IANA-shaped zone string (e.g. Europe/Bucharest). auto_refresh is on or off. Server-side sanitisation drops any other value. Unset prefs encode as empty strings; the UI applies comfortable, local, and on defaults.

Response shape for GET /api/v1/prefs/views:

{
  "items": [
    {
      "name": "Critical SSH",
      "page": "findings",
      "params": { "severity": "critical", "check": "smtp_bruteforce" },
      "updated": "2026-05-25T21:47:35Z"
    }
  ],
  "total": 1
}

Saved views are operator-scoped and capped at 200 per operator. The saved view collection is stored as one 64 KiB preference blob. page and params keys must be simple identifiers: ASCII letters, digits, underscore, hyphen, or dot, up to 64 bytes. Each view has at most 32 params, and param string values are capped at 256 bytes. name must be 1-80 bytes with no control characters. PUT and DELETE return "ok": true on success.

Bulk-action undo

Finding dismissals, bulk threat block / whitelist and bulk firewall unblock responses return an undo_token when the daemon queues an inverse operation server-side for 30 seconds. The UI surfaces a banner with the same TTL; CLI callers can act on the token through the endpoints below. Each successful undo writes an undo_<original_action> audit entry. Capability flag: webui.undo.v1. These endpoints require admin scope because they read or mutate operator-private action state.

GET  /api/v1/undo/pending    Latest pending undo entry for this operator (empty object if none)
POST /api/v1/undo/run        Consume an entry and dispatch its inverse {id}; empty id uses latest

Non-empty response shape for GET /api/v1/undo/pending:

{
  "id": "188d1f2a6c8b0000",
  "action": "threat_bulk_block",
  "inverse": "threat_bulk_unblock",
  "summary": "Blocked 2 IPs",
  "recorded_at": "2026-05-26T00:07:09Z",
  "expires_at": "2026-05-26T00:07:39Z"
}

POST /api/v1/undo/run returns {ok, action, inverse, count} on success, or 410 Gone when the entry is missing, already consumed, or past its 30-second TTL. Recognised inverse action keys are threat_bulk_unblock, threat_bulk_block, threat_bulk_unwhitelist, threat_bulk_whitelist, firewall_bulk_reblock, and finding_undismiss. Other bulk actions (quarantine delete, generic fix) do not surface an undo token because they have no clean inverse.

Dismissals accept at most 500 keys per request and deduplicate repeated keys. contents maps a key to the content_sha256 its row showed: an empty string for a finding without one, or a string of 64 lowercase hex characters. All other values, including null, answer 400 before any findings are dismissed. A key whose listed finding now carries different content is not dismissed: a single key answers 409, and a bulk request dismisses the rest, returns the refused keys in refused, and counts only the applied dismissals in count. A request with every key refused returns no undo_token. A key missing from contents is dismissed as before and covers the listed content. Undo skips findings changed by a later dismissal, successful re-check or baseline reset, and count reports only the dismissals it actually reversed. Newer scan copies remain in the current findings list.

Finding fields

Every finding in /api/v1/findings, /api/v1/events, and the JSONL audit log carries optional correlation fields when CSM can attribute them:

FieldMeaning
tenant_idTenant attribution from the verdict callback or panel-side webhook reply
domainDomain associated with the event (e.g. PHP-relay scriptKey host, mailbox domain)
mailboxMailbox attribution (e.g. mail brute-force target, PHP-relay envelope-from)
cidrsOffending subnets the finding names (e.g. a distributed crawl’s collapsed subnets, or a mail or SMTP password spray’s /24; sprays leave source_ip empty)
relay_totalPHP-relay trigger count for the path that fired
relay_breakdownPHP-relay script samples that contributed to the alert, with script key, hit count, last seen time, and a bounded sample subject when available

Fields are omitted when the daemon could not attribute them. Orchestrators should treat absence as “unknown,” not “global.”

JSONL and syslog audit events include cidrs for new findings and replayed parked findings after upgrade. Existing audit records are not backfilled.

Cleanup fields

GET /api/v1/quarantine also powers the Cleanup page’s file-backup list. Entries include:

FieldMeaning
kindquarantine or pre_clean
live_stateoriginal_missing, live_differs, original_not_file, archive_missing, archive_not_file, or unknown. Byte-identical restored entries are hidden.

GET /api/v1/db-object-backups returns restored and restored_at when a captured MySQL trigger/event/procedure/function backup has already been replayed.

Incidents

GET /api/v1/incidents/groups is a read-scope rollup of active incidents by kind and source. It accepts status=active|all|open|contained|resolved|dismissed, kind, limit and offset, allowing a credential spray to render as one row per attacker rather than one row per target. total counts the groups and scanned_incidents the incidents they came from; truncated is true when the scan cap left incidents out.

GET /api/v1/incidents

Returns one page of incidents sorted by updated_at descending, with items, total, offset, limit and status. limit defaults to 50 and is at most 500. status filters by open, contained, resolved, dismissed, or active for open and contained; empty means all.

GET /api/v1/incidents/<id>

Returns one incident by id. 404 if not found.

POST /api/v1/incidents/<id>/status

Body:

{"status": "resolved", "details": "operator-marked"}

Status values: open, contained, resolved, dismissed. Closing an incident (resolved/dismissed) means future findings for the same correlation key start a fresh incident. Reopening an incident binds the same key again. Incident JSON includes correlation_key when CSM has a stored account, mailbox, domain, process, or remote-IP key.