审核消息组件(audit_api_message_emit)
从MySQL 8.0.14开始,该 udit_api_message_emit
组件使应用程序可以使用 udit_api_message_emit_udf()
用户定义的函数将其自己的消息事件添加到审核日志中。
该 udit_api_message_emit
组件与所有审核类型的插件配合使用。具体而言,示例使用“ MySQL企业审计”中 udit_log
描述的插件。
- 安装或卸载审核消息组件
- 审核消息功能
安装或卸载审核消息组件
要由服务器使用,组件库文件必须位于MySQL插件目录(由plugin_dir
系统变量命名的目录)中。如有必要,通过设置plugin_dir
服务器启动时的值来配置插件目录位置。
要安装 udit_api_message_emit
组件,请使用以下语句:
INSTALL COMPONENT "file://component_audit_api_message_emit";
组件安装是一次性的操作,不需要在每次服务器启动时进行。INSTALL COMPONENT
加载组件,并将其注册在mysql.component
系统表中,以使其在后续服务器启动期间加载。
要卸载 udit_api_message_emit
组件,请使用以下语句:
UNINSTALL COMPONENT "file://component_audit_api_message_emit";
UNINSTALL COMPONENT
卸载组件,然后从mysql.component
系统表中注销该组件,以使其在后续服务器启动期间不被加载。
安装或卸载 udit_api_message_emit
组件将安装或卸载 udit_api_message_emit_udf()
组件实现的功能。不必使用CREATE FUNCTION
或DROP FUNCTION
这样做。
审核消息功能
本节描述了 udit_api_message_emit_udf()
由 udit_api_message_emit
组件实现的用户定义功能(UDF)。
在使用审核消息功能之前,请根据“安装或卸载审核消息组件”中提供的说明安装审核消息组件。
udit_api_message_emit_udf(
component
,producer
,message
[,key
,value
]...)将消息事件添加到审核日志。消息事件包括调用者选择的组件,生产者和消息字符串,以及可选的一组键值对。
该UDF发布的事件将发送到所有启用的审计类型的插件,每个插件均根据其自己的规则处理该事件。如果未启用审核类型的插件,则发布事件无效。
参数:
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 | +--------- +附加信息:
每个接收事件的审核插件都会以
udit_api_message_emit_udf()
特定于插件的格式记录该事件。例如,取决于系统变量配置的日志格式,udit_log
插件(请参见“ MySQL企业审核”)记录消息值如下udit_log_format
:JSON格式(
udit_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格式(
udit_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格式(
udit_log_format=OLD
):<AUDIT_RECORD ... NAME="Message" ... COMMAND_CLASS="user" COMPONENT="component_text" PRODUCER="producer_text" MESSAGE="message_text"/>
注意
由于该格式施加的表示性限制,以旧式XML格式记录的消息事件不包括键值映射。
所发布的消息
udit_api_message_emit_udf()
的事件类为MYSQL_AUDIT_MESSAGE_CLASS
,子类为MYSQL_AUDIT_MESSAGE_USER
。(内部生成的审核消息具有相同的类和的子类MYSQL_AUDIT_MESSAGE_INTERNAL
;该子类当前未使用。)要在udit_log
过滤规则中引用此类事件,请使用值为的class
元素。例如:name
message
{ "filter": { "class": { "name": "message" } } }
如果有必要区分用户生成的消息事件和内部生成的消息事件,请
subclass
针对user
或测试值internal
。不支持基于键值映射的内容进行过滤。
有关编写过滤规则的信息,请参见“MySQL审核日志过滤”。