Use the audit log
The audit log provides a history of changes to user accounts, user roles, and more.
The logs list every incoming CQL command request,
as well as authentication (successful/unsuccessful login) to a node.
Currently, there are two implementations provided.
The custom logger can be implemented and injected with the class name as a parameter in the cassandra.yaml
file.
-
BinAuditLogger
: an efficient way to log events to file in a binary format (community-recommended logger for performance) -
FileAuditLogger
: logs events toaudit/audit.log
file using slf4j logger
What does audit logging capture
Audit logging captures the following events:
-
Successful as well as unsuccessful login attempts
-
All database commands executed via native CQL protocol attempted or successfully executed
Limitations
Executing prepared statements will log the query as provided by the client in the prepare call, along with the execution timestamp and all other attributes (see below). Actual values bound for prepared statement execution will not show up in the audit log.
What gets logged
Each audit log implementation has access to the following attributes, and for the default text based logger these fields are concatenated with pipes to yield the final message.
-
user
: User name(if available) -
host
: Host IP, where the command is being executed -
source ip address
: Source IP address from where the request initiated -
source port
: Source port number from where the request initiated -
timestamp
: unix time stamp -
type
: Type of the request (SELECT, INSERT, etc.,) -
category
- Category of the request (DDL, DML, etc.,) -
keyspace
- Keyspace(If applicable) on which request is targeted to be executed -
scope
- Table/Aggregate name/ function name/ trigger name etc., as applicable -
operation
- CQL command being executed
Configuring AuditLog
Auditlog can be configured in the cassandra.yaml
file.
To use audit logging on one node, either edit that file, or enable and configure using nodetool
.
cassandra.yaml configurations for AuditLog
The following options are supported:
-
enabled
: This option enables/ disables audit log -
logger
: Class name of the logger/ custom logger. -
audit_logs_dir
: Auditlogs directory location, if not set, default to cassandra.logdir.audit or cassandra.logdir
/audit/ -
included_keyspaces
: Comma-separated list of keyspaces to be included in audit log, default - includes all keyspaces -
excluded_keyspaces
: Comma-separated list of keyspaces to be excluded from audit log, default - excludes no keyspace except system, system_schema and system_virtual_schema -
included_categories
: Comma-separated list of Audit Log Categories to be included in audit log, default - includes all categories -
excluded_categories
: Comma-separated list of Audit Log Categories to be excluded from audit log, default - excludes no category -
included_users
: Comma-separated list of users to be included in audit log, default - includes all users -
excluded_users
: Comma-separated list of users to be excluded from audit log, default - excludes no user
List of available categories are: QUERY, DML, DDL, DCL, OTHER, AUTH, ERROR, PREPARE
Use nodetool
to enable AuditLog
The nodetool enableauditlog
command enables AuditLog with the cassandra.yaml
file defaults.
Those defaults can be overridden using options with this nodetool command.
nodetool enableauditlog
Options
Option | Description |
---|---|
|
Comma-separated list of audit log categories to be excluded for audit log.
If not set, the |
|
Comma-separated list of keyspaces to be excluded for audit log.
If not set, the |
|
Comma-separated list of users to be excluded for audit log.
If not set, the |
|
Comma-separated list of audit log categories to be included for audit log.
If not set, the |
|
Comma-separated list of keyspaces to be included for audit log. If not set the value from cassandra.yaml will be used. |
|
Comma-separated list of users to be included for audit log.
If not set, the |
|
Logger name to be used for AuditLogging.
If not set, the |
nodetool
command to disable AuditLog
The nodetool disableauditlog
command disables AuditLog.
nodetool disableuditlog
nodetool
command to reload AuditLog filters
The nodetool enableauditlog
command can be used to reload auditlog filters with either defaults or previous loggername
and updated filters:
nodetool enableauditlog --loggername <Default/ existing loggerName> --included-keyspaces <New Filter values>
View the contents of AuditLog files
The auditlogviewer
is used to view the contents of the audit binlog file in human-readable text format.
auditlogviewer <path1> [<path2>...<pathN>] [options]
Options
Option | Description |
---|---|
|
Upon reaching the end of the log, continue indefinitely, waiting for more records. |
|
How often to roll the log file was rolled. Choices are: MINUTELY, HOURLY, DAILY. Default HOURLY. |
|
Display the help message |
For example, to dump the contents of audit log files to the console:
auditlogviewer /logs/cassandra/audit
results in
LogMessage: user:anonymous|host:localhost/X.X.X.X|source:/X.X.X.X|port:60878|timestamp:1521158923615|type:USE_KS|category:DDL|ks:dev1|operation:USE "dev1"
Configuring BinAuditLogger
To use BinAuditLogger
as a logger in AuditLogging, set the logger to BinAuditLogger
in the cassandra.yaml
file
under the audit_logging_options
section.
BinAuditLogger
can be futher configued using its advanced options in cassandra.yaml
.
Advanced Options for BinAuditLogger
Option | Description |
---|---|
|
Indicates if the audit log should block if the it falls behind or should drop audit log records.
Default is set to |
|
Maximum weight of in-memory queue for records waiting to be written to the audit log file before blocking or dropping the log records.
Default is set to |
|
Maximum size of the rolled files to retain on disk before deleting the oldest file. Default is set to |
|
How often to roll audit log segments so they can potentially be reclaimed.
Available options are: MINUTELY, HOURLY, DAILY,LARGE_DAILY, XLARGE_DAILY, HUGE_DAILY.
For more options, see |
Configuring FileAuditLogger
To use FileAuditLogger
as a logger in AuditLogging, set the class name in the cassandra.yaml
file and configure
the audit log events to flow through separate log file instead of system.log.
<!-- Audit Logging (FileAuditLogger) rolling file appender to audit.log -->
<appender name="AUDIT" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>${cassandra.logdir}/audit/audit.log</file>
<rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
<!-- rollover daily -->
<fileNamePattern>${cassandra.logdir}/audit/audit.log.%d{yyyy-MM-dd}.%i.zip</fileNamePattern>
<!-- each file should be at most 50MB, keep 30 days worth of history, but at most 5GB -->
<maxFileSize>50MB</maxFileSize>
<maxHistory>30</maxHistory>
<totalSizeCap>5GB</totalSizeCap>
</rollingPolicy>
<encoder>
<pattern>%-5level [%thread] %date{ISO8601} %F:%L - %msg%n</pattern>
</encoder>
</appender>
<!-- Audit Logging additivity to redirect audt logging events to audit/audit.log -->
<logger name="org.apache.cassandra.audit" additivity="false" level="INFO">
<appender-ref ref="AUDIT"/>
</logger>