Audit module

Audit log events

The Tarantool audit log module can record various 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.
• Access events – events related to authorization and authentication of users. For example, such logs record failed attempts to access secure data.
• Data access and modification – events of data manipulation in the storage.
• System events – events related to modification or configuration of resources. For example, such logs record the replacement of a space.
• Custom events – any events added manually using the audit module API.

The full list of available audit log events is provided in the table below:

Event groups

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

Tarantool provides the following event groups:

• all – all events.

  Note

  Events call and eval are included only into the all group.

• audit – audit_enable event.

• auth – authorization events: auth_ok, auth_fail.

• priv – events related to authentication, authorization, users, and roles: user_create, user_drop, role_create, role_drop, user_enable, user_disable, user_grant_rights, user_revoke_rights, role_grant_rights, role_revoke_rights.

• ddl – events of space creation, altering, and dropping: space_create, space_alter, space_drop.

• dml – events of data modification in spaces: space_insert, space_replace, space_delete.

• data_operations – events of data modification or selection from spaces: space_select, space_insert, space_replace, space_delete.

• compatibility – events available in Tarantool before the version 2.10.0. auth_ok, auth_fail, disconnect, user_create, user_drop, role_create, role_drop, user_enable, user_disable, user_grant_rights, user_revoke_rights, role_grant_rights. role_revoke_rights, password_change, access_denied. This group enables the compatibility with earlier Tarantool versions.

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, audit logging is disabled. To enable audit logging, define the logs location by setting the box.cfg.audit_log option. Tarantool can write audit logs to a file, to a pipe, or to the system logger.

To disable audit logging, set the audit_log option to nil.

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'}

{
  "__CURSOR" : "s=81564632436a4de590e80b89b0151148;i=11519;b=def80c1464fe49d1aac8a64895d6614d;m=8c825ebfc;t=5edb27a75f282;x=7eba320f7cc9ae4d",
  "__REALTIME_TIMESTAMP" : "1668725698065026",
  "__MONOTONIC_TIMESTAMP" : "37717666812",
  "_BOOT_ID" : "def80c1464fe49d1aac8a64895d6614d",
  "_UID" : "1003",
  "_GID" : "1004",
  "_COMM" : "tarantool",
  "_EXE" : "/app/tarantool/dist/tdg-2.6.4.0.x86_64/tarantool",
  "_CMDLINE" : "tarantool init.lua <running>: core-03",
  "_CAP_EFFECTIVE" : "0",
  "_AUDIT_SESSION" : "1",
  "_AUDIT_LOGINUID" : "1003",
  "_SYSTEMD_CGROUP" : "/user.slice/user-1003.slice/user@1003.service/app.slice/app@core-03.service",
  "_SYSTEMD_OWNER_UID" : "1003",
  "_SYSTEMD_UNIT" : "user@1003.service",
  "_SYSTEMD_USER_UNIT" : "app@core-03.service",
  "_SYSTEMD_SLICE" : "user-1003.slice",
  "_SYSTEMD_USER_SLICE" : "app.slice",
  "_SYSTEMD_INVOCATION_ID" : "be368b4243d842ea8c06b010e0df62c2",
  "_MACHINE_ID" : "2e2339725deb4bc198c54ff4a2e8d626",
  "_HOSTNAME" : "vm-0.test.env",
  "_TRANSPORT" : "syslog",
  "PRIORITY" : "6",
  "SYSLOG_FACILITY" : "23",
  "SYSLOG_IDENTIFIER" : "tarantool",
  "SYSLOG_PID" : "101562",
  "_PID" : "101562",
  "MESSAGE" : "remote: session_type:background module:common.admin.auth user: type:custom_tdg_audit tag:tdg_severity_INFO description:[119eae0e-a691-42cc-9b4c-f14c499e6726] subj: \"anonymous\", msg: \"Access granted to anonymous user\"",
  "_SOURCE_REALTIME_TIMESTAMP" : "1668725698064202"
}

Select events to write to audit log

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

To select events to write to audit log, use the box.cfg.audit_filter option. Its value can be a list of events and event groups. The default value for the box.cfg.audit_filter option is compatibility, which enables logging of all events available before 2.10.0.

box.cfg{
        audit_log = 'audit.log',
        audit_filter = 'audit,auth,priv,password_change,access_denied'
       }

box.cfg{
        audit_log = 'audit.log',
        audit_filter = 'password_change'
       }

box.cfg{
        audit_log = 'audit.log',
        audit_filter = 'compatibility'
       }

box.cfg{
        audit_log = 'audit.log',
        audit_filter = 'auth,priv'
       }

box.cfg{
        audit_log = 'audit.log',
        audit_filter = 'priv,disconnect'
       }

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')

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'}

remote:
session_type:background
module:common.admin.auth
user: type:custom_tdg_audit
tag:tdg_severity_INFO
description:[5e35b406-4274-4903-857b-c80115275940]
subj: "anonymous",
msg: "Access granted to anonymous user"

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

{
    "time": "2022-11-17T21:55:49.880+0300",
    "remote": "",
    "session_type": "background",
    "module": "common.admin.auth",
    "user": "",
    "type": "custom_tdg_audit",
    "tag": "tdg_severity_INFO",
    "description": "[c26cd11a-3342-4ce6-8f0b-a4b222268b9d] subj: \"anonymous\", msg: \"Access granted to anonymous user\""
}

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

2022-11-17T21:58:03.131+0300,,background,common.admin.auth,,,custom_tdg_audit,tdg_severity_INFO,"[b3dfe2a3-ec29-4e61-b747-eb2332c83b2e] subj: ""anonymous"", msg: ""Access granted to anonymous user"""

Custom events

Tarantool provides an API for writing custom audit log events. To enable custom audit log events, specify the custom value in the box.cfg.audit_filter option.

To add a new event, 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()). The type of the log module for writing custom events must either be message or have the custom_ prefix.

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