[ Switch to styled version → ]
The system generates structured audit events. It supports SIEM export, webhooks, and dead-letter queues.
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 runs at the registry level and captures events across all networks. Enterprise features add more event types, such as RBAC changes, policy updates, and directory sync. The core audit infrastructure is always active.
Each audit event contains:
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 `entries` array of audit events, newest first. The `network_id` filter is optional. If omitted or set to 0, it returns all events.
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. Configure an export endpoint 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 temporarily unavailable, events are retried with exponential backoff up to 3 times. Events that exceed the retry limit are dropped, but they remain in the in-memory ring buffer for API queries.
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 with the `event` field containing the audit data. The HEC token is sent in the `Authorization` header.
Common Event Format (CEF) output is compatible with ArcSight, QRadar, and other 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 the Pilot Protocol vendor and product identifiers, severity mapping, and extension fields containing the audit context.
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, which has the same structure returned by `get_audit_log`. This format is for custom integrations, log aggregators, or data pipelines.
Webhooks deliver audit events to HTTP endpoints with delivery guarantees. 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 and replay.
To query the DLQ:
{
"command": "get_webhook_dlq",
"admin_token": "your-admin-token"
}This command returns an `entries` array of failed webhook events with original payload, error, and timestamps.
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 metrics can be scraped from the registry’s metrics endpoint to set up alerts for delivery failures or DLQ growth.