AUDIT ACTIONS

swamp serve writes an audit log when its config file has an audit block. Read it with swamp audit log --server, stream it with swamp audit log --follow --server, and alert on it with audit.alerts rules. Reading it needs admin on access:audit; see Authorization — Audit log.

This log is separate from the repository's command audit, which records agent and CLI commands in .swamp/audit and is read with swamp audit. See The Audit System for that log.

Entry fields

Every entry has these fields. Optional fields are absent, not empty, when they do not apply.

An action, resourceName or detail value that contains an absolute file path is recorded as [redacted]. No entry carries a secret value, a token, a signal payload or a request body.

Categories

Recording policy

No entry is written unless the serve config file has an audit block. Within it, audit.policy decides per entry whether it is recorded:

audit:
  policy:
    default-level: metadata
    rules:
      - action: workflow.schedule.skipped
        level: none
      - category: data
        level: none

• Rules are tried in order and the first rule whose every given key matches decides the level.
• none drops the entry. Every other level records the same fields.
• The management tier is every system entry plus audit.query, audit.verify, audit.subscribe and serve.reload. Every other entry is in the data tier.
• An action in a rule may use the behavior spelling: behavior. at its start is read as model.. Stored actions keep the model. spelling.
• serve.config.reloaded is decided under the policy in force before the reload, so a reload that lowers auditing still records itself.
• A success entry is dropped when an entry with the same requestId was already recorded as denied.

swamp serve reload applies a changed audit.policy without a restart.

Entry shapes

Entries come in three shapes:

A refused request writes an access denial entry and then a request entry with outcome failure under the same requestId.

Request entries

Every request on the WebSocket API is recorded when serve answers it. The HTTP routes that run requests through the same path (/api/v1/request, /api/v1/action) record the same entries.

On success, detail is set for:

• workflow.run started again under an idempotency key it already used: replayed start.
• model.method.run of an integration behavior (swamp/integration): state=<state> ceiling=<digest>, plus previous=<digest> when the ceiling changed.

Category and resource kind by request type:

Requests with no request entry:

• commits.subscribe and commits.head, which filter what they return per caller and refuse nothing.
• audit.unsubscribe, which only ends the caller's own stream.
• A request refused by --restricted-commands. Its access denial entry is the record: action admin, resource kind access, resource name the request type.
• A request refused because the audit log cannot record durably (audit_unavailable, with fail-open: false).

Access denial entries

Authorization writes an entry each time it refuses an action. Allowed decisions are not recorded.

decision fields:

The same shape records refusals from the HTTP datastore API, the signal route and the run cancel route.

A run that a schedule or webhook starts and authorization refuses is recorded the same way, with action run, principal service:scheduler or service:webhook, and detail holding key=value pairs: fireTime and replayed for a schedule, route, run and replayed for a webhook, and reason (for example no grant allows it or denied by grant <id>) for both.

The resource kinds and access actions are described in Authorization.

Authentication and sessions

Category auth. These entries are written on the HTTP path before any WebSocket exists.

For auth.session.terminated, initiatedBy is the admin who revoked or rotated the token, or system when serve's own revalidation ended the session, and sourceIp is the closed session's address.

Delegation links

Category auth. Resource kind delegation, resource name and delegation field the delegation id. The principal is the linked person once Swamp Club has reported them, and the integration before that; client is integration:<id>. sourceIp is server.

detail always starts with outcome=<value> request=<id>, then link=<id> once Swamp Club has issued one, then external=<platform>/<team>/<user>.

Runs and cancellation

system entries always have outcome success, principal system and source address 127.0.0.1; read workflow.auto_resume_failed by its action, not its outcome.

Runs started by request are recorded as the workflow.run and model.method.run request entries.

Workflow schedules

Category execution, resource kind workflow, resource name the workflow. Principal service:scheduler, source address 127.0.0.1.

Pausing and resuming a schedule are the workflow.schedule.pause and workflow.schedule.resume request entries. A fire refused by authorization is an access denial entry.

Webhooks

workflow.webhook.fire and workflow.webhook.rejected have principal service:webhook and the sender's address (X-Forwarded-For with --trust-proxy). reason is one of Missing <header> header, Request body too large, Invalid signature, Not the leader, Server starting, Queue full, Server shutting down, Webhook handler unavailable, Webhook handler failed, or a refusal of a scheme from an untrusted collective. Rejections are coalesced per route and reason: the first in each 60-second window is written, and suppressed counts the ones dropped since the previous entry.

A delivery whose run authorization refuses is an access denial entry with action run, not a webhook action. The webhook_denied event in serve's output is not an audit action.

webhook.routes.applied names the caller of swamp serve reload as its principal, or system for a poll. Its detail holds these keys, each present only when it has a value:

Each list shows at most 50 items, then +<n> more. Route and file names percent-encode spaces, control characters and %=,().

Signals

Category execution, resource kind workflow, resource name the workflow.

workflow.signal.taken is a system entry: principal system, resource server. The signal payload is never recorded.

Approvals and rejections are the workflow.approve and workflow.reject request entries.

Vaults and secrets

Category secrets.

vault.read and vault.write name the run's principal and carry a decision like an access denial entry, with grantId set when a deny grant matched. A run writes one entry per refused vault, key and action.

worker.secrets.load is written at every level but none, and names the worker as principal worker:<name> when the dispatch credential verified, or anonymous when it did not. denied covers an unverified credential, an ended dispatch or a refused reference; failure covers a malformed or oversized request or a vault error.

Vault requests from clients are request entries.

Datastore administration

Category admin, written by the HTTP datastore API. The principal is the caller.

Serve config and instance

Resource kind server and resource name the instance id, except alert.fired, which has resource kind alert-rule, the rule name, and principal id audit-engine. An alert rule with action: webhook posts to its URL and writes no entry.

serve.config.reloaded names the caller of swamp serve reload as its principal; trigger is reload for that request, signal for SIGHUP, and poll for a config poll, which have principal system. The entry holds setting names only, never values. The serve.reload request writes its own request entry.

Related

• Authorization — resource kinds, access actions, and the audit.* requests
• Hot Reload — what swamp serve reload applies
• Webhooks — webhook routes and provider schemes
• REST API — the cancel endpoints