audit: Add documentation for the audit subsystem
Adds detailed documentation covering the new audit subsystem: - Add new audit.md design document explaining: - Core concepts and design decisions - CQL extensions for audit management - Implementation details and trigger evaluation - Prior art references from other databases - Add user-facing documentation: - New auditing.rst guide with configuration and usage details - Integration with security documentation index - Updates to cluster management procedures - Updates to security checklist The documentation covers all aspects of the audit system including: - Configuration options and storage backends (syslog/table) - Audit categories (DCL/DDL/AUTH/DML/QUERY/ADMIN) - Permission model and security considerations - Failure handling and logging - Example configurations and output formats This ensures users have complete guidance for setting up and using the new audit capabilities.
This commit is contained in:
Paweł Zakrzewski
113
docs/dev/audit.md
Normal file
113
docs/dev/audit.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Introduction
|
||||
|
||||
Similar to the approach described in CASSANDRA-14471, we add the
|
||||
concept of an audit specification. An audit has a target (syslog or a
|
||||
table) and a set of events/actions that it wants recorded. We
|
||||
introduce new CQL syntax for Scylla users to describe and manipulate
|
||||
audit specifications.
|
||||
|
||||
Prior art:
|
||||
- Microsoft SQL Server [audit
|
||||
description](https://docs.microsoft.com/en-us/sql/relational-databases/security/auditing/sql-server-audit-database-engine?view=sql-server-ver15)
|
||||
- pgAudit [docs](https://github.com/pgaudit/pgaudit/blob/master/README.md)
|
||||
- MySQL audit_log docs in
|
||||
[MySQL](https://dev.mysql.com/doc/refman/8.0/en/audit-log.html) and
|
||||
[Azure](https://docs.microsoft.com/en-us/azure/mysql/concepts-audit-logs)
|
||||
- DynamoDB can [use CloudTrail](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/logging-using-cloudtrail.html) to log all events
|
||||
|
||||
# CQL extensions
|
||||
|
||||
## Create an audit
|
||||
|
||||
```cql
|
||||
CREATE AUDIT [IF NOT EXISTS] audit-name WITH TARGET { SYSLOG | table-name }
|
||||
[ AND TRIGGER KEYSPACE IN (ks1, ks2, ks3) ]
|
||||
[ AND TRIGGER TABLE IN (tbl1, tbl2, tbl3) ]
|
||||
[ AND TRIGGER ROLE IN (usr1, usr2, usr3) ]
|
||||
[ AND TRIGGER CATEGORY IN (cat1, cat2, cat3) ]
|
||||
;
|
||||
```
|
||||
|
||||
From this point on, every database event that matches all present
|
||||
triggers will be recorded in the target. When the target is a table,
|
||||
it behaves like the [current
|
||||
design](https://docs.scylladb.com/operating-scylla/security/auditing/#table-storage).
|
||||
|
||||
The audit name must be different from all other audits, unless IF NOT
|
||||
EXISTS precedes it, in which case the existing audit must be identical
|
||||
to the new definition. Case sensitivity and length limit are the same
|
||||
as for table names.
|
||||
|
||||
A trigger kind (ie, `KEYSPACE`, `TABLE`, `ROLE`, or `CATEGORY`) can be
|
||||
specified at most once.
|
||||
|
||||
## Show an audit
|
||||
|
||||
```cql
|
||||
DESCRIBE AUDIT [audit-name ...];
|
||||
```
|
||||
|
||||
Prints definitions of all audits named herein. If no names are
|
||||
provided, prints all audits.
|
||||
|
||||
## Delete an audit
|
||||
|
||||
```cql
|
||||
DROP AUDIT audit-name;
|
||||
```
|
||||
|
||||
Stops logging events specified by this audit. Doesn't impact the
|
||||
already logged events. If the target is a table, it remains as it is.
|
||||
|
||||
## Alter an audit
|
||||
|
||||
```cql
|
||||
ALTER AUDIT audit-name WITH {same syntax as CREATE}
|
||||
```
|
||||
|
||||
Any trigger provided will be updated (or newly created, if previously
|
||||
absent). To drop a trigger, use `IN *`.
|
||||
|
||||
## Permissions
|
||||
|
||||
Only superusers can modify audits or turn them on and off.
|
||||
|
||||
Only superusers can read tables that are audit targets; no user can
|
||||
modify them. Only superusers can drop tables that are audit targets,
|
||||
after the audit itself is dropped. If a superuser doesn't drop a
|
||||
target table, it remains in existence indefinitely.
|
||||
|
||||
# Implementation
|
||||
|
||||
## Efficient trigger evaluation
|
||||
|
||||
```c++
|
||||
namespace audit {
|
||||
|
||||
/// Stores triggers from an AUDIT statement.
|
||||
class triggers {
|
||||
// Use trie structures for speedy string lookup.
|
||||
optional<trie> _ks_trigger, _tbl_trigger, _usr_trigger;
|
||||
|
||||
// A logical-AND filter.
|
||||
optional<unsigned> _cat_trigger;
|
||||
|
||||
public:
|
||||
/// True iff every non-null trigger matches the corresponding ainf element.
|
||||
bool should_audit(const audit_info& ainf);
|
||||
};
|
||||
|
||||
} // namespace audit
|
||||
```
|
||||
|
||||
To prevent modification of target tables, `audit::inspect()` will
|
||||
check the statement and throw if it is disallowed, similar to what
|
||||
`check_access()` currently does.
|
||||
|
||||
## Persisting audit definitions
|
||||
|
||||
Obviously, an audit definition must survive a server restart and stay
|
||||
consistent among all nodes in a cluster. We'll accomplish both by
|
||||
storing audits in a system table. They will be cached in memory the
|
||||
same way `permissions_cache` caches table contents in `permission_set`
|
||||
objects resident in memory.
|
||||
@@ -161,6 +161,7 @@ Add New DC
|
||||
|
||||
* Keyspace created by the user (which needed to replicate to the new DC).
|
||||
* System: ``system_distributed``, ``system_traces``, for example, replicate the data to three nodes in the new DC.
|
||||
* ``audit`` - if enabled - replicate the data to three nodes in the new DC.
|
||||
|
||||
For example:
|
||||
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
* :doc:`Enable Authorization</operating-scylla/security/enable-authorization/>`
|
||||
* :doc:`Grant Authorization CQL Reference </operating-scylla/security/authorization/>`
|
||||
* :doc:`Role Based Access Control (RBAC) </operating-scylla/security/rbac-usecase/>`
|
||||
* :doc:`Scylla Auditing Guide </operating-scylla/security/auditing/>`
|
||||
* :doc:`Encryption: Data in Transit Client to Node </operating-scylla/security/client-node-encryption/>`
|
||||
* :doc:`Encryption: Data in Transit Node to Node </operating-scylla/security/node-node-encryption/>`
|
||||
* :doc:`Generating a self-signed Certificate Chain Using openssl </operating-scylla/security/generate-certificate/>`
|
||||
|
||||
227
docs/operating-scylla/security/auditing.rst
Normal file
227
docs/operating-scylla/security/auditing.rst
Normal file
@@ -0,0 +1,227 @@
|
||||
========================
|
||||
ScyllaDB Auditing Guide
|
||||
========================
|
||||
|
||||
:label-tip:`ScyllaDB Enterprise`
|
||||
|
||||
|
||||
Auditing allows the administrator to monitor activities on a Scylla cluster, including queries and data changes.
|
||||
The information is stored in a Syslog or a Scylla table.
|
||||
|
||||
Prerequisite
|
||||
------------
|
||||
|
||||
Enable ScyllaDB :doc:`Authentication </operating-scylla/security/authentication>` and :doc:`Authorization </operating-scylla/security/enable-authorization>`.
|
||||
|
||||
|
||||
Enabling Audit
|
||||
---------------
|
||||
|
||||
By default, auditing is **disabled**. Enabling auditing is controlled by the ``audit:`` parameter in the ``scylla.yaml`` file.
|
||||
You can set the following options:
|
||||
|
||||
* ``none`` - Audit is disabled (default).
|
||||
* ``table`` - Audit is enabled, and messages are stored in a Scylla table.
|
||||
* ``syslog`` - Audit is enabled, and messages are sent to Syslog.
|
||||
|
||||
Configuring any other value results in an error at Scylla startup.
|
||||
|
||||
Configuring Audit
|
||||
-----------------
|
||||
|
||||
The audit can be tuned using the following flags or ``scylla.yaml`` entries:
|
||||
|
||||
================== ================================== ========================================================================================================================
|
||||
Flag Default Value Description
|
||||
================== ================================== ========================================================================================================================
|
||||
audit_categories "DCL,DDL,AUTH,ADMIN" Comma-separated list of statement categories that should be audited
|
||||
------------------ ---------------------------------- ------------------------------------------------------------------------------------------------------------------------
|
||||
audit_tables “” Comma-separated list of table names that should be audited, in the format of <keyspacename>.<tablename>
|
||||
------------------ ---------------------------------- ------------------------------------------------------------------------------------------------------------------------
|
||||
audit_keyspaces “” Comma-separated list of keyspaces that should be audited. You must specify at least one keyspace.
|
||||
If you leave this option empty, no keyspace will be audited.
|
||||
================== ================================== ========================================================================================================================
|
||||
|
||||
To audit all the tables in a keyspace, set the ``audit_keyspaces`` with the keyspace you want to audit and leave ``audit_tables`` empty.
|
||||
|
||||
You can use DCL, AUTH, and ADMIN audit categories without including any keyspace or table.
|
||||
|
||||
audit_categories parameter description
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
========= =========================================================================================
|
||||
Parameter Logs Description
|
||||
========= =========================================================================================
|
||||
AUTH Logs login events
|
||||
--------- -----------------------------------------------------------------------------------------
|
||||
DML Logs insert, update, delete, and other data manipulation language (DML) events
|
||||
--------- -----------------------------------------------------------------------------------------
|
||||
DDL Logs object and role create, alter, drop, and other data definition language (DDL) events
|
||||
--------- -----------------------------------------------------------------------------------------
|
||||
DCL Logs grant, revoke, create role, drop role, and list roles events
|
||||
--------- -----------------------------------------------------------------------------------------
|
||||
QUERY Logs all queries
|
||||
--------- -----------------------------------------------------------------------------------------
|
||||
ADMIN Logs service level operations: create, alter, drop, attach, detach, list.
|
||||
For :ref:`service level <workload-priorization-service-level-management>`
|
||||
auditing, this parameter is available in Scylla Enterprise 2019.1 and later.
|
||||
========= =========================================================================================
|
||||
|
||||
Note that audit for every DML or QUERY might impact performance and consume a lot of storage.
|
||||
|
||||
Configuring Audit Storage
|
||||
---------------------------
|
||||
|
||||
Auditing messages can be sent to :ref:`Syslog <auditing-syslog-storage>` or stored in a Scylla :ref:`table <auditing-table-storage>`.
|
||||
Currently, auditing messages can only be saved to one location at a time. You cannot log into both a table and the Syslog.
|
||||
|
||||
.. _auditing-syslog-storage:
|
||||
|
||||
Storing Audit Messages in Syslog
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
**Procedure**
|
||||
|
||||
#. Set the ``audit`` parameter in the ``scylla.yaml`` file to ``syslog``.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
# audit setting
|
||||
# by default, Scylla does not audit anything.
|
||||
# It is possible to enable auditing to the following places:
|
||||
# - audit.audit_log column family by setting the flag to "table"
|
||||
audit: "syslog"
|
||||
#
|
||||
# List of statement categories that should be audited.
|
||||
audit_categories: "DCL,DDL,AUTH"
|
||||
#
|
||||
# List of tables that should be audited.
|
||||
audit_tables: "mykespace.mytable"
|
||||
#
|
||||
# List of keyspaces that should be fully audited.
|
||||
# All tables in those keyspaces will be audited
|
||||
audit_keyspaces: "mykespace"
|
||||
|
||||
#. Restart the Scylla node.
|
||||
|
||||
.. include:: /rst_include/scylla-commands-restart-index.rst
|
||||
|
||||
By default, audit messages are written to the same destination as Scylla :doc:`logging </getting-started/logging>`, with ``scylla-audit`` as the process name.
|
||||
|
||||
Logging output example (drop table):
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
Mar 18 09:53:52 ip-10-143-2-108 scylla-audit[28387]: "10.143.2.108", "DDL", "ONE", "team_roster", "nba", "DROP TABLE nba.team_roster ;", "127.0.0.1", "anonymous", "false"
|
||||
|
||||
To redirect the Syslog output to a file, follow the steps below (available only for CentOS) :
|
||||
|
||||
#. Install rsyslog sudo ``dnf install rsyslog``.
|
||||
#. Edit ``/etc/rsyslog.conf`` and append the following to the file: ``if $programname contains 'scylla-audit' then /var/log/scylla-audit.log``.
|
||||
#. Start rsyslog ``systemctl start rsyslog``.
|
||||
#. Enable rsyslog ``systemctl enable rsyslog``.
|
||||
|
||||
.. _auditing-table-storage:
|
||||
|
||||
Storing Audit Messages in a Table
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Messages are stored in a Scylla table named ``audit.audit_log``.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
CREATE TABLE IF NOT EXISTS audit.audit_log (
|
||||
date timestamp,
|
||||
node inet,
|
||||
event_time timeuuid,
|
||||
category text,
|
||||
consistency text,
|
||||
table_name text,
|
||||
keyspace_name text,
|
||||
operation text,
|
||||
source inet,
|
||||
username text,
|
||||
error boolean,
|
||||
PRIMARY KEY ((date, node), event_time));
|
||||
|
||||
.. note:: The schema of ``audit.audit_log`` has been migrated in the 2024.2 version from ``SimpleStrategy RF=1`` to ``NetworkTopologyStrategy RF=3``:
|
||||
|
||||
* By default every DC will contain 3 audit replicas. If a new DC is added, in order for it to also contain audit replicas, audit's schema has to be manually altered.
|
||||
* CL for writes is still equal to ``1``, which implies that reading audit rows with CL=Quorum may fail, which is especially true for clusters with less than 3 nodes.
|
||||
|
||||
**Procedure**
|
||||
|
||||
#. Set the ``audit`` parameter in the ``scylla.yaml`` file to ``table``.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
# audit setting
|
||||
# by default, Scylla does not audit anything.
|
||||
# It is possible to enable auditing to the following places:
|
||||
# - audit.audit_log column family by setting the flag to "table"
|
||||
audit: "table"
|
||||
#
|
||||
# List of statement categories that should be audited.
|
||||
audit_categories: "DCL,DDL,AUTH"
|
||||
#
|
||||
# List of tables that should be audited.
|
||||
audit_tables: "mykespace.mytable"
|
||||
#
|
||||
# List of keyspaces that should be fully audited.
|
||||
# All tables in those keyspaces will be audited
|
||||
audit_keyspaces: "mykespace"
|
||||
|
||||
#. Restart Scylla node.
|
||||
|
||||
.. include:: /rst_include/scylla-commands-restart-index.rst
|
||||
|
||||
Table output example (drop table):
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
SELECT * FROM audit.audit_log ;
|
||||
|
||||
returns:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
date | node | event_time | category | consistency | error | keyspace_name | operation | source | table_name | username |
|
||||
-------------------------+--------------+--------------------------------------+----------+-------------+-------+---------------+------------------------------+-----------------+-------------+----------+
|
||||
2018-03-18 00:00:00+0000 | 10.143.2.108 | 3429b1a5-2a94-11e8-8f4e-000000000001 | DDL | ONE | False | nba | DROP TABLE nba.team_roster ; | 127.0.0.1 | team_roster | Scylla |
|
||||
(1 row)
|
||||
|
||||
Handling Audit Failures
|
||||
---------------------------
|
||||
|
||||
In some cases, auditing may not be possible, for example, when:
|
||||
|
||||
* A table is used as the audit’s backend, and the audit partition where the audit row is saved is not available because the node that holds this partition is down.
|
||||
* Syslog is used as the audit’s backend, and the Syslog sink (a regular unix socket) is unresponsive/unavailable.
|
||||
|
||||
If the audit fails and audit messages are not stored in the configured audit’s backend, you can still review the audit log in the regular ScyllaDB logs.
|
||||
|
||||
The following example shows audit information in the regular ScyllaDB logs in the case when the Syslog backend is broken (for example, because the socket was closed) and you tried to connect to a node with incorrect credentials:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
ERROR 2024-01-15 14:09:41,516 [shard 0:sl:d] audit - Unexpected exception when writing login log with: node_ip <IP:port> client_ip <IP:port> username <username> error true exception audit::audit_exception (Starting syslog audit backend failed (sending a message to <socket_path> resulted in sendto: No such file or directory).)
|
||||
|
||||
Additional Resources
|
||||
-----------------------------------
|
||||
|
||||
* :doc:`Authorization</operating-scylla/security/authorization>`
|
||||
|
||||
* :doc:`Authentication</operating-scylla/security/authentication>`
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -14,6 +14,7 @@ Security
|
||||
authorization
|
||||
certificate-authentication
|
||||
rbac-usecase
|
||||
auditing
|
||||
client-node-encryption
|
||||
node-node-encryption
|
||||
generate-certificate
|
||||
@@ -28,6 +29,7 @@ Security
|
||||
:class: my-panel
|
||||
|
||||
* :doc:`ScyllaDB Security Checklist </operating-scylla/security/security-checklist/>`
|
||||
* :doc:`ScyllaDB Auditing Guide </operating-scylla/security/auditing/>`
|
||||
|
||||
.. panel-box::
|
||||
:title: Authentication and Authorization
|
||||
|
||||
@@ -71,10 +71,7 @@ The ScyllaDB ports are detailed in the table below. For ScyllaDB Manager ports,
|
||||
|
||||
Audit System Activity
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Auditing is available in `ScyllaDB Enterprise <https://enterprise.docs.scylladb.com/>`_.
|
||||
|
||||
Using the `auditing feature <https://enterprise.docs.scylladb.com/stable/operating-scylla/security/auditing.html>`_ allows the administrator to know “who did / looked at / changed what and when.” It also allows logging some or all the activities a user performs on the ScyllaDB cluster.
|
||||
Using the :doc:`auditing feature</operating-scylla/security/auditing/>` allows the administrator to know “who did / looked at / changed what and when.” It also allows logging some or all the activities a user performs on the ScyllaDB cluster.
|
||||
|
||||
General Recommendations
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Reference in New Issue
Block a user