Audit Logging
How a state change becomes an audit entry, and the gates that keep it that way. The user-facing description is Audit Log; the generated audit events reference lists every route's decision.
The contract
An audit entry answers six questions: when (ts), who (actor_sub, actor_username, client IP and user agent), object (resource_type, resource_id), action, details (details_json), and diff (the before and after snapshots inside the details). A route that changes durable state records an entry that answers all six, or the registry says why it does not.
The vocabulary is fixed: AuditAction, AuditOutcome, and AuditResourceType in packages/core/enums.py, plus the event-type namespaces in packages/core/audit.py. An installed extension adds resource types and namespaces of its own (audit_resource_types, audit_namespaces; see Audit vocabulary). emit_audit_log accepts the enum members or their string values, and an extension's names as strings; an unknown outcome always raises, and an unknown action, resource type, or event type raises under HEGEMONY_AUDIT_STRICT_VOCABULARY (on in the test suite) and is logged as drift in production.
Safe failure details
Record a stable error code instead of arbitrary exception text in audit payloads. For example, both approval decision routes (POST /approvals/{approval_id}/decision and POST /runs/{run_id}/approvals/{approval_id}/decision) record approval.signal_failed with code: APPROVAL_SIGNAL_FAILED and stage: temporal_signal when Temporal connection or signaling fails. The saved decision and its successful decision audit entry remain committed. The route returns a generic HTTP 500 message explaining that the decision was saved but workflow notification failed; it does not return transport exception details, and it does not send the decision notification. The application log records the exception type only.
Auditing a route
- Snapshot the object with
entity_to_dictand the router's*_AUDIT_FIELDSlist. Add every column the handler can change; leave out secret values (references such aspassword_refstay in, they are what an auditor needs to see change). - Capture
beforefrom the loaded row before mutating it. Never hard-code a before state. - Call
emit_audit_logafter the last point that can raise and before the commit. The entry joins the caller's transaction, so it is committed exactly when the change is. Passentity=so the id, display name, and, on request-less paths and platform routes, the org come from the row; passorg_id=explicitly when the entry concerns a different org than the row. A platform route never takes the org from the request, so one whose entry belongs to an organization passesorg_id=(or anentity=that carries it); otherwise the entry is platform-level. For a fact that must survive whatever the transaction does (a post-commit side effect that failed, an attempt rejected as stale, an access denial) useemit_audit_log_now, which writes through an independent session and never raises. - Register the route in
apps/api/audit_coverage.yamlunderaudited:with itsresource_type,actions, andsnapshot(before,after,both,none, ormixed). Usemixedwhen the route emits entries with different snapshot shapes. Declare additional resource types inalso_recordsand include their actions inactions: a webhook trigger also starts a run, and configuration import/apply records each created, updated or deleted object. For routes emitting several kinds of entry, snapshots depend on the event: an operation summary has no state, creation has an after-state, deletion a before-state, and an update can have both. - Add a test that drives the route and asserts on the row: resource id, action, and that
beforeandafterdiffer on the changed field.
A POST that changes nothing durable (a validation, a probe such as a file repository's test-connection or a registry credential's login test, a query carried in a body) goes under exempt: with a reason. So do the worker's grants of a step's short-lived tokens (for one Terraform state, or a container step's access, which brings the platform registry's token and whatever extensions grant): the token is the run's, and what the step does with it is audited on the state routes or recorded in the run's events. A route that does change state and cannot be audited in the same change goes under known_gaps: naming the change that will close it; the suite enforces that this list only shrinks.
A GET that changes durable state as a side effect (the object-types listing of a NetBox provider adopts a refreshed shared schema, which bumps the config version and can stale rows) goes under audited: too, so the emitter gate covers it; its entry is recorded under a system actor (system:inventory-discovery) because no person asked for the change. Reads are never required to carry a decision -- the completeness gate walks only mutating methods -- and exempt: and known_gaps: do not accept them.
When the handler reaches emit_audit_log through something the static walk cannot follow (a class method, a callback), add emitter: to its entry with the dotted name of the function to treat as the terminal. Every emitter named this way, and every entry of AUDIT_EMITTERS in apps/api/audit_coverage.py, must itself call emit_audit_log.
Vocabulary notes
Some spellings are kept on purpose:
deleteis the hard delete of a resource with no soft-delete lifecycle;soft_delete,permanent_delete, andrestoreare the three steps of that lifecycle. They are different events, not synonyms.- A run start is always
start; the trigger (manual, run-now, schedule, webhook) is the entry'strigger_sourcedetail, not a separate verb. syncanddiscoverare different verbs for an inventory provider.syncpulls rows from the source into the local tables;discoverasks the source which object types it serves and stores only that answer. A provider that cannot answer refuses the route, so adiscoverentry means the source was actually asked.- An inbound webhook records two entries because it touches two objects:
webhook.triggeredon the endpoint andrun.startedon the run. conflictis the outcome of a request rejected as a duplicate or stale.authz.denied(actionaccess) is a known caller refused a route;auth.failed(actionauthenticate) is a credential that established no caller. Only failures that still name an identity (a revoked or expired personal access token) reach the table; anonymous ones are log-only. Both are written by the middleware (apps/api/auth/access_audit.py), not by a route, so the coverage registry does not list them.
Rows written before the vocabulary existed were migrated onto it; each keeps its original spelling under a legacy_outcome, legacy_action, or legacy_event_type key in its details.
The gates
| Gate | Where | What it catches | What it cannot see |
|---|---|---|---|
| Registry completeness | tests/api/audit/test_audit_coverage.py | A mutating route with no decision; an entry for a route that no longer exists; a growing known_gaps list | Whether the decision is right |
| Emitter reachability | tests/api/audit/test_audit_coverage.py | An audited route whose handler has no call path to an emitter | A call behind a condition a test never takes; calls through instances (use emitter:) |
| Vocabulary (static) | tests/api/audit/test_audit_vocabulary.py | A literal action, outcome, resource type, or event type outside the enums and namespaces, at any call site | Values computed at runtime |
| Vocabulary (runtime) | emit_audit_log | The same, on every path the suite executes | Paths no test executes; in production it warns instead of failing |
| Docs freshness | docs/docs-map.yaml, audit-log-backend | Changing the audit backend or the registry without touching the audit docs | Whether the prose is true |
| Session guards (runtime) | apps/api/audit_session.py | An entry lost to a rollback or an unclosed session (logged with its payload; a savepoint's rollback logs the entries added in it, and a released savepoint's entries wait for the transaction around it); application code modifying or deleting an entry (refused at flush) | A handler that never emits |
| Route contracts | tests/api/audit/test_router_audit_contracts*.py | For the routes in the case tables: the wrong resource type or action, a missing snapshot the registry promises, an update with no changes, an entry left by a failed request | Routes no case covers |
Extensions
An installed extension brings the audit decisions for its own mutating routes, in the shape of audit_coverage.yaml; they merge into the registry when it is first read (_registry() in apps/api/audit_coverage.py). The suite's gates do not see an extension's routes, so the platform checks them when it mounts the extension: a mutating route without a decision, decisions that do not parse, or a decision for a route the registry already classifies refuses the extension, and nothing of it is mounted.
Run them with task test:audit:coverage (the two static gates, also a pre-commit hook and a CI step beside the auth boundary check) or task test:audit (everything under tests/api/audit). The coverage gate has no override label: a route is audited, exempt with a reason, or a named gap.
The deterministic gates cannot judge the quality of an entry: an under-detailed field list, a before captured after the mutation, an extra_details that would not tell an auditor what changed. The route contract tests catch that for the routes they drive; for everything else it is left to review of the changed handlers.