6.4.6 审计消息组件_MySQL 8.0 参考手册

MySQL 8.0 参考手册 / 第 6 章安全 / 6.4 安全组件和插件 / 6.4.6 审计消息组件

6.4.6 审计消息组件

从 MySQL 8.0.14 开始，该audit_api_message_emit 组件使应用程序能够使用函数将自己的消息事件添加到审计日志中 audit_api_message_emit_udf() 。

该audit_api_message_emit组件与所有审计类型的插件合作。具体而言，示例使用第 6.4.5 节“MySQL 企业审计”audit_log中描述的插件。

安装或卸载审计消息组件

要被服务器使用，组件库文件必须位于MySQL插件目录（由plugin_dir系统变量命名的目录）中。plugin_dir如有必要，通过在服务器启动时设置值来配置插件目录位置。

要安装该audit_api_message_emit 组件，请使用以下语句：

INSTALL COMPONENT "file://component_audit_api_message_emit";

组件安装是一次性操作，不需要在每次服务器启动时都完成。INSTALL COMPONENT加载组件，并将其注册到mysql.component系统表中，以便在后续服务器启动期间加载它。

要卸载该audit_api_message_emit 组件，请使用以下语句：

UNINSTALL COMPONENT "file://component_audit_api_message_emit";

UNINSTALL COMPONENT卸载组件，并从 mysql.component系统表中注销它，以使其在后续服务器启动期间不被加载。

因为安装和卸载 audit_api_message_emit组件就是安装和卸载 audit_api_message_emit_udf() 组件实现的功能，所以没有必要使用CREATE FUNCTION或 DROP FUNCTION 这样做。

审核消息功能

本节介绍组件audit_api_message_emit_udf() 实现的功能 audit_api_message_emit。

在使用审计消息功能之前，请按照安装或卸载审计消息组件中的说明安装审计消息组件。

audit_api_message_emit_udf(component, producer, message[, key, value] ...)
将消息事件添加到审计日志。消息事件包括调用者选择的组件、生产者和消息字符串，以及可选的一组键值对。
此函数发布的事件将发送到所有已启用的审计类型插件，每个插件都根据自己的规则处理事件。如果没有启用审核类型的插件，则发布事件无效。
参数：
- component：指定组件名称的字符串。
- producer：指定生产者名称的字符串。
- message：指定事件消息的字符串。
- key, value: 事件可能包含 0 个或多个指定任意应用程序提供的数据映射的键值对。每个 key参数都是一个字符串，为紧随其后的 value参数指定名称。每个 value参数为其紧随其后的参数指定一个值 key。每个 value都可以是字符串或数值，或NULL.
返回值：
OK指示成功的字符串。如果函数失败，则会发生错误。
例子：
```
mysql> SELECT audit_api_message_emit_udf('component_text',
                                         'producer_text',
                                         'message_text',
                                         'key1', 'value1',
                                         'key2', 123,
                                         'key3', NULL) AS 'Message';
+---------+
| Message |
+---------+
| OK      |
+---------+
```
附加信息：
每个接收由发布的事件的审计插件都会以 audit_api_message_emit_udf() 特定于插件的格式记录事件。例如， audit_log插件（参见第 6.4.5 节，“MySQL Enterprise Audit”）记录消息值如下，具体取决于 audit_log_format系统变量配置的日志格式：
- JSON 格式 ( audit_log_format=JSON):
```
{
  ...
  "class": "message",
  "event": "user",
  ...
  "message_data": {
    "component": "component_text",
    "producer": "producer_text",
    "message": "message_text",
    "map": {
      "key1": "value1",
      "key2": 123,
      "key3": null
    }
  }
}
```
- 新式 XML 格式 ( audit_log_format=NEW):
```
<AUDIT_RECORD>
 ...
 <NAME>Message</NAME>
 ...
 <COMMAND_CLASS>user</COMMAND_CLASS>
 <COMPONENT>component_text</COMPONENT>
 <PRODUCER>producer_text</PRODUCER>
 <MESSAGE>message_text</MESSAGE>
 <MAP>
   <ELEMENT>
     <KEY>key1</KEY>
     <VALUE>value1</VALUE>
   </ELEMENT>
   <ELEMENT>
     <KEY>key2</KEY>
     <VALUE>123</VALUE>
   </ELEMENT>
   <ELEMENT>
     <KEY>key3</KEY>
     <VALUE/>
   </ELEMENT>
 </MAP>
</AUDIT_RECORD>
```
- 旧式 XML 格式 ( audit_log_format=OLD):
```
<AUDIT_RECORD
  ...
  NAME="Message"
  ...
  COMMAND_CLASS="user"
  COMPONENT="component_text"
  PRODUCER="producer_text"
  MESSAGE="message_text"/>
```
  笔记
  
  由于这种格式强加的表示限制，以旧式 XML 格式记录的消息事件不包括键值映射。
发布的消息 audit_api_message_emit_udf() 有一个事件类 MYSQL_AUDIT_MESSAGE_CLASS和一个子类MYSQL_AUDIT_MESSAGE_USER。（内部生成的审核消息具有相同的类和子类MYSQL_AUDIT_MESSAGE_INTERNAL；此子类当前未使用。）要在 audit_log过滤规则中引用此类事件，请使用值为的class元素。例如： namemessage
```
{
  "filter": {
    "class": {
      "name": "message"
    }
  }
}
```
如果有必要区分用户生成的和内部生成的消息事件，请根据或测试该subclass值。 userinternal
不支持基于键值映射的内容进行过滤。
有关编写过滤规则的信息，请参阅第 6.4.5.7 节，“审计日志过滤”。