Skip to content

Audit and Compliance

A managed install records every gated or blocked action and, optionally, reports those records to the policy server. The records are secret-free by construction, so they are safe to centralize. This page covers what is recorded, how reporting works, and how to collect and retain the records.

What is recorded

A managed install produces two kinds of audit records, both on the same local audit channel (the tracing target audit).

  • Policy-gated denials: every action blocked by a policy produces exactly one structured record, an authz_denial event with reason = "policy_gated". The record names the action (the tool, command, or route path), the transport that rejected it (agent, tauri, rest, or mcp), and the deciding policy (the organization, when the policy names one). It records at the outermost enforcement choke point of each transport, so one blocked action is one record, not one per layer.
  • Egress decisions: when egress auditing is on, the egress firewall records its allow and block decisions. These records are secret-free: they carry the decision and the host, never request bodies, tokens, or keys.

Scope denials (a request that lacks the required API scope) share the same channel, so a single filter catches policy-gated denials, egress decisions, and scope denials together.

Client-to-server reporting

A managed install can report its audit records back to the policy server, so an administrator sees fleet-wide enforcement without logging into each device. Records are buffered locally under <app_data>/enterprise/audit/, batched, and POSTed to POST /api/v1/audit, signed with the device identity. The server re-emits each event to its own audit channel, tagged with the reporting device id, where your log pipeline collects it.

Reporting is bounded and self-protecting:

  • A batch carries at most 1,000 events.
  • A device may only report for itself; the authenticated device id must match the batch.
  • The event fields are checked against a secret-field guard, so a field whose name resembles a secret (token, password, private key, signature) is rejected. The only secret-adjacent field is a masked credential, which is already reduced to a first-and-last-few-characters form before it leaves the device.

The server in the policy-server binary accepts these batches under the enterprise_read scope granted to enrolled devices. See Policy Server Deployment and Operation.

Audit event fields

A reported audit event carries only non-secret fields. The shape is stable and camelCase on the wire:

Field Present for Meaning
event All The event kind (authz_denial or auth_failure).
reason Most The denial or failure reason (for example policy_gated, insufficient_scope).
action Policy-gated denials The blocked action (the tool, command, or route).
path Policy-gated denials The transport that rejected it (agent, tauri, rest, mcp).
policy Policy-gated denials The deciding organization, when named.
endpoint Scope denials, auth failures The endpoint involved.
keyId Scope denials The key identifier.
requiredScope Scope denials The scope that was missing.
maskedKey Auth failures A masked credential (never the raw key).
timestamp All RFC3339 timestamp.

No raw API keys, enrollment tokens, private signing keys, proxy passwords, or CA bundles ever appear. This is enforced, not just a convention: the build-out path masks credentials, and the secret-field guard rejects anything that looks like a secret by name.

Collection and retention

Because the records are secret-free, you can collect and retain them with standard tooling. Two collection patterns work, and you can use both.

  • Per-device collection: the audit channel writes to the device's log stream. On Linux that is the journal; on a headless host it is the process log. Forward these with your existing log agent (for example to a SIEM or a log aggregator). This captures records even from devices that do not report to the server.
  • Central collection at the policy server: enable client reporting so devices POST their batches to the policy server, and collect the server's re-emitted audit stream. This gives a single fleet-wide feed without touching each device, at the cost of a network path from each device to the server.

For retention, treat the records as operational security logs. Keep them long enough to satisfy your compliance window (commonly 90 days to one year for access and authorization logs), and store them in your existing immutable or write-once log store. The records carry no secrets, so they do not raise the sensitivity of the store that holds them. The local buffer under <app_data>/enterprise/audit/ is bounded and append-only; it is a staging area for reporting, not the system of record. Rely on your aggregator or SIEM for long-term retention.

What is and is not covered

The audit surface records authorization and enforcement decisions: policy-gated denials, scope denials, egress allow and block decisions, and authentication failures. It is not a content or conversation log. It does not record prompts, model outputs, or file contents. For a record of what a deployment may do (the policy itself), the authoritative source is the signed policy served by the policy server and the resolved managed status on each device.

Next steps