Audit Event Repository

Overview

The Audit Event Repository is a service component responsible for creating a persistent, append-only log of significant actions within the platform. It writes structured event data to the s2r_audit_event database table.

This component solves the problem of tracking "who did what, to what, and when" for both tenant-specific activities and platform-level administrative operations. It is called by other services to record the outcome of actions, capturing the actor, the entity acted upon, the state before and after the action, and whether the action succeeded or failed.

Key features of the audit repository include:

• Multi-Tenancy: Events are strictly partitioned by tenant. A robust tenancy model ensures that tenants can only access their own audit data, while platform-level events are isolated from all tenants.
• Secret Redaction: The repository includes mechanisms to prevent sensitive data, such as credentials, from being written to or read from the audit log.
• Structured Events: Audit events are stored with a consistent structure, including actor details, action type, target entity, state change diffs (before_state, after_state), and a correlation ID to link related operations.

How it Works

The repository provides a straightforward mechanism for recording successful and failed operations. The core logic handles tenancy context and data serialization before persisting the event to the database.

Event Persistence Flow

The process of writing an audit event follows these steps:

1. An internal service calls either the success() or failure() method with details of the completed action.
2. The repository determines if the action is a "platform event" or a "tenant event" based on the entityType.
3. The beforeState and afterState objects are serialized into JSON format. If serialization fails, the corresponding field is populated with a {"serialization":"failed"} object.
4. An INSERT statement is executed against the s2r_audit_event table. A new UUID is generated for the event's primary key, and the occurred_at timestamp is set to the current time.

The following diagram illustrates the high-level data flow for event creation:

flowchart TD
    A[Action occurs in the system] --> B[AuditRepository method is called];
    B --> C{Check entity type};
    C -- "tenant" or "fleet" --> D[Write as Platform Event];
    C -- Other types --> E[Write as Tenant Event];
    D --> F[INSERT into s2r_audit_event with tenant_id = NULL];
    E --> G[INSERT into s2r_audit_event with tenant_id = current tenant's UUID];
    F --> H[Event persisted];
    G --> H;

Tenancy Model

The audit repository implements a strict multi-tenancy model to isolate tenant data.

• Tenant Events: By default, all audit events are associated with the tenant that initiated the action. The INSERT operation omits the tenant_id column, relying on a database DEFAULT that populates it from the connection's app.tenant_id session setting. Database Row-Level Security (RLS) policies ensure that queries only return rows matching the active tenant context.

• Platform Events: Actions related to core platform management are recorded as platform events. These events have a NULL tenant_id and are not visible to any tenant. An event is classified as a platform event if its entityType is one of the following:

  • tenant (e.g., tenant provisioning)
  • fleet (e.g., fleet reconciliation)

  When writing a platform event, the repository runs the database insertion within a special platform context where the app.tenant_id session setting is unset, causing the DEFAULT to yield NULL.

Secret Redaction

To prevent accidental leakage of sensitive information, the repository implements a multi-layered secret redaction strategy for system_setting audit events.

Legacy Data Scrubbing

A one-time scrubbing operation is available to remove secrets from historical audit records written before redaction was enforced. The scrubLegacySecretSettingValues() method executes an UPDATE statement that finds all system_setting audit events for the current tenant containing secret keys in their before_state or after_state fields.

For each matched row, it rewrites the state objects by:

1. Removing all key-value pairs identified as secrets.
2. Adding a boolean flag for each removed secret (e.g., secret_key_set: true) to indicate that a value was present without exposing the value itself.

This operation is idempotent; running it a second time on the same data results in no changes.

Read-Time Redaction

As a defense-in-depth measure, all reads of audit data are expected to apply redaction logic at query time. The repository provides a helper, redactedStateSql(String column), that generates a SQL expression to perform the same redaction as the legacy scrub. This ensures that even if a row has not yet been scrubbed, its secrets are never exposed to a client reading the audit log.

API Reference

The repository exposes methods for writing audit events and managing legacy data.

Methods

success(...) and failure(...)

These methods write a new audit event to the s2r_audit_event table. The only difference is the value of the result column, which is set to "success" or "failure" respectively.

scrubLegacySecretSettingValues()

This method executes a one-time cleanup of historical system_setting audit events to redact secret values. It operates only on the events belonging to the tenant of the current request context.

• Returns: int – The number of audit rows that were updated.

Data Model: s2r_audit_event Table

All audit events are persisted to the s2r_audit_event table. The repository's insert method populates the following columns.

Troubleshooting

JSON Serialization Failures

The before_state and after_state fields in the s2r_audit_event table are populated by serializing Java objects to JSON. If this serialization process fails for any reason, the repository does not fail the write operation. Instead, it writes a specific JSON object to the corresponding column to indicate the failure:

{"serialization":"failed"}

If you encounter this value when reading the audit log, it means the state object provided by the calling service could not be converted to a valid JSON string.

Empty Query Results for Tenant

When querying for audit events, if you receive an empty result set unexpectedly, verify that the database connection has the correct tenant context (app.tenant_id) set. The security model is "fail-closed," meaning that if the tenant ID is missing from the session, the query will correctly return zero rows rather than leaking platform events or data from other tenants.

See Also

• System Settings: The secret redaction logic is closely tied to the list of secret keys defined in the System Settings service.

All SOAP-to-REST docs