Audit logging is available on self-hosted deployments, where you control the log pipeline.
Overview
Onyx emits a normalized, structured audit-event stream for security-relevant actions — authentication, user and access-control changes, admin configuration changes, and credential access. Every event is a single JSON object, so you can forward the stream to any SIEM — Splunk, Microsoft Sentinel, Elastic, Google Chronicle, AWS Security Lake — with no Onyx-side integration to build. Field names and the action taxonomy are shaped toward OCSF (the Open Cybersecurity Schema Framework), so events map cleanly onto the event classes most SIEMs already understand. This maps directly onto common compliance controls — SOC 2 CC7 and the NIST 800-53 / FedRAMP AU family (AU-2 auditable events, AU-3 record content, AU-6 review, AU-12 generation).What gets captured
Authentication
Authentication
Login success, login failure, logout, registration, password forgot, password reset, email verification,
and admin impersonation.
User & access management
User & access management
User creation (admin invites), deletion, deactivation, reactivation, role changes, and Craft access changes.
Group management
Group management
User-group creation, rename, deletion, membership changes, permission changes, and group-manager changes.
Changes made through SCIM use the same actions.
Configuration & resources
Configuration & resources
Create / update / delete of LLM providers, connectors, connector-credential pairs, API keys, and credentials,
plus selected workspace settings and credential-access (decrypt) events.
How it works
Audit events are emitted asINFO log records on a dedicated onyx.audit logger.
The message body of each record is a single JSON object — Onyx serializes the event itself,
so the audit line is identical regardless of your log format.
Emission is fail-safe: it never interrupts a user request or a connector run.
High-volume event classes are de-duplicated within a short window. If de-duplication is unavailable,
Onyx still emits the event, so an audit event is never silently dropped (you may see a duplicate).
The subsystem is always on — there is no enable/disable flag, output-format, or destination setting.
The only related knob is LOG_FORMAT (below), which shapes the surrounding log records;
the audit JSON body itself is identical either way.
Event schema
The
action values are a stable, append-only contract — safe to filter and build dashboards against.
New actions may be added over time; existing ones do not change meaning.
Example event
Forward to your SIEM
1
Run Onyx with JSON logging
Set
LOG_FORMAT=json so every log record is structured and carries a logger and message field.2
Ship Onyx's logs
Point Fluent Bit, Vector, the CloudWatch agent, Filebeat,
or your existing collector at the Onyx container stdout (or the mounted log files).
3
Isolate and parse the audit stream
Keep only records whose
logger starts with onyx.audit,
then parse each record’s message field as JSON to recover the event fields above.4
Route to your SIEM
Send the parsed events to your SIEM’s ingest endpoint. The OCSF-shaped fields map onto Authentication,
Account Change, User Access Management, Group Management, and API Activity event classes.
Shipper examples
Filter on the
onyx.audit prefix to capture everything.
The stream is also split into per-class child loggers — onyx.audit.authentication, onyx.audit.account_change,
onyx.audit.user_access_management, onyx.audit.group_management, onyx.audit.api_activity,
and onyx.audit.credential_access — if you want to route classes to different destinations.Event reference
Everyaction value, what triggers it, and the fields most useful for building SIEM detection rules. actor,
tenant_id, request_id, endpoint, source_ip,
and outcome are present on every event (see Event schema) and are omitted from the tables below.
Authentication
ocsf_class: authentication
User & access management
ocsf_class: account_change or user_access_management — resource_type is user.
Group management
ocsf_class: group_management — resource_type is user_group.
Changes that arrive through SCIM reuse these actions. They carry
extra.source: "scim" and extra.scim_token_name,
and the actor is the provisioning token (auth_type: "scim"). SCIM emits an event only when something changes.
Configuration & resources
ocsf_class: api_activity
Credential access
onyx.audit.credential_access
Credential-decrypt events predate the generalized schema and are emitted on a flat,
legacy field set for backward compatibility.
They share the onyx.audit logger tree and the same fail-safe / fail-open behavior,
but do not carry the generalized fields — there is no action, ocsf_class, outcome,
resource_type/resource_id, extra, or nested actor object, and the client IP is client_ip (not source_ip).
Parse this stream separately; detection rules written against the generalized schema will not match it.
Export logs for support
Enterprise self-hosted admins can download the raw server log files, including the audit stream, from Admin Panel > Export Logs. Click Export Logs to collect logs from the API server and background workers into one ZIP file. Attach the file to an Onyx support thread.Notes
- Secrets are never logged. Actor objects and
extracontext are scrubbed of credential values by design. - For Onyx Cloud (multi-tenant) deployments, audit-log forwarding is handled differently since you don’t control the log pipeline — contact us to discuss SIEM delivery options.