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"
}
| Field | Meaning |
|---|---|
op | The privileged operation, using the IDs from the capability matrix. The matrix says what an operation may do; this says what it did. |
action | The specific change within an operation, such as block, unblock, apply or rollback. |
actor | daemon, cli or webui. actor_detail carries the operator’s source address or the command name. |
finding_id | The finding that caused the action, using the same ID the audit log emits, so the two streams join. |
command | The exact argv when CSM ran a program. Absent when the action used system calls only. |
before / after | The target file’s digest, size, mode and owner around the change. "exists": false after a quarantine is the record that the file is gone. |
result | applied, dry_run, failed or refused. A dry-run record says what CSM would have done. |
undo | A command that reverses the action, when an exact inverse is available. |
recovery_path | Retained 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.