Skip to content

Commit eb2100c

Browse files
p7novp7nov
committed
Add TCM audit log docs
1 parent 40e9ad4 commit eb2100c

File tree

2 files changed

+337
-0
lines changed

2 files changed

+337
-0
lines changed

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

Lines changed: 2 additions & 0 deletions
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

Lines changed: 335 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,335 @@
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 model, 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+
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+
In addition to writing audit logs, |tcm| has a built-in interface for reading and
34+
searching them. For details, see :ref:`Viewing audit logs <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: 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+
To send |tcm| audit logs to a syslog server:
82+
83+
1. Go to **Audit settings** and select the **syslog** protocol.
84+
2. Enter the syslog server URI and select the network protocol. Typically,
85+
``syslogd`` listens on port 514 and use the UDP protocol.
86+
3. Specify the syslog logging parameters: timeout, priority, and facility.
87+
88+
.. TODO: move to UI reference
89+
90+
Configuration parameters:
91+
92+
- **Protocol**. The network protocol used for connecting to the syslog server. Default: ``udp``.
93+
- **Output**. The syslog server URI. Default: 127.0.0.1:514 (localhost).
94+
- **Timeout**. The syslog write timeout in the `ISO 8601 duration format <https://en.wikipedia.org/wiki/ISO_8601#Durations>`__.
95+
Default: ``PT2S`` (two seconds).
96+
- **Priority**. The syslog severity level. Default: ``info``.
97+
- **Facility**. The syslog facility. Default: ``local0``.
98+
99+
Selecting audit events to record
100+
--------------------------------
101+
102+
When audit log is enabled, |tcm| records all audit events listed in :ref:`Event types <tcm_audit_log_event_types>`.
103+
To decrease load and make the audit log comply with specific security
104+
requirements, you can record only selected events. For example, these can be events
105+
of user account management or events of cluster data access.
106+
107+
To select events to record into the audit log, go to **Audit settings** and
108+
enter their :ref:`types <tcm_audit_log_event_types>` into the **Filters** field
109+
one-by-one, pressing the **Enter** key after each type.
110+
111+
To remove an event type from a filters list, click the cross icon beside it.
112+
113+
.. _tcm_audit_log_view:
114+
115+
Viewing audit log
116+
-----------------
117+
118+
If audit log is written to a file, you can view it in |tcm|.
119+
To view audit log in |tcm|, go to the **Audit log** page. On this page, you can
120+
view or search for events.
121+
122+
To view the details of a logged audit event, click the corresponding line in the
123+
table.
124+
125+
To search for an event, use the search bar on the top of the page. Note that the
126+
search is case-sensitive. For example, to find events with the ``ALARM`` severity,
127+
enter ``ALARM``, not ``alarm``.
128+
129+
.. _tcm_audit_log_structure:
130+
131+
Structure of audit log events
132+
-----------------------------
133+
134+
All entries of the |tcm| audit log include the mandatory fields listed in the table below.
135+
136+
.. container:: table
137+
138+
.. list-table::
139+
:widths: 20 40 40
140+
:header-rows: 1
141+
142+
* - Field
143+
- Description
144+
- Example
145+
* - ``time``
146+
- Time of the event
147+
- 2023-11-23T12:05:27.099+07:00
148+
* - ``severity``
149+
- Event severity: ``VERBOSE``, ``INFO``, ``WARNING``, or ``ALARM``
150+
- INFO
151+
* - ``type``
152+
- Audit :ref:`event type <tcm_audit_log_event_types>`
153+
- user.update
154+
* - ``description``
155+
- Human-readable event description
156+
- Update user
157+
* - ``uuid``
158+
- Event UUID
159+
- f8744f51-5760-40c3-ae2d-0b4d6b44836f
160+
* - ``user``
161+
- UUID of the user who triggered the event
162+
- 942a4f54-cf7f-4f46-80ce-3511dbbb57b7
163+
* - ``remote``
164+
- Remote host that triggered the event
165+
- 100.96.163.226:48722
166+
* - ``host``
167+
- The |tcm| host on which the event happened
168+
- 100.96.163.226:8080
169+
* - ``userAgent``
170+
- Information about the client application and platform that was used to trigger the event
171+
- 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
172+
* - ``permission``
173+
- The permission that was used to trigger the event
174+
- ["admin.users.write"]
175+
* - ``result``
176+
- Event result: ``ok`` or ``nok``
177+
- ok
178+
* - ``err``
179+
- Human-readable error description for events with ``nok`` result
180+
- failed to login
181+
* - ``fields``
182+
- Additional fields for specific event types in the key-value format
183+
- Key examples:
184+
185+
- ``clusterId`` in cluster-related events.
186+
- ``username`` in ``current.*`` or ``auth.*`` events
187+
- ``payload`` in events that include sending data to the server
188+
189+
This is an example of an audit log entry on a successful login attempt:
190+
191+
.. code-block:: json
192+
193+
{
194+
"time": "2023-11-23T12:01:27.247+07:00",
195+
"severity": "INFO",
196+
"description": "Login user",
197+
"type": "current.login",
198+
"uuid": "4b9c2dd1-d9a1-4b40-a448-6bef4a0e5c79",
199+
"user": "",
200+
"remote": "127.0.0.1:63370",
201+
"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",
202+
"host": "127.0.0.1:8080",
203+
"permissions": [],
204+
"result": "ok",
205+
"fields": [
206+
{
207+
"Key": "username",
208+
"Value": "admin"
209+
},
210+
{
211+
"Key": "method",
212+
"Value": "null"
213+
},
214+
{
215+
"Key": "output",
216+
"Value": "true"
217+
}
218+
]
219+
}
220+
221+
.. _tcm_audit_log_event_types:
222+
223+
Event types
224+
-----------
225+
226+
The following table lists all possible values of the ``type`` field of |tcm|
227+
audit log events.
228+
229+
.. container:: table
230+
231+
.. list-table::
232+
:widths: auto
233+
:header-rows: 1
234+
235+
* - Event type
236+
- Description
237+
238+
* - ``auth.fail``
239+
- Authentication failed
240+
* - ``auth.ok``
241+
- Authentication successful
242+
* - ``access.denied``
243+
- An attempt to access an object without the required permission
244+
* - ``user.add``
245+
- User added
246+
* - ``user.update``
247+
- User updated
248+
* - ``user.delete``
249+
- User deleted
250+
* - ``secret.add``
251+
- User secret added
252+
* - ``secret.update``
253+
- User secret updated
254+
* - ``secret.block``
255+
- User secret blocked
256+
* - ``secret.unblock``
257+
- User secret unblocked
258+
* - ``secret.delete``
259+
- User secret deleted
260+
* - ``secret.expire``
261+
- User secret expired
262+
* - ``session.revoke``
263+
- Session revoked
264+
* - ``session.revokeuser``
265+
- All user's sessions revoked
266+
* - ``explorer.insert``
267+
- Data inserted in a cluster
268+
* - ``explorer.delete``
269+
- Data deleted from a cluster
270+
* - ``explorer.replace``
271+
- Data replaced in a cluster
272+
* - ``explorer.call``
273+
- Stored function called on a cluster
274+
* - ``explorer.evaluate``
275+
- Code executed on a cluster
276+
* - ``explorer.switchover``
277+
- Master switched manually
278+
* - ``test.devmode``
279+
- Switched to development mode
280+
* - ``auditlog.config``
281+
- Audit log configuration changed
282+
* - ``passwordpolicy.save``
283+
- Password policy changed
284+
* - ``passwordpolicy.resetpasswords``
285+
- All passwords expired by an administrator
286+
* - ``ddl.save``
287+
- Cluster data model saved
288+
* - ``ddl.apply``
289+
- Cluster data model applied
290+
* - ``cluster.config.save``
291+
- Cluster configuration saved
292+
* - ``cluster.config.reset``
293+
- Saved cluster configuration reset
294+
* - ``cluster.config.apply``
295+
- Cluster configuration applied
296+
* - ``current.logout``
297+
- User logged out their own session
298+
* - ``current.revoke``
299+
- User revoked their own session
300+
* - ``current.revokeall``
301+
- User revoked all their active sessions
302+
* - ``current.changepassword``
303+
- User changed their password
304+
* - ``role.add``
305+
- Role added
306+
* - ``role.update``
307+
- Role updated
308+
* - ``role.delete``
309+
- Role deleted
310+
* - ``cluster.add``
311+
- Cluster added
312+
* - ``cluster.update``
313+
- Cluster updated
314+
* - ``cluster.delete``
315+
- Cluster removed
316+
* - ``ldap.testlogin``
317+
- Login test executed for a LDAP configuration
318+
* - ``ldap.testconnection``
319+
- Connection test executed for a LDAP configuration
320+
* - ``ldap.add``
321+
- LDAP configuration added
322+
* - ``ldap.update``
323+
- LDAP configuration updated
324+
* - ``ldap.delete``
325+
- LDAP configuration deleted
326+
* - ``addon.enable``
327+
- Add-on enabled
328+
* - ``addon.disable``
329+
- Add-on disabled
330+
* - ``addon.delete``
331+
- Add-on removed
332+
* - ``tcmstate.save``
333+
- Low-level information saved in the TCM storage (for debug purposes)
334+
* - ``tcmstate.delete``
335+
- Low-level information deleted from the TCM storage (for debug purposes)

0 commit comments

Comments
 (0)