AUDIT_LOG_FILTER_SET_FILTER

描述

该函数（表达式）用于创建过滤器。

语法

AUDIT_LOG_FILTER_SET_FILTER('filter_name', 'definition_of_filters');

说明

参数解释

• filter_name：用于指定过滤器名称。

  说明

  AUDIT_LOG_FILTER_SET_FILTER 是 CREATE OR REPLACE 语义，对已存在的对象执行 DDL 会覆盖。

• definition_of_filters：用于定义审计过滤器的具体配置，采用 JSON 格式进行表述。在事件类型（Class）之上，可配置事件类型细分（Event Type）、事件字段（Event Field）及字段条件间的 AND / OR 组合：

  • 事件类型细分（Event Type）：用于对指定事件类型进行进一步细分和过滤。在 JSON 字符串中，通过 class 下的 event 下的 name 参数指定相关字段，如{"class": [{"name": "connection", "event": [{"name": "disconnect"}]}]}。
  • 事件字段（Event Field）过滤：事件字段用于对指定事件类型进行进一步细分和过滤。可通过设置 field 参数，实现对 connection、general 和 table_access 三类事件的具体字段（field）进行筛选。在 JSON 字符串中，通过 event 下的 log 参数指定相关字段，如 "event": [{"name": "read", "log": {"field": {"name": "table_name", "value": "t1"}}}]。
  • 逻辑组合：支持通过 AND / OR 对多个 field 进行逻辑组合。

事件类型细分支持的子类型：

事件字段过滤支持的字段：

包含 connection、general、table_access 三个事件类型，每个事件类型下支持多个事件字段，详见下表：

查看 general_sql_command 支持的完整 SQL 类型，请参考文末相关文档。

log 字段的层级、差异与默认行为

日志记录行为取决于 log 的取值，以及是否指定了 class 或 event 项。

其他说明：

• 表格中层级一列是路径表示法的简写，其中：
  • filter.log 表示 filter 对象下的 log 属性，例如 {"filter": {"log": true}}。
  • filter.class[].log 表示 filter 对象下的 class 数组中的单个元素的 log 属性，例如 {"filter": {"class": [{"log": true}]}}。
  • filter.class[].event[].log 表示 filter 对象下的 class 数组中的单个元素的 event 数组中的单个元素的 log 属性，例如 {"filter":{"class":[{"name":"table_access","event":[{"name":"read","log":true}]}]}}。
• 文档中 “JSON 外层 log” 与 “class/event 层 log” 不是重复配置：前者是总开关，后者是局部覆盖或条件过滤。

常用过滤器 JSON 写法

在 class 基础上可按上表继续扩展细分事件类型、事件字段及逻辑组合。以下为几种常用写法：

• 记录所有事件。

  { "filter": { "log": true } }
  

• 不记录所有事件。

  { "filter": { "log": false } }
  

• 只记录登录登出（仅 connection class）。

  { "filter": { "log": true, "class": [ { "name": "connection" } ] } }
  

• 显式列出全部 class（与记录所有事件等价的一种写法）。

  {
    "filter": {
      "log": true,
      "class": [
        { "name": "connection" },
        { "name": "general" },
        { "name": "table_access" }
      ]
    }
  }
  

  也可将同层多项合并为数组（等价写法）：在过滤器定义的同一层级上，若对某一类项多次出现且仅取值不同（例如多个 class 元素各自只有不同的 name），可将这些取值合并进同一项的数组中，只保留一个对象：

  {
    "filter": {
      "log": true,
      "class": [
        { "name": [ "connection", "general", "table_access" ] }
      ]
    }
  }
  

事件类型细分（Event Type）

• 在 connection 下只保留 connect（不包含 disconnect）。

  {
    "filter": {
      "log": true,
      "class": [ { "name": "connection", "event": [ { "name": "connect" } ] } ]
    }
  }
  

• event 数组中的单个事件条目可显式包含 log，用于指定是否记录满足该条目条件的事件。下例在同一 table_access 下选中多种事件类型，并对各类型分别指定是否写入审计：

  {
    "filter": {
      "log": true,
      "class": [
        {
          "name": "table_access",
          "event": [
            { "name": "read", "log": false },
            { "name": "insert", "log": true },
            { "name": "delete", "log": true },
            { "name": "update", "log": true }
          ]
        }
      ]
    }
  }
  

事件字段（Event Field）与逻辑组合

• 记录 connection 的 connect 和 disconnect 事件，以及 table_access 的 insert、delete 和 update 事件。

  {
    "filter": {
      "log": true,
      "class": [
        {
          "name": "connection",
          "event": [
            { "name": "connect" },
            { "name": "disconnect" }
          ]
        },
        { "name": "general" },
        {
          "name": "table_access",
          "event": [
            { "name": "insert" },
            { "name": "delete" },
            { "name": "update" }
          ]
        }
      ]
    }
  }
  

• 逻辑运算符 and、or 可嵌套构造复杂条件。下列过滤器在 general / status 事件上，仅在 log 条件内记录满足两组 and 之一的事件：第一组为 general_command.str 等于 Query 且 general_command.length 等于 5；第二组为 general_command.str 等于 Execute 且 general_command.length 等于 7。

  {
    "filter": {
      "class": {
        "name": "general",
        "event": {
          "name": "status",
          "log": {
            "or": [
              {
                "and": [
                  { "field": { "name": "general_command.str",    "value": "Query" } },
                  { "field": { "name": "general_command.length", "value": 5 } }
                ]
              },
              {
                "and": [
                  { "field": { "name": "general_command.str",    "value": "Execute" } },
                  { "field": { "name": "general_command.length", "value": 7 } }
                ]
              }
            ]
          }
        }
      }
    }
  }
  

返回值

表达式输入必须是字符串常量，输出是字符串类型。

• 当 DDL 执行成功时，表达式返回 OK。
• 当 DDL 执行失败时，SELECT 语句仍然执行成功，表达式的输出结果为错误信息。

示例

• 创建记录所有事件的过滤器 log_all。

  SELECT AUDIT_LOG_FILTER_SET_FILTER('log_all', '{ "filter": { "log": true } }');
  

  返回结果如下：

  +-------------------------------------------------------------------------+
  | AUDIT_LOG_FILTER_SET_FILTER('log_all', '{ "filter": { "log": true } }') |
  +-------------------------------------------------------------------------+
  | OK                                                                      |
  +-------------------------------------------------------------------------+
  1 row in set
  

• 当 DDL 失败时，SELECT 语句仍然执行成功，表达式的输出结果为错误信息。

  SELECT AUDIT_LOG_FILTER_SET_FILTER('log_err', '1');
  

  返回结果如下：

  +---------------------------------------------+
  | AUDIT_LOG_FILTER_SET_FILTER('log_err', '1') |
  +---------------------------------------------+
  | ERROR: JSON parsing error.                  |
  +---------------------------------------------+
  1 row in set
  

相关文档

• general_sql_command 语句类型清单：附录：general_sql_command 支持的完整 SQL 类型
• 开启安全审计