From 53511a5f000546ad7c1f39d56a0820f1c8f27f88 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Fri, 15 Dec 2023 11:24:23 +0300 Subject: [PATCH 1/4] audit log: update section * Add `audit_log` config section * Rewrite `Audit log module` page --- .../instances.enabled/audit_log/config.yaml | 16 + .../instances.enabled/audit_log/instances.yml | 1 + .../audit_log_pipe/config.yaml | 14 + .../audit_log_pipe/instances.yml | 1 + .../audit_log_syslog/config.yaml | 16 + .../audit_log_syslog/instances.yml | 1 + doc/enterprise/audit_log.rst | 669 ++++++++---------- .../configuration/configuration_reference.rst | 324 ++++++++- doc/reference/tooling/tt_cli/search.rst | 4 +- 9 files changed, 653 insertions(+), 393 deletions(-) create mode 100644 doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml create mode 100644 doc/code_snippets/snippets/config/instances.enabled/audit_log/instances.yml create mode 100644 doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml create mode 100644 doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/instances.yml create mode 100644 doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml create mode 100644 doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/instances.yml diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml new file mode 100644 index 0000000000..257ef47c8a --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml @@ -0,0 +1,16 @@ +groups: + group001: + iproto: + listen: + - uri: '127.0.0.1:3301' + replicasets: + replicaset001: + instances: + instance001: + audit_log: + to: file + file: 'audit_tarantool.log' + filter: [ user_create,data_operations,ddl ] + format: json + spaces: [ bands ] + extract_key: true \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/audit_log/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml new file mode 100644 index 0000000000..5fbe2cdf37 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml @@ -0,0 +1,14 @@ +groups: + group001: + iproto: + listen: + - uri: '127.0.0.1:3301' + replicasets: + replicaset001: + instances: + instance001: + audit_log: + to: pipe + pipe: 'cronolog audit_tarantool.log' + format: json + extract_key: false \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml new file mode 100644 index 0000000000..b28e40ec5c --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml @@ -0,0 +1,16 @@ +groups: + group001: + iproto: + listen: + - uri: '127.0.0.1:3301' + replicasets: + replicaset001: + instances: + instance001: + audit_log: + to: syslog + syslog_server: 'unix:/dev/log' + syslog_facility: user + syslog_identity: 'tarantool' + filter: 'audit,auth,priv,password_change,access_denied' + extract_key: false \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/enterprise/audit_log.rst b/doc/enterprise/audit_log.rst index 9c3a2d814b..8ddb65d05e 100644 --- a/doc/enterprise/audit_log.rst +++ b/doc/enterprise/audit_log.rst @@ -3,24 +3,12 @@ Audit module ============ -The audit module available in Tarantool Enterprise Edition writes messages that record Tarantool events in plain text, CSV, or JSON format. +The audit module available in Tarantool Enterprise Edition writes messages that record Tarantool events in plain text, +CSV, or JSON format. It provides detailed reports of security-related activities and helps you find and fix breaches to protect your business. For example, you can see who created a new user -and when: - -.. code-block:: json - - { - "time": "2022-04-07T13:39:36.046+0300", - "remote": "", - "session_type": "background", - "module": "tarantool", - "user": "admin", - "type": "user_create", - "tag": "", - "description": "Create user alice" - } +and when. It is up to each company to decide exactly what activities to audit and what actions to take. System administrators, security engineers, and people in charge of the company may want to @@ -34,7 +22,7 @@ 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. +* Administrator 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. @@ -53,89 +41,116 @@ The full list of available audit log events is provided in the table below: .. container:: table .. list-table:: - :widths: 30 35 35 + :widths: 20 25 20 35 :header-rows: 1 * - Event - Type of event written to the audit log + - Severity level - Example of an event description * - Audit log enabled for events - - ``audit_enable`` + - ``audit_enable`` + - ``VERBOSE`` - * - :ref:`User-defined events ` - ``custom`` + - ``INFO`` (default) - * - User authorized successfully - - ``auth_ok`` + - ``auth_ok`` + - ``VERBOSE`` - ``Authenticate user `` * - User authorization failed - - ``auth_fail`` + - ``auth_fail`` + - ``ALARM`` - ``Failed to authenticate user `` * - User logged out or quit the session - - ``disconnect`` + - ``disconnect`` + - ``VERBOSE`` - ``Close connection`` * - User created - ``user_create`` + - ``INFO`` - ``Create user `` * - User dropped - ``user_drop`` + - ``INFO`` - ``Drop user `` * - Role created - ``role_create`` + - ``INFO`` - ``Create role `` * - Role dropped - ``role_drop`` + - ``INFO`` - ``Drop role `` * - User disabled - - ``user_disable`` + - ``user_disable`` + - ``INFO`` - ``Disable user `` * - User enabled - - ``user_enable`` + - ``user_enable`` + - ``INFO`` - ``Enable user `` * - User granted rights - ``user_grant_rights`` + - ``INFO`` - ``Grant rights for to user `` * - User revoked rights - ``user_revoke_rights`` + - ``INFO`` - ``Revoke rights for from user `` * - Role granted rights - ``role_grant_rights`` + - ``INFO`` - ``Grant rights for to role `` * - Role revoked rights - ``role_revoke_rights`` + - ``INFO`` - ``Revoke rights for from role `` * - User password changed - - ``password_change`` + - ``password_change`` + - ``INFO`` - ``Change password for user `` - * - Failed attempt to access secure data (personal records, details, geolocation, etc.) + * - Failed attempt to access secure data (for example, personal records, details, geolocation) - ``access_denied`` + - ``ALARM`` - `` denied to `` * - Expressions with arguments evaluated in a string - ``eval`` + - ``INFO`` - ``Evaluate expression `` * - Function called with arguments - ``call`` + - ``VERBOSE`` - ``Call function with arguments `` * - Iterator key selected from ``space.index`` - ``space_select`` + - ``VERBOSE`` - ``Select from .`` * - Space created - - ``space_create`` + - ``space_create`` + - ``INFO`` - ``Create space `` * - Space altered - - ``space_alter`` + - ``space_alter`` + - ``INFO`` - ``Alter space `` * - Space dropped - - ``space_drop`` + - ``space_drop`` + - ``INFO`` - ``Drop space `` * - Tuple inserted into space - - ``space_insert`` + - ``space_insert`` + - ``VERBOSE`` - ``Insert tuple into space `` * - Tuple replaced in space - - ``space_replace`` + - ``space_replace`` + - ``VERBOSE`` - ``Replace tuple with in space `` * - Tuple deleted from space - - ``space_delete`` + - ``space_delete`` + - ``VERBOSE`` - ``Delete tuple from space `` @@ -147,476 +162,350 @@ The full list of available audit log events is provided in the table below: and :ref:`Module net.box -- eval `. To separate the data, specify ``console`` or ``binary`` in the session field. -.. _audit-log-event-groups: - -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 :ref:`events `. - - .. note:: - - Events ``call`` and ``eval`` are included only into the ``all`` group. - -* ``audit`` -- ``audit_enable`` event. +.. _audit-log-structure: -* ``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. - -.. warning:: +Structure of audit log event +---------------------------- - Be careful when recording ``all`` and ``data_operations`` event groups. - 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. +Each audit log event contains a number of fields that can be used to filter and aggregate the resulting logs. +An example of a Tarantool audit log entry in JSON: -.. _audit-log-structure: +.. code-block:: json -Structure of audit log events ------------------------------ + { + "time": "2024-01-15T13:39:36.046+0300", + "uuid": "cb44fb2b-5c1f-4c4b-8f93-1dd02a76cec0", + "severity": "VERBOSE", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "auth_ok", + "tag": "", + "description": "Authenticate user Admin" + } -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. +Each event consists of the following fields: .. container:: table .. list-table:: :widths: 30 35 35 :header-rows: 1 - + * - Field - Description - Example of a log field display - * - ``time`` - - Time of the event - - 2022-04-07T13:20:05.327+0300 - * - ``remote`` - - Remote host that triggered the event - - 100.96.163.226:48722 - * - ``session_type`` - - Session type - - console - * - ``module`` + * - ``time`` + - Time of the event + - ``2024-01-15T16:33:12.368+0300`` + * - ``uuid``. Since :doc:`3.0.0 ` + - A unique identifier of audit log event + - ``cb44fb2b-5c1f-4c4b-8f93-1dd02a76cec0`` + * - ``severity``. Since :doc:`3.0.0 ` + - A severity level + - ``VERBOSE`` + * - ``remote`` + - Remote host that triggered the event + - ``unix/:(socket)`` + * - ``session_type`` + - Session type + - ``console`` + * - ``module`` - Audit log module. Set to ``tarantool`` for system events; - can be overwritten for user-defined events - - tarantool - * - ``user`` - - User who triggered the event - - admin - * - ``type`` - - Audit event type - - access_denied - * - ``tag`` - - A text field that can be overwritten by the user - - - * - ``description`` - - Human-readable event description - - Authenticate user Alice - - .. warning:: - - You can set all these parameters only once. Unlike many other parameters in ``box.cfg``, - they cannot be changed. - -.. _audit-log-start: - -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. + can be overwritten for user-defined events + - ``tarantool`` + * - ``user`` + - User who triggered the event + - ``admin`` + * - ``type`` + - Audit event type + - ``auth_ok`` + * - ``tag`` + - A text field that can be overwritten by the user + - + * - ``description`` + - Human-readable event description + - ``Authenticate user Admin`` -To disable audit logging, set the ``audit_log`` option to ``nil``. + .. warning:: -Write to a file -~~~~~~~~~~~~~~~ + You can set all these parameters only once. -.. code-block:: lua +.. _audit-log-event-groups: - box.cfg{audit_log = 'audit_tarantool.log'} - -- or - box.cfg{audit_log = 'file:audit_tarantool.log'} +Event groups +------------ -This opens the ``audit_tarantool.log`` file for output in the server’s default directory. -If the ``audit_log`` string has no prefix or the prefix ``file:``, the string is interpreted as a file path. +Built-in event groups are used to filter the event types that you want to audit. +For example, you can set to record only authorization events, +or only events related to a space. -Send to a pipe -~~~~~~~~~~~~~~ +Tarantool provides the following event groups: -.. code-block:: lua + * ``all`` -- all :ref:`events `. - box.cfg{audit_log = '| cronolog audit_tarantool.log'} - -- or - box.cfg{audit_log = 'pipe: cronolog audit_tarantool.log'}' - -This starts the `cronolog `_ program when the server starts -and sends all ``audit_log`` messages to cronolog's standard input (``stdin``). -If the ``audit_log`` string starts with '|' or contains the prefix ``pipe:``, -the string is interpreted as a Unix `pipeline `_. + .. note:: -Send to syslog -~~~~~~~~~~~~~~ + Events ``call`` and ``eval`` are included only in the ``all`` group. -.. warning:: + * ``audit`` -- ``audit_enable`` event. - Below is an example of writing audit logs to a directory shared with the system logs. - Tarantool allows this option, but it is not recommended to do this to avoid difficulties - when working with audit logs. System and audit logs should be written separately. - To do this, create separate paths and specify them. + * ``auth`` -- authorization events: ``auth_ok``, ``auth_fail``. -This example setting sends the audit log to syslog: + * ``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``. -.. code-block:: lua - - 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'} - -If the ``audit_log`` string starts with "syslog:", -it is interpreted as a message for the `syslogd `_ program, -which normally runs in the background of any Unix-like platform. -The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...', 'syslog:server=...' or a combination. - -The ``syslog:identity`` setting is an arbitrary string that is placed at the beginning of all messages. -The default value is ``tarantool``. - -The ``syslog:facility`` setting is currently ignored, but will be used in the future. -The value must be one of the `syslog `_ keywords -that tell ``syslogd`` where to send the message. -The possible values are ``auth``, ``authpriv``, ``cron``, ``daemon``, ``ftp``, -``kern``, ``lpr``, ``mail``, ``news``, ``security``, ``syslog``, ``user``, ``uucp``, -``local0``, ``local1``, ``local2``, ``local3``, ``local4``, ``local5``, ``local6``, ``local7``. -The default value is ``local7``. - -The ``syslog:server`` setting is the locator for the syslog server. -It can be a Unix socket path starting with "unix:" or an ipv4 port number. -The default socket value is ``/dev/log`` (on Linux) or ``/var/run/syslog`` (on Mac OS). -The default port value is 514, which is the UDP port. - -If you log to a file, Tarantool will reopen the audit log at `SIGHUP `_. -If log is a program, its pid is stored in the ``audit_log.logger_pid`` variable. -You need to send it a signal to rotate logs. - -An example of a Tarantool audit log entry in the syslog: + * ``ddl`` -- events of space creation, altering, and dropping: + ``space_create``, ``space_alter``, ``space_drop``. -.. code-block:: json + * ``dml`` -- events of data modification in spaces: + ``space_insert``, ``space_replace``, ``space_delete``. - { - "__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 : 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" - } + * ``data_operations`` -- events of data modification or selection from spaces: + ``space_select``, ``space_insert``, ``space_replace``, ``space_delete``. -.. _audit-log-filters: + * ``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. -Select events to write to audit log ------------------------------------ +.. warning:: -Tarantool's extensive filtering options help you write only the events you need to the audit log. + Be careful when recording ``all`` and ``data_operations`` event groups. + The more events you record, the slower the requests are processed over time. + It is recommended that you select only those groups + whose events your company needs to monitor and analyze. -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. +.. _audit-log-custom: -.. code-block:: lua +Create user-defined events +-------------------------- - box.cfg{ - audit_log = 'audit.log', - audit_filter = 'audit,auth,priv,password_change,access_denied' - } +Tarantool provides an API for writing user-defined audit log events. +To enable custom events, specify the ``custom`` value in the :ref:`audit_log.filter ` option. -.. _audit-log-combinations: +To add a new event, use the ``audit.log()`` function that takes one of the following values: -Customize your filters -~~~~~~~~~~~~~~~~~~~~~~ +* Message string. Printed to the audit log with type ``message``. + Example: ``audit.log('Hello, World!')``. -You can customize the filters and use different combinations of filters for your purposes. +* Format string and arguments. Passed to string format and then output to the audit log with type ``message``. + Example: ``audit.log('Hello, %s!', 'World')``. -Filter based on a specific event -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +* Table with audit log field values. The table must contain at least one field -- ``description``. + Example: ``audit.log({type = 'custom_hello', description = 'Hello, World!'})``. -You can set only certain events that you need to record. +Using the option ``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 user-defined events must either be ``message`` or +have the ``custom_`` prefix. -For example, select ``password_change`` to monitor the users who have changed their passwords. +Example +~~~~~~~ .. code-block:: lua - box.cfg{ - audit_log = 'audit.log', - audit_filter = 'password_change' - } + audit.log({type = 'custom_hello', module = 'my_module', description = 'Hello, Alice!' }) + audit.log({type = 'custom_hello', module = 'my_module', tag = 'admin', description = 'Hello, Bob!'}) -Filter based on a specific group -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You can set one of the groups of events that you need to record. +Some user-defined audit log fields (``time``, ``remote``, ``session_type``) +are set in the same way as for a system event. +If a field is not overwritten, it is set to the same value as for a system event. -For example, select ``compatibility`` to monitor only events of user authorization, -granted privileges, disconnection, user password change, and denied access. +Some audit log fields you can overwrite with ``audit.new()`` and ``audit.log()``: -.. code-block:: lua +* ``type`` +* ``user`` +* ``module`` +* ``tag`` +* ``description`` - box.cfg{ - audit_log = 'audit.log', - audit_filter = 'compatibility' - } +.. note:: -Filter based on multiple groups -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + To avoid confusion with system events, the value of the type field must either be ``message`` (default) + or begin with the ``custom_`` prefix. Otherwise, you receive the error message. + User-defined events are filtered out by default.. -You can specify multiple groups depending on the purpose. -For example, select ``auth`` and ``priv`` to see only events related to authorization and granted privileges. +.. _audit-log-example: -.. code-block:: lua +Example: using Tarantool audit log +---------------------------------- - box.cfg{ - audit_log = 'audit.log', - audit_filter = 'auth,priv' - } +The example shows how to enable and configure audit logging and write logs to a selected destination (a file, a pipe, +or a system logger). -Filter based on a group and a specific event -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Before starting this example: -You can specify a group and a certain event depending on the purpose. +#. Install the :ref:`tt ` utility. -For example, you can select ``priv`` and ``disconnect`` to see only events related to -granted privileges and disconnect events. +#. Create a tt environment in the current directory by executing the :ref:`tt init ` command. -.. code-block:: lua +#. Inside the ``instances.enabled`` directory of the created tt environment, create the ``audit_log`` directory. - box.cfg{ - audit_log = 'audit.log', - audit_filter = 'priv,disconnect' - } +#. Inside ``instances.enabled/audit_log``, create the ``instances.yml`` and ``config.yaml`` files: -Example -~~~~~~~ + - ``instances.yml`` specifies instances to run in the current environment and should look like this: -Run the command to filter: + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/instances.yml + :language: yaml + :end-at: instance001: + :dedent: -.. code-block:: lua + - The ``config.yaml`` file stores an audit log configuration (the ``audit_log`` section). The configuration is described in detail in the next section. - local audit = require('audit') +.. _audit-log-enable: - 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') +Enable audit logging +~~~~~~~~~~~~~~~~~~~~ -.. _audit-log-nonblock: +To enable audit logging, define the log location using the +:ref:`audit_log.to ` option in the ``audit_log`` section of the configuration file. +Possible logs locations: -Configure a blocking mode -------------------------- +* a :ref:`file ` +* a :ref:`pipe ` +* a :ref:`system logger ` -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``. +To disable audit logging, set the ``audit_log`` option to ``devnull``. -.. _audit-log-format: +In this tutorial, the logs are written to a file. To do this, set the +:ref:`audit_log.to ` option to ``file``. +After that, you can define a file path (for example, ``audit_tarantool.log``) using +the :ref:`audit_log.file ` option. +If the option is omitted, the default path is used: ``var/log/instance001/audit.log``. -Configure the format of audit log events ----------------------------------------- +The configuration might look as follows: -You can choose the format of audit log events -- plain text, CSV or JSON format. +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: audit_tarantool.log + :dedent: -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. +If you log to a file, Tarantool reopens the audit log at `SIGHUP `_. -Use these commands to configure the format of audit log events in Tarantool. +.. _audit-log-filters: -Plain text -~~~~~~~~~~ +Filter the events +~~~~~~~~~~~~~~~~~ -.. code-block:: lua +Tarantool's extensive filtering options help you write only the events you need to the audit log. - box.cfg{audit_log = 'audit.log', audit_format = 'plain'} +To select the recorded events, use the :ref:`audit_log.filter ` option. +Its value can be a list of events and event groups. +You can customize the filters and use different combinations of them for your purposes. +Possible filtering options: -Example: +- Filter by event. You can set a list of :ref:`events ` to be recorded. For example, select + ``password_change`` to monitor the users who have changed their passwords: -.. code-block:: text + .. code-block:: yaml - 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" + audit_log: + filter: [ password_change ] -JSON format -~~~~~~~~~~~ +- Filter by group. You can specify a list of :ref:`event groups ` to be recorded. For example, + select ``auth`` and ``priv`` to see only events related to authorization and granted privileges. -.. code-block:: lua + .. code-block:: yaml - box.cfg{audit_log = 'audit.log', audit_format = 'json'} + audit_log: + filter: [ auth,priv ] -Example: +- Filter by group and event. You can specify a group and a certain event depending on the purpose. + For example, you can select ``user_create``, ``data_operations``, and ``ddl`` to see the events related to -.. code-block:: json + * user creation + * space creation, altering, and dropping + * data modification or selection from spaces - { - "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\"" - } + Let's add this filter to our configuration file: -CSV format -~~~~~~~~~~ + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: audit_tarantool.log + :dedent: -.. code-block:: lua - box.cfg{audit_log = 'audit.log', audit_format = 'csv'} +.. _audit-log-format: -Example: +Set the format of audit log events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: text +Use the :ref:`audit_log.format ` option to choose the format of audit log events +-- plain text, CSV, or JSON. - 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""" +JSON is used by default. It is more convenient to receive log events, analyze them, and integrate them with other systems if needed. +The plain format can be efficiently compressed. +The CSV format allows you to view audit log events in tabular form. -.. _audit-log-custom: +In this tutorial, set the format to JSON: -Create user-defined events --------------------------- +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: format: json + :dedent: -Tarantool provides an API for writing user-defined audit log events. +.. _audit-log-spaces: -To add a new event, use the ``audit.log()`` function that takes one of the following values: +Specify the spaces to be logged +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Message string. Printed to the audit log with type ``message``. Example: ``audit.log('Hello, World!')``. +Since: :doc:`3.0.0 `, it is possible to :ref:`specify a list of space names ` +for which data operation events should be logged. -* Format string and arguments. Passed to string format and then output to the audit log with type message. - Example: ``audit.log('Hello, %s!', 'World')``. +To log the events from the ``bands`` space only, specify the option in the configuration file: -* Table with audit log field values. The table must contain at least one field -- description. - Example: ``audit.log({type = 'custom_hello', description = 'Hello, World!'})``. +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :liines: 15 + :dedent: -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 user-defined events must either be ``message`` or -have the ``custom_`` prefix. +.. _audit-log-extract: -Example -~~~~~~~ +Specify the logging mode in DML events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: lua +Since: :doc:`3.0.0 `, it is possible to +force the audit subsystem to log the primary key instead of a full tuple in DML operations. - local my_audit = audit.new({type = 'custom_hello', module = 'my_module'}) - my_audit:log('Hello, Alice!') - my_audit:log({tag = 'admin', description = 'Hello, Bob!'}) +To do so, set the :ref:`audit_log.extract_key ` option to ``true``. - -- 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!'}) +The resulting configuration in ``config.yaml`` now looks as follows: +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :dedent: -Some user-defined audit log fields (``time``, ``remote``, ``session_type``) -are set in the same way as for a system event. -If a field is not overwritten, it is set to the same value as for a system event. +.. _audit-log-run-example: -Some audit log fields you can overwrite with ``audit.new()`` and ``audit.log()``: +Check the example +~~~~~~~~~~~~~~~~~ -* type -* user -* module -* tag -* description +After the configuration is done, execute the :ref:`tt start ` command from the :ref:`tt environment directory `: - .. note:: - - To avoid confusion with system events, the value of the type field must either be ``message`` (default) - or begin with ``custom_``. Otherwise you will get the error message. - User-defined events are filtered out by default. - To enable user-defined audit log events, you must add ``custom`` to ``box.cfg.audit_filter``. + .. code-block:: console -Example -~~~~~~~ + $ tt start audit_log + • Starting an instance [audit_log:instance001]... -.. code-block:: lua +After that, connect to the instance with :ref:`tt connect `: + +.. code-block:: console - local audit = require('audit') + $ tt connect audit_log:instance001 - 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!'}) +In the interactive console. run the following commands: - 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'}) .. _audit-log-read: @@ -647,8 +536,8 @@ How many events can be recorded? If you write to a file, the size of the Tarantool audit module is limited by the disk space. If you write to a system logger, the size of the Tarantool audit module is limited by the system logger. -If you write to a pipe, the size of the Tarantool audit module is limited by the system buffer -if the ``audit_nonblock`` = ``false``; if ``audit_nonblock`` = ``true``, there is no limit. +If you write to a pipe, the size of the Tarantool audit module is limited by the system buffer. +If the ``audit_nonblock = false``, if ``audit_nonblock`` = ``true``, there is no limit. However, it is not recommended to use the entire memory, as this may cause performance degradation and even loss of some logs. diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index d3a758a44e..99c8ad93af 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -11,6 +11,328 @@ This topic describes all :ref:`configuration parameters ` provide Most of the configuration options described in this reference can be applied to a specific instance, replica set, group, or to all instances globally. To do so, you need to define the required option at the :ref:`specified level `. +.. _configuration_reference_audit: + +audit_log +--------- + +.. admonition:: Enterprise Edition + :class: fact + + Configuring ``audit_log`` parameters is available in the `Enterprise Edition `_ only. + + +The ``audit_log`` section defines configuration parameters related to :ref:`audit logging `. + +.. NOTE:: + + ``audit_log`` can be defined in any :ref:`scope `. + + +* :ref:`audit_log.extract_key ` +* :ref:`audit_log.file ` +* :ref:`audit_log.filter ` +* :ref:`audit_log.format ` +* :ref:`audit_log.nonblock ` +* :ref:`audit_log.pipe ` +* :ref:`audit_log.spaces ` +* :ref:`audit_log.syslog_facility ` +* :ref:`audit_log.syslog_identity ` +* :ref:`audit_log.syslog_server ` +* :ref:`audit_log.to ` + +.. _configuration_reference_audit_extract_key: + +.. confval:: audit_log.extract_key + + **Since:** :doc:`3.0.0 `. + + Specify the logging mode in DML events. + If set to ``true``, the audit subsystem extracts and prints only the primary key instead of full + tuples in DML events (``space_insert``, ``space_replace``, ``space_delete``). + Otherwise, full tuples are logged. + The option may be useful in case tuples are big. + + | + | Type: boolean + | Default: false + | Environment variable: TT_AUDIT_LOG_EXTRACT_KEY + +.. _configuration_reference_audit_file: + +.. confval:: audit_log.file + + Specify a file for the audit log destination. + You can set the ``file`` type using the :ref:`audit_log.to ` option. + If you write logs to a file, Tarantool reopens the audit log at `SIGHUP `_. + + | + | Type: string + | Default: 'var/log/{{ instance_name }}/audit.log' + | Environment variable: TT_AUDIT_LOG_FILE + +.. _configuration_reference_audit_filter: + +.. confval:: audit_log.filter + + Enable logging for a specified subset of audit events. + This option accepts the following values: + + * event names (for example, ``password_change``). For details, see :ref:`Audit log events `. + * event groups (for example, ``audit``). For details, see :ref:`Event groups `. + + The option contains either one value from above or a combination of them. + + To enable :ref:`user-defined audit log events `, specify the ``custom`` value in this option. + + | + | Type: array + | Possible values: 'all', 'audit', 'auth', 'priv', 'ddl', 'dml', 'data_operations', 'compatibility', + 'audit_enable', 'auth_ok', 'auth_fail', 'disconnect', 'user_create', 'user_drop', 'role_create', 'role_drop', + 'user_disable', 'user_enable', 'user_grant_rights', 'role_grant_rights', 'role_revoke_rights', 'password_change', + 'access_denied', 'eval', 'call', 'space_select', 'space_create', 'space_alter', 'space_drop', 'space_insert', + 'space_replace', 'space_delete', 'custom' + | Default: 'nil' + | Environment variable: TT_AUDIT_LOG_FILTER + +.. _configuration_reference_audit_format: + +.. confval:: audit_log.format + + Specify a format that is used for the audit log. + + **Example** + + If you set the option to ``plain``, + + .. code-block:: yaml + + audit_log: + to: file + format: plain + + the output in the file might look as follows: + + .. code-block:: text + + 2024-01-17T00:12:27.155+0300 + 4b5a2624-28e5-4b08-83c7-035a0c5a1db9 + INFO remote:unix/:(socket) + session_type:console + module:tarantool + user:admin + type:space_create + tag: + description:Create space Bands + + | + | Type: string + | Possible values: 'json', 'csv', 'plain' + | Default: 'json' + | Environment variable: TT_AUDIT_LOG_FORMAT + +.. _configuration_reference_audit_nonblock: + +.. confval:: audit_log.nonblock + + Specify the logging behavior if the system is not ready to write. + If set to ``true``, Tarantool does not block during logging if the system is non-writable and writes a message instead. + Using this value may improve logging performance at the cost of losing some log messages. + + .. note:: + + The option only has an effect if the :ref:`audit_log.to ` is set to ``syslog`` + ``pipe``. + + | + | Type: boolean + | Default: false + | Environment variable: TT_AUDIT_LOG_NONBLOCK + +.. _configuration_reference_audit_pipe: + +.. confval:: audit_log.pipe + + Specify a pipe for the audit log destination. + You can set the ``pipe`` type using the :ref:`audit_log.to ` option. + If log is a program, its pid is stored in the ``audit_log.logger_pid`` variable. + You need to send it a signal to rotate logs. + + **Example** + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: '| cronolog audit_tarantool.log' + :dedent: + + This starts the `cronolog `_ program when the server starts + and sends all ``audit_log`` messages to cronolog standard input (``stdin``). + If the ``audit_log`` string starts with '|', + the string is interpreted as a Unix `pipeline `_. + + | + | Type: string + | Default: box.NULL + | Environment variable: TT_AUDIT_LOG_PIPE + +.. _configuration_reference_audit_spaces: + +.. confval:: audit_log.spaces + + **Since:** :doc:`3.0.0 `. + + The array of space names for which data operation events (``space_select``, ``space_insert``, ``space_replace``, + ``space_delete``) should be logged. The array accepts string values. + If set to :ref:`box.NULL `, the data operation events are logged for all spaces. + + **Example** + + In the example, only the events of ``bands`` and ``singers`` spaces are logged: + + .. code-block:: yaml + + audit_log: + spaces: [bands, singers] + + | + | Type: array + | Default: box.NULL + | Environment variable: TT_AUDIT_LOG_SPACES + +.. _configuration_reference_audit_syslog-facility: + +.. confval:: audit_log.syslog_facility + + Specify a system logger keyword that tells `syslogd `__ where to send the message. + You can enable logging to a system logger using the :ref:`audit_log.to ` option. + + See also: :ref:`syslog configuration example `. + + | + | Type: string + | Possible values: 'auth', 'authpriv', 'cron', 'daemon', 'ftp', 'kern', 'lpr', 'mail', 'news', 'security', 'syslog', 'user', 'uucp', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7' + | Default: 'local7' + | Environment variable: TT_AUDIT_LOG_SYSLOG_FACILITY + +.. _configuration_reference_audit_syslog-identity: + +.. confval:: audit_log.syslog_identity + + Specify an arbitrary string that will be placed at the beginning of all messages. + You can enable logging to a system logger using the :ref:`audit_log.to ` option. + + See also: :ref:`syslog configuration example `. + + | + | Type: string + | Default: 'tarantool' + | Environment variable: TT_AUDIT_LOG_SYSLOG_IDENTITY + +.. _configuration_reference_audit_syslog-server: + +.. confval:: audit_log.syslog_server + + Set a location for the syslog server. + It can be a Unix socket path starting with 'unix:' or an ipv4 port number. + You can enable logging to a system logger using the :ref:`audit_log.to ` option. + +.. _configuration_reference_audit_syslog-example: + + **Example** + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: 'tarantool' + :dedent: + + - :ref:`audit_log.syslog_server ` -- a syslog server location. + + - :ref:`audit_log.syslog_facility ` -- a system logger keyword that tells syslogd where to send the message. + The default value is ``local7``. + + - :ref:`audit_log.syslog_identity ` -- a string placed at the beginning of every message. + The default value is ``tarantool``. + + These options are interpreted as a message for the `syslogd `_ program, + which runs in the background of any Unix-like platform. + + An example of a Tarantool audit log entry in the syslog: + + .. code-block:: json + + { + "__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 : 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" + } + + .. warning:: + + Above is an example of writing audit logs to a directory shared with the system logs. + Tarantool allows this option, but it is not recommended to do this to avoid difficulties + when working with audit logs. System and audit logs should be written separately. + To do this, create separate paths and specify them. + + | + | Type: string + | Default: box.NULL + | Environment variable: TT_AUDIT_LOG_SYSLOG_SERVER + +.. _configuration_reference_audit_to: + +.. confval:: audit_log.to + + Enable audit logging and define the log location. + This option accepts the following values: + + - ``devnull``: disable audit logging. + - ``file``: write audit logs to a file (see :ref:`audit_log.file `). + - ``pipe``: write audit logs to a pipe (see :ref:`audit_log.pipe `). + - ``syslog``: write audit logs to a system logger (see :ref:`audit_log.syslog `). + + By default, audit logging is disabled. + + **Example** + + The basic audit log configuration in the :doc:`3.0.0 ` version might look as follows: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :dedent: + + | + | Type: string + | Possible values: 'devnull', 'file', 'pipe', 'syslog' + | Default: 'devnull' + | Environment variable: TT_AUDIT_LOG_TO .. _configuration_reference_config: @@ -19,7 +341,7 @@ config The ``config`` section defines various parameters related to centralized configuration. -.. NOTE:: +.. NOTE:: ``config`` can be defined in the global :ref:`scope ` only. diff --git a/doc/reference/tooling/tt_cli/search.rst b/doc/reference/tooling/tt_cli/search.rst index 0437d295e0..f2994eaf82 100644 --- a/doc/reference/tooling/tt_cli/search.rst +++ b/doc/reference/tooling/tt_cli/search.rst @@ -25,7 +25,7 @@ Options .. option:: --debug - **Applicable to:** ``taranttol-ee`` + **Applicable to:** ``tarantool-ee`` Search for debug builds of Tarantool Enterprise Edition's SDK. @@ -36,7 +36,7 @@ Options .. option:: --version VERSION - **Applicable to:** ``taranttol-ee`` + **Applicable to:** ``tarantool-ee`` Tarantool Enterprise version. From eb056809e5ab99685dc1933c474c3baa18ac5db2 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Thu, 18 Jan 2024 15:02:49 +0300 Subject: [PATCH 2/4] audit log: restructure the section --- .../instances.enabled/audit_log/config.yaml | 21 +- .../instances.enabled/audit_log/myapp.lua | 51 ++ .../audit_log_pipe/config.yaml | 15 +- .../audit_log_syslog/config.yaml | 18 +- doc/enterprise/audit_log.rst | 606 ++++++++++-------- .../configuration/configuration_reference.rst | 2 +- 6 files changed, 433 insertions(+), 280 deletions(-) create mode 100644 doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml index 257ef47c8a..a1f6a2be38 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml @@ -1,16 +1,17 @@ +audit_log: + to: file + file: 'audit_tarantool.log' + filter: [ user_create,data_operations,ddl,custom ] + format: json + spaces: [ bands ] + extract_key: true + groups: group001: - iproto: - listen: - - uri: '127.0.0.1:3301' replicasets: replicaset001: instances: instance001: - audit_log: - to: file - file: 'audit_tarantool.log' - filter: [ user_create,data_operations,ddl ] - format: json - spaces: [ bands ] - extract_key: true \ No newline at end of file + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua new file mode 100644 index 0000000000..2db8e5f747 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua @@ -0,0 +1,51 @@ +-- myapp.lua -- + +-- Create space +function create_space() + box.schema.space.create('Bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { type = "tree", parts = { 'id' } }) + box.space.bands:create_index('secondary', { type = "tree", parts = { 'band_name' } }) + box.schema.user.grant('guest', 'read,write,execute', 'universe') +end +-- Insert data +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } +end + +local audit = require('audit') +-- Log message string +audit.log('Hello, Alice!') +-- Log format string and arguments +audit.log('Hello, %s!', 'Bob') +-- Log table with audit log field values +audit.log({ type = 'custom_hello', description = 'Hello, World!' }) +audit.log({ type = 'custom_farewell', user = 'eve', module = 'custom', description = 'Farewell, Eve!' }) +-- Create a new log module +local my_audit = audit.new({ type = 'custom_hello', module = 'my_module' }) +my_audit:log('Hello, Alice!') +my_audit:log({ tag = 'admin', description = 'Hello, Bob!' }) + +-- Log 'Hello!' message with the VERBOSE severity level +audit.log({ severity = 'VERBOSE', description = 'Hello!' }) + +-- Log 'Hello!' message with a shortcut helper function +audit.verbose('Hello!') + +-- Like audit.log(), a shortcut helper function accepts a table of options +audit.verbose({ description = 'Hello!' }) + +-- Severity levels are available for custom loggers +local my_logger = audit.new({ module = 'my_module' }) +my_logger:log({ severity = 'ALARM', description = 'Alarm' }) +my_logger:alarm('Alarm') + +-- Overwrite session_type and remote fields +audit.log({ type = 'custom_hello', description = 'Hello!', + session_type = 'my_session', remote = 'my_remote' }) +-- End \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml index 5fbe2cdf37..1cb999804f 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml @@ -1,14 +1,13 @@ +audit_log: + to: pipe + pipe: '| cronolog audit_tarantool.log' + groups: group001: - iproto: - listen: - - uri: '127.0.0.1:3301' replicasets: replicaset001: instances: instance001: - audit_log: - to: pipe - pipe: 'cronolog audit_tarantool.log' - format: json - extract_key: false \ No newline at end of file + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml index b28e40ec5c..2b2709936d 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml @@ -1,3 +1,11 @@ +audit_log: + to: syslog + syslog_server: 'unix:/dev/log' + syslog_facility: user + syslog_identity: 'tarantool' + filter: 'audit,auth,priv,password_change,access_denied' + extract_key: false + groups: group001: iproto: @@ -7,10 +15,6 @@ groups: replicaset001: instances: instance001: - audit_log: - to: syslog - syslog_server: 'unix:/dev/log' - syslog_facility: user - syslog_identity: 'tarantool' - filter: 'audit,auth,priv,password_change,access_denied' - extract_key: false \ No newline at end of file + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/enterprise/audit_log.rst b/doc/enterprise/audit_log.rst index 8ddb65d05e..1a3776b570 100644 --- a/doc/enterprise/audit_log.rst +++ b/doc/enterprise/audit_log.rst @@ -1,12 +1,15 @@ -.. _enterprise_audit_module: +.. _enterprise_audit_module: Audit module ============ +**Example on GitHub**: `audit_log `_ + The audit module available in Tarantool Enterprise Edition writes messages that record Tarantool events in plain text, CSV, or JSON format. - -It provides detailed reports of security-related activities and helps you find and +Each :ref:`event ` is an action related to authorization and authentication, data manipulation, +administrator activity, or system events. +The module provides detailed reports of these activities and helps you find and fix breaches to protect your business. For example, you can see who created a new user and when. @@ -14,11 +17,233 @@ It is up to each company to decide exactly what activities to audit and what act System administrators, security engineers, and people in charge of the company may want to audit different events for different reasons. Tarantool provides such an option for each of them. -.. _audit-log-events: +.. _audit-log-configure: + +Configuring audit log +--------------------- + +The section describes how to enable and configure audit logging and write logs to a selected destination -- a file, a pipe, +or a system logger. + +Read more: :ref:`Audit log configuration reference `. + +.. _audit-log-enable: + +Enable audit logging +~~~~~~~~~~~~~~~~~~~~ + +To enable audit logging, define the log location using the +:ref:`audit_log.to ` option in the ``audit_log`` section of the configuration file. +Possible log locations: + +* a :ref:`file ` +* a :ref:`pipe ` +* a :ref:`system logger ` + +To disable audit logging, set the ``audit_log`` option to ``devnull``. + +In the configuration below, the :ref:`audit_log.to ` option is set to ``file``. +It means that the logs are written to a file. +In this case, you should also define a file path (for example, ``audit_tarantool.log``) using +the :ref:`audit_log.file ` option. +If the option is omitted, the default path is used: ``var/log/instance001/audit.log``. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: 'audit_tarantool.log' + :dedent: + +If you log to a file, Tarantool reopens the audit log at `SIGHUP `_. + +.. _audit-log-filters: + +Filter the events +~~~~~~~~~~~~~~~~~ + +Tarantool's extensive filtering options help you write only the events you need to the audit log. +To select the recorded events, use the :ref:`audit_log.filter ` option. +Its value can be a list of events and event groups. +You can customize the filters and use different combinations of them for your purposes. +Possible filtering options: + +- Filter by event. You can set a list of :ref:`events ` to be recorded. For example, select + ``password_change`` to monitor the users who have changed their passwords: + + .. code-block:: yaml + + audit_log: + filter: [ password_change ] + +- Filter by group. You can specify a list of :ref:`event groups ` to be recorded. For example, + select ``auth`` and ``priv`` to see the events related to authorization and granted privileges: + + .. code-block:: yaml + + audit_log: + filter: [ auth,priv ] + +- Filter by group and event. You can specify a group and a certain event depending on the purpose. + In the configuration below, ``user_create``, ``data_operations``, ``ddl``, and ``custom`` are selected to see the events related to + + * user creation + * space creation, altering, and dropping + * data modification or selection from spaces + * :ref:`custom events ` (any events added manually using the audit module API) + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: filter: + :end-at: custom ] + :dedent: + +.. _audit-log-format: + +Set the format of audit log events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the :ref:`audit_log.format ` option to choose the format of audit log events +-- plain text, CSV, or JSON. + +JSON is used by default. It is more convenient to receive log events, analyze them, and integrate them with other systems if needed. +The plain format can be efficiently compressed. +The CSV format allows you to view audit log events in tabular form. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: format: + :end-at: json + :dedent: + +.. _audit-log-spaces: + +Specify the spaces to be logged +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since :doc:`3.0.0 `, :ref:`audit_log.spaces ` is used to specify +a list of space names for which data operation events should be logged. + +In the configuration below, only the events from the ``bands`` space are logged: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: spaces: + :end-at: bands ] + :dedent: + +.. _audit-log-extract: + +Specify the logging mode in DML events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since :doc:`3.0.0 `, it is possible to +force the audit subsystem to log the primary key instead of a full tuple in DML operations. +To do so, set the :ref:`audit_log.extract_key ` option to ``true``. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: extract_key: + :end-at: true + :dedent: + +.. _audit-log-run-read: + +Reading audit logs +------------------ + +In the example, the logs are written to the ``audit_tarantool.log`` file. +Let's create a space ``bands`` and check the logs in the file after the creation: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Create space + :end-before: -- Insert data + :dedent: + +The audit log entry for the ``space_create`` event might look as follows: + +.. code-block:: json + + { + "time": "2024-01-24T11:43:21.566+0300", + "uuid": "26af0a7d-1052-490a-9946-e19eacc822c9", + "severity": "INFO", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "space_create", + "tag": "", + "description": "Create space Bands" + } + +Then insert one tuple to space: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: load_data() + :end-before: box.space.bands:insert { 2 + :dedent: + +As the ``extract_key`` option is set to ``true``, the audit system prints the primary key instead of the full tuple: + +.. code-block:: json + + { + "time": "2024-01-24T11:45:42.358+0300", + "uuid": "b437934d-62a7-419a-8d59-e3b33c688d7a", + "severity": "VERBOSE", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "space_insert", + "tag": "", + "description": "Insert key [2] into space bands" + } + +If the ``extract_key`` option is set to ``false``, the audit system prints the full tuple like this: + +.. code-block:: json + + { + "time": "2024-01-24T11:45:42.358+0300", + "uuid": "b437934d-62a7-419a-8d59-e3b33c688d7a", + "severity": "VERBOSE", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "space_insert", + "tag": "", + "description": "Insert tuple [1, \"Roxette\", 1986] into space bands" + } + +.. note:: + + To easily read the audit log events in the needed form, you can use these commands: + + * ``cat`` -- print one or more files + + * ``grep`` -- print a specific text + + * ``head`` -- print the first N lines of the file + + * ``tail`` -- print the last N lines of the file + + These are the basic commands to help you read the logs. If necessary, you can use other commands. + + +.. _audit-log-events: Audit log events ---------------- +.. _audit-log-events-types: + +Events types +~~~~~~~~~~~~ + The Tarantool audit log module can record various events that you can monitor and decide whether you need to take actions: @@ -33,7 +258,7 @@ decide whether you need to take actions: * System events -- events related to modification or configuration of resources. For example, such logs record the replacement of a space. -* :ref:`User-defined events `-- any events added manually using +* :ref:`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: @@ -48,7 +273,7 @@ The full list of available audit log events is provided in the table below: - Type of event written to the audit log - Severity level - Example of an event description - * - Audit log enabled for events + * - Audit log enabled for events - ``audit_enable`` - ``VERBOSE`` - @@ -56,15 +281,15 @@ The full list of available audit log events is provided in the table below: - ``custom`` - ``INFO`` (default) - - * - User authorized successfully + * - User authorized successfully - ``auth_ok`` - ``VERBOSE`` - ``Authenticate user `` - * - User authorization failed + * - User authorization failed - ``auth_fail`` - ``ALARM`` - ``Failed to authenticate user `` - * - User logged out or quit the session + * - User logged out or quit the session - ``disconnect`` - ``VERBOSE`` - ``Close connection`` @@ -84,11 +309,11 @@ The full list of available audit log events is provided in the table below: - ``role_drop`` - ``INFO`` - ``Drop role `` - * - User disabled + * - User disabled - ``user_disable`` - ``INFO`` - ``Disable user `` - * - User enabled + * - User enabled - ``user_enable`` - ``INFO`` - ``Enable user `` @@ -132,40 +357,40 @@ The full list of available audit log events is provided in the table below: - ``space_create`` - ``INFO`` - ``Create space `` - * - Space altered + * - Space altered - ``space_alter`` - ``INFO`` - ``Alter space `` - * - Space dropped + * - Space dropped - ``space_drop`` - ``INFO`` - ``Drop space `` - * - Tuple inserted into space + * - Tuple inserted into space - ``space_insert`` - ``VERBOSE`` - ``Insert tuple into space `` - * - Tuple replaced in space + * - Tuple replaced in space - ``space_replace`` - ``VERBOSE`` - ``Replace tuple with in space `` - * - Tuple deleted from space + * - Tuple deleted from space - ``space_delete`` - ``VERBOSE`` - ``Delete tuple from space `` .. note:: - + The ``eval`` event displays data from the ``console`` module and the ``eval`` function of the ``net.box`` module. For more on how they work, see :ref:`Module console ` - and :ref:`Module net.box -- eval `. + and :ref:`Module net.box -- eval `. To separate the data, specify ``console`` or ``binary`` in the session field. .. _audit-log-structure: Structure of audit log event ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each audit log event contains a number of fields that can be used to filter and aggregate the resulting logs. An example of a Tarantool audit log entry in JSON: @@ -199,11 +424,13 @@ Each event consists of the following fields: * - ``time`` - Time of the event - ``2024-01-15T16:33:12.368+0300`` - * - ``uuid``. Since :doc:`3.0.0 ` - - A unique identifier of audit log event + * - ``uuid`` + - Since :doc:`3.0.0 `. A unique identifier of audit log event - ``cb44fb2b-5c1f-4c4b-8f93-1dd02a76cec0`` - * - ``severity``. Since :doc:`3.0.0 ` - - A severity level + * - ``severity`` + - Since :doc:`3.0.0 `. A severity level. Each system audit event has a severity level determined by its importance. + :ref:`Custom events ` have the ``INFO`` severity level by default. + - ``VERBOSE`` * - ``remote`` - Remote host that triggered the event @@ -232,10 +459,11 @@ Each event consists of the following fields: You can set all these parameters only once. + .. _audit-log-event-groups: Event groups ------------- +~~~~~~~~~~~~ Built-in event groups are used to filter the event types that you want to audit. For example, you can set to record only authorization events, @@ -243,35 +471,35 @@ or only events related to a space. Tarantool provides the following event groups: - * ``all`` -- all :ref:`events `. +* ``all`` -- all :ref:`events `. - .. note:: + .. note:: - Events ``call`` and ``eval`` are included only in the ``all`` group. + Events ``call`` and ``eval`` are included only in the ``all`` group. - * ``audit`` -- ``audit_enable`` event. +* ``audit`` -- ``audit_enable`` event. - * ``auth`` -- authorization events: ``auth_ok``, ``auth_fail``. +* ``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``. +* ``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``. +* ``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``. +* ``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``. +* ``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. +* ``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. .. warning:: @@ -280,253 +508,123 @@ Tarantool provides the following event groups: It is recommended that you select only those groups whose events your company needs to monitor and analyze. -.. _audit-log-custom: +.. _audit-log-custom: -Create user-defined events --------------------------- +Creating custom events +---------------------- Tarantool provides an API for writing user-defined audit log events. -To enable custom events, specify the ``custom`` value in the :ref:`audit_log.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 option ``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 user-defined events must either be ``message`` or -have the ``custom_`` prefix. - -Example -~~~~~~~ - -.. code-block:: lua - - audit.log({type = 'custom_hello', module = 'my_module', description = 'Hello, Alice!' }) - audit.log({type = 'custom_hello', module = 'my_module', tag = 'admin', description = 'Hello, Bob!'}) - - -Some user-defined audit log fields (``time``, ``remote``, ``session_type``) -are set in the same way as for a system event. -If a field is not overwritten, it is set to the same value as for a system event. - -Some audit log fields you can overwrite with ``audit.new()`` and ``audit.log()``: - -* ``type`` -* ``user`` -* ``module`` -* ``tag`` -* ``description`` - -.. note:: - - To avoid confusion with system events, the value of the type field must either be ``message`` (default) - or begin with the ``custom_`` prefix. Otherwise, you receive the error message. - User-defined events are filtered out by default.. - - -.. _audit-log-example: - -Example: using Tarantool audit log ----------------------------------- - -The example shows how to enable and configure audit logging and write logs to a selected destination (a file, a pipe, -or a system logger). - -Before starting this example: - -#. Install the :ref:`tt ` utility. - -#. Create a tt environment in the current directory by executing the :ref:`tt init ` command. - -#. Inside the ``instances.enabled`` directory of the created tt environment, create the ``audit_log`` directory. - -#. Inside ``instances.enabled/audit_log``, create the ``instances.yml`` and ``config.yaml`` files: - - - ``instances.yml`` specifies instances to run in the current environment and should look like this: - - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/instances.yml - :language: yaml - :end-at: instance001: - :dedent: - - - The ``config.yaml`` file stores an audit log configuration (the ``audit_log`` section). The configuration is described in detail in the next section. - -.. _audit-log-enable: - -Enable audit logging -~~~~~~~~~~~~~~~~~~~~ - -To enable audit logging, define the log location using the -:ref:`audit_log.to ` option in the ``audit_log`` section of the configuration file. -Possible logs locations: - -* a :ref:`file ` -* a :ref:`pipe ` -* a :ref:`system logger ` - -To disable audit logging, set the ``audit_log`` option to ``devnull``. - -In this tutorial, the logs are written to a file. To do this, set the -:ref:`audit_log.to ` option to ``file``. -After that, you can define a file path (for example, ``audit_tarantool.log``) using -the :ref:`audit_log.file ` option. -If the option is omitted, the default path is used: ``var/log/instance001/audit.log``. - -The configuration might look as follows: +To enable custom events, specify the ``custom`` value in the :ref:`audit_log.filter ` option: .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml :language: yaml - :start-at: audit_log: - :end-at: audit_tarantool.log + :start-at: filter: + :end-at: custom ] :dedent: -If you log to a file, Tarantool reopens the audit log at `SIGHUP `_. - -.. _audit-log-filters: +.. _audit-log-custom-new: -Filter the events -~~~~~~~~~~~~~~~~~ - -Tarantool's extensive filtering options help you write only the events you need to the audit log. - -To select the recorded events, use the :ref:`audit_log.filter ` option. -Its value can be a list of events and event groups. -You can customize the filters and use different combinations of them for your purposes. -Possible filtering options: - -- Filter by event. You can set a list of :ref:`events ` to be recorded. For example, select - ``password_change`` to monitor the users who have changed their passwords: - - .. code-block:: yaml +Add a new custom event +~~~~~~~~~~~~~~~~~~~~~~ - audit_log: - filter: [ password_change ] - -- Filter by group. You can specify a list of :ref:`event groups ` to be recorded. For example, - select ``auth`` and ``priv`` to see only events related to authorization and granted privileges. - - .. code-block:: yaml - - audit_log: - filter: [ auth,priv ] - -- Filter by group and event. You can specify a group and a certain event depending on the purpose. - For example, you can select ``user_create``, ``data_operations``, and ``ddl`` to see the events related to - - * user creation - * space creation, altering, and dropping - * data modification or selection from spaces +To add a new event, use the ``audit.log()`` function that takes one of the following values: - Let's add this filter to our configuration file: +* Message string. Printed to the audit log with type ``message``: - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml - :language: yaml - :start-at: audit_log: - :end-at: audit_tarantool.log + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Log message string + :end-before: Log format string and arguments :dedent: +* Format string and arguments. Passed to string format and then output to the audit log with type ``message``: -.. _audit-log-format: - -Set the format of audit log events -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Use the :ref:`audit_log.format ` option to choose the format of audit log events --- plain text, CSV, or JSON. - -JSON is used by default. It is more convenient to receive log events, analyze them, and integrate them with other systems if needed. -The plain format can be efficiently compressed. -The CSV format allows you to view audit log events in tabular form. - -In this tutorial, set the format to JSON: - -.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml - :language: yaml - :start-at: audit_log: - :end-at: format: json - :dedent: - -.. _audit-log-spaces: + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Log format string and arguments + :end-before: Log table with audit log field values + :dedent: -Specify the spaces to be logged -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Table with audit log field values. The table must contain at least one field -- ``description``. -Since: :doc:`3.0.0 `, it is possible to :ref:`specify a list of space names ` -for which data operation events should be logged. + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Log table with audit log field values + :end-at: description = 'Farewell, Eve!' }) + :dedent: -To log the events from the ``bands`` space only, specify the option in the configuration file: +Alternatively, you can use ``audit.new()`` to create a new log module. +This allows you to avoid passing all custom audit log fields each time ``audit.log()`` is called. +The ``audit.new()`` function 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. -.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml - :language: yaml - :liines: 15 +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Create a new log module + :end-before: Log 'Hello!' message with the VERBOSE severity level :dedent: -.. _audit-log-extract: - -Specify the logging mode in DML events -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Since: :doc:`3.0.0 `, it is possible to -force the audit subsystem to log the primary key instead of a full tuple in DML operations. +.. _audit-log-custom-field-overwrite: -To do so, set the :ref:`audit_log.extract_key ` option to ``true``. +Overwrite custom event fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The resulting configuration in ``config.yaml`` now looks as follows: +It is possible to overwrite most of the custom audit log :ref:`fields ` using ``audit.new()`` or ``audit.log()``. +The only audit log field that cannot be overwritten is ``time``. -.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml - :language: yaml +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Overwrite session_type and remote fields + :end-at: remote = 'my_remote' }) :dedent: -.. _audit-log-run-example: - -Check the example -~~~~~~~~~~~~~~~~~ - -After the configuration is done, execute the :ref:`tt start ` command from the :ref:`tt environment directory `: - - .. code-block:: console - - $ tt start audit_log - • Starting an instance [audit_log:instance001]... - -After that, connect to the instance with :ref:`tt connect `: - -.. code-block:: console +If omitted, the ``session_type`` is set to the current session type, ``remote`` is set to the remote peer address. - $ tt connect audit_log:instance001 - -In the interactive console. run the following commands: +.. note:: + To avoid confusion with system events, the value of the type field must either be ``message`` (default) + or begin with the ``custom_`` prefix. Otherwise, you receive the error message. + User-defined events are filtered out by default. -.. _audit-log-read: +.. _audit-log-custom-severity: -Use read commands ------------------ +Severity level +~~~~~~~~~~~~~~ -To easily read the audit log events in the needed form, use the different commands: +By default, custom events have the ``INFO`` :ref:`severity level `. +To override the level, you can: -* ``cat`` -- prints one or more files +* specify the ``severity`` field +* use a shortcut function -* ``grep`` -- prints a specific text +The following shortcuts are available: -* ``head`` -- prints the first N lines of the file +.. container:: table -* ``tail`` -- prints the last N lines of the file + .. list-table:: + :widths: 40 60 + :header-rows: 1 - .. note:: - - These are the basic commands to help you read the logs. If necessary, you can use other commands. + * - Shortcut + - Equivalent + * - ``audit.verbose(...)`` + - ``audit.log({severity = 'VERBOSE', ...})`` + * - ``audit.info(...)`` + - ``audit.log({severity = 'INFO', ...})`` + * - ``audit.warning(...)`` + - ``audit.log({severity = 'WARNING', ...})`` + * - ``audit.alarm(...)`` + - ``audit.log({severity = 'ALARM', ...})`` + +**Example** + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-at: audit.log({ severity + :end-at: description = 'Hello!' }) + :dedent: -.. _audit-log-tips: +.. _audit-log-tips: Tips ---- diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 99c8ad93af..183b2735df 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -142,7 +142,7 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi .. note:: The option only has an effect if the :ref:`audit_log.to ` is set to ``syslog`` - ``pipe``. + or ``pipe``. | | Type: boolean From f615a1345c1654ae80c35e04b672e877540fabea Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Thu, 1 Feb 2024 16:14:19 +0300 Subject: [PATCH 3/4] audit log: apply review suggestions --- doc/enterprise/audit_log.rst | 105 +++++++----------- .../configuration/configuration_reference.rst | 9 +- 2 files changed, 47 insertions(+), 67 deletions(-) diff --git a/doc/enterprise/audit_log.rst b/doc/enterprise/audit_log.rst index 1a3776b570..931d7f012f 100644 --- a/doc/enterprise/audit_log.rst +++ b/doc/enterprise/audit_log.rst @@ -5,10 +5,10 @@ Audit module **Example on GitHub**: `audit_log `_ -The audit module available in Tarantool Enterprise Edition writes messages that record Tarantool events in plain text, -CSV, or JSON format. +The audit module available in Tarantool Enterprise Edition allows you to record various events occurred in Tarantool. Each :ref:`event ` is an action related to authorization and authentication, data manipulation, administrator activity, or system events. + The module provides detailed reports of these activities and helps you find and fix breaches to protect your business. For example, you can see who created a new user and when. @@ -19,8 +19,8 @@ audit different events for different reasons. Tarantool provides such an option .. _audit-log-configure: -Configuring audit log ---------------------- +Configure audit log +------------------- The section describes how to enable and configure audit logging and write logs to a selected destination -- a file, a pipe, or a system logger. @@ -33,20 +33,17 @@ Enable audit logging ~~~~~~~~~~~~~~~~~~~~ To enable audit logging, define the log location using the -:ref:`audit_log.to ` option in the ``audit_log`` section of the configuration file. +:ref:`audit_log.to ` option in the configuration file. Possible log locations: * a :ref:`file ` * a :ref:`pipe ` * a :ref:`system logger ` -To disable audit logging, set the ``audit_log`` option to ``devnull``. - In the configuration below, the :ref:`audit_log.to ` option is set to ``file``. It means that the logs are written to a file. -In this case, you should also define a file path (for example, ``audit_tarantool.log``) using -the :ref:`audit_log.file ` option. -If the option is omitted, the default path is used: ``var/log/instance001/audit.log``. +By default, audit logs are saved in the ``var/log/{{ instance_name }}/audit.log`` file. +To specify the path to an audit log file explicitly, use the :ref:`audit_log.file ` option. .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml :language: yaml @@ -56,6 +53,8 @@ If the option is omitted, the default path is used: ``var/log/instance001/audit. If you log to a file, Tarantool reopens the audit log at `SIGHUP `_. +To disable audit logging, set the ``audit_log.to`` option to ``devnull``. + .. _audit-log-filters: Filter the events @@ -84,7 +83,7 @@ Possible filtering options: filter: [ auth,priv ] - Filter by group and event. You can specify a group and a certain event depending on the purpose. - In the configuration below, ``user_create``, ``data_operations``, ``ddl``, and ``custom`` are selected to see the events related to + In the configuration below, ``user_create``, ``data_operations``, ``ddl``, and ``custom`` are selected to see the events related to: * user creation * space creation, altering, and dropping @@ -105,22 +104,22 @@ Set the format of audit log events Use the :ref:`audit_log.format ` option to choose the format of audit log events -- plain text, CSV, or JSON. -JSON is used by default. It is more convenient to receive log events, analyze them, and integrate them with other systems if needed. -The plain format can be efficiently compressed. -The CSV format allows you to view audit log events in tabular form. - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml :language: yaml :start-at: format: :end-at: json :dedent: +JSON is used by default. It is more convenient to receive log events, analyze them, and integrate them with other systems if needed. +The plain format can be efficiently compressed. +The CSV format allows you to view audit log events in tabular form. + .. _audit-log-spaces: Specify the spaces to be logged ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Since :doc:`3.0.0 `, :ref:`audit_log.spaces ` is used to specify +The :ref:`audit_log.spaces ` option is used to specify a list of space names for which data operation events should be logged. In the configuration below, only the events from the ``bands`` space are logged: @@ -136,9 +135,8 @@ In the configuration below, only the events from the ``bands`` space are logged: Specify the logging mode in DML events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Since :doc:`3.0.0 `, it is possible to -force the audit subsystem to log the primary key instead of a full tuple in DML operations. -To do so, set the :ref:`audit_log.extract_key ` option to ``true``. +If set to ``true``, the :ref:`audit_log.extract_key ` option +forces the audit subsystem to log the primary key instead of a full tuple in DML operations. .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml :language: yaml @@ -146,18 +144,19 @@ To do so, set the :ref:`audit_log.extract_key `-- any events added manually using +* :ref:`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: @@ -270,14 +254,14 @@ The full list of available audit log events is provided in the table below: :header-rows: 1 * - Event - - Type of event written to the audit log + - Event type - Severity level - - Example of an event description + - Example * - Audit log enabled for events - ``audit_enable`` - ``VERBOSE`` - - * - :ref:`User-defined events ` + * - :ref:`Custom events ` - ``custom`` - ``INFO`` (default) - @@ -420,7 +404,7 @@ Each event consists of the following fields: * - Field - Description - - Example of a log field display + - Example * - ``time`` - Time of the event - ``2024-01-15T16:33:12.368+0300`` @@ -440,7 +424,7 @@ Each event consists of the following fields: - ``console`` * - ``module`` - Audit log module. Set to ``tarantool`` for system events; - can be overwritten for user-defined events + can be overwritten for custom events - ``tarantool`` * - ``user`` - User who triggered the event @@ -455,10 +439,6 @@ Each event consists of the following fields: - Human-readable event description - ``Authenticate user Admin`` - .. warning:: - - You can set all these parameters only once. - .. _audit-log-event-groups: @@ -466,8 +446,7 @@ Event groups ~~~~~~~~~~~~ Built-in event groups are used to filter the event types that you want to audit. -For example, you can set to record only authorization events, -or only events related to a space. +For example, you can set to record only authorization events or only events related to a space. Tarantool provides the following event groups: @@ -510,11 +489,11 @@ Tarantool provides the following event groups: .. _audit-log-custom: -Creating custom events ----------------------- +Custom events +------------- -Tarantool provides an API for writing user-defined audit log events. -To enable custom events, specify the ``custom`` value in the :ref:`audit_log.filter ` option: +Tarantool provides an API for writing custom audit log events. +To enable these events, specify the ``custom`` value in the :ref:`audit_log.filter ` option: .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml :language: yaml @@ -522,12 +501,12 @@ To enable custom events, specify the ``custom`` value in the :ref:`audit_log.fil :end-at: custom ] :dedent: -.. _audit-log-custom-new: +.. _audit-log-custom-log: -Add a new custom event -~~~~~~~~~~~~~~~~~~~~~~ +Log a custom event +~~~~~~~~~~~~~~~~~~ -To add a new event, use the ``audit.log()`` function that takes one of the following values: +To log an event, use the ``audit.log()`` function that takes one of the following values: * Message string. Printed to the audit log with type ``message``: @@ -584,7 +563,7 @@ If omitted, the ``session_type`` is set to the current session type, ``remote`` To avoid confusion with system events, the value of the type field must either be ``message`` (default) or begin with the ``custom_`` prefix. Otherwise, you receive the error message. - User-defined events are filtered out by default. + Custom events are filtered out by default. .. _audit-log-custom-severity: @@ -635,7 +614,7 @@ How many events can be recorded? If you write to a file, the size of the Tarantool audit module is limited by the disk space. If you write to a system logger, the size of the Tarantool audit module is limited by the system logger. If you write to a pipe, the size of the Tarantool audit module is limited by the system buffer. -If the ``audit_nonblock = false``, if ``audit_nonblock`` = ``true``, there is no limit. +If the ``audit_log.nonblock = false``, if ``audit_log.nonblock`` = ``true``, there is no limit. However, it is not recommended to use the entire memory, as this may cause performance degradation and even loss of some logs. diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 183b2735df..e36c29decb 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -47,7 +47,6 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi **Since:** :doc:`3.0.0 `. - Specify the logging mode in DML events. If set to ``true``, the audit subsystem extracts and prints only the primary key instead of full tuples in DML events (``space_insert``, ``space_replace``, ``space_delete``). Otherwise, full tuples are logged. @@ -78,8 +77,8 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi Enable logging for a specified subset of audit events. This option accepts the following values: - * event names (for example, ``password_change``). For details, see :ref:`Audit log events `. - * event groups (for example, ``audit``). For details, see :ref:`Event groups `. + * Event names (for example, ``password_change``). For details, see :ref:`Audit log events `. + * Event groups (for example, ``audit``). For details, see :ref:`Event groups `. The option contains either one value from above or a combination of them. @@ -322,10 +321,12 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi **Example** - The basic audit log configuration in the :doc:`3.0.0 ` version might look as follows: + The basic audit log configuration might look as follows: .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml :language: yaml + :start-at: audit_log + :end-at: extract_key: true :dedent: | From 849bb3d00451cad4b8853636bfff5afcf8535bd7 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Fri, 2 Feb 2024 12:43:57 +0300 Subject: [PATCH 4/4] audit log: apply review suggestions --- .../instances.enabled/audit_log/myapp.lua | 2 +- .../audit_log_syslog/config.yaml | 2 +- doc/enterprise/audit_log.rst | 18 +++--- .../configuration/configuration_reference.rst | 56 ++++++------------- 4 files changed, 30 insertions(+), 48 deletions(-) diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua index 2db8e5f747..abd2380609 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua @@ -2,7 +2,7 @@ -- Create space function create_space() - box.schema.space.create('Bands') + box.schema.space.create('bands') box.space.bands:format({ { name = 'id', type = 'unsigned' }, { name = 'band_name', type = 'string' }, diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml index 2b2709936d..93e5cf4925 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml @@ -1,7 +1,7 @@ audit_log: to: syslog syslog_server: 'unix:/dev/log' - syslog_facility: user + syslog_facility: 'user' syslog_identity: 'tarantool' filter: 'audit,auth,priv,password_change,access_denied' extract_key: false diff --git a/doc/enterprise/audit_log.rst b/doc/enterprise/audit_log.rst index 931d7f012f..fb3c8aff1c 100644 --- a/doc/enterprise/audit_log.rst +++ b/doc/enterprise/audit_log.rst @@ -149,9 +149,15 @@ forces the audit subsystem to log the primary key instead of a full tuple in DML Examples of audit log entries ----------------------------- -In the example, the logs are written to the ``audit_tarantool.log`` file. +In this example, the following audit log configuration is used: -First, create a space ``bands`` and check the logs in the file after the creation: +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: audit_log + :end-at: extract_key: true + :dedent: + +Create a space ``bands`` and check the logs in the file after the creation: .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua :language: lua @@ -611,12 +617,10 @@ Tips How many events can be recorded? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you write to a file, the size of the Tarantool audit module is limited by the disk space. -If you write to a system logger, the size of the Tarantool audit module is limited by the system logger. -If you write to a pipe, the size of the Tarantool audit module is limited by the system buffer. +If you write to a file, the size of the Tarantool audit log is limited by the disk space. +If you write to a system logger, the size of the Tarantool audit log is limited by the system logger. +If you write to a pipe, the size of the Tarantool audit message is limited by the system buffer. If the ``audit_log.nonblock = false``, if ``audit_log.nonblock`` = ``true``, there is no limit. -However, it is not recommended to use the entire memory, as this may cause performance degradation -and even loss of some logs. How often should audit logs be reviewed? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index e36c29decb..16bb7ec5d3 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -80,9 +80,17 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi * Event names (for example, ``password_change``). For details, see :ref:`Audit log events `. * Event groups (for example, ``audit``). For details, see :ref:`Event groups `. - The option contains either one value from above or a combination of them. + The option contains either one value from ``Possible values`` section (see below) or a combination of them. - To enable :ref:`user-defined audit log events `, specify the ``custom`` value in this option. + To enable :ref:`custom audit log events `, specify the ``custom`` value in this option. + + **Example** + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-at: filter: + :end-at: custom ] + :dedent: | | Type: array @@ -154,7 +162,7 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi Specify a pipe for the audit log destination. You can set the ``pipe`` type using the :ref:`audit_log.to ` option. - If log is a program, its pid is stored in the ``audit_log.logger_pid`` variable. + If log is a program, its pid is stored in the ``audit.pid`` field. You need to send it a signal to rotate logs. **Example** @@ -218,7 +226,7 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi .. confval:: audit_log.syslog_identity - Specify an arbitrary string that will be placed at the beginning of all messages. + Specify an application name to show in logs. You can enable logging to a system logger using the :ref:`audit_log.to ` option. See also: :ref:`syslog configuration example `. @@ -251,7 +259,7 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi - :ref:`audit_log.syslog_facility ` -- a system logger keyword that tells syslogd where to send the message. The default value is ``local7``. - - :ref:`audit_log.syslog_identity ` -- a string placed at the beginning of every message. + - :ref:`audit_log.syslog_identity ` -- an application name to show in logs. The default value is ``tarantool``. These options are interpreted as a message for the `syslogd `_ program, @@ -259,39 +267,9 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi An example of a Tarantool audit log entry in the syslog: - .. code-block:: json - - { - "__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 : 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" - } + .. code-block:: text + + 09:32:52 tarantool: {"time": "2024-02-08T09:32:52.190+0300", "uuid": "94454e46-9a0e-493a-bb9f-d59e44a43581", "severity": "INFO", "remote": "unix/:(socket)", "session_type": "console", "module": "tarantool", "user": "admin", "type": "space_create", "tag": "", "description": "Create space bands"} .. warning:: @@ -314,7 +292,7 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi - ``devnull``: disable audit logging. - ``file``: write audit logs to a file (see :ref:`audit_log.file `). - - ``pipe``: write audit logs to a pipe (see :ref:`audit_log.pipe `). + - ``pipe``: start a program and write audit logs to it (see :ref:`audit_log.pipe `). - ``syslog``: write audit logs to a system logger (see :ref:`audit_log.syslog `). By default, audit logging is disabled.