EMQX 审计日志（emqx_audit）原理与实践：事件采集、REST 查询与数据清理

EMQX 审计日志emqx_audit原理与实践事件采集、REST 查询与数据清理【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx导读EMQX 在apps/emqx_audit应用中内置了审计日志Audit Log能力用于记录管理员通过 Dashboard、REST API、CLI 以及 Erlang Console 发起的各类管理操作帮助运维与安全团队高效访问审计轨迹数据支撑审计Auditing、合规Compliance、故障排查Troubleshooting与安全分析Security Analysis。阅读本文后你将掌握 EMQX 审计日志的完整数据模型、采集与存储链路、配置文件参数、GET /audit查询 API 的全部过滤维度以及容量清理与敏感信息脱敏等关键机制。一、emqx_audit 应用概览apps/emqx_audit/README.md对模块的定位概括为为 EMQX 提供审计日志帮助用户高效获取所需的审计轨迹数据服务于审计、合规、故障排查与安全分析。从仓库源码结构看该应用由 4 个 Erlang 源文件组成文件职责emqx_audit_app.erlOTP application 入口负责启动监督树emqx_audit_sup.erl监督者以one_for_all策略管理单个 gen_server workeremqx_audit.erl核心 gen_server接收审计事件、写文件与写数据库、周期清理过期数据emqx_audit_api.erlminirest_api实现暴露GET /audit查询接口监督树采用one_for_all策略emqx_audit_sup.erlworker 以transient方式重启保证审计组件异常退出后能被自动拉起避免审计链路长期失效。二、审计记录的数据模型审计记录的字段定义在 emqx_audit.hrl 中一份审计记录#?AUDITrecord包含三大类信息基本信息created_at事件产生时间微秒级系统时间戳node产生事件的节点名from事件来源取值dashboard、rest_api、cli、erlang_consolesource操作者身份如 Dashboard 用户名source_ip操作者来源 IP操作信息operation_id操作标识例如 REST 端点路径/rules/{id}或空串CLI 场景operation_type操作类型例如rules、configs、conf、emqx、api_keys、node_dumpargs操作参数CLI 参数列表operation_result操作结果取值success/failurefailure失败原因duration_ms操作耗时毫秒请求细节REST API 场景http_methodHTTP 方法取值post/put/deletehttp_request请求详情bindings、body、headers、method、query_string、namespacehttp_status_codeHTTP 响应状态码extra预留扩展字段该表以mnesia/mria的ordered_set类型、disc_copies存储、归属COMMON_SHARD公共分片见 emqx_audit.erl。ordered_set按created_at键序存储天然支持按时间顺序扫描与清理。三、审计事件采集来源与写入链路3.1 四种事件来源审计事件通过?AUDIT(Level, Meta)宏最终调用emqx_audit:log/3从调用点发出。to_audit/1emqx_audit.erl针对不同from构造不同的审计记录CLIfrom cli记录命令名与参数列表如emqx ctl conf show log会被记录为operation_type conf、args [show, log]。测试用例 emqx_audit_api_SUITE.erl 验证了这一行为。Erlang Consolefrom erlang_console将函数调用格式化为字符串存入args。Dashboard / REST APIfrom为自定义原子记录来源用户、来源 IP、操作 ID、操作类型、结果、HTTP 方法与状态码、请求详情及耗时。Dashboard 的审计元数据由emqx_dashboard_audit:log_meta/3等模块在请求处理时构造测试用例中对该函数有直接引用见 emqx_audit_api_SUITE.erl。3.2 写入流程log/3emqx_audit.erl的执行链路为在 Meta 中补充time与level通过 logger handler写入审计日志文件log_to_file/3默认路径${EMQX_LOG_DIR}/audit.log通过try_log_to_db/1写入 mnesia 表mria:dirty_write(?AUDIT, Audit)并补充node与微秒级created_at调用remove_handler_when_disabled/0若配置log.audit.enable为false则移除 logger handler。需要特别指出的是写数据库被包裹在try...catch中emqx_audit.erl审计事件常从cluster_rpc事务和 CLI 命令内部发出若审计写入自身抛错绝不能反过来破坏被审计的操作本身。测试用例t_malformed_event_does_not_crash/1专门回归验证了这一点emqx_audit_api_SUITE.erl。另外EMQX 启动时handle_continue(setup, ...)会自动写入一条cli来源、operation_type emqx、args [start]的启动审计记录emqx_audit.erl方便追溯节点生命周期。四、配置文件参数详解审计模块的配置位于log.audit命名空间下Schema 定义见 emqx_conf_schema.erl。审计功能默认关闭代码中以emqx_config:get([log, audit, enable], false)读取默认false。配置示例log { audit { enable true # 开启审计日志 level info # 日志级别默认 info隐藏级参数 path ${EMQX_LOG_DIR}/audit.log # 审计日志文件路径 rotation_count 10 # 轮转文件数量范围 1~128默认 10 rotation_size 50MB # 单文件轮转大小默认 50MB可设 infinity cache_size 5000 # 数据库缓存条数上限范围 10~30000默认 5000 ignore_high_frequency_request true # 忽略高频请求默认 true time_offset system # 时间偏移测试配置中出现 } }各参数作用如下参数默认值说明enablefalse总开关。关闭后GET /audit返回400 BAD_REQUEST且不再记录新事件levelinfo审计日志级别隐藏级配置项path${EMQX_LOG_DIR}/audit.log审计日志文件路径重要性高rotation_count10轮转文件保留个数取值1~128rotation_size50MB单文件达到该大小即轮转可设infinitycache_size5000数据库审计记录条数上限取值10~30000旧名max_filter_size二者为别名关系ignore_high_frequency_requesttrue忽略高频只读请求避免审计表被海量读操作刷爆cache_size的别名max_filter_size在代码中仍有兼容读取逻辑emqx_audit.erl从源码结构看这是为兼容旧版本配置而保留的。五、REST API查询审计日志5.1 接口形态审计查询接口为GET /auditnamespace 为audit由 emqx_audit_api.erl 实现未开启审计返回400code BAD_REQUESTmessage Audit is disabled分页参数非法返回400 page_limit_invalid目标节点 RPC 失败返回500 NODE_DOWN正常返回200data为审计记录数组meta含page、limit、count、hasnext。查询本质上是调用emqx_mgmt_api:node_query/6在指定节点上按 match_spec 扫描审计表gen_match_spec/3emqx_audit_api.erl将查询参数编译为 ets/mnesia 匹配模式。5.2 过滤参数全部可选参数类型说明nodeatom按节点过滤如emqx127.0.0.1fromenumdashboard/rest_api/cli/erlang_consolesourcebinary操作者身份如adminsource_ipbinary来源 IP如127.0.0.1operation_idbinary操作标识如/rules/{id}、/configs/global_zoneoperation_typebinary操作类型如rules、configs、confoperation_resultenumsuccess/failurehttp_status_codeinteger响应状态码http_methodenumpost/put/deletegte_duration_ms/lte_duration_msinteger耗时区间过滤gte_created_at/lte_created_attimestamp时间区间过滤支持微秒/毫秒时间戳及 RFC3339如2023-10-15T00:00:00.82038408:00page/limitinteger分页参数测试用例 emqx_audit_api_SUITE.erl 验证了created_at过滤同时接受微秒时间戳、毫秒时间戳与 RFC3339 三种格式便于与各类客户端集成。5.3 响应示例REST API 场景的一条审计记录源自源码中的 swagger 示例 emqx_audit_api.erl{ created_at: 2023-10-17T10:41:20.38399308:00, node: emqx127.0.0.1, from: dashboard, source: admin, source_ip: 127.0.0.1, operation_id: /login, operation_type: login, operation_result: success, http_status_code: 200, http_method: post, duration_ms: 0, args: , failure: , http_request: { method: post, bindings: {}, body: {username: admin, password: ******}, headers: {authorization: ******, content-type: application/json} } }CLI 场景的审计记录则operation_id、source_ip、http_*字段为空串args为参数列表例如{from: cli, operation_type: conf, args: [show, log]}。六、存储与容量清理机制审计记录写入 mnesia/mria 的emqx_audit表disc_copies持久化。为避免表无限膨胀gen_server 周期性执行清理emqx_audit.erl清理周期默认 10 秒测试环境为 100ms且核心节点会叠加随机抖动避免集群内所有节点同时清理清理阈值由cache_size别名max_filter_size决定当表大小超过阈值时从最旧记录created_at最小开始删除超额部分删除通过mria:sync_dirty在公共分片上执行且先比较表首键与调用方传入的Oldest防止多节点重复删除误删本应保留的记录若清理事务失败会记录错误日志并在 60 秒后重试。replicant副本节点不执行定时清理interval/1返回hibernate由核心节点统一负责见 emqx_audit.erl。测试用例t_max_size/1emqx_audit_api_SUITE.erl验证了写入超过cache_size后表大小会被收敛回配置值。七、敏感信息脱敏审计日志会记录请求体与 CLI 参数因此必须对敏感信息做脱敏处理仓库中有多层防护HTTP 请求体脱敏emqx_dashboard_audit在生成审计元数据时对登录、License、SSO MFA 等敏感操作的请求体按字段/位置打码为******。测试用例覆盖了POST /license请求体脱敏emqx_audit_api_SUITE.erl、SSO MFA 的setup_token、totp_code等凭据脱敏emqx_audit_api_SUITE.erl以及按位置脱敏未知凭据字段的回归测试。请求头脱敏authorization头在审计记录中被替换为******。CLI 参数脱敏如emqx ctl api_keys add --api-secret secret中的 secret 值被脱敏t_cli_redaction/1emqx_audit_api_SUITE.erl而plugins install name-vsn这类不含敏感信息的参数则原样保留。超长请求体截断写入数据库时HTTP 请求体经truncate_http_body/1处理使用io_lib:format(~0p, ..., [{chars_limit, 1024}])限制为 1024 字符emqx_audit.erl防止超大请求体撑爆审计表。八、权限控制审计日志属于高敏数据REST 接口通过 API scope?SCOPE_AUDIT与角色双重控制。测试用例t_http_api_rejects_namespaced_principals/1emqx_audit_api_SUITE.erl验证命名空间namespaced下的 Dashboard 用户administrator / viewer与命名空间 API Key 访问GET /audit一律返回403 UNAUTHORIZED_ROLE全局管理员可以正常读取审计日志。这确保了多租户/多命名空间场景下审计数据不会跨命名空间泄露。九、测试验证apps/emqx_audit/test/emqx_audit_api_SUITE.erl是完整的 Common Test 套件覆盖了本文提到的全部行为REST 写入与查询、CLI 审计、禁用开关t_disabled/1验证关闭后接口返回错误且不再记录新事件、容量清理、敏感信息脱敏、SSO 来源用户兼容t_http_api_sso_source/1、t_http_api_sso_login_pre_auth_source/1、异常事件不崩溃、命名空间权限拒绝等。这些用例既是功能回归的保障也为二次开发或定制审计策略提供了可直接参考的范例。十、小结EMQX 审计日志apps/emqx_audit是一个麻雀虽小五脏俱全的模块通过?AUDIT宏在 Dashboard、REST API、CLI、Erlang Console 四个入口采集管理操作同步落盘audit.log支持轮转与落库mnesia 表cache_size控制容量对外提供过滤维度丰富的GET /audit查询接口并内置了敏感信息脱敏、命名空间权限隔离、异常隔离与容量自清理机制。运维与安全团队可在开启log.audit.enable true后直接通过 Dashboard 或GET /audit完成合规审计、变更追溯与安全分析。【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考