Set up database auditing

Capture Hyper-Converged Database (HCD) activity to a binary audit log. Each node only records the events that happen locally. Use the configuration to refine the type of events captured. HCD provides the following customizations:

Keyspace filtering: Capture activity in every keyspace or only targeted keyspaces.
Category filtering: Identify event categories to limit the number of events captured.
User filtering: Track the activity of particular users by their login username.
Node specific: Enable auditing on specific nodes, an entire datacenter, or the whole cluster.

Enable audit logging

You configure audit logging options per node, so settings can differ across nodes. HCD records database activity using the BinAuditLogger, which writes events as binary log files to a configurable directory.

To enable audit logging, set the audit_logging_options in the cassandra.yaml file:

Locate the cassandra.yaml configuration file.

The location of the cassandra.yaml file depends on your installation type:
- Package installations: /etc/hcd/cassandra/cassandra.yaml
- Tarball installations: INSTALL_DIRECTORY/resources/cassandra/conf/cassandra.yaml
Set enabled: true and configure the options as needed:
```
audit_logging_options:
    enabled: true
    logger:
      - class_name: BinAuditLogger
#    audit_logs_dir:
#    included_keyspaces:
#    excluded_keyspaces: system, system_schema, system_virtual_schema
#    included_categories:
#    excluded_categories:
#    included_users:
#    excluded_users:
#    roll_cycle: HOURLY
#    block: true
#    max_queue_weight: 268435456      # 256 MiB
#    max_log_size: 17179869184        # 16 GiB
#    archive_command:
#    max_archive_retries: 10
```
- enabled: true: Enables audit logging after the next start up.
- logger: BinAuditLogger: Writes audit events as binary log files.
- audit_logs_dir: Directory where binary audit log files are written. If not set, defaults to the log.dir system property.
- roll_cycle: How frequently the binary log file rolls over. Default: HOURLY.
- block: When true, slows down write operations rather than dropping audit log entries if the queue is full. Default: true.
- max_queue_weight: Maximum number of bytes of data in the queue before block takes effect. Default: 268435456 (256 MiB).
- max_log_size: Maximum size in bytes for the audit log directory. If archive_command is not set, the oldest files are deleted when this limit is reached. Default: 17179869184 (16 GiB).
- archive_command: Optional shell command to run when a log file is rolled. Use %path as a placeholder for the file path, for example /path/to/script.sh %path. If not set, HCD automatically deletes the oldest files when max_log_size is reached. If set, the script is responsible for any cleanup — HCD does not delete old files automatically.
- max_archive_retries: Number of times to retry the archive command on failure. Default: 10.

Filter event categories

Configure which categories to capture in the audit_logging_options section of the cassandra.yaml file.

By default, HCD captures all event categories when audit_logging_options.enabled: true and the filters (included_categories and excluded_categories) are commented out:

audit_logging_options:
    enabled: true
    logger:
      - class_name: BinAuditLogger
#    included_categories:
#    excluded_categories:

To set filters, uncomment one of the following parameters, and then set the value to the relevant event categories:

included_categories: Includes only listed categories, and excludes all others.
excluded_categories: Excludes listed categories, and includes all others.

For example, to include only data retrieval and manipulation events:

audit_logging_options:
    enabled: true
    logger:
      - class_name: BinAuditLogger
    included_categories: QUERY, DDL, AUTH
#    excluded_categories:

Audit logging event categories and types

All events have both a category and a type. A type usually maps directly to a CQL command.

The following tables list all types in each category.

`DDL` category

The DDL category includes data definition language type events that modify the database schema:

Event type CQL command

Event type	CQL command
`ADD_KS`	CREATE KEYSPACE
`DROP_KS`	DROP KEYSPACE
`UPDATE_KS`	ALTER KEYSPACE
`ADD_CF`	CREATE TABLE
`DROP_CF`	DROP TABLE
`UPDATE_CF`	ALTER TABLE
`CREATE_INDEX`	CREATE INDEX
`DROP_INDEX`	DROP INDEX
`CREATE_TYPE`	CREATE TYPE
`DROP_TYPE`	DROP TYPE
`UPDATE_TYPE`	ALTER TYPE
`CREATE_FUNCTION`	CREATE FUNCTION
`DROP_FUNCTION`	DROP FUNCTION
`CREATE_AGGREGATE`	CREATE AGGREGATE
`DROP_AGGREGATE`	DROP AGGREGATE
`CREATE_VIEW`	CREATE MATERIALIZED VIEW
`DROP_VIEW`	DROP MATERIALIZED VIEW
`ALTER_VIEW`	ALTER MATERIALIZED VIEW

ADD_KS

DROP_KS

UPDATE_KS

ADD_CF

DROP_CF

UPDATE_CF

CREATE_INDEX

DROP_INDEX

CREATE_TYPE

DROP_TYPE

UPDATE_TYPE

CREATE_FUNCTION

DROP_FUNCTION

CREATE_AGGREGATE

DROP_AGGREGATE

CREATE_VIEW

CREATE MATERIALIZED VIEW

DROP_VIEW

DROP MATERIALIZED VIEW

ALTER_VIEW

ALTER MATERIALIZED VIEW

`DML` category

The DML category captures events related to data manipulation language operations in the database:

Event type CQL command

Event type	CQL command
`SET_KS`	USE
`INSERT`	INSERT
`BATCH`	BATCH
`TRUNCATE`	TRUNCATE
`CQL_UPDATE`	UPDATE
`CQL_DELETE`	DELETE
`CQL_PREPARE_STATEMENT`	Cassandra driver prepared statement, such as a Java driver prepared statement
`MANAGEMENT_API_OP`

SET_KS

INSERT

BATCH

TRUNCATE

CQL_UPDATE

CQL_DELETE

CQL_PREPARE_STATEMENT

Cassandra driver prepared statement, such as a Java driver prepared statement

MANAGEMENT_API_OP

`DCL` category

The DCL category captures events related to database control, role, and permission changes:

Event type CQL command

Event type	CQL command
`CREATE_ROLE`	CREATE ROLE
`ALTER_ROLE`	ALTER ROLE
`DROP_ROLE`	DROP ROLE
`LIST_ROLES`	LIST ROLES
`LIST_USERS`	LIST USERS
`LIST_PERMISSIONS`	LIST PERMISSIONS
`GRANT`	GRANT
`REVOKE`	REVOKE
`RESTRICT`	RESTRICT
`UNRESTRICT`	UNRESTRICT
`RESTRICT_ROWS_STATEMENT`	RESTRICT ROWS
`UNRESTRICT_ROWS_STATEMENT`	UNRESTRICT ROWS

CREATE_ROLE

ALTER_ROLE

DROP_ROLE

LIST_ROLES

LIST_USERS

LIST_PERMISSIONS

GRANT

REVOKE

RESTRICT

UNRESTRICT

RESTRICT_ROWS_STATEMENT

RESTRICT ROWS

UNRESTRICT_ROWS_STATEMENT

UNRESTRICT ROWS

`QUERY` category

The QUERY category captures events related to data retrieval operations:

Event type CQL command

Event type	CQL command
`CQL_SELECT`	SELECT
`RPC_CALL_STATEMENT`	Remote Procedure Call (RPC) statement.

CQL_SELECT

SELECT

RPC_CALL_STATEMENT

Remote Procedure Call (RPC) statement.

`AUTH` category

The AUTH category captures events related to authentication and authorization operations:

Event type CQL shell (cqlsh) command

Event type	CQL shell (`cqlsh`) command
`LOGIN_SUCCESS`	Successful login attempt from `LOGIN` or a login request sent from a Cassandra driver.
`LOGIN_ERROR`	Failed login attempt from `LOGIN` or a login request sent from a Cassandra driver.
`UNAUTHORIZED_ATTEMPT`	Unauthorized access attempt from `LOGIN` or a login request sent from a Cassandra driver.

LOGIN_SUCCESS

Successful login attempt from LOGIN or a login request sent from a Cassandra driver.

LOGIN_ERROR

Failed login attempt from LOGIN or a login request sent from a Cassandra driver.

UNAUTHORIZED_ATTEMPT

Unauthorized access attempt from LOGIN or a login request sent from a Cassandra driver.

`ERROR` category

The ERROR category captures events related to error occurrences:

Event type Information

Event type	Information
`ERROR`	CQL statement failures.
`REQUEST_FAILURE`	Failed requests.

ERROR

CQL statement failures.

REQUEST_FAILURE

Failed requests.

`UNKNOWN` category

The UNKNOWN category captures events related to unknown occurrences:

Event type Information

Event type	Information
`UNKNOWN`	Unknown events.

UNKNOWN

Unknown events.

Filter keyspaces

Configure which keyspaces to capture in audit logs in the audit_logging_options section of the cassandra.yaml file:

audit_logging_options:
    enabled: true
    logger:
      - class_name: BinAuditLogger
#    included_categories:
#    excluded_categories:
#    included_keyspaces:
#    excluded_keyspaces:

By default, both keyspace parameters are commented out, and events are captured for all keyspaces.

To filter keyspaces in audit log events, uncomment and set only one of the following parameters:

included_keyspaces: Include only matching keyspaces, and exclude all others.

When using included_keyspaces, AUTH messages are not captured.
excluded_keyspaces: Exclude matching keyspaces, and include all others.

The value must be either a regular expression (regex) or a comma-separated list of keyspace names as exact matches.

For example, HCD queries the system_local keyspace on every login. The following exclusion captures login events without capturing additional queries to system_local:

audit_logging_options:
    enabled: true
    logger:
      - class_name: BinAuditLogger
#    included_categories:
#    excluded_categories:
#    included_keyspaces:
    excluded_keyspaces: system_local

Filter users

Track specific users in audit logs in the audit_logging_options section of the cassandra.yaml:

audit_logging_options:
    enabled: true
    logger:
      - class_name: BinAuditLogger
#    included_categories:
#    excluded_categories:
#    included_keyspaces:
#    excluded_keyspaces:
#    included_users:
#    excluded_users:

By default, both *_users parameters are commented out, and audit log events are captured for all users.

To track specific users only, uncomment and set one of the following parameters:

included_users: Includes only matching users, and excludes all others.
excluded_users: Excludes matching users, and includes all others.

The value of these parameters must be a comma-separated list of usernames as exact matches.

The following example records audit log events for all users except hcd_admin and jim:

audit_logging_options:
    enabled: true
    logger:
      - class_name: BinAuditLogger
#    included_categories:
#    excluded_categories:
#    included_keyspaces:
#    excluded_keyspaces:
#    included_users:
    excluded_users: hcd_admin, jim

Set up database auditing

Enable audit logging

Filter event categories

Audit logging event categories and types

`DDL` category

`DML` category

`DCL` category

`QUERY` category

`AUTH` category

`ERROR` category

`UNKNOWN` category

Filter keyspaces

Filter users

See also

Was this helpful?

Give Feedback