From 5fce3b812736119e6d36fe667374d65fecff4f13 Mon Sep 17 00:00:00 2001 From: taomaolou Date: Tue, 17 Nov 2026 21:45:53 +0800 Subject: [PATCH 1/4] docs(en): add Security / Database Auditing to nav.adoc --- EN/modules/ROOT/nav.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index a2026117..9eb854c6 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -186,6 +186,8 @@ *** xref:master/compatibility_features_design/to_binary_float_function_impl.adoc[TO_BINARY_FLOAT Function] *** xref:master/compatibility_features_design/to_binary_double_function_impl.adoc[TO_BINARY_DOUBLE Function] ** xref:master/gb18030.adoc[GB18030 Character Set] +* Security +** xref:master/security/database_auditing.adoc[Database Auditing] * Reference ** xref:master/tools_reference.adoc[Tool Reference] ** xref:master/contribution/asciidoc_syntax_reference.adoc[asciidoc grammar quick reference] From 705df90774bb49fcd1ab24c6477afd01796da7cf Mon Sep 17 00:00:00 2001 From: taomaolou Date: Tue, 17 Nov 2026 21:47:20 +0800 Subject: [PATCH 2/4] docs(cn): add Security / Database Auditing to nav.adoc --- CN/modules/ROOT/nav.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 66bc54e6..c1d5d1fc 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -187,6 +187,8 @@ **** xref:master/compatibility_features_design/to_binary_float_function_impl.adoc[二进制浮点转换函数] **** xref:master/compatibility_features_design/to_binary_double_function_impl.adoc[双精度浮点转换函数] *** xref:master/gb18030.adoc[国标GB18030] +* 安全指南 +** xref:master/security/database_auditing.adoc[数据库审计] * 参考指南 ** xref:master/tools_reference.adoc[工具参考] ** xref:master/contribution/asciidoc_syntax_reference.adoc[asciidoc语法快速参考] From 80dc4ae32d1647e40bda9ea2624479abaa7ec45f Mon Sep 17 00:00:00 2001 From: taomaolou Date: Tue, 17 Nov 2026 21:48:43 +0800 Subject: [PATCH 3/4] docs(en): add Security / Database Auditing guide This document provides an overview of database auditing, focusing on the PgAudit extension for fine-grained auditing in IvorySQL. It includes configuration steps for enabling PgAudit, session and object audit logging, audit management practices, log storage, and reviewing audit logs. --- .../master/security/database_auditing.adoc | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 EN/modules/ROOT/pages/master/security/database_auditing.adoc diff --git a/EN/modules/ROOT/pages/master/security/database_auditing.adoc b/EN/modules/ROOT/pages/master/security/database_auditing.adoc new file mode 100644 index 00000000..cdcc8062 --- /dev/null +++ b/EN/modules/ROOT/pages/master/security/database_auditing.adoc @@ -0,0 +1,134 @@ += Database Auditing + +== Overview + +Database auditing records database access and operations for security monitoring, troubleshooting, and regulatory compliance. While IvorySQL provides built-in statement logging through standard parameters such as `log_statement`, built-in logging is coarse-grained and cannot easily track object-level access (such as specific tables or columns). + +For fine-grained auditing, IvorySQL supports the **PgAudit** (`pgaudit`) extension. PgAudit integrates with the IvorySQL server logging subsystem to generate detailed session and object audit logs across both PostgreSQL-compatible mode (default port `5432`) and Oracle-compatible mode (default port `1521`). + +* **Session Audit Logging**: Records all statements executed by a user session that match configured statement classes (such as `READ`, `WRITE`, `DDL`, or `ROLE`). +* **Object Audit Logging**: Records operations (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) on specific relations (tables, views, columns) based on privileges granted to a designated auditor role (`pgaudit.role`). + +For source compilation and basic extension installation steps, see xref:master/ecosystem_components/pgaudit.adoc[PgAudit Ecosystem Integration]. + +== Audit Function Configuration + +=== Enabling PgAudit + +Before configuring audit rules, load the `pgaudit` shared library at server startup and create the extension in each database you want to audit. + +1. Add `pgaudit` to `shared_preload_libraries` in `postgresql.conf`: ++ +[source,ini] +---- +shared_preload_libraries = 'pgaudit' +---- ++ +[NOTE] +==== +If `shared_preload_libraries` already contains other modules (for example, IvorySQL compatibility plugins), append `pgaudit` as a comma-separated entry and restart the IvorySQL server for the change to take effect. +==== + +2. Restart the IvorySQL instance and create the extension in the target database: ++ +[source,sql] +---- +CREATE EXTENSION pgaudit; +---- + +=== Configuring Session Audit Logging + +Session auditing logs statements based on categories defined in `pgaudit.log`. + +[cols="1,1,2",options="header"] +|=== +| Parameter | Default | Description +| `pgaudit.log` | `none` | Comma-separated list of statement classes to audit: `READ`, `WRITE`, `FUNCTION`, `ROLE`, `DDL`, `MISC`, `MISC_SET`, `ALL`, or `none`. Prefix a class with `-` to exclude it (for example, `all, -misc`). +| `pgaudit.log_level` | `log` | Server log level used for `AUDIT:` entries (`debug5`..`debug1`, `info`, `notice`, `warning`, `log`). +| `pgaudit.log_catalog` | `on` | Controls whether statements referencing only system catalogs (`pg_catalog`) are logged. Setting `off` reduces log noise from client drivers. +| `pgaudit.log_client` | `off` | Sends audit log messages to the client session in addition to the server log (usually kept `off` in production). +| `pgaudit.log_parameter` | `off` | Includes bind/parameter values alongside the SQL statement in audit logs. +| `pgaudit.log_parameter_max_size` | `0` | Maximum byte length logged per parameter value (`0` means unlimited). +| `pgaudit.log_relation` | `off` | Creates a separate audit log entry for each relation (table/view) referenced in a `SELECT` or DML statement. +| `pgaudit.log_statement_once` | `off` | Logs the statement text and parameters only on the first audit entry for a statement/substatement combination. +|=== + +Example configuration in `postgresql.conf` for auditing DDL, privilege changes, and writes while excluding `pg_catalog`-only queries: + +[source,ini] +---- +pgaudit.log = 'ddl, role, write' +pgaudit.log_catalog = off +pgaudit.log_parameter = on +pgaudit.log_relation = on +---- + +Reload the configuration without restarting the database: + +[source,sql] +---- +SELECT pg_reload_conf(); +---- + +=== Configuring Object Audit Logging + +Object auditing targets specific tables, views, or columns by assigning privileges to a dedicated non-login audit role specified by `pgaudit.role`. + +1. Create an audit role and configure `pgaudit.role` in `postgresql.conf`: ++ +[source,sql] +---- +CREATE ROLE auditor NOLOGIN; +ALTER SYSTEM SET pgaudit.role = 'auditor'; +SELECT pg_reload_conf(); +---- + +2. Grant the operations you want to audit to `auditor`: ++ +[source,sql] +---- +-- Audit SELECT and INSERT on a sensitive table +GRANT SELECT, INSERT ON public.accounts TO auditor; + +-- Audit UPDATE only on a specific column +GRANT UPDATE (balance) ON public.accounts TO auditor; +---- + +When any user executes a matching operation on `public.accounts`, PgAudit emits an `OBJECT` audit log entry, even if `pgaudit.log` is `none`. + +== Audit Management + +=== Protecting Audit Configuration + +* **Restrict superuser access**: Only superusers can modify `shared_preload_libraries`, `pgaudit.role`, or `pgaudit.log` globally. Do not grant superuser privileges to application accounts. +* **Control `SET` overrides**: Non-superusers cannot change `pgaudit.log` or `pgaudit.role` in their own sessions, ensuring users cannot disable auditing for their connections. +* **Use `postgresql.conf` or `ALTER SYSTEM`**: Persist audit parameters centrally rather than relying on per-database or per-role `ALTER` settings unless intentional exceptions are required. + +=== Log Storage and Rotation + +PgAudit writes entries prefixed with `AUDIT:` to the IvorySQL server log. Configure log collection and rotation in `postgresql.conf` to prevent disk exhaustion and support retention policies: + +[source,ini] +---- +logging_collector = on +log_directory = 'log' +log_filename = 'ivorysql-%Y-%m-%d.log' +log_rotation_age = 1d +log_rotation_size = 100MB +log_line_prefix = '%m [%p] %q%u@%d/%a ' +---- + +=== Reviewing Audit Logs + +Audit records follow a structured CSV-like format (`AUDIT: ,,,,,,,,`). + +Example log output: + +[source,text] +---- +LOG: AUDIT: SESSION,1,1,DDL,CREATE TABLE,,,CREATE TABLE t1 (id int, name varchar(50));, +LOG: AUDIT: OBJECT,2,1,READ,SELECT,TABLE,public.accounts,SELECT balance FROM public.accounts;, +---- + +* Filter `AUDIT:` lines using standard log tools (`grep "AUDIT:" log/ivorysql-*.log`) or forward logs to a centralized SIEM / log aggregation platform for tamper-resistant retention and alerting. +* In Oracle-compatible mode (port `1521`), verify both `log_directory` permissions and `pgaudit.log_parameter` settings according to your data-masking and compliance requirements, since `pgaudit.log_parameter = on` records literal parameter values in plaintext. From b8900386ab1fccbebb0921771dd1af95341287fa Mon Sep 17 00:00:00 2001 From: taomaolou Date: Tue, 17 Nov 2026 21:51:15 +0800 Subject: [PATCH 4/4] docs(cn): add database auditing guide This document provides an overview and configuration steps for database auditing using PgAudit in IvorySQL, including session and object auditing features. --- .../master/security/database_auditing.adoc | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 CN/modules/ROOT/pages/master/security/database_auditing.adoc diff --git a/CN/modules/ROOT/pages/master/security/database_auditing.adoc b/CN/modules/ROOT/pages/master/security/database_auditing.adoc new file mode 100644 index 00000000..b62515ef --- /dev/null +++ b/CN/modules/ROOT/pages/master/security/database_auditing.adoc @@ -0,0 +1,134 @@ += 数据库审计 + +== 概述 + +数据库审计用于记录数据库的访问与操作行为,以满足安全监控、故障排查及合规审计要求。虽然 IvorySQL 可以通过 `log_statement` 等内置参数记录 SQL 语句,但内置日志粒度较粗,难以精确审计对特定表或列的对象级访问。 + +为实现细粒度审计,IvorySQL 支持 **PgAudit**(`pgaudit`)扩展。PgAudit 深度集成于 IvorySQL 服务日志子系统,可在 PostgreSQL 兼容模式(默认端口 `5432`)和 Oracle 兼容模式(默认端口 `1521`)下生成详细的会话级与对象级审计日志。 + +* **会话审计(Session Audit Logging)**:按配置的语句类别(如 `READ`、`WRITE`、`DDL`、`ROLE` 等)记录用户会话中执行的所有匹配语句。 +* **对象审计(Object Audit Logging)**:通过将特定权限授予指定的审计角色(`pgaudit.role`),仅针对指定表、视图或列的 `SELECT`、`INSERT`、`UPDATE`、`DELETE` 操作生成审计记录。 + +关于 PgAudit 源码编译与基础安装步骤,请参考 xref:master/ecosystem_components/pgaudit.adoc[PgAudit 生态集成]。 + +== 审计功能配置 + +=== 启用 PgAudit + +在配置审计规则前,需要在数据库启动时加载 `pgaudit` 共享库,并在需要审计的数据库中创建扩展。 + +1. 在 `postgresql.conf` 中将 `pgaudit` 加入 `shared_preload_libraries`: ++ +[source,ini] +---- +shared_preload_libraries = 'pgaudit' +---- ++ +[NOTE] +==== +如果 `shared_preload_libraries` 中已配置其他模块(例如 IvorySQL 兼容插件),请以英文逗号分隔追加 `pgaudit`,并重启 IvorySQL 服务使配置生效。 +==== + +2. 重启 IvorySQL 实例后,在目标数据库中创建扩展: ++ +[source,sql] +---- +CREATE EXTENSION pgaudit; +---- + +=== 配置会话审计 + +会话审计根据 `pgaudit.log` 中定义的语句类别记录操作日志。 + +[cols="1,1,2",options="header"] +|=== +| 参数 | 默认值 | 说明 +| `pgaudit.log` | `none` | 需要审计的语句类别列表(逗号分隔):`READ`、`WRITE`、`FUNCTION`、`ROLE`、`DDL`、`MISC`、`MISC_SET`、`ALL` 或 `none`。在类别前加 `-` 表示排除(例如 `all, -misc`)。 +| `pgaudit.log_level` | `log` | `AUDIT:` 审计日志的输出级别(`debug5`..`debug1`、`info`、`notice`、`warning`、`log`)。 +| `pgaudit.log_catalog` | `on` | 控制是否记录仅访问系统目录(`pg_catalog`)的语句。设为 `off` 可减少客户端驱动查询产生的噪音日志。 +| `pgaudit.log_client` | `off` | 是否将审计日志同时发送到客户端会话(生产环境通常保持 `off`)。 +| `pgaudit.log_parameter` | `off` | 是否在审计日志中一并记录 SQL 语句的绑定参数值。 +| `pgaudit.log_parameter_max_size` | `0` | 单个参数值的最大记录字节数(`0` 表示不限制)。 +| `pgaudit.log_relation` | `off` | 为 `SELECT` 或 DML 语句中引用的每个关系(表/视图)单独生成一条审计记录。 +| `pgaudit.log_statement_once` | `off` | 同一语句/子语句组合仅在首次记录审计日志时输出完整 SQL 文本和参数。 +|=== + +以下示例在 `postgresql.conf` 中配置审计 DDL、权限变更及写操作,同时过滤纯系统表查询: + +[source,ini] +---- +pgaudit.log = 'ddl, role, write' +pgaudit.log_catalog = off +pgaudit.log_parameter = on +pgaudit.log_relation = on +---- + +无需重启数据库,执行以下命令使配置生效: + +[source,sql] +---- +SELECT pg_reload_conf(); +---- + +=== 配置对象审计 + +对象审计通过将表、视图或列的权限授予 `pgaudit.role` 指定的非登录审计角色来实现精准审计。 + +1. 创建审计角色并在 `postgresql.conf` 中设置 `pgaudit.role`: ++ +[source,sql] +---- +CREATE ROLE auditor NOLOGIN; +ALTER SYSTEM SET pgaudit.role = 'auditor'; +SELECT pg_reload_conf(); +---- + +2. 将需要审计的操作权限授予 `auditor`: ++ +[source,sql] +---- +-- 审计对敏感表的 SELECT 和 INSERT 操作 +GRANT SELECT, INSERT ON public.accounts TO auditor; + +-- 仅审计对特定列的 UPDATE 操作 +GRANT UPDATE (balance) ON public.accounts TO auditor; +---- + +当任意用户对 `public.accounts` 执行匹配操作时,即使 `pgaudit.log` 为 `none`,PgAudit 也会生成 `OBJECT` 类型的审计日志。 + +== 审计管理 + +=== 保护审计配置 + +* **严格管控超级用户权限**:仅超级用户可以修改 `shared_preload_libraries`、`pgaudit.role` 和全局 `pgaudit.log`。切勿向业务应用账号授予超级用户权限。 +* **防止会话级绕过**:普通用户无法在自己的会话中通过 `SET` 修改 `pgaudit.log` 或 `pgaudit.role`,从而确保用户无法自行关闭审计。 +* **集中持久化配置**:建议统一通过 `postgresql.conf` 或 `ALTER SYSTEM` 管理审计参数,避免分散设置。 + +=== 日志存储与轮转 + +PgAudit 生成的审计日志以 `AUDIT:` 为前缀写入 IvorySQL 服务日志。建议在 `postgresql.conf` 中配置日志采集与轮转策略,避免磁盘占满并满足留存周期要求: + +[source,ini] +---- +logging_collector = on +log_directory = 'log' +log_filename = 'ivorysql-%Y-%m-%d.log' +log_rotation_age = 1d +log_rotation_size = 100MB +log_line_prefix = '%m [%p] %q%u@%d/%a ' +---- + +=== 审计日志查看与维护 + +审计记录采用结构化 CSV 风格格式(`AUDIT: <类型>,<语句ID>,<子语句ID>,<类别>,<命令>,<对象类型>,<对象名>,,<参数>`)。 + +日志示例: + +[source,text] +---- +LOG: AUDIT: SESSION,1,1,DDL,CREATE TABLE,,,CREATE TABLE t1 (id int, name varchar(50));, +LOG: AUDIT: OBJECT,2,1,READ,SELECT,TABLE,public.accounts,SELECT balance FROM public.accounts;, +---- + +* 可通过 `grep "AUDIT:" log/ivorysql-*.log` 筛选审计日志,或接入集中式日志平台 / SIEM 系统实现防篡改留存与告警。 +* 在 Oracle 兼容模式(`1521` 端口)下使用时,请结合数据脱敏与合规要求评估是否开启 `pgaudit.log_parameter`(开启后会明文记录参数值),并严格限制 `log_directory` 目录的文件系统访问权限。