Appendix A. Tarantool audit module¶

Overview¶

The Tarantool audit module writes messages that record events from the Tarantool DBMS in plain text, CSV or JSON format.

It provides you with a detailed report of all security-related activities and helps you find and fix breaches to protect your business. For example, you can see who updated user privilege and when:

{"time": "2022-04-07T13:39:36.046+0300", "remote": "", "session_type": "background", "module": "tarantool", "user": "admin", "type": "user_priv", "tag": "", "description": "Update user guest privileges for role super from none to execute"}

It is up to each company to decide exactly what activities to audit and what actions to take. System administrators, security engineers and others in charge in the company may want to audit different events for different reasons. Tarantool provides such an option for each of them.

Types of events you can monitor¶

Tarantool records various types of audit log events that you can monitor and decide whether you need to take actions:

• Admin activity – events related to actions performed by the administrator. For example, such logs record the creation of a user.
• Data access and modification – events related to authorization and authentication of users. For example, such logs record failed attempts to access secure data.
• System events – events related to modification or configuration of resources. For example, such logs record the replacement of a space.

For more details about these audit log events, see the table below.

Structure of audit log events¶

Each audit log event contains several fields to make it easy to filter and aggregate the resulting logs. They are described in the following table.

Enable the Tarantool audit log¶

By default, the audit_enable option is set to false. Set the audit_enable option to true to start working with the Tarantool audit module.

You can also set this option back to false to disable audit logging.

Choose where you want to write logs¶

By default, the audit_log option is set to nil and the Tarantool audit module sends audit logs to the default error stream (stderr). If you want to send the audit log to a file, to a pipe, or to the system logger, you need to specify this audit_log option.

box.cfg{audit_log = 'audit_tarantool.log'}
-- or
box.cfg{audit_log = 'file:audit_tarantool.log'}

box.cfg{audit_log = '| cronolog audit_tarantool.log'}
-- or
box.cfg{audit_log = 'pipe: cronolog audit_tarantool.log'}'

box.cfg{audit_log = 'syslog:identity=tarantool'}
-- or
box.cfg{audit_log = 'syslog:facility=user'}
-- or
box.cfg{audit_log = 'syslog:identity=tarantool,facility=user'}
-- or
box.cfg{audit_log = 'syslog:server=unix:/dev/log'}

Configure a blocking mode¶

By default, the audit_nonblock option is set to true and Tarantool will not block during logging if the system is not ready to write, dropping the message instead. Using this value may improve logging performance at the cost of losing some log messages. This option only has an effect if the output goes to syslog: or pipe:. Setting audit_nonblock to true is not allowed if the output is to a file. In this case, set audit_nonblock to false.

Configure the format of audit log events¶

You can choose the format of audit log events – plain text, CSV or JSON format.

Plain text is used by default. This human-readable format can be efficiently compressed. The JSON format is more convenient to receive log events, analyze them and integrate them with other systems if needed. Using the CSV format allows you to view audit log events in tabular form.

Use these commands to configure the format of audit log events in Tarantool.

box.cfg{audit_log = 'audit.log', audit_format = 'plain'}

box.cfg{audit_log = 'audit.log', audit_format = 'json'}

box.cfg{audit_log = 'audit.log', audit_format = 'csv'}

Use filters¶

Tarantool’s extensive filtering options help you write only the events you need to the audit log.

To set filters, use the box.cfg.audit_filter option.

You have more than 10 values for this option, which you can find in the following table.

local audit = require('audit')

box.cfg{audit_log = 'audit.log', audit_filter = 'custom,user_create', audit_format = 'csv'}
-- The Tarantool audit module writes the event because a filter is set for it
box.schema.user.create('alice')
-- The Tarantool audit module will not write the event because no filter is set for it
box.schema.user.drop('alice')

Use event groups¶

You can simplify working with audit log events by using built-in groups in Tarantool. For example, you can set to record only events related to the enabling of the audit log, or only events related to a space.

Select one or more available groups to record the events you need:

Warning

Be careful when selecting all and data operations. The more events you record, the slower the requests will be processed over time. It is recommended that you select only those groups whose events your company really needs to monitor and analyze.

• all – records absolutely all events.
• audit (audit_enable) – records only events of audit enabling.
• ddl (space_create, space_alter, space_drop) – records events for creating, altering and dropping a space.
• data operations (space_select, space_insert, space_replace, space_delete) – records events for selecting, inserting, replacing, or deleting a space.
• compatibility (auth, priv, disconnect, password_change , access_denied) – records only events of user authorization, granted privileges, disconnection, user password change, and denied access.
• custom – records user-defined events.

Use API to create user-defined events¶

In addition, Tarantool provides you with an API that allows you to write user-defined audit log events.

For this, you can use the audit.log() function that takes one of the following values:

• Message string. Printed to the audit log with type message. Example: audit.log('Hello, World!').
• Format string and arguments. Passed to string format and then output to the audit log with type message. Example: audit.log('Hello, %s!', 'World').
• Table with audit log field values. The table must contain at least one field – description. Example: audit.log({type = 'custom_hello', description = 'Hello, World!'}).

Using the field audit.new(), you can create a new log module that allows you to avoid passing all custom audit log fields each time audit.log() is called. It takes a table of audit log field values (same as audit.log()).

local my_audit = audit.new({type = 'custom_hello', module = 'my_module'})

my_audit:log('Hello, Alice!')

my_audit:log({tag = 'admin', description = 'Hello, Bob!'})

-- is equivalent to

audit.log({type = 'custom_hello', module = 'my_module',

description = 'Hello, Alice!'})

audit.log({type = 'custom_hello', module = 'my_module',

tag = 'admin', description = 'Hello, Bob!'})

local audit = require('audit')

box.cfg{audit_log = 'audit.log', audit_filter = 'custom', audit_format = 'csv'}

audit.log('Hello, Alice!')

audit.log('Hello, %s!', 'Bob')

audit.log({type = 'custom_hello', description = 'Hello, Eve!'})

audit.log({type = 'custom_farewell', user = 'eve', module = 'custom', description = 'Farewell, Eve!'})

local my_audit = audit.new({module = 'my_module', tag = 'default'})

my_audit:log({description = 'Message 1'})

my_audit:log({description = 'Message 2', tag = 'my_tag'})

my_audit:log({description = 'Message 3', module = 'other_module'})

Use read commands¶

To easily read the audit log events in the needed form, use the different commands:

• cat – prints one or more files

• grep – prints a specific text

• head – prints the first N lines of the file

• tail – prints the last N lines of the file

  Note

  These are the basic commands to help you read the logs. If necessary, you can use other commands.

Tips¶