Skip to content

Commit c8574be

Browse files
patrickbirchpatrickbirch
committed
PS-10225 [DOCS] - Add Advanced Filter Configuration 8.0
 On branch ps-10225-8.0 new file: docs/advanced-audit-log-filter-example.md modified: mkdocs-base.yml
1 parent ffa7847 commit c8574be

File tree

2 files changed

+253
-0
lines changed

2 files changed

+253
-0
lines changed

‎docs/advanced-audit-log-filter-example.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Advanced audit log filter configuration
2+
3+
## Overview
4+
5+
Audit log filtering controls which database events the audit log plugin records. This configuration example shows how to set up comprehensive logging for general users while completely disabling logging for monitoring users.
6+
7+
## Prerequisites
8+
9+
Before configuring audit log filters, ensure that:
10+
11+
* The audit log filter plugin is installed and enabled
12+
13+
* You have administrative privileges to configure audit log settings
14+
15+
* The audit log filter plugin has the necessary permissions to write log files
16+
17+
You can tune the audit log filter plugin using the following variables:
18+
19+
20+
| Variable | Default | Typical value for heavy logging | Description |
21+
|----------|---------|--------------------------------|-------------|
22+
| [audit-log-filter](audit-log-filter-variables.md#audit-log-filter) | OFF | ON | Master switch for the filter subsystem. |
23+
| [audit_log_filter_max_size](audit-log-filter-variables.md#audit_log_filter_max_size) | 0 (unlimited) | 1073741824 (1 GB) | Max size of the filter definition file; rotation occurs when exceeded. |
24+
| [audit_log_filter_prune_seconds](audit-log-filter-variables.md#audit_log_filter_prune_seconds) | 0 (no pruning) | 86400 (24 h) | Age after which old filter entries are pruned. |
25+
| [audit_log_filter_strategy](audit-log-filter-variables.md#audit_log_filter_strategy) | default | default | Determines how overlapping filters are resolved (keep‑first vs. most‑specific). |
26+
| [audit_log_filter_rotate_on_size](audit-log-filter-variables.md#audit_log_filter_rotate_on_size) | 0 | 1 | Rotate the audit log file when it reaches `audit_log_buffer_size`. |
27+
| [audit_log_filter_file](audit-log-filter-variables.md#audit_log_filter_file) | `<datadir>/audit.log` | *unchanged* | Path of the audit log file (requires server restart to change). |
28+
29+
Most of these variables in the table are dynamic system variables – you can view or change them at runtime with `SHOW GLOBAL VARIABLES / SET GLOBAL`.
30+
31+
Only `audit_log_file` (the path) is static; changing this variable requires a restart.
32+
33+
## Rule precedence
34+
35+
* User-Specific Filter Wins: A specific user filter set with `audit_log_filter_set_user` always takes precedence over the wildcard (`%`) filter.
36+
37+
* Most Specific Pattern Wins: If a user matches multiple connection patterns (e.g., `user@host`), the most specific pattern is applied. For example, `monitor@%` is applied instead of the less specific `%`.
38+
39+
* Last Call Wins: When a user has multiple filters attached using `audit_log_filter_set_user`, the filter from the last execution of that command is the one that is applied.
40+
41+
### Global system control
42+
43+
* The `audit-log-filter` global can enable or disable the auditing subsystem but does not affect the internal precedence logic of individual user filters.
44+
45+
## Use case requirements
46+
47+
The following requirements define the audit logging behavior:
48+
49+
For user % (wildcard/general users):
50+
51+
* Log SELECT operations
52+
53+
* Log INSERT operations
54+
55+
* Log UPDATE operations
56+
57+
* Log DELETE operations
58+
59+
* Log TRUNCATE operations
60+
61+
* Log CREATE operations
62+
63+
* Log DROP operations
64+
65+
* Log ALTER operations
66+
67+
* Log connection events (successful and failed)
68+
69+
* Log disconnection events
70+
71+
For user monitor:
72+
73+
* Log no events (completely disable logging)
74+
75+
## Filter configuration details
76+
77+
The configuration uses two distinct filter types:
78+
79+
* Comprehensive logging filter: Captures connection events and specific SQL operations for general users
80+
* No logging filter: Completely disables audit logging for monitoring users
81+
82+
The filter applies to users matching the specified patterns:
83+
84+
* `%` matches all users (wildcard pattern)
85+
86+
* `monitor@%` matches users with the monitor username from any host
87+
88+
## Implementation
89+
90+
Create and apply the audit log filters using the following configuration:
91+
92+
```sql
93+
-- Define a custom filter for comprehensive logging
94+
SET @log_custom_filter = '{
95+
"filter": {
96+
"class": [
97+
{
98+
"name": "connection",
99+
"event": [
100+
{ "name": "connect" },
101+
{ "name": "disconnect" },
102+
{ "name": "error" } /* captures failed login attempts */
103+
]
104+
},
105+
{
106+
"name": "general",
107+
"event": [
108+
{
109+
"name": "status",
110+
"log": {
111+
"or": [
112+
{ "field": { "name": "general_sql_command.str", "value": "select" } },
113+
{ "field": { "name": "general_sql_command.str", "value": "insert" } },
114+
{ "field": { "name": "general_sql_command.str", "value": "update" } },
115+
{ "field": { "name": "general_sql_command.str", "value": "delete" } },
116+
{ "field": { "name": "general_sql_command.str", "value": "truncate" } },
117+
{ "field": { "name": "general_sql_command.str", "value": "create" } }, /* DDL fix */
118+
{ "field": { "name": "general_sql_command.str", "value": "alter" } }, /* DDL fix */
119+
{ "field": { "name": "general_sql_command.str", "value": "drop" } } /* DDL fix */
120+
]
121+
}
122+
}
123+
]
124+
}
125+
]
126+
}
127+
}';
128+
```
129+
130+
```sql
131+
-- Verify JSON syntax before loading (optional but recommended)
132+
SELECT JSON_VALID(@log_custom_filter) AS is_valid;
133+
```
134+
135+
`JSON_VALID()` returns `1` if the string is valid JSON, `0` otherwise.
136+
137+
```sql
138+
-- Define a filter that disables logging
139+
SET @log_none_filter = '{
140+
"filter": { "log": false }
141+
}';
142+
```
143+
144+
```sql
145+
-- Define a filter that logs only specific SQL commands
146+
SET @log_custom_filter = '{
147+
"filter": {
148+
"log": true,
149+
"rules": [
150+
{
151+
"type": "sql",
152+
"conditions": [
153+
{ "field": { "name": "general_sql_command.str", "value": "select" } },
154+
{ "field": { "name": "general_sql_command.str", "value": "insert" } },
155+
{ "field": { "name": "general_sql_command.str", "value": "update" } },
156+
{ "field": { "name": "general_sql_command.str", "value": "delete" } },
157+
{ "field": { "name": "general_sql_command.str", "value": "create" } },
158+
{ "field": { "name": "general_sql_command.str", "value": "alter" } },
159+
{ "field": { "name": "general_sql_command.str", "value": "drop" } }
160+
]
161+
}
162+
]
163+
}
164+
}';
165+
```
166+
167+
```sql
168+
-- Apply filters to specific users
169+
SELECT audit_log_filter_set_filter('log_custom', @log_custom_filter);
170+
SELECT audit_log_filter_set_filter('log_none', @log_none_filter);
171+
172+
-- Set user-specific audit logging rules
173+
SELECT audit_log_filter_set_user('%', 'log_custom');
174+
SELECT audit_log_filter_set_user('monitor@%', 'log_none');
175+
```
176+
177+
178+
179+
## Testing and validation
180+
181+
Verify that the audit log filters work correctly by performing these tests:
182+
183+
```sql
184+
-- Check that filters are applied correctly
185+
SELECT audit_log_filter_set_user('testuser@localhost', 'log_custom');
186+
SELECT audit_log_filter_set_user('monitor@localhost', 'log_none');
187+
188+
-- Verify filter assignments
189+
SELECT * FROM mysql.audit_log_filter;
190+
SELECT * FROM mysql.audit_log_user;
191+
```
192+
193+
Test the configuration by:
194+
* Connecting as a general user and performing various SQL operations
195+
196+
* Connecting as a monitor user and performing operations
197+
198+
* Checking the audit log file for expected entries
199+
200+
## Troubleshooting
201+
202+
Common issues and solutions:
203+
204+
205+
| Issue | Description |
206+
|-------------------------------|----------------------------------------------------------------------------------------------|
207+
| Filter not applied | Verify that the audit log plugin is enabled and the filter names are correct |
208+
| Unexpected logging | Check user pattern matching and filter precedence rules |
209+
| Performance impact | Monitor system performance when comprehensive logging is enabled |
210+
211+
212+
## Configuration Breakdown
213+
214+
| Filter Type | Description | Key Characteristics |
215+
|------------|-------------|---------------------|
216+
| <b>Wildcard User Filter (`%`)</b> | Captures operations for general users | • Ensures <b>comprehensive auditing</b><br>• Applies to all users matching the wildcard<br>• Logs multiple SQL operation types |
217+
| <b>Monitor User Filter</b> | Logging control for specific users | • <b>Completely disables logging</b><br>• Provides granular user-level exclusion<br>• Prevents any audit trail for specified users |
218+
| <b>Flexible Matching</b> | User pattern-based filtering | • Uses `%` wildcard for broad rule application<br>• Enables dynamic user group configurations<br>• Simplifies management of similar user accounts |
219+
220+
## Security considerations
221+
222+
When configuring audit log filters:
223+
224+
* Review filter rules regularly to ensure they meet security requirements
225+
226+
* Consider the impact of comprehensive logging on system performance
227+
228+
* Ensure that monitoring users cannot bypass audit logging through filter manipulation
229+
230+
* Document all filter changes for compliance and auditing purposes
231+
232+
## Performance impact
233+
234+
Comprehensive audit logging affects system performance:
235+
236+
* Each logged event requires disk I/O operations
237+
238+
* Large numbers of concurrent users increase logging overhead
239+
240+
* Consider log rotation and cleanup strategies for long-term operation
241+
242+
## Best practices
243+
244+
* Always align audit filters with specific security and compliance requirements
245+
246+
* Regularly review and update audit logging configurations
247+
248+
* Use the principle of least privilege when defining logging scopes
249+
250+
* Test filter configurations in a development environment before applying to production
251+
252+
* Monitor audit log file sizes and implement appropriate rotation policies

‎mkdocs-base.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -221,6 +221,7 @@ nav:
221221
- XML (New style): audit-log-filter-new.md
222222
- XML (Old style): audit-log-filter-old.md
223223
- JSON: audit-log-filter-json.md
224+
- advanced-audit-log-filter-example.md
224225
- audit-log-filter-security.md
225226
- audit-log-filter-compression-encryption.md
226227
- reading-audit-log-filter-files.md

0 commit comments

Comments
 (0)