Wazuh 漏洞扫描器索引 API 深度解析wazuh-states-vulnerabilities 文档结构、字段语义与文档生命周期【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh本篇基于 Wazuh 官方文档 API Reference 展开讲清楚 Vulnerability Scanner以下简称 VD模块将 CVE 检测结果写入 Wazuh-indexerOpenSearch的机制wazuh-states-vulnerabilities索引如何检索、检测文档 ID 如何生成、哪些字段有特殊语义以及 upsert/delete 如何表达活跃漏洞与已解决漏洞。读完本文你能直接基于 OpenSearch API 查询和解释 Wazuh 的漏洞检测数据并能从源码层面理解每条字段的来龙去脉。1. 数据模型VD 把检测结果写进哪里VD 模块是一个事件驱动的 CVE 检测组件它消费 InventorySync 归一化后的清点数据与本地 CVE 数据库解析自 CTI 源存入本地 RocksDB做关联产出两类输出遵循 ECSElastic Common Schema规范、写入wazuh-states-vulnerabilities索引的检测文档经由 Indexer Connector通过queue-http.sock使用 H/E 协议发送给 Engine 的告警事件。这一背景在同目录的 模块介绍 中有完整描述。索引写入的实际入口在源码 ResultIndexer它遍历一次扫描上下文中的全部检测结果按检测结果上携带的操作类型ElementOperation::Upsert或ElementOperation::Delete分别调用 Indexer Connector 的bulkIndex与bulkDelete目标索引名即常量wazuh-states-vulnerabilities。写入前还会对每个待 upsert 的 ECS JSON 做 Schema 校验若该索引在 Schema Validator 工厂中注册了对应的校验器校验失败的文档只记录告警日志并被跳过不会污染索引——这与文档中mapping 是 strict 的这一约定相互印证。2. 快速检索GET /wazuh-states-vulnerabilities/_search文档给出的最短检索路径是通过GET /wazuh-states-vulnerabilities/_search端点直接查询该索引例如按 CVE 过滤GET /wazuh-states-vulnerabilities/_search { query: { term: { vulnerability.id: CVE-2016-2781 } } }按 Agent 或严重级别过滤时可以使用agent.id、vulnerability.severity等字段这些字段名以第 4 节的示例文档为准。该索引遵循 ECS 规范组织字段因此host.os.*、package.*、vulnerability.*等命名空间的行为与 ECS 字段参考一致。3. 文档生命周期与 ID 规则文档原文明确了以下生命周期规则它们决定了如何理解索引中的现存文档VD 通过 bulk upsert 与 delete 两种方式写入wazuh-states-vulnerabilities包级检测的 ID 规则agentId_packageInventoryId_cveIdOS 级检测的 ID 规则agentId_osName_osVersion_cveIdupsert 表示一次活跃的漏洞检测delete 表示该检测已被解决如漏洞包被升级修复。因此索引中任意时刻现存的文档就是未修复漏洞的全量快照被删除的 ID 对应已解决项。这也意味着可以用ID 中缀做幂等去重同一 Agent 上同一包同一库存 ID命中同一 CVE 时反复扫描只会 upsert 同一条文档不会产生重复。从源码结构看这两条 ID 规则由两个扫描器分别实现包扫描器 packageScanner.hpp 中注释明确detectionId agentId_packageInventoryId_cveIdOS 扫描器 osScanner.hpp 中注释明确detectionId agentId_osName_osVersion_cveId。delete 路径同样有源码依据编排器会先由 EventGetContext 查询wazuh-states-vulnerabilities中该 Agent 现有的全部检测若某个已索引的检测对应的包/OS 数据在当前清点中已不存在则将其装载为Delete操作最终由 ResultIndexer 执行bulkDelete。此外当 Agent 离线或数据整体失效时ScanOrchestrator 还支持按查询批量删除该索引中的记录。4. 字段语义说明Field notes原文档的 Field notes 部分解释了若干非直觉的字段行为逐条对应源码实现如下字段语义规则源码依据host.os.full由 OS 的nameversion拼接而成macOS 使用codename参与构造scanContext.hpp 的 buildOSFullName()host.os.version由major.minor.patch.build规范化构造而非原始 OS 版本字符串同上buildOSVersion()package.*OS 检测时OS 级漏洞没有包但会用 OS 数据填充package.*来表示受影响组件eventDetailsBuilder.hpp 中 OS 分支显式将osName/osVersion/osArchitecture写入package.name/version/...package.path、package.type源数据为空时索引为nulldelete 查询把这些情形视为缺失字段处理eventDetailsBuilder.hpp 中packageCtx-format/location为空时写入nullptrtimestamp、event.*有意不写入索引文档因为索引 mapping 是 strict 模式eventDetailsBuilder.hpp 注释说明 the wazuh-states-vulnerabilities template uses dynamic: strict第 5 点的含义由于索引模板使用dynamic: strict任何未定义的字段如 ECS 时间戳字段timestamp与event.*命名空间都会导致写入失败所以构建器刻意不生成这些字段。查询时不应期待timestamp可用检测时间应以vulnerability.detected_at为准。5. 索引文档示例以下三个示例来自原文档分别展示了 Ubuntudeb 包、CentOSrpm 包和 WindowsOS 级检测三类典型文档。它们完整覆盖了上述字段语义包级文档含package.*与host.os.*Windows 文档的vulnerability.category为OS且package.name被填充为 OS 全名加版本。5.1 Ubuntudeb 包级检测{ _index: wazuh-states-vulnerabilities, _id: 001_9ad9d4c11defa663706b9812ffdf99572e969058_CVE-2016-2781, _score: 1, _source: { agent: { id: 001, name: 1495da319fdc, type: Wazuh, version: v4.11.2 }, host: { os: { full: Ubuntu 22.04.5 LTS (Jammy Jellyfish), kernel: 5.15.0-138-generic, name: Ubuntu, platform: ubuntu, type: ubuntu, version: 22.04.5 } }, package: { architecture: amd64, description: GNU core utilities, name: coreutils, size: 7282688, type: deb, version: 8.32-4.1ubuntu1.2 }, vulnerability: { category: Packages, classification: -, description: chroot in GNU coreutils, when used with --userspec, allows local users to escape to the parent session via a crafted TIOCSTI ioctl call, which pushes characters to the terminals input buffer., detected_at: 2025-05-05T19:04:19.577Z, enumeration: CVE, id: CVE-2016-2781, published_at: 2017-02-07T15:59:00Z, reference: https://ubuntu.com/security/CVE-2016-2781, https://www.cve.org/CVERecord?idCVE-2016-2781, scanner: { condition: Package default status, reference: https://cti.wazuh.com/vulnerabilities/cves/CVE-2016-2781, source: Canonical Security Tracker, vendor: Wazuh }, score: { base: 6.5, version: 3.0 }, severity: Medium, under_evaluation: false }, wazuh: { cluster: { name: jammy }, schema: { version: 1.0.0 } } } }注意_id的结构001_9ad9d4c11defa663706b9812ffdf99572e969058_CVE-2016-2781001是 Agent ID中间一段是包在 InventorySync 中的库存 IDSHA 形式最后是 CVE 编号——正对应第 3 节的包级 ID 规则。wazuh.schema.version为1.0.0与构建器源码中的常量WAZUH_SCHEMA_VERSION 1.0.0eventDetailsBuilder.hpp 第 28 行一致。5.2 CentOSrpm 包级检测{ _index: wazuh-states-vulnerabilities, _id: 002_f660c0f64f48a92f0afe744f658e223bd5238bf1_CVE-2022-3219, _score: 1, _source: { agent: { id: 002, name: 5abe6b9cecda, type: Wazuh, version: v4.11.2 }, host: { os: { full: CentOS Linux 8.4.2105, kernel: 5.15.0-138-generic, name: CentOS Linux, platform: centos, type: centos, version: 8.4.2105 } }, package: { architecture: x86_64, description: Utility for secure communication and data storage, installed: 2021-09-15T14:17:36.000Z, name: gnupg2, size: 9923131, type: rpm, version: 2.2.20-2.el8 }, vulnerability: { category: Packages, classification: -, description: DOCUMENTATION: A vulnerability was found in GnuPG. GnuPG can spin on a relatively small input by crafting a public key with thousands of signatures attached and compressed down to a few kilobytes. This issue can potentially cause a denial of service., detected_at: 2025-05-05T19:04:20.037Z, enumeration: CVE, id: CVE-2022-3219, published_at: 2023-02-23T20:15:12Z, reference: https://access.redhat.com/security/cve/CVE-2022-3219, scanner: { condition: Package default status, reference: https://cti.wazuh.com/vulnerabilities/cves/CVE-2022-3219, source: Red Hat CVE Database, vendor: Wazuh }, score: { base: 6.2, version: 3.1 }, severity: Medium, under_evaluation: false }, wazuh: { cluster: { name: jammy }, schema: { version: 1.0.0 } } } }与 Ubuntu 示例对比可见 rpm 包额外带package.installed安装时间ISO8601 格式来源是 构建器对install_time的转换。vulnerability.scanner.source在两个 Linux 示例中分别为 Canonical Security Tracker 和 Red Hat CVE Database——源码中该值由 CNA 标识经 ADP 描述映射表解析而来enrichVulnerabilityModel解析失败时回退为 CNA 原名。5.3 WindowsOS 级检测{ _index: wazuh-states-vulnerabilities, _id: 003_Microsoft Windows Server 2019 Datacenter Evaluation_CVE-2024-43558, _score: 1, _source: { agent: { id: 003, name: vagrant, type: Wazuh, version: v4.11.2 }, host: { os: { full: Microsoft Windows Server 2019 Datacenter Evaluation 10.0.17763.1935, name: Microsoft Windows Server 2019 Datacenter Evaluation, platform: windows, type: windows, version: 10.0.17763.1935 } }, package: { architecture: x86_64, name: Microsoft Windows Server 2019 Datacenter Evaluation 10.0.17763.1935, type: windows, version: 10.0.17763.1935 }, vulnerability: { category: OS, classification: CVSS, description: Windows Mobile Broadband Driver Denial of Service Vulnerability, detected_at: 2025-05-05T19:23:53.627Z, enumeration: CVE, id: CVE-2024-43558, published_at: 2024-10-08T18:15:22Z, reference: https://msrc.microsoft.com/update-guide/vulnerability/CVE-2024-43558, scanner: { condition: Package less than 10.0.17763.6414, reference: https://cti.wazuh.com/vulnerabilities/cves/CVE-2024-43558, source: National Vulnerability Database, vendor: Wazuh }, score: { base: 6.5, version: 3.1 }, severity: Medium, under_evaluation: false }, wazuh: { cluster: { name: jammy }, schema: { version: 1.0.0 } } } }Windows 示例印证了两条 Field notes_id采用 OS 级 ID 规则003 OS 名 版本号 CVEvulnerability.category为OS且package.name被填充为OS 全名 版本package.type为windows。另外vulnerability.scanner.condition展示了版本匹配规则的四种可能取值源码 buildScannerCondition 中定义为Package equal to X、Package less than X、Package less than or equal to X、Package default status厂商安全追踪器的默认状态匹配。6. 关键衍生字段是如何生成的除文档已说明的字段外示例文档中几个字段的生成逻辑值得从源码角度确认vulnerability.score.base/versionCVSS 基础分保留两位小数评分版本直接取自 CVE 描述数据两者任一缺失时vulnerability.under_evaluation置为true表示暂无法评级enrichVulnerabilityModel。vulnerability.detected_at写入时刻的 ISO8601 时间戳published_at来自 CVE 的发布日期。vulnerability.severity首字母大写化处理如medium→Medium空值以-占位。vulnerability.scanner.reference统一拼接为 CTI 的 CVE 页面 URL CVE 编号scanner.vendor恒为Wazuh。vulnerability.category按受影响组件类型区分Packages/OS在文档构建时单独设置因为依赖组件类型判定。这些字段与告警事件的对应关系可进一步参考同目录的 events.md告警侧通过 H/E 协议走 Engine 而非索引。7. 如何验证与深入单元测试 eventDetailsBuilder_test.cpp 覆盖了文档构建的各分支含包级/OS 级、空字段回退、under_evaluation 判定resultIndexer_test.cpp 与 eventGetContext_test.cpp 则验证 upsert/delete 写入与已存在检测的装载逻辑可作为字段行为的回归证据。端到端验证可通过 QAC 场景 qa 测试 观察wazuh-states-vulnerabilities的写入日志该索引的模板样例也随 Indexer Connector 的 QA 测试数据一并提供template.json。更上层的架构VD 如何消费 InventorySync 会话、CTI feed 下载与 RocksDB 本地库的关系见 architecture.md模块开关与参数见 configuration.md从 4.x 检测器迁移到 CTI feed 的说明见 vulnerability-detection-cti-feeds.md。Framework 侧对该索引的组件定义可参考 states_components.py其中登记了wazuh-states-vulnerabilities作为可查询的 states 索引之一。8. 小结wazuh-states-vulnerabilities是 VD 模块对外提供漏洞数据的核心接口以 ECS 规范组织agent.*/host.os.*/package.*/vulnerability.*字段以agentId_componentId_cveId作为幂等文档 ID用 upsert 表达活跃检测、delete 表达已解决检测。查询侧只需对索引执行标准的 OpenSearch search 请求理解第 4 节字段语义尤其是host.os.full的构造、OS 检测借用package.*表达受影响组件、strict mapping 下无timestamp即可正确解读每一条检索结果。【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考