日志分析运维观测【免费下载链接】graylog2-serverFree and open log management项目地址https://gitcode.com/gh_mirrors/gr/graylog2-server点击查看免费下载本文以官方 UPGRADING.md 为骨架系统梳理从 Graylog 7.1 升级到 7.2.x 时必须关注的破坏性变更、Web 界面变化、Java API 变化、插件构建规则、Sigma 规则到事件定义Event Definitions的迁移以及 AWS Kinesis/CloudWatch 输入升级到 KCL 3.5 后所需的 DynamoDB 权限与单表状态迁移步骤。读完本文你将能够逐项评估升级影响、修正受影响的搜索与解析逻辑、为 Kinesis 输入补齐 IAM 权限并安全执行状态表迁移。一、破坏性变更Breaking Changes1. 实体建议搜索query 参数不再支持正则表达式/entity_suggestions端点的query参数过去会被当作正则表达式直接交给 MongoDB 求值。恶意构造的输入如foo.*bar可以触发 ReDoS正则拒绝服务攻击。升级后query被当作纯文本子串进行匹配包含.、*、、?、(、)等正则元字符的查询串将按字面量匹配不再被解释为模式。如果你此前依赖正则语义调用该端点需要自行改为在客户端完成模式匹配后再以普通文本传入。从源码实现可以看到这一变更的落地方式。在 MongoEntitySuggestionService.java 中过滤器通过Filters.regex(field, Pattern.quote(query), i)构建——Pattern.quote()将用户输入整体转义为字面量配合i选项实现大小写不敏感的子串匹配从根本上杜绝了正则注入final Bson bsonFilter; if (filterIsEmpty) { bsonFilter Filters.empty(); } else if (displayFields ! null !displayFields.isEmpty()) { final SetString searchFields new LinkedHashSet(displayFields); searchFields.add(valueColumn); bsonFilter Filters.or(searchFields.stream() .map(field - Filters.regex(field, Pattern.quote(query), i)) .toList()); } else { bsonFilter Filters.regex(valueColumn, Pattern.quote(query), i); }该端点的入口定义在 EntitySuggestionResource.javaquery参数的默认值为空字符串支持collection、identifier、column、display_fields、display_template、page、per_page等查询参数。2. 分页 REST API排序与过滤统一采用大小写不敏感、数值感知的排序规则分页实体端点Streams、Event Definitions、Notifications、Lookup Tables、Dashboards、Sigma Rules、Investigations 等现在对排序和过滤统一使用大小写不敏感、数值感知的 collation。此前只有个别端点自行启用排序受影响且匹配始终区分大小写。升级后需要留意两点行为变化排序title、name等字符串字段排序时大写与小写条目交错排列包含数字的字符串按自然序排列Stream 2排在Stream 10之前。过滤字符串字段的过滤表达式改为大小写不敏感匹配。例如原本只匹配test的查询现在也会匹配Test和TEST。依赖分页端点精确大小写匹配的 API 客户端会看到额外结果需审视相关调用逻辑。3.gl2_accounted_message_size对恢复的 Data Lake 消息可为0从 Data Lake 恢复消息时不计入许可证流量license traffic的消息其gl2_accounted_message_size字段现在会被设置为0。此前无论恢复是否计入许可证该字段始终保存消息的计费大小。需要明确该字段仅作信息展示不参与许可证用量计算因此你的许可证消费不受影响。但如果你有依赖该字段数值的监控、报表或处理逻辑请注意数值语义的变化。该字段定义在 Message.java 的插件消息模型体系中。4. Okta 日志事件securityContext.userBehaviors字段解析方式变化由于 Okta SDK 的序列化缺陷Graylog 7.1 引入了一个 workaround将Okta Log Events输入拉取到的securityContext.userBehaviors数组中的对象字符串化。升级后的 SDK 已正确将该字段序列化为对象数组workaround 被移除。因此如果你有自定义解析逻辑期望securityContext.userBehaviors是字符串数组升级后必须改为期望对象数组与 Okta API 一致。两种版本下的序列化对比如下。7.1字符串数组{ securityContext: { userBehaviors: [ {\name\:\New City\,\id\:\bbbbbbbbbbbbbbbbbbbb\,\result\:\NEGATIVE\}, {\name\:\New Country\,\id\:\aaaaaaaaaaaaaaaaaaaa\,\result\:\NEGATIVE\} ] } }7.2对象数组{ securityContext: { userBehaviors: [ { name: New City, id: bbbbbbbbbbbbbbbbbbbb, result: NEGATIVE }, { name: New Country, id: aaaaaaaaaaaaaaaaaaaa, result: NEGATIVE } ] } }5. CEF 输入不再为source字段添加斜杠前缀当 CEF 消息既不带deviceAddress/dvc扩展、也没有 syslog 主机名时CEF 输入会用发送方的 socket 地址作为source字段的兜底值。旧实现使用InetAddress.toString()格式化该地址会渲染成hostname/1.2.3.4的形式由于 CEF 输入从不解析主机名主机名部分始终为空导致source带一个前导斜杠如/128.66.23.42。IPv6 发送方还会被记录为完全展开形式如0:0:0:0:0:0:0:1。升级后source保存的是裸地址IPv6 会被压缩如128.66.23.42、::1与其他输入保持一致。如果你围绕旧值做了任何处理需要重点排查剥离source前导斜杠的 Pipeline 规则以斜杠前缀形式为键的保存搜索saved searches或查找表lookup tables匹配该形式的流规则stream rules。这些逻辑升级后不再匹配应及时更新。注意升级前已摄取的消息保留其原始source因此新旧两种形式会在现有索引中长期共存。相关实现可参考 CEFCodec.java 及 CEF 输入模块 CEFInputModule.java。6. 脚本 APIScripting API消息导出默认包含所有字段此前消息导出默认只导出一小部分固定字段且没有导出全部字段的选项——用户必须通过前端FE预先知道消息里到底有哪些字段。升级后默认导出消息的全部字段并可通过显式指定字段列表来限制导出的字段范围。7. 容器化部署时系统 CPU 与内存指标反映容器限制当 Graylog Server 或 Data Node 运行在配置了 cgroup CPU/内存限制的容器中例如 Docker 的--memory/--cpus或 Kubernetes 的resources.limits时以下指标从宿主机视角改为容器 cgroup 视角org.graylog2.system.cpu.percent指标在 NodeMetricPeriodical.java 中注册为 gaugeData Node 的mem_total、mem_free、mem_total_used_bytes、mem_total_used指标采集逻辑位于 NodeMetricsCollector.java。旧版本这些指标始终上报宿主机数值当容器内存限制远低于宿主机总内存时内存已用百分比会显示得很低具有误导性。升级后同一指标会按容器的实际限制缩放已用百分比可能明显跳变——但节点真实的 CPU/内存压力并未变化。请审查并视需要调整基于旧宿主机口径建立的 Dashboard 和告警阈值。二、Web 界面变化Event Definition 向导的 Fields 步骤更名为 Additional Details事件定义Event Definition向导中的 Fields 步骤已更名为 Additional Details以更准确地反映其内容——该步骤现在不仅包含事件字段还涵盖 tags 等更多内容。除了界面文案步骤对应的 URLstep查询参数也从fields改为additional-details即该步骤的 URL 现在是.../edit?stepadditional-details旧书签?stepfields仍可跳转到同名步骤会被映射到重命名后的步骤但建议尽快更新为新的值因为旧值可能在未来的版本中被移除。三、Java API 变更本次升级移除的 Java API 如下调用方需在编译/运行前修正文件/方法说明org.graylog2.contentpacks.facades.EntityWithExcerptFacade#resolveGrants已移除四、插件构建新增requireUpperBoundDepsMaven Enforcer 规则继承自graylog-plugin-parent或graylog-plugin-web-parentMaven 父 POM 的插件构建现在会执行requireUpperBoundDepsenforcer 规则定义在 graylog-plugin-parent/pom.xml。该规则在传递依赖解析到比其他依赖所要求版本更低时会使构建失败。此类冲突的常规修复方式有两种升级过时的依赖到错误信息中显示的更高版本为被标记的构件在dependencyManagement中添加一条记录版本取错误信息中显示的最高所需版本。无法对齐依赖的插件作者可以在自己的 POM 中覆盖maven-enforcer-plugin的enforce-versions执行块。五、Sigma 规则并入事件定义Event Definitions这是 7.2 中影响面最大的架构变更之一。1. 实体模型变化7.2 之前Sigma 规则是一等实体可直接管理每条规则背后都有一个控制执行调度的 Event Definition且部分配置可直接管理。7.2 之后Sigma 规则已并入 Event Definitions不再存在一等的 Sigma 规则实体Sigma 规则事件定义只能通过文件上传或配置的 Git 仓库导入两种方式创建不再支持手工修改 Sigma 规则源 YAML规则以 Event Definition 形式导入后所有管理都直接在 Event Definition 上进行Security Sigma Rules菜单及其关联 UI 已移除Sigma 规则 Git 仓库的管理迁移到Alerts Sigma Repos。Sigma 关联Correlation规则不能再直接导入或上传对event_count和value_count类型关联规则导入后可通过修改生成的事件定义补充聚合信息无需再导入另一条 Sigma 规则对temporal_ordered类型可在规则导入后创建一个Event Correlation事件定义实现同样的时间序列关联。所有此前导入的 Sigma 规则含关联规则都会在升级时自动迁移到新的 Event Definition 模式并保持原有工作行为。2. Sigma 级别到事件定义优先级Priority的修正由 Sigma 规则创建的事件定义此前只映射到一部分受支持的优先级取值现在映射到完整取值范围且所有现存规则都会在 7.2 升级过程中获得正确的优先级。Sigma level之前之后informational1 (Low)0 (Informational)low1 (Low)1 (Low)medium2 (Medium)2 (Medium)high3 (High)3 (High)critical3 (High)4 (Critical)3. Sigma 事件的变化sigma_rule_tag_*字段不再添加到触发的事件中。旧版本触发事件会在 Additional Fields 中携带sigma_rule_tag_1、sigma_rule_tag_2等字段。现在 Graylog 识别的 MITRE 信息存储在事件定义的tactics_techniques字段中该字段在 EventDefinitionDto.java 与 TacticsTechniquesValidator.java 中定义与校验其他标签值移入专门的tags字段。tactics_techniques和tags都是多值数组字段与被替换的单个sigma_rule_tag_N字段不同。如果你在摘要模板、通知正文或下游处理中依赖sigma_rule_tag_*需要更新这些引用。触发事件标题不再添加Sigma:前缀。已存储在索引中的事件保留原标题但新触发的事件不会带此前缀。对之前导入的 Sigma 规则升级迁移会自动完成上述调整源规则标签写入对应 Event DefinitionMITRE 引用进入tactics_techniques其余标签进入tags并从 Event Definition 标题中移除Sigma:前缀。无需重新导入或重新配置规则。注意已存储在索引中的事件不会被重写——它们保留触发时的sigma_rule_tag_*Additional Fields 和标题上述变化只作用于升级后触发的新事件。4. Sigma API 变更端点说明POST /plugins/org.graylog.plugins.securityapp.sigma/sigma/rules/validate_zip迁移至POST /plugins/org.graylog.plugins.securityapp.sigma/sigma/import/validate_zipPOST /plugins/org.graylog.plugins.securityapp.sigma/sigma/rules/import迁移至POST /plugins/org.graylog.plugins.securityapp.sigma/sigma/import/bulk/importPOST /plugins/org.graylog.plugins.securityapp.sigma/sigma/rules/upload迁移至POST /plugins/org.graylog.plugins.securityapp.sigma/sigma/import/bulk/upload其余所有/plugins/org.graylog.plugins.securityapp.sigma/sigma/rules/...已删除改用 Event Definition API 管理六、升级后威胁覆盖率Threat Coverage百分比可能变化由于 7.2 将 Sigma 规则迁移到 Event DefinitionsThreat Coverage 组件显示的百分比可能与 7.1 不同。覆盖率现在直接从 Event Definitions 计算而非此前的 Sigma 规则每个分配了 MITRE tactics/techniques 的 Event Definition 都被纳入统计覆盖率反映这些定义中启用与禁用enabled/disabled的比例不再有 Sigma 规则时期存在的日志源log source检查。因此即使实际安装的 Event Definitions 没有任何变化某个 tactic 的百分比也可能比 7.1 偏高或偏低。七、AWS Kinesis/CloudWatch 输入必需的 DynamoDB 权限7.2 将 AWS Kinesis/CloudWatch 输入升级到 Kinesis Client Library (KCL) 3.5它会调用 KCL 2.x 不会调用的 DynamoDB 操作。这一点适用于每个 Kinesis/CloudWatch 输入无论它是新建的还是 7.2 之前就已存在的——为旧版 Graylog 编写的策略可能看起来没问题实际却在拒绝输入运行。一个只授予 KCL 2.x 所需操作的策略会让输入按固定周期记录授权错误且不消费任何记录。7.2 中 Graylog 会监视两个消费端无法绕开的关键调用——DynamoDB lease 发现Query和 Kinesis 记录拉取GetRecords一旦某个操作被持续拒绝两分钟输入就会失败并明确指出被拒绝的操作而 KCL 能够绕开的拒绝例如只影响 lease 再平衡的拒绝仍会允许输入继续运行。这一检测机制在源码中有完整实现见 AWSAuthorizationFailureDetector.java其注释明确解释了设计意图Watches an AWS client for authorization denials that no amount of retrying will fix, and reports one once an operation the consumer cannot work without has been denied...并把Query与GetRecords列入监视名单第 84–87 行。需要补充的权限在 lease 表已有的操作CreateTable、DescribeTable、GetItem、PutItem、Scan、UpdateItem、DeleteItem之外KCL 3.5 还要求dynamodb:Query资源为arn:aws:dynamodb:region:account:table/graylog-aws-plugin-*/index/*。KCL 3.5 通过 lease 表上的全局二级索引发现 lease。索引是与表分离的 IAM 资源因此仅在表上授予Query仍会拒绝该调用。dynamodb:UpdateTable资源为arn:aws:dynamodb:region:account:table/graylog-aws-plugin-*。KCL 在首次启动时创建该索引。若被拒绝KCL 会在整个启动过程中重试然后中止输入会以通用初始化错误失败而不是启动——这超出了上述稳态检测只监视运行中输入对Query和GetRecords的拒绝但输入仍会明显失败而不是空转不消费。两张遗留表的访问需求遗留表application-name-CoordinatorState和application-name-WorkerMetricStats也需要访问具体取决于输入7.2 或之后创建的输入两张表只需要dynamodb:DescribeTable。KCL 每次启动都会检查它们是否存在并把表不存在以外的任何情况视为失败因此作用域仅限 lease 表的策略会让输入无法启动——即便输入从未使用过这两张表。7.2 之前已存在的输入在完成下一节的单表迁移之前输入会继续使用这两张表。它们需要与 lease 表相同的条目级操作GetItem、PutItem、UpdateItem、DeleteItem、Scan以及DescribeTableKCL 在-CoordinatorState中持有 leader 锁并每 30 秒向-WorkerMetricStats写入 worker 指标。一个资源为arn:aws:dynamodb:region:account:table/graylog-aws-plugin-*的策略可同时覆盖 lease 表和两张遗留表因为它们的名称共享该前缀。启用单表迁移时的额外权限如果你启用下一节的单表迁移它会在一个 DynamoDB 事务中移动状态实体除了上述条目级操作外还额外要求对-CoordinatorState表授予dynamodb:ConditionCheckItem。ConditionCheckItem仅用于事务为非事务访问编写的策略通常不会包含它缺少它时迁移永远不会完成而 Graylog UI 中不会显示任何错误。八、AWS Kinesis/CloudWatch 输入单 DynamoDB 表状态跟踪KCL 将协调状态存储在 DynamoDB 中。KCL 3.5 之前每个输入使用三张表lease 表外加独立的application-name-CoordinatorState和application-name-WorkerMetricStats表。KCL 3.5 引入了单表格式将所有内容合并进 lease 表每个条目带有entityType属性从而减少 DynamoDB 表数量有助于保持在账户级表数量限制以内。两点关键信息新输入自动使用单表格式。这是 AWS KCL 3.5 对新建 consumer 的默认行为全新输入总是使用单张 lease 表。已有输入保持三表布局直到你通过新的 Migrate to single DynamoDB table for state tracking迁移到单一 DynamoDB 表进行状态跟踪输入选项主动迁移。输入编辑页面上提供了 Migrate to single DynamoDB table for state tracking 选项仅对 7.2 之前创建的输入有意义。对这类输入启用该选项会启动一次性迁移将-CoordinatorState和-WorkerMetricStats的实体合并进输入自己的 lease 表。流检查点stream checkpoints会被保留因此摄取过程应无重放、无缺口地继续。7.2 之前已存在的 Kinesis 输入的迁移步骤升级到 Graylog 7.2并在关闭 Migrate to single DynamoDB table for state tracking 选项的情况下让输入启动并运行一个小时。KCL 3.5 要求输入稳定运行整整一小时后才会接受迁移。这个就绪期由 KCL 3.5 固定无法缩短。启用选项前确认输入已就绪。在 DynamoDB 中打开输入的 coordinator-state 表graylog-aws-plugin-stream-name-CoordinatorState找到TableMigration3.5条目检查其tm属性。它必须为TABLE_MIGRATION_STATUS_DEPLOYED。如果仍是TABLE_MIGRATION_STATUS_INIT说明就绪期尚未结束请等待后重新检查。在此之前启用选项会导致输入启动失败。在输入编辑页启用 Migrate to single DynamoDB table for state tracking 选项并保存。迁移随即开始。验证完成。KCL 3.5 默认会固化bake24 小时后才完成最终化。该时段结束后再次检查同一个TableMigration3.5条目其tm属性应变为TABLE_MIGRATION_STATUS_COMPLETE。完成后遗留的-CoordinatorState和-WorkerMetricStats表不再被使用可以删除。迁移是单向的完成后不可回退。它也不是瞬时完成的AWS 建议持续监控直到迁移达成完成状态。迁移相关的实现细节可进一步阅读 KinesisConsumer.java 与 AWSInput.java。升级检查清单综合以上内容在规划 7.2 升级时可对照如下要点实体建议搜索排查调用/entity_suggestions时传入正则的客户端代码改为纯文本子串。分页 API复核依赖大小写敏感过滤或非自然排序的 API 客户端。Okta 输入更新securityContext.userBehaviors的自定义解析逻辑接受对象数组。CEF 输入检查 Pipeline 规则、保存搜索、查找表和流规则中针对斜杠前缀source的匹配。脚本 API确认消息导出默认字段范围变化带来的数据量影响。容器指标调整基于旧宿主机口径的 Dashboard 与告警阈值。Sigma 规则更新摘要模板/通知中对sigma_rule_tag_*的引用切换 API 到新的sigma/import/...路径把 Sigma 仓库管理迁移到Alerts Sigma Repos。AWS Kinesis 输入按上文补齐 DynamoDB IAM 权限含索引资源与UpdateTable对已有输入规划单表迁移并预留 1 小时就绪期与 24 小时固化期。赞分享日志分析运维观测【免费下载链接】graylog2-serverFree and open log management项目地址https://gitcode.com/gh_mirrors/gr/graylog2-server点击查看免费下载相关推荐FluentValidation 12.0 升级指南从 11.x 迁移的破坏性变更全解析FluentValidation 12.0 升级指南从 11.x 迁移的破坏性变更全解析 导读 FluentValidation 12.0 是一次以清理为后端Luxon 升级指南从 1.x / 2.x 迁移到 3.0 的破坏性变更全解析Luxon 升级指南从 1.x / 2.x 迁移到 3.0 的破坏性变更全解析 Luxon 是专为 JavaScript 设计的日期与时间处理库提供了 Da开发工具psutil 迁移指南从 6.x/7.x 升级到 8.0 的破坏性变更全解析psutil 迁移指南从 6.x/7.x 升级到 8.0 的破坏性变更全解析 psutil 是一个跨平台的进程与系统监控库。本文档基于仓库中的 docs/mi可观测性系统编程上一篇如何在Windows上实现Android应用一键安装APK Installer完整指南下一篇通达信缠论指标终极指南3分钟实现专业级技术分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
