Skip to main content
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

Login success, login failure, logout, registration, password forgot, password reset, email verification, and admin impersonation.
User creation (admin invites), deletion, deactivation, reactivation, role changes, and Craft access changes.
User-group creation, rename, deletion, membership changes, permission changes, and group-manager changes. Changes made through SCIM use the same actions.
Create / update / delete of LLM providers, connectors, connector-credential pairs, API keys, and credentials, plus selected workspace settings and credential-access (decrypt) events.
Writes that a scoped permission gate refuses, for example a group manager acting outside the groups they manage.

How it works

Audit events are emitted as INFO 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.
Run Onyx with LOG_FORMAT=json so that all log records — not just audit events — are machine-parseable, and request/tenant context is promoted to top-level fields. This makes filtering and parsing in your shipper much simpler.

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

Every action 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 extra context 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.