From a1f4a229db62b687b70498dede029a871de1d8bd Mon Sep 17 00:00:00 2001 From: Leto_b Date: Mon, 2 Feb 2026 16:49:49 +0800 Subject: [PATCH] update audit log from 208 --- .../sidebar_timecho/V2.0.x/en-Table.ts | 1 + .../sidebar_timecho/V2.0.x/en-Tree.ts | 2 +- .../sidebar_timecho/V2.0.x/zh-Table.ts | 1 + .../sidebar_timecho/V2.0.x/zh-Tree.ts | 2 +- .../Table/User-Manual/Audit-Log_timecho.md | 123 ++++++++++++++ .../Tree/User-Manual/Audit-Log_timecho.md | 143 +++++++++------- .../User-Manual/Audit-Log_timecho.md | 123 ++++++++++++++ .../latest/User-Manual/Audit-Log_timecho.md | 143 +++++++++------- .../Table/User-Manual/Audit-Log_timecho.md | 123 ++++++++++++++ .../Tree/User-Manual/Audit-Log_timecho.md | 157 ++++++++++-------- .../User-Manual/Audit-Log_timecho.md | 123 ++++++++++++++ .../latest/User-Manual/Audit-Log_timecho.md | 157 ++++++++++-------- 12 files changed, 844 insertions(+), 254 deletions(-) create mode 100644 src/UserGuide/Master/Table/User-Manual/Audit-Log_timecho.md create mode 100644 src/UserGuide/latest-Table/User-Manual/Audit-Log_timecho.md create mode 100644 src/zh/UserGuide/Master/Table/User-Manual/Audit-Log_timecho.md create mode 100644 src/zh/UserGuide/latest-Table/User-Manual/Audit-Log_timecho.md diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts b/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts index e302eb8e5..0b538275d 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts @@ -140,6 +140,7 @@ export const enSidebar = { children: [ { text: 'Authority Management', link: 'Authority-Management_timecho' }, { text: 'Black White List', link: 'Black-White-List_timecho' }, + { text: 'Security Audit', link: 'Audit-Log_timecho' }, ], }, { text: 'Tiered Storage', link: 'Tiered-Storage_timecho' }, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts index abba81951..18e3b5580 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts @@ -145,7 +145,6 @@ export const enSidebar = { { text: 'Trigger', link: 'Trigger' }, ], }, - { text: 'Tiered Storage', link: 'Tiered-Storage_timecho' }, { text: 'UDF', link: 'User-defined-function_timecho' }, { text: 'View', link: 'IoTDB-View_timecho' }, { @@ -157,6 +156,7 @@ export const enSidebar = { { text: 'Security Audit', link: 'Audit-Log_timecho' }, ], }, + { text: 'Tiered Storage', link: 'Tiered-Storage_timecho' }, { text: 'System Maintenance', collapsible: true, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts index 506359791..259d2f296 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts @@ -131,6 +131,7 @@ export const zhSidebar = { children: [ { text: '权限管理', link: 'Authority-Management_timecho' }, { text: '黑白名单', link: 'Black-White-List_timecho' }, + { text: '安全审计', link: 'Audit-Log_timecho' }, ], }, { text: '多级存储', link: 'Tiered-Storage_timecho' }, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts index acc087698..c79a955c9 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts @@ -127,7 +127,6 @@ export const zhSidebar = { { text: '触发器', link: 'Trigger' }, ], }, - { text: '多级存储', link: 'Tiered-Storage_timecho' }, { text: 'UDF', link: 'User-defined-function_timecho' }, { text: '视图', link: 'IoTDB-View_timecho' }, { @@ -139,6 +138,7 @@ export const zhSidebar = { { text: '安全审计', link: 'Audit-Log_timecho' }, ], }, + { text: '多级存储', link: 'Tiered-Storage_timecho' }, { text: '系统运维', collapsible: true, diff --git a/src/UserGuide/Master/Table/User-Manual/Audit-Log_timecho.md b/src/UserGuide/Master/Table/User-Manual/Audit-Log_timecho.md new file mode 100644 index 000000000..f29a1fa78 --- /dev/null +++ b/src/UserGuide/Master/Table/User-Manual/Audit-Log_timecho.md @@ -0,0 +1,123 @@ + + + +# Security Audit + +## 1. Introduction + +Audit logs provide a documented record of database activities. Through the audit log feature, you can track operations like data creation, deletion, modification, and querying to ensure information security. IoTDB's audit log functionality supports the following features: + +* Configurable enable/disable of audit logging +* Configurable auditable operation types and privilege levels +* Configurable audit log retention periods using TTL (time-based rolling) and SpaceTL (space-based rolling) +* Default encryption storage for audit logs + +> Note: This feature is available from version V2.0.8 onwards. + +## 2. Configuration Parameters + +Edit the `iotdb-system.properties` file to enable audit logging using the following parameters: + +| Parameter Name | Description | Data Type | Default Value | Application Method | +|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|----------------------------|--------------------| +| `enable_audit_log` | Enable audit logging. true: enabled. false: disabled. | Boolean | false | Restart Required | +| `auditable_operation_type` | Operation type selection. DML: All DML operations; DDL: All DDL operations; QUERY: All queries; CONTROL: All control statements; | String | DML,DDL,QUERY,CONTROL | Restart Required | +| `auditable_operation_level` | Privilege level selection. global: Record all audit logs; object: Only record audit logs for data instances; Containment relationship: object < global. | String | global | Restart Required | +| `auditable_operation_result` | Audit result selection. success: Only record successful events; fail: Only record failed events; | String | success, fail | Restart Required | +| `audit_log_ttl_in_days` | Audit log TTL (Time To Live) in days. Logs older than this threshold will expire. | Double | -1.0 (never deleted) | Restart Required | +| `audit_log_space_tl_in_GB` | Audit log SpaceTL in GB. When total audit log size exceeds this threshold, log rotation starts deleting oldest files. | Double | 1.0 | Restart Required | +| `audit_log_batch_interval_in_ms` | Batch write interval for audit logs in milliseconds | Long | 1000 | Restart Required | +| `audit_log_batch_max_queue_bytes` | Maximum queue size in bytes for batch processing audit logs. Subsequent writes will be blocked when queue exceeds this value. | Long | 268435456 | Restart Required | + +## 3. Access Methods + +Supports direct reading of audit logs via SQL. + +### 3.1 SQL Syntax + +```SQL +SELECT (, )* log FROM WHERE whereclause ORDER BY order_expression +``` + +Where: + +* `AUDIT_LOG_PATH`: Audit log storage location `__audit.audit_log`; +* `audit_log_field`: Query fields refer to the metadata structure below +* Supports WHERE clause filtering and ORDER BY sorting + +### 3.2 Metadata Structure + +| Field | Description | Data Type | +|------------------------|--------------------------------------------------|----------------| +| `time` | The date and time when the event started | timestamp | +| `username` | User name | string | +| `cli_hostname` | Client hostname identifier | string | +| `audit_event_type` | Audit event type, e.g., WRITE_DATA, GENERATE_KEY| string | +| `operation_type` | Operation type, e.g., DML, DDL, QUERY, CONTROL | string | +| `privilege_type` | Privilege used, e.g., WRITE_DATA, MANAGE_USER | string | +| `privilege_level` | Event privilege level, global or object | string | +| `result` | Event result, success=1, fail=0 | boolean | +| `database` | Database name | string | +| `sql_string` | User's original SQL statement | string | +| `log` | Detailed event description | string | + +### 3.3 Usage Examples + +* Query times, usernames and host information for successfully executed DML operations: + +```SQL +IoTDB:__audit> select time,username,cli_hostname from audit_log where result = true and operation_type='DML' ++-----------------------------+--------+------------+ +| time|username|cli_hostname| ++-----------------------------+--------+------------+ +|2026-01-23T11:43:46.697+08:00| root| 127.0.0.1| +|2026-01-23T11:45:39.950+08:00| root| 127.0.0.1| ++-----------------------------+--------+------------+ +Total line number = 2 +It costs 0.284s +``` + +* Query latest operation details: + +```SQL +IoTDB:__audit> select time,username,cli_hostname,operation_type,sql_string from audit_log order by time desc limit 1 ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +| time|username|cli_hostname|operation_type| sql_string| ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +|2026-01-23T11:46:31.026+08:00| root| 127.0.0.1| QUERY|select time,username,cli_hostname,operation_type,sql_string from audit_log order by time desc limit 1| ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +Total line number = 1 +It costs 0.053s +``` + +* Query failed operations: + +```SQL +IoTDB:__audit> select time,database,operation_type,log from audit_log where result=false ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +| time|database|operation_type| log| ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +|2026-01-23T11:47:42.136+08:00| | CONTROL|User user1 (ID=-1) login failed with code: 804, Authentication failed.| ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +Total line number = 1 +It costs 0.011s +``` \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/User-Manual/Audit-Log_timecho.md b/src/UserGuide/Master/Tree/User-Manual/Audit-Log_timecho.md index 61ba509c5..89b599690 100644 --- a/src/UserGuide/Master/Tree/User-Manual/Audit-Log_timecho.md +++ b/src/UserGuide/Master/Tree/User-Manual/Audit-Log_timecho.md @@ -21,73 +21,104 @@ # Security Audit -## 1. Background of the function +## 1. Introduction -Audit log is the record credentials of a database, which can be queried by the audit log function to ensure information security by various operations such as user add, delete, change and check in the database. With the audit log function of IoTDB, the following scenarios can be achieved: +Audit logs provide a documented record of database activities. Through the audit log feature, you can track operations like data creation, deletion, modification, and querying to ensure information security. IoTDB's audit log functionality supports the following features: -- We can decide whether to record audit logs according to the source of the link ( human operation or not), such as: non-human operation such as hardware collector write data no need to record audit logs, human operation such as ordinary users through cli, workbench and other tools to operate the data need to record audit logs. -- Filter out system-level write operations, such as those recorded by the IoTDB monitoring system itself. +* Ability to enable/disable audit logging through configuration +* Ability to set auditable operation types and privilege levels via parameters +* Ability to configure audit log file retention periods using TTL (time-based rolling) and SpaceTL (space-based rolling) +* Audit logs are encrypted by default -### 1.1 Scene Description +> Note: This feature is available from version V2.0.8 onwards. -#### Logging all operations (add, delete, change, check) of all users +## 2. Configuration Parameters -The audit log function traces all user operations in the database. The information recorded should include data operations (add, delete, query) and metadata operations (add, modify, delete, query), client login information (user name, ip address). +Edit the `iotdb-system.properties` file to enable audit logging using the following parameters: -Client Sources： -- Cli、workbench、Zeppelin、Grafana、通过 Session/JDBC/MQTT 等协议传入的请求 +| Parameter Name | Description | Data Type | Default Value | Application Method | +|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|----------------------------|--------------------| +| `enable_audit_log` | Enable audit logging. true: enabled. false: disabled. | Boolean | false | Restart Required | +| `auditable_operation_type` | Operation type selection. DML: All DML operations; DDL: All DDL operations; QUERY: All queries; CONTROL: All control statements; | String | DML,DDL,QUERY,CONTROL | Restart Required | +| `auditable_operation_level` | Privilege level selection. global: Record all audit logs; object: Only record audit logs for data instances; Containment relationship: object < global. | String | global | Restart Required | +| `auditable_operation_result` | Audit result selection. success: Only record successful events; fail: Only record failed events; | String | success, fail | Restart Required | +| `audit_log_ttl_in_days` | Audit log TTL (Time To Live) in days. Logs older than this threshold will expire. | Double | -1.0 (never deleted) | Restart Required | +| `audit_log_space_tl_in_GB` | Audit log SpaceTL in GB. When total audit log size exceeds this threshold, log rotation starts deleting oldest files. | Double | 1.0 | Restart Required | +| `audit_log_batch_interval_in_ms` | Batch write interval for audit logs in milliseconds | Long | 1000 | Restart Required | +| `audit_log_batch_max_queue_bytes` | Maximum queue size in bytes for batch processing audit logs. Subsequent writes will be blocked when queue exceeds this value. | Long | 268435456 | Restart Required | -![](/img/audit-log.png) +## 3. Access Methods -#### Audit logging can be turned off for some user connections +Supports direct reading of audit logs via SQL. -No audit logs are required for data written by the hardware collector via Session/JDBC/MQTT if it is a non-human action. +### 3.1 SQL Syntax -## 2. Function Definition - -It is available through through configurations: - -- Decide whether to enable the audit function or not -- Decide where to output the audit logs, support output to one or more - 1. log file - 2. IoTDB storage -- Decide whether to block the native interface writes to prevent recording too many audit logs to affect performance. -- Decide the content category of the audit log, supporting recording one or more - 1. data addition and deletion operations - 2. data and metadata query operations - 3. metadata class adding, modifying, and deleting operations. - -### 2.1 configuration item - -In iotdb-system.properties, change the following configurations: - -```YAML -#################### -### Audit log Configuration -#################### - -# whether to enable the audit log. -# Datatype: Boolean -# enable_audit_log=false - -# Output location of audit logs -# Datatype: String -# IOTDB: the stored time series is: root.__system.audit._{user} -# LOGGER: log_audit.log in the log directory -# audit_log_storage=IOTDB,LOGGER +```SQL +SELECT (, )* log FROM WHERE whereclause ORDER BY order_expression +``` -# whether enable audit log for DML operation of data -# whether enable audit log for DDL operation of schema -# whether enable audit log for QUERY operation of data and schema -# Datatype: String -# audit_log_operation=DML,DDL,QUERY +* `AUDIT_LOG_PATH`: Audit log storage location `root.__audit.log..` +* `audit_log_field`: Query fields refer to the metadata structure below +* Supports WHERE clause filtering and ORDER BY sorting + +### 3.2 Metadata Structure + +| Field | Description | Data Type | +|------------------------|--------------------------------------------------|----------------| +| `time` | The date and time when the event started | timestamp | +| `username` | User name | string | +| `cli_hostname` | Client hostname identifier | string | +| `audit_event_type` | Audit event type, e.g., WRITE_DATA, GENERATE_KEY| string | +| `operation_type` | Operation type, e.g., DML, DDL, QUERY, CONTROL | string | +| `privilege_type` | Privilege used, e.g., WRITE_DATA, MANAGE_USER | string | +| `privilege_level` | Event privilege level, global or object | string | +| `result` | Event result, success=1, fail=0 | boolean | +| `database` | Database name | string | +| `sql_string` | User's original SQL statement | string | +| `log` | Detailed event description | string | + +### 3.3 Usage Examples + +* Query times, usernames and host information for successfully executed queries: + +```SQL +IoTDB> select username,cli_hostname from root.__audit.log.** where operation_type='QUERY' and result=true align by device ++-----------------------------+---------------------------+--------+------------+ +| Time| Device|username|cli_hostname| ++-----------------------------+---------------------------+--------+------------+ +|2026-01-23T10:39:21.563+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| +|2026-01-23T10:39:33.746+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| +|2026-01-23T10:42:15.032+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| ++-----------------------------+---------------------------+--------+------------+ +Total line number = 3 +It costs 0.036s +``` -# whether the local write api records audit logs -# Datatype: Boolean -# This contains Session insert api: insertRecord(s), insertTablet(s),insertRecordsOfOneDevice -# MQTT insert api -# RestAPI insert api -# This parameter will cover the DML in audit_log_operation -# enable_audit_log_for_native_insert_api=true +* Query latest operation details: + +```SQL +IoTDB> select username,cli_hostname,operation_type,sql_string from root.__audit.log.** order by time desc limit 1 align by device ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +| Time| Device|username|cli_hostname|operation_type| sql_string| ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +|2026-01-23T10:42:32.795+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| QUERY|select username,cli_hostname from root.__audit.log.** where operation_type='QUERY' and result=true align by device| ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +Total line number = 1 +It costs 0.033s ``` +* Query failed operations: + +```SQL +IoTDB> select database,operation_type,log from root.__audit.log.** where result=false align by device ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +| Time| Device| database|operation_type| log| ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +|2026-01-23T10:49:55.159+08:00|root.__audit.log.node_1.u_10000| | CONTROL| User user1 (ID=10000) login failed with code: 801, Authentication failed.| +|2026-01-23T10:52:04.579+08:00|root.__audit.log.node_1.u_10000| [root.**]| QUERY| User user1 (ID=10000) requests authority on object [root.**] with result false| +|2026-01-23T10:52:43.412+08:00|root.__audit.log.node_1.u_10000|root.userdb| DDL| User user1 (ID=10000) requests authority on object root.userdb with result false| +|2026-01-23T10:52:48.075+08:00|root.__audit.log.node_1.u_10000| null| QUERY|User user1 (ID=10000) requests authority on object root.__audit with result false| ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +Total line number = 4 +It costs 0.024s +``` \ No newline at end of file diff --git a/src/UserGuide/latest-Table/User-Manual/Audit-Log_timecho.md b/src/UserGuide/latest-Table/User-Manual/Audit-Log_timecho.md new file mode 100644 index 000000000..f29a1fa78 --- /dev/null +++ b/src/UserGuide/latest-Table/User-Manual/Audit-Log_timecho.md @@ -0,0 +1,123 @@ + + + +# Security Audit + +## 1. Introduction + +Audit logs provide a documented record of database activities. Through the audit log feature, you can track operations like data creation, deletion, modification, and querying to ensure information security. IoTDB's audit log functionality supports the following features: + +* Configurable enable/disable of audit logging +* Configurable auditable operation types and privilege levels +* Configurable audit log retention periods using TTL (time-based rolling) and SpaceTL (space-based rolling) +* Default encryption storage for audit logs + +> Note: This feature is available from version V2.0.8 onwards. + +## 2. Configuration Parameters + +Edit the `iotdb-system.properties` file to enable audit logging using the following parameters: + +| Parameter Name | Description | Data Type | Default Value | Application Method | +|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|----------------------------|--------------------| +| `enable_audit_log` | Enable audit logging. true: enabled. false: disabled. | Boolean | false | Restart Required | +| `auditable_operation_type` | Operation type selection. DML: All DML operations; DDL: All DDL operations; QUERY: All queries; CONTROL: All control statements; | String | DML,DDL,QUERY,CONTROL | Restart Required | +| `auditable_operation_level` | Privilege level selection. global: Record all audit logs; object: Only record audit logs for data instances; Containment relationship: object < global. | String | global | Restart Required | +| `auditable_operation_result` | Audit result selection. success: Only record successful events; fail: Only record failed events; | String | success, fail | Restart Required | +| `audit_log_ttl_in_days` | Audit log TTL (Time To Live) in days. Logs older than this threshold will expire. | Double | -1.0 (never deleted) | Restart Required | +| `audit_log_space_tl_in_GB` | Audit log SpaceTL in GB. When total audit log size exceeds this threshold, log rotation starts deleting oldest files. | Double | 1.0 | Restart Required | +| `audit_log_batch_interval_in_ms` | Batch write interval for audit logs in milliseconds | Long | 1000 | Restart Required | +| `audit_log_batch_max_queue_bytes` | Maximum queue size in bytes for batch processing audit logs. Subsequent writes will be blocked when queue exceeds this value. | Long | 268435456 | Restart Required | + +## 3. Access Methods + +Supports direct reading of audit logs via SQL. + +### 3.1 SQL Syntax + +```SQL +SELECT (, )* log FROM WHERE whereclause ORDER BY order_expression +``` + +Where: + +* `AUDIT_LOG_PATH`: Audit log storage location `__audit.audit_log`; +* `audit_log_field`: Query fields refer to the metadata structure below +* Supports WHERE clause filtering and ORDER BY sorting + +### 3.2 Metadata Structure + +| Field | Description | Data Type | +|------------------------|--------------------------------------------------|----------------| +| `time` | The date and time when the event started | timestamp | +| `username` | User name | string | +| `cli_hostname` | Client hostname identifier | string | +| `audit_event_type` | Audit event type, e.g., WRITE_DATA, GENERATE_KEY| string | +| `operation_type` | Operation type, e.g., DML, DDL, QUERY, CONTROL | string | +| `privilege_type` | Privilege used, e.g., WRITE_DATA, MANAGE_USER | string | +| `privilege_level` | Event privilege level, global or object | string | +| `result` | Event result, success=1, fail=0 | boolean | +| `database` | Database name | string | +| `sql_string` | User's original SQL statement | string | +| `log` | Detailed event description | string | + +### 3.3 Usage Examples + +* Query times, usernames and host information for successfully executed DML operations: + +```SQL +IoTDB:__audit> select time,username,cli_hostname from audit_log where result = true and operation_type='DML' ++-----------------------------+--------+------------+ +| time|username|cli_hostname| ++-----------------------------+--------+------------+ +|2026-01-23T11:43:46.697+08:00| root| 127.0.0.1| +|2026-01-23T11:45:39.950+08:00| root| 127.0.0.1| ++-----------------------------+--------+------------+ +Total line number = 2 +It costs 0.284s +``` + +* Query latest operation details: + +```SQL +IoTDB:__audit> select time,username,cli_hostname,operation_type,sql_string from audit_log order by time desc limit 1 ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +| time|username|cli_hostname|operation_type| sql_string| ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +|2026-01-23T11:46:31.026+08:00| root| 127.0.0.1| QUERY|select time,username,cli_hostname,operation_type,sql_string from audit_log order by time desc limit 1| ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +Total line number = 1 +It costs 0.053s +``` + +* Query failed operations: + +```SQL +IoTDB:__audit> select time,database,operation_type,log from audit_log where result=false ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +| time|database|operation_type| log| ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +|2026-01-23T11:47:42.136+08:00| | CONTROL|User user1 (ID=-1) login failed with code: 804, Authentication failed.| ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +Total line number = 1 +It costs 0.011s +``` \ No newline at end of file diff --git a/src/UserGuide/latest/User-Manual/Audit-Log_timecho.md b/src/UserGuide/latest/User-Manual/Audit-Log_timecho.md index 61ba509c5..89b599690 100644 --- a/src/UserGuide/latest/User-Manual/Audit-Log_timecho.md +++ b/src/UserGuide/latest/User-Manual/Audit-Log_timecho.md @@ -21,73 +21,104 @@ # Security Audit -## 1. Background of the function +## 1. Introduction -Audit log is the record credentials of a database, which can be queried by the audit log function to ensure information security by various operations such as user add, delete, change and check in the database. With the audit log function of IoTDB, the following scenarios can be achieved: +Audit logs provide a documented record of database activities. Through the audit log feature, you can track operations like data creation, deletion, modification, and querying to ensure information security. IoTDB's audit log functionality supports the following features: -- We can decide whether to record audit logs according to the source of the link ( human operation or not), such as: non-human operation such as hardware collector write data no need to record audit logs, human operation such as ordinary users through cli, workbench and other tools to operate the data need to record audit logs. -- Filter out system-level write operations, such as those recorded by the IoTDB monitoring system itself. +* Ability to enable/disable audit logging through configuration +* Ability to set auditable operation types and privilege levels via parameters +* Ability to configure audit log file retention periods using TTL (time-based rolling) and SpaceTL (space-based rolling) +* Audit logs are encrypted by default -### 1.1 Scene Description +> Note: This feature is available from version V2.0.8 onwards. -#### Logging all operations (add, delete, change, check) of all users +## 2. Configuration Parameters -The audit log function traces all user operations in the database. The information recorded should include data operations (add, delete, query) and metadata operations (add, modify, delete, query), client login information (user name, ip address). +Edit the `iotdb-system.properties` file to enable audit logging using the following parameters: -Client Sources： -- Cli、workbench、Zeppelin、Grafana、通过 Session/JDBC/MQTT 等协议传入的请求 +| Parameter Name | Description | Data Type | Default Value | Application Method | +|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|----------------------------|--------------------| +| `enable_audit_log` | Enable audit logging. true: enabled. false: disabled. | Boolean | false | Restart Required | +| `auditable_operation_type` | Operation type selection. DML: All DML operations; DDL: All DDL operations; QUERY: All queries; CONTROL: All control statements; | String | DML,DDL,QUERY,CONTROL | Restart Required | +| `auditable_operation_level` | Privilege level selection. global: Record all audit logs; object: Only record audit logs for data instances; Containment relationship: object < global. | String | global | Restart Required | +| `auditable_operation_result` | Audit result selection. success: Only record successful events; fail: Only record failed events; | String | success, fail | Restart Required | +| `audit_log_ttl_in_days` | Audit log TTL (Time To Live) in days. Logs older than this threshold will expire. | Double | -1.0 (never deleted) | Restart Required | +| `audit_log_space_tl_in_GB` | Audit log SpaceTL in GB. When total audit log size exceeds this threshold, log rotation starts deleting oldest files. | Double | 1.0 | Restart Required | +| `audit_log_batch_interval_in_ms` | Batch write interval for audit logs in milliseconds | Long | 1000 | Restart Required | +| `audit_log_batch_max_queue_bytes` | Maximum queue size in bytes for batch processing audit logs. Subsequent writes will be blocked when queue exceeds this value. | Long | 268435456 | Restart Required | -![](/img/audit-log.png) +## 3. Access Methods -#### Audit logging can be turned off for some user connections +Supports direct reading of audit logs via SQL. -No audit logs are required for data written by the hardware collector via Session/JDBC/MQTT if it is a non-human action. +### 3.1 SQL Syntax -## 2. Function Definition - -It is available through through configurations: - -- Decide whether to enable the audit function or not -- Decide where to output the audit logs, support output to one or more - 1. log file - 2. IoTDB storage -- Decide whether to block the native interface writes to prevent recording too many audit logs to affect performance. -- Decide the content category of the audit log, supporting recording one or more - 1. data addition and deletion operations - 2. data and metadata query operations - 3. metadata class adding, modifying, and deleting operations. - -### 2.1 configuration item - -In iotdb-system.properties, change the following configurations: - -```YAML -#################### -### Audit log Configuration -#################### - -# whether to enable the audit log. -# Datatype: Boolean -# enable_audit_log=false - -# Output location of audit logs -# Datatype: String -# IOTDB: the stored time series is: root.__system.audit._{user} -# LOGGER: log_audit.log in the log directory -# audit_log_storage=IOTDB,LOGGER +```SQL +SELECT (, )* log FROM WHERE whereclause ORDER BY order_expression +``` -# whether enable audit log for DML operation of data -# whether enable audit log for DDL operation of schema -# whether enable audit log for QUERY operation of data and schema -# Datatype: String -# audit_log_operation=DML,DDL,QUERY +* `AUDIT_LOG_PATH`: Audit log storage location `root.__audit.log..` +* `audit_log_field`: Query fields refer to the metadata structure below +* Supports WHERE clause filtering and ORDER BY sorting + +### 3.2 Metadata Structure + +| Field | Description | Data Type | +|------------------------|--------------------------------------------------|----------------| +| `time` | The date and time when the event started | timestamp | +| `username` | User name | string | +| `cli_hostname` | Client hostname identifier | string | +| `audit_event_type` | Audit event type, e.g., WRITE_DATA, GENERATE_KEY| string | +| `operation_type` | Operation type, e.g., DML, DDL, QUERY, CONTROL | string | +| `privilege_type` | Privilege used, e.g., WRITE_DATA, MANAGE_USER | string | +| `privilege_level` | Event privilege level, global or object | string | +| `result` | Event result, success=1, fail=0 | boolean | +| `database` | Database name | string | +| `sql_string` | User's original SQL statement | string | +| `log` | Detailed event description | string | + +### 3.3 Usage Examples + +* Query times, usernames and host information for successfully executed queries: + +```SQL +IoTDB> select username,cli_hostname from root.__audit.log.** where operation_type='QUERY' and result=true align by device ++-----------------------------+---------------------------+--------+------------+ +| Time| Device|username|cli_hostname| ++-----------------------------+---------------------------+--------+------------+ +|2026-01-23T10:39:21.563+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| +|2026-01-23T10:39:33.746+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| +|2026-01-23T10:42:15.032+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| ++-----------------------------+---------------------------+--------+------------+ +Total line number = 3 +It costs 0.036s +``` -# whether the local write api records audit logs -# Datatype: Boolean -# This contains Session insert api: insertRecord(s), insertTablet(s),insertRecordsOfOneDevice -# MQTT insert api -# RestAPI insert api -# This parameter will cover the DML in audit_log_operation -# enable_audit_log_for_native_insert_api=true +* Query latest operation details: + +```SQL +IoTDB> select username,cli_hostname,operation_type,sql_string from root.__audit.log.** order by time desc limit 1 align by device ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +| Time| Device|username|cli_hostname|operation_type| sql_string| ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +|2026-01-23T10:42:32.795+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| QUERY|select username,cli_hostname from root.__audit.log.** where operation_type='QUERY' and result=true align by device| ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +Total line number = 1 +It costs 0.033s ``` +* Query failed operations: + +```SQL +IoTDB> select database,operation_type,log from root.__audit.log.** where result=false align by device ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +| Time| Device| database|operation_type| log| ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +|2026-01-23T10:49:55.159+08:00|root.__audit.log.node_1.u_10000| | CONTROL| User user1 (ID=10000) login failed with code: 801, Authentication failed.| +|2026-01-23T10:52:04.579+08:00|root.__audit.log.node_1.u_10000| [root.**]| QUERY| User user1 (ID=10000) requests authority on object [root.**] with result false| +|2026-01-23T10:52:43.412+08:00|root.__audit.log.node_1.u_10000|root.userdb| DDL| User user1 (ID=10000) requests authority on object root.userdb with result false| +|2026-01-23T10:52:48.075+08:00|root.__audit.log.node_1.u_10000| null| QUERY|User user1 (ID=10000) requests authority on object root.__audit with result false| ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +Total line number = 4 +It costs 0.024s +``` \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Table/User-Manual/Audit-Log_timecho.md b/src/zh/UserGuide/Master/Table/User-Manual/Audit-Log_timecho.md new file mode 100644 index 000000000..89d214405 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/User-Manual/Audit-Log_timecho.md @@ -0,0 +1,123 @@ + + + +# 安全审计 + +## 1. 引言 + +审计日志是数据库的记录凭证，通过审计日志功能可以查询数据库中增删改查等各项操作，以保证信息安全。IoTDB 审计日志功能支持以下特性： + +* 可通过配置决定是否开启审计日志功能 +* 可通过参数设置审计日志记录的操作类型和权限级别 +* 可通过参数设置审计日志文件的存储周期，包括基于 TTL 实现时间滚动和基于 SpaceTL 实现空间滚动。 +* 审计日志文件默认加密存储 + +> 注意：该功能从 V2.0.8 版本开始提供。 + +## 2. 配置参数 + +通过编辑配置文件 `iotdb-system.properties` 中如下参数来启动审计日志功能。 + +| 参数名称 | 参数描述 | 数据类型 | 默认值 | 生效方式 | +|-----------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------ | ---------- | +| `enable_audit_log` | 是否开启审计日志。 true：启用。false：禁用。 | Boolean | false | 重启 | +| `auditable_operation_type` | 操作类型选择。 DML ：所有 DML 都会记录审计日志； DDL ：所有 DDL 都会记录审计日志； QUERY ：所有 QUERY 都会记录审计日志； CONTROL：所有控制语句都会记录审计日志； | String | DML,DDL,QUERY,CONTROL | 重启 | +| `auditable_operation_level` | 权限级别选择。 global ：记录全部的审计日志； object：仅针对数据实例的事件的审计日志会被记录； 包含关系：object < global。 例如：设置为 global 时，所有审计日志正常记录；设置为 object 时，仅记录对具体数据实例的操作。 | String | global | 重启 | +| `auditable_operation_result` | 审计结果选择。 success：只记录成功事件的审计日志； fail：只记录失败事件的审计日志； | String | success, fail | 重启 | +| `audit_log_ttl_in_days` | 审计日志的 TTL，生成审计日志的时间达到该阈值后过期。 | Double | -1.0（永远不会被删除） | 重启 | +| `audit_log_space_tl_in_GB` | 审计日志的 SpaceTL，审计日志总空间达到该阈值后开始轮转删除。 | Double | 1.0| 重启| +| `audit_log_batch_interval_in_ms` | 审计日志批量写入的时间间隔 | Long | 1000 | 重启 | +| `audit_log_batch_max_queue_bytes` | 用于批量处理审计日志的队列最大字节数。当队列大小超过此值时，后续的写入操作将被阻塞。 | Long | 268435456 | 重启 | + +## 3. 查阅方法 + +支持通过 SQL 直接阅读、获取审计日志相关信息。 + +### 3.1 SQL 语法 + +```SQL +SELECT (, )* log FROM WHERE whereclause ORDER BY order_expression +``` + +其中： + +* `AUDIT_LOG_PATH` ：审计日志存储位置`__audit.audit_log`； +* `audit_log_field`：查询字段请参考下一小节元数据结构。 +* 支持 Where 条件搜索和 Order By 排序。 + +### 3.2 元数据结构 + +| 字段 | 含义 | 类型 | +| ------------------------ | -------------------------------------------------- | ----------- | +| `time` | 事件开始的的日期和时间 | timestamp | +| `username` | 用户名称 | string | +| `cli_hostname` | 用户主机标识 | string | +| `audit_event_type` | 审计事件类型，WRITE\_DATA, GENERATE\_KEY 等 | string | +| `operation_type` | 审计事件的操作类型，DML, DDL, QUERY, CONTROL | string | +| `privilege_type` | 审计事件使用的权限，WRITE\_DATA, MANAGE\_USER 等 | string | +| `privilege_level` | 事件的权限级别，global, object | string | +| `result` | 事件结果，success=1, fail=0 | boolean | +| `database` | 数据库名称 | string | +| `sql_string` | 用户的原始 SQL | string | +| `log` | 具体的事件描述 | string | + +### 3.3 使用示例 + +* 查询成功执行了DML操作的时间、用户名及主机信息 + +```SQL +IoTDB:__audit> select time,username,cli_hostname from audit_log where result = true and operation_type='DML' ++-----------------------------+--------+------------+ +| time|username|cli_hostname| ++-----------------------------+--------+------------+ +|2026-01-23T11:43:46.697+08:00| root| 127.0.0.1| +|2026-01-23T11:45:39.950+08:00| root| 127.0.0.1| ++-----------------------------+--------+------------+ +Total line number = 2 +It costs 0.284s +``` + +* 查询最近一次操作的时间、用户名、主机信息、操作类型以及原始 SQL + +```SQL +IoTDB:__audit> select time,username,cli_hostname,operation_type,sql_string from audit_log order by time desc limit 1 ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +| time|username|cli_hostname|operation_type| sql_string| ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +|2026-01-23T11:46:31.026+08:00| root| 127.0.0.1| QUERY|select time,username,cli_hostname,operation_type,sql_string from audit_log order by time desc limit 1| ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +Total line number = 1 +It costs 0.053s +``` + +* 查询所有事件结果为false的操作数据库、操作类型及日志信息 + +```SQL +IoTDB:__audit> select time,database,operation_type,log from audit_log where result=false ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +| time|database|operation_type| log| ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +|2026-01-23T11:47:42.136+08:00| | CONTROL|User user1 (ID=-1) login failed with code: 804, Authentication failed.| ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +Total line number = 1 +It costs 0.011s +``` diff --git a/src/zh/UserGuide/Master/Tree/User-Manual/Audit-Log_timecho.md b/src/zh/UserGuide/Master/Tree/User-Manual/Audit-Log_timecho.md index 3fd2eac0d..a4de129c8 100644 --- a/src/zh/UserGuide/Master/Tree/User-Manual/Audit-Log_timecho.md +++ b/src/zh/UserGuide/Master/Tree/User-Manual/Audit-Log_timecho.md @@ -22,87 +22,104 @@ # 安全审计 -## 1. 功能背景 +## 1. 引言 - 审计日志是数据库的记录凭证，通过审计日志功能可以查询到用户在数据库中增删改查等各项操作，以保证信息安全。关于IoTDB的审计日志功能可以实现以下场景的需求： +审计日志是数据库的记录凭证，通过审计日志功能可以查询到数据库中增删改查等各项操作，以保证信息安全。IoTDB 审计日志功能支持以下特性： -- 可以按链接来源（是否人为操作）决定是否记录审计日志，如：非人为操作如硬件采集器写入的数据不需要记录审计日志，人为操作如普通用户通过cli、workbench等工具操作的数据需要记录审计日志。 -- 过滤掉系统级别的写入操作，如IoTDB监控体系本身记录的写入操作等。 +* 可通过配置决定是否开启审计日志功能 +* 可通过参数设置审计日志记录的操作类型和权限级别 +* 可通过参数设置审计日志文件的存储周期，包括基于 TTL 实现时间滚动和基于 SpaceTL 实现空间滚动。 +* 审计日志文件默认加密存储 +> 注意：该功能从 V2.0.8 版本开始提供。 +## 2. 配置参数 -### 1.1 场景说明 +通过编辑配置文件 `iotdb-system.properties` 中如下参数来启动审计日志功能。 +| 参数名称 | 参数描述 | 数据类型 | 默认值 | 生效方式 | +|-----------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------ | ---------- | +| `enable_audit_log` | 是否开启审计日志。 true：启用。false：禁用。 | Boolean | false | 重启 | +| `auditable_operation_type` | 操作类型选择。 DML ：所有 DML 都会记录审计日志； DDL ：所有 DDL 都会记录审计日志； QUERY ：所有 QUERY 都会记录审计日志； CONTROL：所有控制语句都会记录审计日志； | String | DML,DDL,QUERY,CONTROL | 重启 | +| `auditable_operation_level` | 权限级别选择。 global ：记录全部的审计日志； object：仅针对数据实例的事件的审计日志会被记录； 包含关系：object < global。 例如：设置为 global 时，所有审计日志正常记录；设置为 object 时，仅记录对具体数据实例的操作。 | String | global | 重启 | +| `auditable_operation_result` | 审计结果选择。 success：只记录成功事件的审计日志； fail：只记录失败事件的审计日志； | String | success, fail | 重启 | +| `audit_log_ttl_in_days` | 审计日志的 TTL，生成审计日志的时间达到该阈值后过期。 | Double | -1.0（永远不会被删除） | 重启 | +| `audit_log_space_tl_in_GB` | 审计日志的 SpaceTL，审计日志总空间达到该阈值后开始轮转删除。 | Double | 1.0| 重启| +| `audit_log_batch_interval_in_ms` | 审计日志批量写入的时间间隔 | Long | 1000 | 重启 | +| `audit_log_batch_max_queue_bytes` | 用于批量处理审计日志的队列最大字节数。当队列大小超过此值时，后续的写入操作将被阻塞。 | Long | 268435456 | 重启 | +## 3. 查阅方法 -#### 对所有用户的所有操作（增、删、改、查）进行记录 +支持通过 SQL 直接阅读、获取审计日志相关信息。 -通过审计日志功能追踪到所有用户在数据中的各项操作。其中所记录的信息要包含数据操作（新增、删除、查询）及元数据操作（新增、修改、删除、查询）、客户端登录信息（用户名、ip地址）。 +### 3.1 SQL 语法 +```SQL +SELECT (, )* log FROM WHERE whereclause ORDER BY order_expression +``` +* `AUDIT_LOG_PATH` ：审计日志存储位置`root.__audit.log..`； +* `audit_log_field`：查询字段请参考下一小节元数据结构。 +* 支持 Where 条件搜索和 Order By 排序。 + +### 3.2 元数据结构 + +| 字段 | 含义 | 类型 | +| ------------------------ | -------------------------------------------------- | ----------- | +| `time` | 事件开始的的日期和时间 | timestamp | +| `username` | 用户名称 | string | +| `cli_hostname` | 用户主机标识 | string | +| `audit_event_type` | 审计事件类型，WRITE\_DATA, GENERATE\_KEY 等 | string | +| `operation_type` | 审计事件的操作类型，DML, DDL, QUERY, CONTROL | string | +| `privilege_type` | 审计事件使用的权限，WRITE\_DATA, MANAGE\_USER 等 | string | +| `privilege_level` | 事件的权限级别，global, object | string | +| `result` | 事件结果，success=1, fail=0 | boolean | +| `database` | 数据库名称 | string | +| `sql_string` | 用户的原始 SQL | string | +| `log` | 具体的事件描述 | string | + +### 3.3 使用示例 + +* 查询成功执行了 QUERY 操作的时间、用户名及主机信息 + +```SQL +IoTDB> select username,cli_hostname from root.__audit.log.** where operation_type='QUERY' and result=true align by device ++-----------------------------+---------------------------+--------+------------+ +| Time| Device|username|cli_hostname| ++-----------------------------+---------------------------+--------+------------+ +|2026-01-23T10:39:21.563+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| +|2026-01-23T10:39:33.746+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| +|2026-01-23T10:42:15.032+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| ++-----------------------------+---------------------------+--------+------------+ +Total line number = 3 +It costs 0.036s +``` -客户端的来源 - -- Cli、workbench、Zeppelin、Grafana、通过 Session/JDBC/MQTT 等协议传入的请求 - -![](/img/audit-log.png) - - -#### 可关闭部分用户连接的审计日志 - - - -如非人为操作，硬件采集器通过 Session/JDBC/MQTT 写入的数据不需要记录审计日志 - - - -## 2. 功能定义 - - - -通过配置可以实现： - -- 决定是否开启审计功能 -- 决定审计日志的输出位置，支持输出至一项或多项 - 1. 日志文件 - 2. IoTDB存储 -- 决定是否屏蔽原生接口的写入，防止记录审计日志过多影响性能 -- 决定审计日志内容类别，支持记录一项或多项 - 1. 数据的新增、删除操作 - 2. 数据和元数据的查询操作 - 3. 元数据类的新增、修改、删除操作 - -### 2.1 配置项 - - 在iotdb-system.properties中修改以下几项配置 - -```YAML -#################### -### Audit log Configuration -#################### - -# whether to enable the audit log. -# Datatype: Boolean -# enable_audit_log=false - -# Output location of audit logs -# Datatype: String -# IOTDB: the stored time series is: root.__system.audit._{user} -# LOGGER: log_audit.log in the log directory -# audit_log_storage=IOTDB,LOGGER - -# whether enable audit log for DML operation of data -# whether enable audit log for DDL operation of schema -# whether enable audit log for QUERY operation of data and schema -# Datatype: String -# audit_log_operation=DML,DDL,QUERY - -# whether the local write api records audit logs -# Datatype: Boolean -# This contains Session insert api: insertRecord(s), insertTablet(s),insertRecordsOfOneDevice -# MQTT insert api -# RestAPI insert api -# This parameter will cover the DML in audit_log_operation -# enable_audit_log_for_native_insert_api=true +* 查询最近一次操作的时间、用户名、主机信息、操作类型以及原始 SQL + +```SQL +IoTDB> select username,cli_hostname,operation_type,sql_string from root.__audit.log.** order by time desc limit 1 align by device ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +| Time| Device|username|cli_hostname|operation_type| sql_string| ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +|2026-01-23T10:42:32.795+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| QUERY|select username,cli_hostname from root.__audit.log.** where operation_type='QUERY' and result=true align by device| ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +Total line number = 1 +It costs 0.033s ``` +* 查询所有事件结果为false的操作数据库、操作类型及日志信息 + +```SQL +IoTDB> select database,operation_type,log from root.__audit.log.** where result=false align by device ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +| Time| Device| database|operation_type| log| ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +|2026-01-23T10:49:55.159+08:00|root.__audit.log.node_1.u_10000| | CONTROL| User user1 (ID=10000) login failed with code: 801, Authentication failed.| +|2026-01-23T10:52:04.579+08:00|root.__audit.log.node_1.u_10000| [root.**]| QUERY| User user1 (ID=10000) requests authority on object [root.**] with result false| +|2026-01-23T10:52:43.412+08:00|root.__audit.log.node_1.u_10000|root.userdb| DDL| User user1 (ID=10000) requests authority on object root.userdb with result false| +|2026-01-23T10:52:48.075+08:00|root.__audit.log.node_1.u_10000| null| QUERY|User user1 (ID=10000) requests authority on object root.__audit with result false| ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +Total line number = 4 +It costs 0.024s +``` \ No newline at end of file diff --git a/src/zh/UserGuide/latest-Table/User-Manual/Audit-Log_timecho.md b/src/zh/UserGuide/latest-Table/User-Manual/Audit-Log_timecho.md new file mode 100644 index 000000000..89d214405 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/User-Manual/Audit-Log_timecho.md @@ -0,0 +1,123 @@ + + + +# 安全审计 + +## 1. 引言 + +审计日志是数据库的记录凭证，通过审计日志功能可以查询数据库中增删改查等各项操作，以保证信息安全。IoTDB 审计日志功能支持以下特性： + +* 可通过配置决定是否开启审计日志功能 +* 可通过参数设置审计日志记录的操作类型和权限级别 +* 可通过参数设置审计日志文件的存储周期，包括基于 TTL 实现时间滚动和基于 SpaceTL 实现空间滚动。 +* 审计日志文件默认加密存储 + +> 注意：该功能从 V2.0.8 版本开始提供。 + +## 2. 配置参数 + +通过编辑配置文件 `iotdb-system.properties` 中如下参数来启动审计日志功能。 + +| 参数名称 | 参数描述 | 数据类型 | 默认值 | 生效方式 | +|-----------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------ | ---------- | +| `enable_audit_log` | 是否开启审计日志。 true：启用。false：禁用。 | Boolean | false | 重启 | +| `auditable_operation_type` | 操作类型选择。 DML ：所有 DML 都会记录审计日志； DDL ：所有 DDL 都会记录审计日志； QUERY ：所有 QUERY 都会记录审计日志； CONTROL：所有控制语句都会记录审计日志； | String | DML,DDL,QUERY,CONTROL | 重启 | +| `auditable_operation_level` | 权限级别选择。 global ：记录全部的审计日志； object：仅针对数据实例的事件的审计日志会被记录； 包含关系：object < global。 例如：设置为 global 时，所有审计日志正常记录；设置为 object 时，仅记录对具体数据实例的操作。 | String | global | 重启 | +| `auditable_operation_result` | 审计结果选择。 success：只记录成功事件的审计日志； fail：只记录失败事件的审计日志； | String | success, fail | 重启 | +| `audit_log_ttl_in_days` | 审计日志的 TTL，生成审计日志的时间达到该阈值后过期。 | Double | -1.0（永远不会被删除） | 重启 | +| `audit_log_space_tl_in_GB` | 审计日志的 SpaceTL，审计日志总空间达到该阈值后开始轮转删除。 | Double | 1.0| 重启| +| `audit_log_batch_interval_in_ms` | 审计日志批量写入的时间间隔 | Long | 1000 | 重启 | +| `audit_log_batch_max_queue_bytes` | 用于批量处理审计日志的队列最大字节数。当队列大小超过此值时，后续的写入操作将被阻塞。 | Long | 268435456 | 重启 | + +## 3. 查阅方法 + +支持通过 SQL 直接阅读、获取审计日志相关信息。 + +### 3.1 SQL 语法 + +```SQL +SELECT (, )* log FROM WHERE whereclause ORDER BY order_expression +``` + +其中： + +* `AUDIT_LOG_PATH` ：审计日志存储位置`__audit.audit_log`； +* `audit_log_field`：查询字段请参考下一小节元数据结构。 +* 支持 Where 条件搜索和 Order By 排序。 + +### 3.2 元数据结构 + +| 字段 | 含义 | 类型 | +| ------------------------ | -------------------------------------------------- | ----------- | +| `time` | 事件开始的的日期和时间 | timestamp | +| `username` | 用户名称 | string | +| `cli_hostname` | 用户主机标识 | string | +| `audit_event_type` | 审计事件类型，WRITE\_DATA, GENERATE\_KEY 等 | string | +| `operation_type` | 审计事件的操作类型，DML, DDL, QUERY, CONTROL | string | +| `privilege_type` | 审计事件使用的权限，WRITE\_DATA, MANAGE\_USER 等 | string | +| `privilege_level` | 事件的权限级别，global, object | string | +| `result` | 事件结果，success=1, fail=0 | boolean | +| `database` | 数据库名称 | string | +| `sql_string` | 用户的原始 SQL | string | +| `log` | 具体的事件描述 | string | + +### 3.3 使用示例 + +* 查询成功执行了DML操作的时间、用户名及主机信息 + +```SQL +IoTDB:__audit> select time,username,cli_hostname from audit_log where result = true and operation_type='DML' ++-----------------------------+--------+------------+ +| time|username|cli_hostname| ++-----------------------------+--------+------------+ +|2026-01-23T11:43:46.697+08:00| root| 127.0.0.1| +|2026-01-23T11:45:39.950+08:00| root| 127.0.0.1| ++-----------------------------+--------+------------+ +Total line number = 2 +It costs 0.284s +``` + +* 查询最近一次操作的时间、用户名、主机信息、操作类型以及原始 SQL + +```SQL +IoTDB:__audit> select time,username,cli_hostname,operation_type,sql_string from audit_log order by time desc limit 1 ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +| time|username|cli_hostname|operation_type| sql_string| ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +|2026-01-23T11:46:31.026+08:00| root| 127.0.0.1| QUERY|select time,username,cli_hostname,operation_type,sql_string from audit_log order by time desc limit 1| ++-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+ +Total line number = 1 +It costs 0.053s +``` + +* 查询所有事件结果为false的操作数据库、操作类型及日志信息 + +```SQL +IoTDB:__audit> select time,database,operation_type,log from audit_log where result=false ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +| time|database|operation_type| log| ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +|2026-01-23T11:47:42.136+08:00| | CONTROL|User user1 (ID=-1) login failed with code: 804, Authentication failed.| ++-----------------------------+--------+--------------+----------------------------------------------------------------------+ +Total line number = 1 +It costs 0.011s +``` diff --git a/src/zh/UserGuide/latest/User-Manual/Audit-Log_timecho.md b/src/zh/UserGuide/latest/User-Manual/Audit-Log_timecho.md index 3fd2eac0d..a4de129c8 100644 --- a/src/zh/UserGuide/latest/User-Manual/Audit-Log_timecho.md +++ b/src/zh/UserGuide/latest/User-Manual/Audit-Log_timecho.md @@ -22,87 +22,104 @@ # 安全审计 -## 1. 功能背景 +## 1. 引言 - 审计日志是数据库的记录凭证，通过审计日志功能可以查询到用户在数据库中增删改查等各项操作，以保证信息安全。关于IoTDB的审计日志功能可以实现以下场景的需求： +审计日志是数据库的记录凭证，通过审计日志功能可以查询到数据库中增删改查等各项操作，以保证信息安全。IoTDB 审计日志功能支持以下特性： -- 可以按链接来源（是否人为操作）决定是否记录审计日志，如：非人为操作如硬件采集器写入的数据不需要记录审计日志，人为操作如普通用户通过cli、workbench等工具操作的数据需要记录审计日志。 -- 过滤掉系统级别的写入操作，如IoTDB监控体系本身记录的写入操作等。 +* 可通过配置决定是否开启审计日志功能 +* 可通过参数设置审计日志记录的操作类型和权限级别 +* 可通过参数设置审计日志文件的存储周期，包括基于 TTL 实现时间滚动和基于 SpaceTL 实现空间滚动。 +* 审计日志文件默认加密存储 +> 注意：该功能从 V2.0.8 版本开始提供。 +## 2. 配置参数 -### 1.1 场景说明 +通过编辑配置文件 `iotdb-system.properties` 中如下参数来启动审计日志功能。 +| 参数名称 | 参数描述 | 数据类型 | 默认值 | 生效方式 | +|-----------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------ | ---------- | +| `enable_audit_log` | 是否开启审计日志。 true：启用。false：禁用。 | Boolean | false | 重启 | +| `auditable_operation_type` | 操作类型选择。 DML ：所有 DML 都会记录审计日志； DDL ：所有 DDL 都会记录审计日志； QUERY ：所有 QUERY 都会记录审计日志； CONTROL：所有控制语句都会记录审计日志； | String | DML,DDL,QUERY,CONTROL | 重启 | +| `auditable_operation_level` | 权限级别选择。 global ：记录全部的审计日志； object：仅针对数据实例的事件的审计日志会被记录； 包含关系：object < global。 例如：设置为 global 时，所有审计日志正常记录；设置为 object 时，仅记录对具体数据实例的操作。 | String | global | 重启 | +| `auditable_operation_result` | 审计结果选择。 success：只记录成功事件的审计日志； fail：只记录失败事件的审计日志； | String | success, fail | 重启 | +| `audit_log_ttl_in_days` | 审计日志的 TTL，生成审计日志的时间达到该阈值后过期。 | Double | -1.0（永远不会被删除） | 重启 | +| `audit_log_space_tl_in_GB` | 审计日志的 SpaceTL，审计日志总空间达到该阈值后开始轮转删除。 | Double | 1.0| 重启| +| `audit_log_batch_interval_in_ms` | 审计日志批量写入的时间间隔 | Long | 1000 | 重启 | +| `audit_log_batch_max_queue_bytes` | 用于批量处理审计日志的队列最大字节数。当队列大小超过此值时，后续的写入操作将被阻塞。 | Long | 268435456 | 重启 | +## 3. 查阅方法 -#### 对所有用户的所有操作（增、删、改、查）进行记录 +支持通过 SQL 直接阅读、获取审计日志相关信息。 -通过审计日志功能追踪到所有用户在数据中的各项操作。其中所记录的信息要包含数据操作（新增、删除、查询）及元数据操作（新增、修改、删除、查询）、客户端登录信息（用户名、ip地址）。 +### 3.1 SQL 语法 +```SQL +SELECT (, )* log FROM WHERE whereclause ORDER BY order_expression +``` +* `AUDIT_LOG_PATH` ：审计日志存储位置`root.__audit.log..`； +* `audit_log_field`：查询字段请参考下一小节元数据结构。 +* 支持 Where 条件搜索和 Order By 排序。 + +### 3.2 元数据结构 + +| 字段 | 含义 | 类型 | +| ------------------------ | -------------------------------------------------- | ----------- | +| `time` | 事件开始的的日期和时间 | timestamp | +| `username` | 用户名称 | string | +| `cli_hostname` | 用户主机标识 | string | +| `audit_event_type` | 审计事件类型，WRITE\_DATA, GENERATE\_KEY 等 | string | +| `operation_type` | 审计事件的操作类型，DML, DDL, QUERY, CONTROL | string | +| `privilege_type` | 审计事件使用的权限，WRITE\_DATA, MANAGE\_USER 等 | string | +| `privilege_level` | 事件的权限级别，global, object | string | +| `result` | 事件结果，success=1, fail=0 | boolean | +| `database` | 数据库名称 | string | +| `sql_string` | 用户的原始 SQL | string | +| `log` | 具体的事件描述 | string | + +### 3.3 使用示例 + +* 查询成功执行了 QUERY 操作的时间、用户名及主机信息 + +```SQL +IoTDB> select username,cli_hostname from root.__audit.log.** where operation_type='QUERY' and result=true align by device ++-----------------------------+---------------------------+--------+------------+ +| Time| Device|username|cli_hostname| ++-----------------------------+---------------------------+--------+------------+ +|2026-01-23T10:39:21.563+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| +|2026-01-23T10:39:33.746+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| +|2026-01-23T10:42:15.032+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| ++-----------------------------+---------------------------+--------+------------+ +Total line number = 3 +It costs 0.036s +``` -客户端的来源 - -- Cli、workbench、Zeppelin、Grafana、通过 Session/JDBC/MQTT 等协议传入的请求 - -![](/img/audit-log.png) - - -#### 可关闭部分用户连接的审计日志 - - - -如非人为操作，硬件采集器通过 Session/JDBC/MQTT 写入的数据不需要记录审计日志 - - - -## 2. 功能定义 - - - -通过配置可以实现： - -- 决定是否开启审计功能 -- 决定审计日志的输出位置，支持输出至一项或多项 - 1. 日志文件 - 2. IoTDB存储 -- 决定是否屏蔽原生接口的写入，防止记录审计日志过多影响性能 -- 决定审计日志内容类别，支持记录一项或多项 - 1. 数据的新增、删除操作 - 2. 数据和元数据的查询操作 - 3. 元数据类的新增、修改、删除操作 - -### 2.1 配置项 - - 在iotdb-system.properties中修改以下几项配置 - -```YAML -#################### -### Audit log Configuration -#################### - -# whether to enable the audit log. -# Datatype: Boolean -# enable_audit_log=false - -# Output location of audit logs -# Datatype: String -# IOTDB: the stored time series is: root.__system.audit._{user} -# LOGGER: log_audit.log in the log directory -# audit_log_storage=IOTDB,LOGGER - -# whether enable audit log for DML operation of data -# whether enable audit log for DDL operation of schema -# whether enable audit log for QUERY operation of data and schema -# Datatype: String -# audit_log_operation=DML,DDL,QUERY - -# whether the local write api records audit logs -# Datatype: Boolean -# This contains Session insert api: insertRecord(s), insertTablet(s),insertRecordsOfOneDevice -# MQTT insert api -# RestAPI insert api -# This parameter will cover the DML in audit_log_operation -# enable_audit_log_for_native_insert_api=true +* 查询最近一次操作的时间、用户名、主机信息、操作类型以及原始 SQL + +```SQL +IoTDB> select username,cli_hostname,operation_type,sql_string from root.__audit.log.** order by time desc limit 1 align by device ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +| Time| Device|username|cli_hostname|operation_type| sql_string| ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +|2026-01-23T10:42:32.795+08:00|root.__audit.log.node_1.u_0| root| 127.0.0.1| QUERY|select username,cli_hostname from root.__audit.log.** where operation_type='QUERY' and result=true align by device| ++-----------------------------+---------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------------------+ +Total line number = 1 +It costs 0.033s ``` +* 查询所有事件结果为false的操作数据库、操作类型及日志信息 + +```SQL +IoTDB> select database,operation_type,log from root.__audit.log.** where result=false align by device ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +| Time| Device| database|operation_type| log| ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +|2026-01-23T10:49:55.159+08:00|root.__audit.log.node_1.u_10000| | CONTROL| User user1 (ID=10000) login failed with code: 801, Authentication failed.| +|2026-01-23T10:52:04.579+08:00|root.__audit.log.node_1.u_10000| [root.**]| QUERY| User user1 (ID=10000) requests authority on object [root.**] with result false| +|2026-01-23T10:52:43.412+08:00|root.__audit.log.node_1.u_10000|root.userdb| DDL| User user1 (ID=10000) requests authority on object root.userdb with result false| +|2026-01-23T10:52:48.075+08:00|root.__audit.log.node_1.u_10000| null| QUERY|User user1 (ID=10000) requests authority on object root.__audit with result false| ++-----------------------------+-------------------------------+-----------+--------------+---------------------------------------------------------------------------------+ +Total line number = 4 +It costs 0.024s +``` \ No newline at end of file