Audit database commands and connections

Describes how to audit commands and connection events.

Redis Software lets you audit database connection, authentication, and command (CRUD) events. This helps you track and troubleshoot connection and data-access activity.

The following events can be tracked, depending on the configured audit mode:

• Database connection attempts
• Authentication requests, including requests for new and existing connections
• Database disconnects
• Individual database commands (CRUD operations) if command auditing is enabled

When a tracked event occurs, Redis Software sends a notification over TCP to the address and port you configure when you enable auditing. Notifications arrive in near real time for an external listener to consume, such as a TCP listener, third-party service, or related utility. Successfully sending a record to the configured endpoint doesn't guarantee that the downstream consumer received, stored, or processed it.

Redis Software doesn't require or enforce any particular SIEM or DAM vendor. Any listener that can consume the TCP notification stream works.

Example external listeners include:

• ncat: useful for debugging but not suitable for production environments.

• Imperva Sonar: a third-party service available for purchase separately from Redis Software. See Redis Onboarding Steps for more information.

• IBM Guardium

• Other SIEM or DAM platforms

In development and testing environments, you can save notifications to a local file. This is neither supported nor intended for production.

Auditing is turned off by default for performance reasons. It runs asynchronously in the background and is non-blocking: the action that triggered a notification continues regardless of the notification's status or the listener's availability.

Redis Software always favors database availability over audit completeness. If auditing fails—for example, because an internal buffer overflows or the audit destination is unreachable—database operations continue uninterrupted. Audit buffers are size-limited to prevent memory exhaustion, and dropped records are reported through the auditing metrics.

Performance considerations

Enabling command (CRUD) auditing adds processing overhead compared to connection-only auditing. Before you enable it:

• Performance impact is workload-dependent. It varies with hardware, operation mix (read-heavy vs. write-heavy), throughput, and the volume of audited events.
• Evaluate command auditing in a non-production environment before enabling it in production.
• Apply username or source IP filters to reduce the volume of audited commands and limit the performance impact.
• Allocate enough hardware resources to keep CPU utilization at a reasonable level.
• Auditing never includes replication traffic on internal connections, such as data synchronization from a primary to a replica or between Active-Active clusters, regardless of the audit configuration.

Configure cluster audit destination

Before enabling auditing on any database, configure the audit destination using one of the following methods:

PUT https://<host>:<port>/v1/cluster/auditing/db_conns
{
    "audit_protocol": "TCP",
    "audit_address": "audit-sink.example.com",
    "audit_port": <port>,
    "audit_reconnect_interval": <seconds>,
    "audit_reconnect_max_attempts": <integer>,
    "audit_queue_max_bytes": <bytes>
}

rladmin cluster config auditing db_conns \
    audit_protocol <TCP|local> \
    audit_address <address> \
    audit_port <port> \
    audit_reconnect_interval <interval in seconds> \
    audit_reconnect_max_attempts <number of attempts>

• audit_protocol sets the protocol used to send notifications. For production systems, TCP is the only supported value. Use local only for development and testing.

• audit_address sets the address where the listener receives notifications.

• audit_port sets the port where the listener receives notifications.

• audit_reconnect_interval sets the interval, in seconds, between reconnection attempts. Default is 1 second.

• audit_reconnect_max_attempts sets the maximum number of reconnection attempts. Default is 0 (infinite).

• audit_queue_max_bytes sets the maximum amount of audit data, in bytes, that can wait in the outgoing audit queue. Default is 524288 (512 KB). When the queue has no remaining capacity, new audit records can be dropped.

Local socket for testing

For testing and training, development systems can set audit_protocol to local. This setting is not supported for production use.

When audit_protocol is set to local, <address> should be set to a stream socket defined on the machine running Redis Software and <port> should not be specified.

PUT https://<host>:<port>/v1/cluster/auditing/db_conns
{
    "audit_protocol": "local",
    "audit_address": "/var/opt/redislabs/run/db-audit.sock"
}

rladmin cluster config auditing db_conns \
    audit_protocol local audit_address <socket-file>

The socket file and path must be accessible by the user and group running Redis Software.

Audit modes

Auditing is configured independently for each database with audit_settings.audit_mode:

Command auditing can't be enabled without connection auditing. connection_and_crud always includes the connection and authentication events that connection mode generates.

Enable command and connection auditing

After you configure the audit destination for your cluster, you can enable command (CRUD) and connection auditing for individual databases.

You can filter by usernames, source IP addresses, or both to manage data volume and avoid capturing irrelevant traffic. If both filters are configured, only requests matching both criteria are audited.

To enable command and connection auditing and configure filters, use an update database configuration REST API request:

PUT https://<host>:<port>/v1/bdbs/<database-id>
{
    "audit_settings": {
        "audit_mode": "connection_and_crud",
        "username_filter": {
            "enabled": true,
            "usernames": ["application-user"],
            "filter_type": "inclusive",
            "allow_while_username_unknown": false
        },
        "source_ip_filter": {
            "enabled": true,
            "ip_addresses": [],
            "cidr_ranges": ["10.20.0.0/16"],
            "filter_type": "inclusive"
        },
        "max_total_key_bytes": 131072
    }
}

Inclusive versus exclusive filters

For full CRUD auditing with clear scoping, use inclusive filters to audit only known application users or networks.

Use exclusive filters when the goal is to audit everything except specific users or networks.

Username filtering

Username filtering controls which client usernames are included in or excluded from command audit records.

Username validation:

• Each username must be 1–255 characters.
• Each username must use printable ASCII characters only.
• Usernames must not contain &, <, >, or double-quote characters.
• If username_filter.enabled is true, usernames must not be empty.

Source IP filtering

Source IP filtering controls which client IP addresses are included in or excluded from command audit records.

Source IP validation:

• ip_addresses must contain only bare IPv4 or IPv6 addresses and no ranges.
• cidr_ranges must contain only valid IPv4 or IPv6 CIDR ranges.
• If source_ip_filter.enabled is true, at least one ip_addresses or cidr_ranges entry is required.
• The combined number of ip_addresses and cidr_ranges entries cannot exceed 512.

Key byte limit

You can set the max_total_key_bytes to control how much key data is captured per command audit record. The default value is 131072 and the minimum is 0.

Partial updates

Updates to audit_settings merge with the database's existing audit configuration, so you can change one setting without resending the others. For example, the following request disables the username filter while preserving its username list and filter type:

PUT https://<host>:<port>/v1/bdbs/<database-id>
{
    "audit_settings": {
        "username_filter": {
            "enabled": false
        }
    }
}

Enable connection auditing only

After you configure the audit destination for your cluster, you can enable connection auditing only for individual databases using one of the following methods:

PUT https://<host>:<port>/v1/bdbs/<database-id>
{
    "audit_settings": {
        "audit_mode": "connection"
    }
}

rladmin tune db db:<id|name> db_conns_auditing enabled

Set policy defaults for new databases

To audit connections for new databases by default, use one of the following methods:

PUT /v1/cluster/policy
{ "db_conns_auditing": true }

rladmin tune cluster db_conns_auditing enabled

Auditing validation errors

Turn off auditing

To turn off auditing for a specific database:

PUT https://<host>:<port>/v1/bdbs/<database-id>
{
    "audit_settings": {
        "audit_mode": "disabled"
    }
}

Notification examples

Audit event notifications are reported as JSON objects.

New connection

This example reports a new connection for a database:

{
    "ts": 1779874366,
    "new_conn": {
        "id": 13001000,
        "srcip": "127.0.0.1",
        "srcp": "46252",
        "trgip": "127.0.0.1",
        "trgp": "12000",
        "bdb_name": "D1",
        "bdb_uid": "1"
    },
    "audit_worker_id": 0,
    "audit_seq": 0
}

Authentication request

Here is a sample authentication request for a database:

{
    "ts": 1779874366,
    "action": "auth",
    "id": 13001000,
    "srcip": "127.0.0.1",
    "srcp": "46252",
    "trgip": "127.0.0.1",
    "trgp": "12000",
    "bdb_name": "D1",
    "bdb_uid": "1",
    "status": 2,
    "username": "default",
    "identity": "user:default",
    "acl-rules": "allkeys +@all allchannels",
    "audit_worker_id": 0,
    "audit_seq": 1
}

Successful command

The following example shows the audit notification for a successful command, such as GET myKey:

{
    "ts": 1779874374,
    "action": "command",
    "id": 13001000,
    "srcip": "127.0.0.1",
    "srcp": "46252",
    "trgip": "127.0.0.1",
    "trgp": "12000",
    "bdb_name": "D1",
    "bdb_uid": "1",
    "status": 9,
    "command": "get",
    "keys": ["myKey"],
    "full_key_size_bytes": 3,
    "captured_key_size_bytes": 3,
    "total_keys_count": 1,
    "key_truncated": false,
    "affected_count": null,
    "audit_worker_id": 0,
    "audit_seq": 3
}

Failed command

The following example shows the audit notification for a failed command, such as when you run SET without a key:

{
    "ts": 1779874378,
    "action": "command",
    "id": 13001000,
    "srcip": "127.0.0.1",
    "srcp": "46252",
    "trgip": "127.0.0.1",
    "trgp": "12000",
    "bdb_name": "D1",
    "bdb_uid": "1",
    "status": 10,
    "command": "set",
    "keys": [],
    "full_key_size_bytes": 0,
    "captured_key_size_bytes": 0,
    "total_keys_count": 0,
    "key_truncated": false,
    "affected_count": null,
    "error": "ERR wrong number of arguments for 'set' command",
    "error_truncated": false,
    "audit_worker_id": 0,
    "audit_seq": 4
}

Close connection

Here's what's reported when a database connection is closed:

{
    "ts": 1779874380,
    "close_conn": {
        "id": 13001000,
        "srcip": "127.0.0.1",
        "srcp": "46252",
        "trgip": "127.0.0.1",
        "trgp": "12000",
        "bdb_name": "D1",
        "bdb_uid": "1"
    },
    "audit_worker_id": 0,
    "audit_seq": 5
}

Notification field reference

All audit records follow a unified JSON structure that is backward compatible with the existing authentication request format used for connection auditing.

Record types

The field that appears immediately after the timestamp ("ts") describes the action that triggered the notification:

Notification fields

The following fields can appear in audit event notifications:

Fields by record type

The following table shows which fields can appear in each record type:

Status result codes

The status field reports a numeric result code. Its meaning depends on the record type: authentication requests ("action": "auth") and commands ("action": "command") use separate sets of codes.

Authentication request status codes

For authentication request records, status reports the result of the authentication attempt:

Command status codes

For command records, status reports whether the command completed successfully:

Monitor auditing metrics

Audit delivery during sink interruptions

If the audit destination becomes unavailable, Redis Software keeps serving database traffic and reconnects according to audit_reconnect_interval and audit_reconnect_max_attempts. Records can wait in the outgoing queue (bounded by audit_queue_max_bytes) while delivery is unavailable.

Audit delivery is best effort—database operations are never delayed or rejected because a record can't be delivered. Redis Software can discard records when the queue is full, a single record exceeds the size limit, no connection to the destination is available, a send attempt fails, or queuing is disabled. Use the audit_sink_* metrics to detect these conditions.

Available metrics

You can use the following metrics exported by Redis Software to monitor your database auditing pipeline. For more information about monitoring Redis Software, see the monitoring v2 documentation.