Skip to content

Commit e205a0d

Browse files
p7novandreyaksenov
p7nov
and
andreyaksenov
authored
Add TCM audit log docs (#3869)
Resolves #3855 Co-authored-by: Andrey Aksenov <[email protected]>
1 parent f820361 commit e205a0d

File tree

2 files changed

+335
-0
lines changed

2 files changed

+335
-0
lines changed

‎doc/reference/tooling/tcm/index.rst

+2
Original file line numberDiff line numberDiff line change
@@ -29,5 +29,7 @@ For example, a user can be an administrator of a specific cluster or only have t
2929
to read data. LDAP authorization is supported as well.
3030

3131
.. toctree::
32+
:maxdepth: 1
3233

3334
tcm_access_control
35+
tcm_audit_log

‎doc/reference/tooling/tcm/tcm_audit_log.rst

+333
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
.. _tcm_audit_log:
2+
3+
Audit log
4+
=========
5+
6+
.. admonition:: Enterprise Edition
7+
:class: fact
8+
9+
|tcm_full_name| is a part of the `Enterprise Edition <https://www.tarantool.io/compare/>`_.
10+
11+
|tcm_full_name| provides the audit logging functionality for tracking user activity
12+
and security-related events, such as:
13+
14+
* Successful and failed login attempts.
15+
* Access to clusters, their configurations, data models, and stored data.
16+
* Changes in the access control system: users, roles, passwords, LDAP configurations.
17+
18+
The complete list of |tcm| audit events is provided in :ref:`Event types <tcm_audit_log_event_types>`.
19+
20+
.. note::
21+
22+
|tcm| audit log records only events that happen in |tcm| itself.
23+
For information about Tarantool audit logging, see :ref:`Audit module <enterprise_audit_module>`.
24+
25+
Audit logging is disabled in |tcm| by default. To start recording events, you need
26+
to :ref:`enable <tcm_audit_log_enable>` and :ref:`configure <tcm_audit_log_config>` it.
27+
28+
The audit log stores event details in the JSON format. Each log entry contains the
29+
event type, description, time, impacted objects, and other information that
30+
may be used for incident investigation. The complete list of fields is provided in
31+
:ref:`Structure of audit log events <tcm_audit_log_structure>`.
32+
33+
|tcm| also provides a built-in interface for reading and searching the audit log.
34+
For details, see :ref:`Viewing audit log <tcm_audit_log_view>`.
35+
36+
.. _tcm_audit_log_enable:
37+
38+
Enabling audit logging
39+
----------------------
40+
41+
To enable audit logging in |tcm|, go to **Audit settings** and click **Enable**.
42+
43+
To additionally send audit log events to the standard output, click **Send to stdout**.
44+
45+
.. _tcm_audit_log_config:
46+
47+
Audit log configuration
48+
-----------------------
49+
50+
|tcm| audit events can be logged to a local file or sent to a
51+
`syslog <https://datatracker.ietf.org/doc/rfc5424/>`__ server.
52+
To configure audit logging, go to **Audit settings**.
53+
54+
Writing to a file
55+
~~~~~~~~~~~~~~~~~
56+
57+
To write |tcm| audit logs to a file:
58+
59+
1. Go to **Audit settings** and select the **file** protocol.
60+
2. Specify the name of the audit log file. The file appears in the |tcm| working directory.
61+
3. Configure the log files rotation: the maximum file size and age, and the number
62+
of files to store simultaneously.
63+
4. (Optional) Enable compression of audit log files.
64+
65+
.. TODO: move to UI reference
66+
67+
Configuration parameters:
68+
69+
- **Output file name**. The name of the audit log file. Default: ``audit.log``
70+
- **Max size (in MB)**. The maximum size of the log file before it gets rotated, in megabytes. Default: 100.
71+
- **Max backups**. The maximum number of stored audit log files. Default: 10.
72+
- **Max age (in days)**. The maximum age of audit log files in days. Default: 30.
73+
- **Compress**. Compress audit log files into ``gzip`` archives when rotating.
74+
75+
Sending to syslog
76+
~~~~~~~~~~~~~~~~~
77+
78+
If you use a centralized log management system based on `syslog <https://datatracker.ietf.org/doc/rfc5424/>`__,
79+
you can configure |tcm| to send its audit log to your syslog server:
80+
81+
1. Go to **Audit settings** and select the **syslog** protocol.
82+
2. Enter the syslog server URI and select the network protocol. Typically,
83+
``syslogd`` listens on port 514 and uses the UDP protocol.
84+
3. Specify the syslog logging parameters: timeout, priority, and facility.
85+
86+
.. TODO: move to UI reference
87+
88+
Configuration parameters:
89+
90+
- **Protocol**. The network protocol used for connecting to the syslog server. Default: ``udp``.
91+
- **Output**. The syslog server URI. Default: 127.0.0.1:514 (localhost).
92+
- **Timeout**. The syslog write timeout in the `ISO 8601 duration format <https://en.wikipedia.org/wiki/ISO_8601#Durations>`__.
93+
Default: ``PT2S`` (two seconds).
94+
- **Priority**. The syslog severity level. Default: ``info``.
95+
- **Facility**. The syslog facility. Default: ``local0``.
96+
97+
Selecting audit events to record
98+
--------------------------------
99+
100+
When the audit log is enabled, |tcm| records all audit events listed in :ref:`Event types <tcm_audit_log_event_types>`.
101+
To decrease load and make the audit log comply with specific security
102+
requirements, you can record only selected events. For example, these can be events
103+
of user account management or events of cluster data access.
104+
105+
To select events to record into the audit log, go to **Audit settings** and
106+
enter their :ref:`types <tcm_audit_log_event_types>` into the **Filters** field
107+
one-by-one, pressing the **Enter** key after each type.
108+
109+
To remove an event type from a filters list, click the cross icon beside it.
110+
111+
.. _tcm_audit_log_view:
112+
113+
Viewing audit log
114+
-----------------
115+
116+
If the audit log is written to a file, you can view it in |tcm| on the **Audit log** page.
117+
On this page, you can view or search for events.
118+
119+
To view the details of a logged audit event, click the corresponding line in the
120+
table.
121+
122+
To search for an event, use the search bar at the top of the page. Note that the
123+
search is case-sensitive. For example, to find events with the ``ALARM`` severity,
124+
enter ``ALARM``, not ``alarm``.
125+
126+
.. _tcm_audit_log_structure:
127+
128+
Structure of audit log events
129+
-----------------------------
130+
131+
All entries of the |tcm| audit log include the mandatory fields listed in the table below.
132+
133+
.. container:: table
134+
135+
.. list-table::
136+
:widths: 20 40 40
137+
:header-rows: 1
138+
139+
* - Field
140+
- Description
141+
- Example
142+
* - ``time``
143+
- Time of the event
144+
- 2023-11-23T12:05:27.099+07:00
145+
* - ``severity``
146+
- Event severity: ``VERBOSE``, ``INFO``, ``WARNING``, or ``ALARM``
147+
- INFO
148+
* - ``type``
149+
- Audit :ref:`event type <tcm_audit_log_event_types>`
150+
- user.update
151+
* - ``description``
152+
- Human-readable event description
153+
- Update user
154+
* - ``uuid``
155+
- Event UUID
156+
- f8744f51-5760-40c3-ae2d-0b4d6b44836f
157+
* - ``user``
158+
- UUID of the user who triggered the event
159+
- 942a4f54-cf7f-4f46-80ce-3511dbbb57b7
160+
* - ``remote``
161+
- Remote host that triggered the event
162+
- 100.96.163.226:48722
163+
* - ``host``
164+
- The |tcm| host on which the event happened
165+
- 100.96.163.226:8080
166+
* - ``userAgent``
167+
- Information about the client application and platform that was used to trigger the event
168+
- 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
169+
* - ``permission``
170+
- The permission that was used to trigger the event
171+
- ["admin.users.write"]
172+
* - ``result``
173+
- Event result: ``ok`` or ``nok``
174+
- ok
175+
* - ``err``
176+
- Human-readable error description for events with ``nok`` result
177+
- failed to login
178+
* - ``fields``
179+
- Additional fields for specific event types in the key-value format
180+
- Key examples:
181+
182+
- ``clusterId`` in cluster-related events
183+
- ``payload`` in events that include sending data to the server
184+
- ``username`` in ``current.*`` or ``auth.*`` events
185+
186+
187+
This is an example of an audit log entry on a successful login attempt:
188+
189+
.. code-block:: json
190+
191+
{
192+
"time": "2023-11-23T12:01:27.247+07:00",
193+
"severity": "INFO",
194+
"description": "Login user",
195+
"type": "current.login",
196+
"uuid": "4b9c2dd1-d9a1-4b40-a448-6bef4a0e5c79",
197+
"user": "",
198+
"remote": "127.0.0.1:63370",
199+
"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",
200+
"host": "127.0.0.1:8080",
201+
"permissions": [],
202+
"result": "ok",
203+
"fields": [
204+
{
205+
"Key": "username",
206+
"Value": "admin"
207+
},
208+
{
209+
"Key": "method",
210+
"Value": "null"
211+
},
212+
{
213+
"Key": "output",
214+
"Value": "true"
215+
}
216+
]
217+
}
218+
219+
.. _tcm_audit_log_event_types:
220+
221+
Event types
222+
-----------
223+
224+
The following table lists all possible values of the ``type`` field of |tcm|
225+
audit log events.
226+
227+
.. container:: table
228+
229+
.. list-table::
230+
:widths: auto
231+
:header-rows: 1
232+
233+
* - Event type
234+
- Description
235+
236+
* - ``auth.fail``
237+
- Authentication failed
238+
* - ``auth.ok``
239+
- Authentication successful
240+
* - ``access.denied``
241+
- An attempt to access an object without the required permission
242+
* - ``user.add``
243+
- User added
244+
* - ``user.update``
245+
- User updated
246+
* - ``user.delete``
247+
- User deleted
248+
* - ``secret.add``
249+
- User secret added
250+
* - ``secret.update``
251+
- User secret updated
252+
* - ``secret.block``
253+
- User secret blocked
254+
* - ``secret.unblock``
255+
- User secret unblocked
256+
* - ``secret.delete``
257+
- User secret deleted
258+
* - ``secret.expire``
259+
- User secret expired
260+
* - ``session.revoke``
261+
- Session revoked
262+
* - ``session.revokeuser``
263+
- All user's sessions revoked
264+
* - ``explorer.insert``
265+
- Data inserted in a cluster
266+
* - ``explorer.delete``
267+
- Data deleted from a cluster
268+
* - ``explorer.replace``
269+
- Data replaced in a cluster
270+
* - ``explorer.call``
271+
- Stored function called on a cluster
272+
* - ``explorer.evaluate``
273+
- Code executed on a cluster
274+
* - ``explorer.switchover``
275+
- Master switched manually
276+
* - ``test.devmode``
277+
- Switched to development mode
278+
* - ``auditlog.config``
279+
- Audit log configuration changed
280+
* - ``passwordpolicy.save``
281+
- Password policy changed
282+
* - ``passwordpolicy.resetpasswords``
283+
- All passwords expired by an administrator
284+
* - ``ddl.save``
285+
- Cluster data model saved
286+
* - ``ddl.apply``
287+
- Cluster data model applied
288+
* - ``cluster.config.save``
289+
- Cluster configuration saved
290+
* - ``cluster.config.reset``
291+
- Saved cluster configuration reset
292+
* - ``cluster.config.apply``
293+
- Cluster configuration applied
294+
* - ``current.logout``
295+
- User logged out their own session
296+
* - ``current.revoke``
297+
- User revoked their own session
298+
* - ``current.revokeall``
299+
- User revoked all their active sessions
300+
* - ``current.changepassword``
301+
- User changed their password
302+
* - ``role.add``
303+
- Role added
304+
* - ``role.update``
305+
- Role updated
306+
* - ``role.delete``
307+
- Role deleted
308+
* - ``cluster.add``
309+
- Cluster added
310+
* - ``cluster.update``
311+
- Cluster updated
312+
* - ``cluster.delete``
313+
- Cluster removed
314+
* - ``ldap.testlogin``
315+
- Login test executed for a LDAP configuration
316+
* - ``ldap.testconnection``
317+
- Connection test executed for a LDAP configuration
318+
* - ``ldap.add``
319+
- LDAP configuration added
320+
* - ``ldap.update``
321+
- LDAP configuration updated
322+
* - ``ldap.delete``
323+
- LDAP configuration deleted
324+
* - ``addon.enable``
325+
- Add-on enabled
326+
* - ``addon.disable``
327+
- Add-on disabled
328+
* - ``addon.delete``
329+
- Add-on removed
330+
* - ``tcmstate.save``
331+
- Low-level information saved in the TCM storage (for debug purposes)
332+
* - ``tcmstate.delete``
333+
- Low-level information deleted from the TCM storage (for debug purposes)

0 commit comments

Comments
 (0)