Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CN/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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语法快速参考]
Expand Down
134 changes: 134 additions & 0 deletions CN/modules/ROOT/pages/master/security/database_auditing.adoc
Original file line number Diff line number Diff line change
@@ -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>,<类别>,<命令>,<对象类型>,<对象名>,<SQL语句>,<参数>`)。

日志示例:

[source,text]
----
LOG: AUDIT: SESSION,1,1,DDL,CREATE TABLE,,,CREATE TABLE t1 (id int, name varchar(50));,<none>
LOG: AUDIT: OBJECT,2,1,READ,SELECT,TABLE,public.accounts,SELECT balance FROM public.accounts;,<none>
----

* 可通过 `grep "AUDIT:" log/ivorysql-*.log` 筛选审计日志,或接入集中式日志平台 / SIEM 系统实现防篡改留存与告警。
* 在 Oracle 兼容模式(`1521` 端口)下使用时,请结合数据脱敏与合规要求评估是否开启 `pgaudit.log_parameter`(开启后会明文记录参数值),并严格限制 `log_directory` 目录的文件系统访问权限。
2 changes: 2 additions & 0 deletions EN/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
134 changes: 134 additions & 0 deletions EN/modules/ROOT/pages/master/security/database_auditing.adoc
Original file line number Diff line number Diff line change
@@ -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: <TYPE>,<STATEMENT_ID>,<SUBSTATEMENT_ID>,<CLASS>,<COMMAND>,<OBJECT_TYPE>,<OBJECT_NAME>,<STATEMENT>,<PARAMETER>`).

Example log output:

[source,text]
----
LOG: AUDIT: SESSION,1,1,DDL,CREATE TABLE,,,CREATE TABLE t1 (id int, name varchar(50));,<none>
LOG: AUDIT: OBJECT,2,1,READ,SELECT,TABLE,public.accounts,SELECT balance FROM public.accounts;,<none>
----

* 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.
Loading