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

Action log

The audit log records what CSM found. The action log records what CSM did: one record per action, one file, one schema, whether the action came from the daemon, an operator command or the web UI.

/var/log/csm/actions.jsonl
csm actions                      # recent actions, one line each
csm actions --since 24h          # RFC 3339 timestamp or a duration
csm actions --op respond.block_ip
csm actions --json               # the raw records
csm action show <action_id>      # one admission response and its attempts

Schema

{
  "v": 1,
  "ts": "2026-09-09T10:32:14.512938Z",
  "hostname": "host.example.com",
  "op": "respond.quarantine_file",
  "actor": "daemon",
  "finding_id": "8e3f1c204c1d8b95",
  "target": "/home/alice/public_html/uploads/x.php",
  "account": "alice",
  "reason": "webshell_realtime",
  "before": {"exists": true, "sha256": "5f2b...", "size": 1841, "mode": "-rw-r--r--", "uid": 1001, "gid": 1001},
  "after": {"exists": false},
  "result": "applied",
  "recovery_path": "/opt/csm/quarantine/2026-09-09T10-32-14-x.php"
}
FieldMeaning
opThe privileged operation, using the IDs from the capability matrix. The matrix says what an operation may do; this says what it did.
actionThe specific change within an operation, such as block, unblock, apply or rollback.
actordaemon, cli or webui. actor_detail carries the operator’s source address or the command name.
finding_idThe finding that caused the action, using the same ID the audit log emits, so the two streams join.
commandThe exact argv when CSM ran a program. Absent when the action used system calls only.
before / afterThe target file’s digest, size, mode and owner around the change. "exists": false after a quarantine is the record that the file is gone.
resultapplied, dry_run, failed or refused. A dry-run record says what CSM would have done.
undoA command that reverses the action, when an exact inverse is available.
recovery_pathRetained quarantine content or a pre-clean backup, with a .meta sidecar. Use the quarantine recovery workflow; csm restore accepts state archives, not these files.

Attempted operations include failures and safety refusals. An already blocked address does not produce another applied record. A successful file replacement or quarantine with a later warning stays visible with its recovery path.

A refused action is recorded too. “The safety rules stopped this” and “CSM never looked” are different operational states, and only one of them is a reason to change the configuration.

v is the schema version. It is bumped only on an incompatible change, so a parser can pin on v: 1 and ignore unknown keys.

Long reasons and error messages are truncated with an explicit marker so one action cannot make the history unreadable. Targets and command arguments are preserved.

A file larger than 64 MiB is recorded without a digest rather than stalling the action while it is hashed. Quarantine digests come from the captured copy, after the move. Cleaning digests describe the exact bytes read and installed through the pinned file handles. Directories and symlinks have no digest.

What is covered

The capability matrix has an “Action record” column. These operations write here today: firewall blocks and unblocks (automatic and operator), whole-ruleset changes, file quarantine, surgical file cleaning, process termination, mailbox suspension, the account-wide outgoing mail hold, and an operator’s release of either (operate.release_mailbox, one record per part undone), and lifting Stalwart’s ban of an address unblocked in CSM (operate.clear_stalwart_ban, one record per ban). A hold record carries the quoted whmapi1 release_outgoing_email command that lifts it. Everything else appears in the daemon log only. The column is the authoritative list. Tests exercise the operation paths, including failures and concurrent blocks.

The firewall keeps its own audit file because the web UI and the API read it. Its entries also appear here; dry-run decisions, failed attempts and whole ruleset apply/rollback records are recorded directly on this stream. Startup rollback records are written before the daemon requests a restart.

Admission records describe each step of an automatic response the admission ledger admitted: op is respond.block_ip, action the kind of response (block_ip, block_subnet, block_service, promote or challenge), target its canonical target, reason the lane and the absolute expiry, and result the step (reserved, executing, then applied, narrowed, failed or unknown). action_id and action_version name the attempt and the step. A record is written durably before the ledger lets it go, so after a crash it can appear twice; drop a copy whose action_id, action_version and ts match another. An admitted IP block takes these steps while the ledger executes, with auto_response.dry_run false, the firewall on and outside observe mode. Otherwise the ledger previews each response it is handed, so an admitted response is reserved and then observe and is never executed; in dry run with the firewall on outside observe mode it forecasts block responses instead. Their terminal outcomes are counted in the ledger without a new per-attempt action-log row; bounded forecast examples and summaries are separate.

csm action show <id> asks the daemon for what the ledger holds on one response, by the action_id of an admission record or by its candidate ID. It prints JSON: the candidate’s kind, target, check, state, reason, outcome and expiry, each attempt with its lane, reservation, finish and outcome, and for a response refused because a block already enforced it, that block’s action and end (link). A response whose history has retired, or that was never admitted, is reported as not recorded. A retained retired attempt still has its unknown outcome and retired: true; retirement is not proof of success. Retention removes the candidate and all its attempts together. If a retained candidate is missing an earlier attempt, the command reports ledger damage; it does not claim the missing part aged out or return a truncated history.

The command uses candidate_id for the candidate and attempts[].action_id for each attempt, matching the action log’s action_id. It never uses the log’s action operation field for an identifier. The other top-level fields are kind, target, optional check and finding_id, state, optional reason, disposition, expires_at and link, and attempts (always an array, including when empty). Each attempt has seq, state, optional disposition and lane, reserved, optional finished, expires_at, and retired only when true. Times use RFC 3339. link.effect identifies the existing block; an omitted link.expires_at means permanent. Omitted candidate expiry means no expiry was assigned; it is not a permanent block.

This command requires a running daemon and never changes admission or firewall state. Each read is audited with op: respond.block_ip, action: show, actor: cli, actor_detail: csm action show, and the requested ID as target. result: read means the lookup succeeded, never that a block was applied; failed lookups use result: failed and error. These read records have no lifecycle action_id or transition version. They use the existing bounded, best-effort action log outside the admission outbox, so a sink failure does not disable the diagnostic read. The finding-stream exporter accepts these records as reads, salts their targets as opaque references and drops error text; they cannot claim a block was applied.

It offers no resolve, retry or undo operation; durable firewall actions remain under csm firewall actions. The admission.action_show.v1 capability advertises this local read command; it does not indicate that automatic execution is on.

Once an hour the ledger owner appends respond.block_ip summary records that count its decisions on the responses handed to it during the hour ending at ts. A summary sets count, how many responses it covers, and names no target: action is the kind of response, reason the check that asked for it, actor_detail the entry it came through (scan, or a derived entry such as challenge_timeout or central), result the decision (queued, coalesced, observe or refused) and error the refusal reason. An attribution refusal also names its cause: no_observation (no reader stamped the finding), kind_not_allowed (no parser vouched for the address in a way the check accepts), target_mismatch (the response names an address its evidence does not attribute), unreachable (the address is a client behind a trusted proxy, which sends this host no packets of its own), proxy_peer (the address is a known CDN or website-firewall edge, which carries many visitors) or rewritten_log (the web server replaced the logged client address, or CSM could not read its configuration, so the connecting peer is unknown). Refusals at submission and queue placement keep the same cause as refusals at evidence minting. A queued response that a later check refuses (its revalidation, an inventory refresh, a configuration opt-out, a lost queue position after reassessment, or the recheck of a pick before an attempt or a preview) counts as refused too, with its reason and cause, in the hour the ledger ended it. A displaced queued response also counts once. These rows retain that hour even after a newer hour was reported. Hours discarded when a logging outage exhausts summary retention stay discarded; later refusals for them never return as partial summaries. An owner that runs automatic blocks and forecasts them in dry-run mode also counts dry_run decisions, each with a prediction of what live admission would have done: capacity_admit, existing_actual, existing_shadow, ceiling, set_full, pending_recovery, forecast_limited, not_modelled, capacity_evict, capacity_rotate or equal_tier_wait. A prediction is not a refusal reason. A clean stop writes the open hour early, so summaries for the same hour add up; a crash loses the open hour, so the counts are lower bounds. Each summary also sets epoch, the daemon run that counted it: a number that rises at every start of the owner, so summaries of two runs never share one.

Refused previews and submissions displaced from the memory queue count as refused with their reason, including every report merged into a displaced submission. While the owner executes, a block it runs shows only in its attempt rows above: the summaries count a live block pick only when the ledger refuses it at its recheck or reservation. A batch the firewall engine refuses while applying it, and a pick the panel verdict callback allows, add no refused row; the first shows in its attempt’s outcome, the second in the log and in the verdict counters of status. Summaries continue while the ledger or its clock is unavailable, and stopping flushes completed decisions even if the final drain fails. Their hour never precedes the latest recorded admission hour, including clock readings from an incomplete startup.

actor uses the caller’s attribution when available and otherwise identifies the process performing the action. Some web UI requests therefore record as daemon; the web UI’s own action log retains the operator’s source address.

Rotation

The file rotates to actions.jsonl.1 at 10 MB. csm actions reads both. Readers and writers coordinate rotation through actions.jsonl.lock. Readers pin both files before releasing the lock, so rotation cannot hide records and a slow reader does not hold up a writer. CSM handles this rotation itself; the installed logrotate configuration leaves the live file alone and archives actions.jsonl.1, which the sink never writes to again, for 90 days. Older history is compressed there and is not read by csm actions; ship the stream to a SIEM if you need it queryable.

Recording is best effort. Sink errors or panics do not change an action’s outcome. A write waits at most 250 ms, with at most 64 writes outstanding; a stalled sink or saturation can lose records. Normal CLI writes finish before the command exits. Keep this log on a local filesystem and monitor write-error warnings. The stream is not a transactional guarantee that every host change survives a crash.