Security: Audit trails

Status: target state. Operational logs exist via actorLog. Structured audit events, queryable store, export, and retention policy are not implemented.

What an audit trail must capture

For every security-sensitive op:

eventType — auth.session.create, auth.hostLink.revoke, etc.
ts — timestamp.
actorPrincipalId — who performed the action.
targetResource — {kind, id}.
outcome — ok or error with reason.
request — relevant payload fields (with sensitive values redacted).
connection — IP, user agent, loopback flag, session jti.

These should be tamper-resistant: append-only, optionally hash-chained, signed.

Events that should be audit-logged

From the security-relevant op surface:

auth.session.create (login).
auth.session.revoke (logout).
auth.principal.ensure (first login of new principal).
auth.namespace.claim / release.
auth.space.create / delete (target).
auth.hostLink.create (Device pair).
auth.hostLink.revoke.
auth.hostLink.credentials.refresh.
auth.role.assign (target).
system.principals.suspend (target).
host.control.runtimes.declare / start / stop / remove.
HTTP-level: /api/devices/:id/revoke, /_auth/host-link/heartbeat (sample, not every).

Today these route through actorLog mixed with operational logs. Filtering by op type works at grep/jq level, not at API level.

Today's pseudo-audit

bash

# What revoke events occurred?
grep '"op":"auth.hostLink.revoke"' /var/lib/hivecast/host-home/logs/runtimes/system-auth.log

# What logins?
grep '"op":"auth.session.create"' /var/lib/hivecast/host-home/logs/runtimes/system-auth.log

# By principal
grep '"principalId":"p_xxx"' /var/lib/hivecast/host-home/logs/runtimes/system-auth.log

These work. They are not a real audit log.

Compliance posture

The platform is not currently fit for audited compliance regimes (SOC 2, HIPAA, PCI). The gaps:

Audit log is not durable / tamper-resistant.
No retention policy.
No separation of duties between auditor and admin.
No standardized export format.

Building the audit pipeline is a target deliverable for compliance-track work.

Target architecture

Per ARCHITECTURE/ARCHITECTURE-OBSERVABILITY-PIPELINE-V2.md:

Audit events emit on a dedicated bus topic.
A system.audit actor subscribes, validates the event shape, persists to a JetStream stream.
The stream replicates to a long-term sink (S3, etc.) for retention.
A query API exposes audit.query for filtered reads.
An admin UI consumes audit.query for the dashboard.

This pipeline is not assembled. The primitives (NATS JetStream, actorLog) exist.

Retention

Target: per-event-type retention with at minimum:

Auth events: 1 year.
Device pair / revoke: 7 years.
Session create / revoke: 90 days.
Operational logs: 30 days.

Today: no retention policy. Logs rotate based on supervisor settings (default size-based).

Export

Target: CSV / NDJSON export from the admin UI for any filtered query.

Today: tail/grep + redirect.

Security of the audit log itself

A real audit log must:

Authenticate writes (only the audit actor + trusted writers can append).
Reject backdating (events are timestamped on receipt, not by the writer).
Be append-only at the storage layer.
Be hash-chained or signed for tamper detection.

None of these protections exist today.

Security: Audit trails ​

What an audit trail must capture ​

Events that should be audit-logged ​

Today's pseudo-audit ​

Compliance posture ​

Target architecture ​

Retention ​

Export ​

Security of the audit log itself ​

See also ​