Audit Logging

Status: Available.

Inspected requests in enforce mode are logged to a best-effort append-only JSONL file at ~/.mezite/local/audit.jsonl. The writer is mutex-protected so concurrent goroutines can append without racing the file. Each row is fsynced before the function returns, so a row that commits survives a power loss.

The local audit log is not hash-chained or tamper-evident. It is append-only by convention, with no prev_hash linking or chain verification. When this workstation is enrolled, audit events are also uploaded to MezHub; rely on that central record. See Managed Policy.

Log entry format

Each entry is a single JSON line with four top-level fields:

{
  "timestamp_ms": 1736947921003,
  "op": "mitm",
  "hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "fields": {
    "host": "my-cluster.eks.amazonaws.com",
    "method": "GET",
    "path": "/api/v1/namespaces/payments/pods",
    "tier": "observe",
    "decision": "allow",
    "status": 200
  }
}

An escalated request that was approved:

{
  "timestamp_ms": 1736947965112,
  "op": "mitm",
  "hash": "f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3",
  "fields": {
    "host": "my-cluster.eks.amazonaws.com",
    "method": "DELETE",
    "path": "/api/v1/namespaces/payments/pods/api-7d4b",
    "tier": "sensitive",
    "decision": "allow",
    "outcome": "approved"
  }
}

Row fields

FieldTypeDescription
timestamp_msnumberUnix epoch in milliseconds
opstringOperation type (e.g. mitm, pin_splice, block, control)
hashstringOpaque random 128-bit row ID (hex), used only for pagination and deduplication
fieldsobjectOp-specific payload (host, method, path, tier, decision, status, …)

The hash field is a random identifier, not a content hash and not part of a chain. Two identical events appended in the same millisecond will have different hash values.

Only hosts that match a policy inspect route are audited, and only in enforce mode. A host that matches no route is a transparent tunnel and leaves no trace; observe mode is a dry-run that records to the observe log (observe.jsonl) instead of the audit log. To audit everything, add "*" under the policy's generic.inspect block.

Viewing logs

# Show the last 50 rows (default)
msh local audit show

# Show the last 20 rows
msh local audit show --last 20

# Filter by host
msh local audit show --host my-cluster.eks.amazonaws.com

# Filter by op
msh local audit show --op mitm

# Show rows from the last hour
msh local audit show --since 1h

# Emit JSON for scripting
msh local audit show --json

# Stream new rows in real time (Ctrl-C to stop)
msh local audit tail

# Show last 10 rows then exit
msh local audit tail --lines 10

# Filter the tail stream
msh local audit tail --filter host=my-cluster.eks.amazonaws.com

# For advanced filtering, pipe the raw JSONL through jq
jq 'select(.op == "block")' ~/.mezite/local/audit.jsonl
jq 'select(.fields.tier == "sensitive")' ~/.mezite/local/audit.jsonl
jq 'select(.fields.decision == "allow")' ~/.mezite/local/audit.jsonl

File permissions

The audit log file is created with 0600 permissions (owner read/write only). It is append-only in normal operation; the daemon never overwrites or truncates it.

There is no msh local audit verify command. The local audit log provides an operational record, not a cryptographic guarantee. An operator with filesystem access can alter or delete it. When enrolled, rely on the audit events uploaded to MezHub.