[ Switch to styled version → ]
The registry generates structured audit events for every state change. These events can be queried via an API, and can be exported to external SIEM systems, webhooks, or other endpoints.
Every state change in the registry generates a structured audit event. Events are emitted as SIEM-ingestible JSON, stored in an in-memory ring buffer for API queries, and can be forwarded to external systems through an audit export pipeline.
The audit system operates at the registry level, capturing events across all networks. Enterprise features add more event types, such as RBAC changes, policy updates, and directory sync.
Each audit event contains the following fields:
Events that modify state include enriched context with both old and new values. For example, a hostname.changed event includes old_hostname and new_hostname; a member.promoted event includes old_role and new_role.
The registry maintains an in-memory ring buffer of the most recent 1,000 audit entries. It can be queried with the get_audit_log command.
# Get all audit entries (newest first)
pilotctl audit
# Filter by network
pilotctl audit --network <network_id>Protocol command:
{
"command": "get_audit_log",
"network_id": 1,
"admin_token": "your-admin-token"
}The command returns an array of audit events named `entries`, newest first. The `network_id` filter is optional.
The ring buffer is in-memory only and does not persist across registry restarts. For persistent audit trails, use audit export.
Audit export forwards events to external systems in real time. An export endpoint is configured with the `set_audit_export` protocol command or through a blueprint.
{
"command": "set_audit_export",
"format": "splunk_hec",
"endpoint": "https://splunk.example.com:8088/services/collector",
"token": "your-hec-token",
"admin_token": "your-admin-token"
}Three export formats are supported:
Delivery guarantees:
Events are buffered and delivered asynchronously. If the export endpoint is unavailable, events are retried up to 3 times with exponential backoff. Events that exceed the retry limit are dropped, but remain in the in-memory ring buffer.
Splunk HEC (HTTP Event Collector) integration sends events in Splunk’s native format.
{
"command": "set_audit_export",
"format": "splunk_hec",
"endpoint": "https://splunk.example.com:8088/services/collector",
"token": "your-hec-token",
"admin_token": "your-admin-token"
}Events are formatted as Splunk HEC JSON payloads. The HEC token is sent in the `Authorization` header.
Common Event Format (CEF) output is compatible with SIEM systems that accept CEF-formatted syslog.
{
"command": "set_audit_export",
"format": "cef",
"endpoint": "https://siem.example.com/api/events",
"admin_token": "your-admin-token"
}Events are formatted as CEF strings with Pilot Protocol vendor and product identifiers.
Generic JSON export sends the raw audit event as a JSON POST to any HTTP endpoint.
{
"command": "set_audit_export",
"format": "json",
"endpoint": "https://logs.example.com/ingest",
"admin_token": "your-admin-token"
}The payload is the audit event object, with the same structure returned by `get_audit_log`.
Webhooks deliver audit events to HTTP endpoints. Each webhook invocation includes a unique event ID for deduplication.
Failed webhook deliveries are retried with exponential backoff. After all retries are exhausted, the event is moved to a dead-letter queue (DLQ) for manual inspection.
The DLQ can be queried with the following command:
{
"command": "get_webhook_dlq",
"admin_token": "your-admin-token"
}This returns an array of failed webhook events named `entries`.
Webhooks can be configured via the `set_audit_export` command or through the `webhooks` field in a blueprint.
The registry exposes Prometheus metrics for monitoring audit and webhook health.
These can be scraped from the registry’s metrics endpoint.