From eb2100c7f083c238b992fc49f8fe5ce2622740ef Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 29 Nov 2023 17:37:31 +0700 Subject: [PATCH 1/4] Add TCM audit log docs --- doc/reference/tooling/tcm/index.rst | 2 + doc/reference/tooling/tcm/tcm_audit_log.rst | 335 ++++++++++++++++++++ 2 files changed, 337 insertions(+) create mode 100644 doc/reference/tooling/tcm/tcm_audit_log.rst diff --git a/doc/reference/tooling/tcm/index.rst b/doc/reference/tooling/tcm/index.rst index 9eb7b53efc..2ea0fa8e6f 100644 --- a/doc/reference/tooling/tcm/index.rst +++ b/doc/reference/tooling/tcm/index.rst @@ -29,5 +29,7 @@ For example, a user can be an administrator of a specific cluster or only have t to read data. LDAP authorization is supported as well. .. toctree:: + :maxdepth: 1 tcm_access_control + tcm_audit_log diff --git a/doc/reference/tooling/tcm/tcm_audit_log.rst b/doc/reference/tooling/tcm/tcm_audit_log.rst new file mode 100644 index 0000000000..64004e96e8 --- /dev/null +++ b/doc/reference/tooling/tcm/tcm_audit_log.rst @@ -0,0 +1,335 @@ +.. _tcm_audit_log: + +Audit log +========= + +.. admonition:: Enterprise Edition + :class: fact + + |tcm_full_name| is a part of the `Enterprise Edition `_. + +|tcm_full_name| provides the audit logging functionality for tracking user activity +and security-related events, such as: + +* Successful and failed login attempts. +* Access to clusters, their configurations, data model, and stored data. +* Changes in the access control system: users, roles, passwords, LDAP configurations. + +The complete list of |tcm| audit events is provided in :ref:`Event types `. + +.. note:: + + |tcm| audit log records only events that happen in |tcm| itself. + For information about Tarantool audit logging, see :ref:`Audit module `. + +Audit logging is disabled in |tcm| by default. To start recording events, you need +to :ref:`enable ` and :ref:`configure ` it. + +Audit log stores event details in the JSON format. Each log entry contains the +event type, description, time, impacted objects, and other information that +may be used for incident investigation. The complete list of fields is provided in +:ref:`Structure of audit log events `. + +In addition to writing audit logs, |tcm| has a built-in interface for reading and +searching them. For details, see :ref:`Viewing audit logs `. + +.. _tcm_audit_log_enable: + +Enabling audit logging +---------------------- + +To enable audit logging in |tcm|, go to **Audit settings** and click **Enable**. + +To additionally send audit log events to the standard output, click **Send to stdout**. + +.. _tcm_audit_log_config: + +Audit log configuration +----------------------- + +|tcm| audit events can be logged to a local file or sent to a +`syslog `__ server. +To configure audit logging, go to **Audit settings**. + +Writing to a file +~~~~~~~~~~~~~~~~~ + +To write |tcm| audit logs to a file: + +1. Go to **Audit settings** and select the **file** protocol. +2. Specify the name of the audit log file. The file appears in the |tcm| working directory. +3. Configure the log files rotation: maximum file size and age, and the number + of files to store simultaneously. +4. (Optional) Enable compression of audit log files. + +.. TODO: move to UI reference + +Configuration parameters: + +- **Output file name**. The name of the audit log file. Default: ``audit.log`` +- **Max size (in MB)**. The maximum size of the log file before it gets rotated,in megabytes. Default: 100. +- **Max backups**. The maximum number of stored audit log files. Default: 10. +- **Max age (in days)**. The maximum age of audit log files in days. Default: 30. +- **Compress**. Compress audit log files into ``gzip`` archives when rotating. + +Sending to syslog +~~~~~~~~~~~~~~~~~ + +If you use a centralized log management system based on `syslog `__, +you can configure |tcm| to send its audit log to your syslog server. + +To send |tcm| audit logs to a syslog server: + +1. Go to **Audit settings** and select the **syslog** protocol. +2. Enter the syslog server URI and select the network protocol. Typically, + ``syslogd`` listens on port 514 and use the UDP protocol. +3. Specify the syslog logging parameters: timeout, priority, and facility. + +.. TODO: move to UI reference + +Configuration parameters: + +- **Protocol**. The network protocol used for connecting to the syslog server. Default: ``udp``. +- **Output**. The syslog server URI. Default: 127.0.0.1:514 (localhost). +- **Timeout**. The syslog write timeout in the `ISO 8601 duration format `__. + Default: ``PT2S`` (two seconds). +- **Priority**. The syslog severity level. Default: ``info``. +- **Facility**. The syslog facility. Default: ``local0``. + +Selecting audit events to record +-------------------------------- + +When audit log is enabled, |tcm| records all audit events listed in :ref:`Event types `. +To decrease load and make the audit log comply with specific security +requirements, you can record only selected events. For example, these can be events +of user account management or events of cluster data access. + +To select events to record into the audit log, go to **Audit settings** and +enter their :ref:`types ` into the **Filters** field +one-by-one, pressing the **Enter** key after each type. + +To remove an event type from a filters list, click the cross icon beside it. + +.. _tcm_audit_log_view: + +Viewing audit log +----------------- + +If audit log is written to a file, you can view it in |tcm|. +To view audit log in |tcm|, go to the **Audit log** page. On this page, you can +view or search for events. + +To view the details of a logged audit event, click the corresponding line in the +table. + +To search for an event, use the search bar on the top of the page. Note that the +search is case-sensitive. For example, to find events with the ``ALARM`` severity, +enter ``ALARM``, not ``alarm``. + +.. _tcm_audit_log_structure: + +Structure of audit log events +----------------------------- + +All entries of the |tcm| audit log include the mandatory fields listed in the table below. + +.. container:: table + + .. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - Field + - Description + - Example + * - ``time`` + - Time of the event + - 2023-11-23T12:05:27.099+07:00 + * - ``severity`` + - Event severity: ``VERBOSE``, ``INFO``, ``WARNING``, or ``ALARM`` + - INFO + * - ``type`` + - Audit :ref:`event type ` + - user.update + * - ``description`` + - Human-readable event description + - Update user + * - ``uuid`` + - Event UUID + - f8744f51-5760-40c3-ae2d-0b4d6b44836f + * - ``user`` + - UUID of the user who triggered the event + - 942a4f54-cf7f-4f46-80ce-3511dbbb57b7 + * - ``remote`` + - Remote host that triggered the event + - 100.96.163.226:48722 + * - ``host`` + - The |tcm| host on which the event happened + - 100.96.163.226:8080 + * - ``userAgent`` + - Information about the client application and platform that was used to trigger the event + - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36 + * - ``permission`` + - The permission that was used to trigger the event + - ["admin.users.write"] + * - ``result`` + - Event result: ``ok`` or ``nok`` + - ok + * - ``err`` + - Human-readable error description for events with ``nok`` result + - failed to login + * - ``fields`` + - Additional fields for specific event types in the key-value format + - Key examples: + + - ``clusterId`` in cluster-related events. + - ``username`` in ``current.*`` or ``auth.*`` events + - ``payload`` in events that include sending data to the server + +This is an example of an audit log entry on a successful login attempt: + +.. code-block:: json + + { + "time": "2023-11-23T12:01:27.247+07:00", + "severity": "INFO", + "description": "Login user", + "type": "current.login", + "uuid": "4b9c2dd1-d9a1-4b40-a448-6bef4a0e5c79", + "user": "", + "remote": "127.0.0.1:63370", + "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36", + "host": "127.0.0.1:8080", + "permissions": [], + "result": "ok", + "fields": [ + { + "Key": "username", + "Value": "admin" + }, + { + "Key": "method", + "Value": "null" + }, + { + "Key": "output", + "Value": "true" + } + ] + } + +.. _tcm_audit_log_event_types: + +Event types +----------- + +The following table lists all possible values of the ``type`` field of |tcm| +audit log events. + +.. container:: table + + .. list-table:: + :widths: auto + :header-rows: 1 + + * - Event type + - Description + + * - ``auth.fail`` + - Authentication failed + * - ``auth.ok`` + - Authentication successful + * - ``access.denied`` + - An attempt to access an object without the required permission + * - ``user.add`` + - User added + * - ``user.update`` + - User updated + * - ``user.delete`` + - User deleted + * - ``secret.add`` + - User secret added + * - ``secret.update`` + - User secret updated + * - ``secret.block`` + - User secret blocked + * - ``secret.unblock`` + - User secret unblocked + * - ``secret.delete`` + - User secret deleted + * - ``secret.expire`` + - User secret expired + * - ``session.revoke`` + - Session revoked + * - ``session.revokeuser`` + - All user's sessions revoked + * - ``explorer.insert`` + - Data inserted in a cluster + * - ``explorer.delete`` + - Data deleted from a cluster + * - ``explorer.replace`` + - Data replaced in a cluster + * - ``explorer.call`` + - Stored function called on a cluster + * - ``explorer.evaluate`` + - Code executed on a cluster + * - ``explorer.switchover`` + - Master switched manually + * - ``test.devmode`` + - Switched to development mode + * - ``auditlog.config`` + - Audit log configuration changed + * - ``passwordpolicy.save`` + - Password policy changed + * - ``passwordpolicy.resetpasswords`` + - All passwords expired by an administrator + * - ``ddl.save`` + - Cluster data model saved + * - ``ddl.apply`` + - Cluster data model applied + * - ``cluster.config.save`` + - Cluster configuration saved + * - ``cluster.config.reset`` + - Saved cluster configuration reset + * - ``cluster.config.apply`` + - Cluster configuration applied + * - ``current.logout`` + - User logged out their own session + * - ``current.revoke`` + - User revoked their own session + * - ``current.revokeall`` + - User revoked all their active sessions + * - ``current.changepassword`` + - User changed their password + * - ``role.add`` + - Role added + * - ``role.update`` + - Role updated + * - ``role.delete`` + - Role deleted + * - ``cluster.add`` + - Cluster added + * - ``cluster.update`` + - Cluster updated + * - ``cluster.delete`` + - Cluster removed + * - ``ldap.testlogin`` + - Login test executed for a LDAP configuration + * - ``ldap.testconnection`` + - Connection test executed for a LDAP configuration + * - ``ldap.add`` + - LDAP configuration added + * - ``ldap.update`` + - LDAP configuration updated + * - ``ldap.delete`` + - LDAP configuration deleted + * - ``addon.enable`` + - Add-on enabled + * - ``addon.disable`` + - Add-on disabled + * - ``addon.delete`` + - Add-on removed + * - ``tcmstate.save`` + - Low-level information saved in the TCM storage (for debug purposes) + * - ``tcmstate.delete`` + - Low-level information deleted from the TCM storage (for debug purposes) From 7a7aa94eb95e04d00fb66163d4bcc547f54f4f16 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 4 Dec 2023 14:59:09 +0700 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Andrey Aksenov <38073144+andreyaksenov@users.noreply.github.com> --- doc/reference/tooling/tcm/tcm_audit_log.rst | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/doc/reference/tooling/tcm/tcm_audit_log.rst b/doc/reference/tooling/tcm/tcm_audit_log.rst index 64004e96e8..cae6d57c28 100644 --- a/doc/reference/tooling/tcm/tcm_audit_log.rst +++ b/doc/reference/tooling/tcm/tcm_audit_log.rst @@ -25,7 +25,7 @@ The complete list of |tcm| audit events is provided in :ref:`Event types ` and :ref:`configure ` it. -Audit log stores event details in the JSON format. Each log entry contains the +The audit log stores event details in the JSON format. Each log entry contains the event type, description, time, impacted objects, and other information that may be used for incident investigation. The complete list of fields is provided in :ref:`Structure of audit log events `. @@ -58,7 +58,7 @@ To write |tcm| audit logs to a file: 1. Go to **Audit settings** and select the **file** protocol. 2. Specify the name of the audit log file. The file appears in the |tcm| working directory. -3. Configure the log files rotation: maximum file size and age, and the number +3. Configure the log files rotation: the maximum file size and age, and the number of files to store simultaneously. 4. (Optional) Enable compression of audit log files. @@ -67,7 +67,7 @@ To write |tcm| audit logs to a file: Configuration parameters: - **Output file name**. The name of the audit log file. Default: ``audit.log`` -- **Max size (in MB)**. The maximum size of the log file before it gets rotated,in megabytes. Default: 100. +- **Max size (in MB)**. The maximum size of the log file before it gets rotated, in megabytes. Default: 100. - **Max backups**. The maximum number of stored audit log files. Default: 10. - **Max age (in days)**. The maximum age of audit log files in days. Default: 30. - **Compress**. Compress audit log files into ``gzip`` archives when rotating. @@ -76,13 +76,11 @@ Sending to syslog ~~~~~~~~~~~~~~~~~ If you use a centralized log management system based on `syslog `__, -you can configure |tcm| to send its audit log to your syslog server. - -To send |tcm| audit logs to a syslog server: +you can configure |tcm| to send its audit log to your syslog server: 1. Go to **Audit settings** and select the **syslog** protocol. 2. Enter the syslog server URI and select the network protocol. Typically, - ``syslogd`` listens on port 514 and use the UDP protocol. + ``syslogd`` listens on port 514 and uses the UDP protocol. 3. Specify the syslog logging parameters: timeout, priority, and facility. .. TODO: move to UI reference @@ -99,7 +97,7 @@ Configuration parameters: Selecting audit events to record -------------------------------- -When audit log is enabled, |tcm| records all audit events listed in :ref:`Event types `. +When the audit log is enabled, |tcm| records all audit events listed in :ref:`Event types `. To decrease load and make the audit log comply with specific security requirements, you can record only selected events. For example, these can be events of user account management or events of cluster data access. @@ -115,14 +113,13 @@ To remove an event type from a filters list, click the cross icon beside it. Viewing audit log ----------------- -If audit log is written to a file, you can view it in |tcm|. -To view audit log in |tcm|, go to the **Audit log** page. On this page, you can -view or search for events. +If the audit log is written to a file, you can view it in |tcm| in the **Audit log** page. +On this page, you can view or search for events. To view the details of a logged audit event, click the corresponding line in the table. -To search for an event, use the search bar on the top of the page. Note that the +To search for an event, use the search bar at the top of the page. Note that the search is case-sensitive. For example, to find events with the ``ALARM`` severity, enter ``ALARM``, not ``alarm``. From b52218ebc927c3790447ecb454381695c124c213 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 4 Dec 2023 15:01:10 +0700 Subject: [PATCH 3/4] Fix TCM audit log doc --- doc/reference/tooling/tcm/tcm_audit_log.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/reference/tooling/tcm/tcm_audit_log.rst b/doc/reference/tooling/tcm/tcm_audit_log.rst index cae6d57c28..febfb150e4 100644 --- a/doc/reference/tooling/tcm/tcm_audit_log.rst +++ b/doc/reference/tooling/tcm/tcm_audit_log.rst @@ -12,7 +12,7 @@ Audit log and security-related events, such as: * Successful and failed login attempts. -* Access to clusters, their configurations, data model, and stored data. +* Access to clusters, their configurations, data models, and stored data. * Changes in the access control system: users, roles, passwords, LDAP configurations. The complete list of |tcm| audit events is provided in :ref:`Event types `. @@ -30,8 +30,8 @@ event type, description, time, impacted objects, and other information that may be used for incident investigation. The complete list of fields is provided in :ref:`Structure of audit log events `. -In addition to writing audit logs, |tcm| has a built-in interface for reading and -searching them. For details, see :ref:`Viewing audit logs `. +|tcm| also provides a built-in interface for reading and searching the audit log. +For details, see :ref:`Viewing audit log `. .. _tcm_audit_log_enable: From c611b0a001b6f0d1c4b44f222c51724d3cabc49d Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 5 Dec 2023 11:30:29 +0700 Subject: [PATCH 4/4] Fix --- doc/reference/tooling/tcm/tcm_audit_log.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/reference/tooling/tcm/tcm_audit_log.rst b/doc/reference/tooling/tcm/tcm_audit_log.rst index febfb150e4..07af2662f2 100644 --- a/doc/reference/tooling/tcm/tcm_audit_log.rst +++ b/doc/reference/tooling/tcm/tcm_audit_log.rst @@ -113,7 +113,7 @@ To remove an event type from a filters list, click the cross icon beside it. Viewing audit log ----------------- -If the audit log is written to a file, you can view it in |tcm| in the **Audit log** page. +If the audit log is written to a file, you can view it in |tcm| on the **Audit log** page. On this page, you can view or search for events. To view the details of a logged audit event, click the corresponding line in the @@ -179,9 +179,10 @@ All entries of the |tcm| audit log include the mandatory fields listed in the ta - Additional fields for specific event types in the key-value format - Key examples: - - ``clusterId`` in cluster-related events. - - ``username`` in ``current.*`` or ``auth.*`` events + - ``clusterId`` in cluster-related events - ``payload`` in events that include sending data to the server + - ``username`` in ``current.*`` or ``auth.*`` events + This is an example of an audit log entry on a successful login attempt: