Wazuh-Engine 端到端测试体系全解析：环境搭建、集成测试、Helper 测试与基准压测实战指南

Wazuh-Engine 端到端测试体系全解析环境搭建、集成测试、Helper 测试与基准压测实战指南【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuhWazuh-Engine 是 Wazuh 开源安全平台统一 XDR 与 SIEM中负责事件处理、规则匹配与资产编排的核心引擎。本文以 src/engine/test/README.md 为骨架系统讲解 Wazuh-Engine 的端到端E2E测试体系如何通过setupEnvironment.py搭建沙箱环境、如何用engine-it运行 BDD 集成测试、如何用engine-helper-test对资产中使用的辅助函数helper做自动化测试以及如何用acceptance_test.sh对引擎做吞吐与资源基准压测。读完本文你将掌握 Wazuh-Engine 从编译产物到可验证、可回归、可压测的完整测试工作流。一、测试体系总览三类测试各司其职Wazuh-Engine 的端到端测试位于仓库的 src/engine/test 目录按测试目标分为三类类别目录定位验收测试Acceptance Testsacceptance_test/性能对比基准衡量 Wazuh-Engine 与 wazuh-manager-analysisd 在不同编排线程数下的资源占用与事件吞吐集成测试Integration Testsintegration_tests/验证引擎各组件之间的交互例如命名空间管理cmcrud、路由器router、地理定位geo、状态status与测试器tester等 API 行为辅助函数测试Helper Testshelper_tests/验证资产assets中使用的 helper 函数是否按预期工作例如filter、map、transformation三类 helper三者共同保证引擎的可靠性reliability与稳定性stability。所有测试都依赖一个共同前提——先用setupEnvironment.py构建一个受控的沙箱环境避免测试与真实安装互相干扰。二、环境搭建setupEnvironment.py沙箱化原理2.1 沙箱到底做了什么从源码 setupEnvironment.py 可以看出setup_engine()函数会完成以下关键工作拷贝 Schema 到 store将wazuh-logpar-overrides、engine-schema、allowed-fields三个 schema 从ruleset/schemas/*.json复制到env/store/schema/name/0创建运行目录queue/sockets、kvdb、logs、outputsCM/CTI 输出文件用、content拷贝时区数据库从src/external/tzdata复制 IANA 时区库到env/tzdb/iana缺失时会提示先下载依赖拷贝引擎二进制将src/build/engine/wazuh-engine复制为env/wazuh-engine若未编译会提示compile the engine first。也就是说沙箱本质上是一个自包含的引擎运行目录schema、KVDB、日志、Unix socket、时区库、二进制全部收纳于一个独立目录中测试时引擎完全不触碰系统级安装路径。2.2 前置条件Python 3.8与pip3engine-suite封装引擎生态常用工具测试与用户都可通过它便捷地与 API 交互api-communication负责与 Wazuh API 通信供直接调用 Wazuh API 的组件使用engine-test-utils供测试使用的公共工具库其核心是EngineHandler见下文。2.3 安装 Python 依赖包在 Wazuh 仓库根目录执行pip3 install tools/api-communication pip3 install test/engine-test-utils pip3 install tools/engine-suite pip3 install test/integration_tests/engine-it pip3 install test/helper_tests/engine_helper_test注意README 中给出的路径如tools/api-communication、test/integration_tests/engine-it是引擎源码树内的相对路径在当前仓库布局下engine-test-utils的实际包位于 src/engine/test/engine-test-utilsengine-it位于 src/engine/test/integration_tests/engine-itengine-helper-test位于 src/engine/test/helper_tests/engine-helper-test各包内均有pyproject.toml可执行pip install ./pkg。若需直接安装可进入对应目录使用pip3 install src/engine/test/engine-test-utils pip3 install src/engine/test/integration_tests/engine-it pip3 install src/engine/test/helper_tests/engine-helper-test2.4 使用方式./setupEnvironment.py [-h] [-e ENVIRONMENT]参数说明-h, --help显示帮助信息并退出-e ENVIRONMENT, --environment ENVIRONMENT指定测试环境目录缺省时默认使用仓库根目录下的environment/示例在src/engine/test目录下执行./setupEnvironment.py -e /tmp/engine该命令会在/tmp/engine目录下构建完整的测试环境。脚本要求先编译引擎产物位于src/build/engine/wazuh-engine并先拉取外部依赖时区库否则会明确报错退出。三、引擎生命周期工具engine-test-utils 的 EngineHandler在深入两类测试前先理解公共工具 engine-test-utils。它提供EngineHandler负责引擎的启停与 API 访问from engine_handler.handler import EngineHandler engine_handler EngineHandler( path/to/engine, path/to/configuration.env) # 启动引擎 engine_handler.start() # 通过 handler 暴露的 api_client 与引擎 API 交互 request {} error, response engine_handler.api_client.send_recv(request) # 停止引擎 engine_handler.stop()引擎配置是一个.env格式文件ENVIROMENT_VARIABLEvalue。仓库中集成的示例配置见 config.env可看到引擎沙箱的全部环境变量例如WAZUH_ENGINE_STANDALONEtrue、WAZUH_STANDALONE_LOG_LEVELdebug以独立模式运行并指定日志级别WAZUH_STORE_PATH、WAZUH_OUTPUTS_PATH、WAZUH_KVDB_IOC_PATH、WAZUH_CM_RULESET_PATH指向沙箱内的 store、outputs、kvdb 与 ruleset 目录WAZUH_SERVER_API_SOCKET、WAZUH_SERVER_EVENT_SOCKET指定 API 与事件 socket 路径WAZUH_ORCHESTRATOR_THREADS2、WAZUH_SERVER_THREAD_POOL_SIZE2控制编排器与服务线程池大小WAZUH_GEO_DB_PATH、WAZUH_TZDB_PATH地理库与时区库路径WAZUH_DUMPER_ENABLEDfalse、WAZUH_STREAMLOG_BASE_PATH调试与流日志开关。提示.env中的ENV_PATH_PLACEHOLDER占位符会被测试工具替换为实际沙箱目录。完整环境变量清单可参考source/conf/src/conf.cpp中Conf::Conf构造函数。四、集成测试用 Behave engine-it 验证组件交互4.1 前置依赖除沙箱基础依赖外集成测试还需要pip3 install test/engine-test-utils # 集成测试工具集 pip3 install behave # Python BDD 框架4.2 完整运行流程第一步建立隔离环境./test/setupEnvironment.py -e /tmp/engine-integration-test第二步初始化测试环境加载全部必要配置-b指向编译产物目录engine-it -e /tmp/engine-integration-test -t ./test/integration_tests init -b ./build/main第三步运行全部集成测试engine-it -e /tmp/engine-integration-test -t ./test/integration_tests run第四步可选运行单个 Featureengine-it -e /tmp/engine-integration-test -t ./test/integration_tests run -f test/integration_tests/catalog/api.feature需要更多参数时使用engine-it run -h查看帮助。4.3 测试用例长什么样以 crud_ns 为例集成测试采用 Gherkin.feature编写。以 crud_ns.feature 为例它验证 cmcrud 命名空间 API 的增删查一致性覆盖了列出无用户命名空间时列表为空创建后能列出创建成功创建、重复创建失败Namespace already exists、空space字段失败Field /space cannot be empty、禁用名system、output、default创建失败删除成功删除、删除不影响其他命名空间、删除不存在的命名空间失败、删除禁用名失败。典型场景片段Scenario: Create a new namespace successfully When I send a request to create the namespace analytics Then the namespace request should succeed And the namespace list should contain analytics Scenario Outline: Fail to create a namespace with a forbidden name When I send a request to create the namespace forbidden_space Then the namespace request should fail And the error message should be expected_error Examples: | forbidden_space | expected_error | | system | Failed to create namespace system: Namespace name is forbidden: system | | output | Failed to create namespace output: Namespace name is forbidden: output | | default | Failed to create namespace default: Namespace name is forbidden: default |同类的 BDD 用例还覆盖路由router/、地理定位geo/含 MMDB 测试数据、状态status/与测试器tester/每个 Feature 目录下都配有对应的steps/与environment.py。这种行为即文档的测试方式让引擎的 API 契约一目了然。五、Helper 测试从描述文件自动生成用例与文档5.1 设计思想资产assets中的 helper 函数filter/map/transformation数量庞大手写用例成本高。engine-helper-test的思路是用 YAML 描述 helper 的参数类型、取值来源与限制由生成器自动产出测试用例每个用例包含被测 helper 的资产、测试条目若存在引用、测试内容描述、期望结果与实际结果。5.2 目录结构与安装helper/ ├── configuration_files # 引擎配置config.env ├── engine-helper-test # 工具包本体 ├── helpers_description # helper 描述文件filter/map/transformation ├── mmdb # 测试用 ASN / 城市 MMDB 数据库 └── README.md安装仓库根目录下pip install wazuh/src/engine/test/helper_tests/engine-helper-test开发模式可修改脚本pip install -e wazuh/src/engine/test/helper_tests/engine-helper-test[dev]5.3 五个子命令engine-helper-test [-h] -e ENVIRONMENT {init,validate,generate-tests,run,generate-doc} ...子命令作用init更新配置、创建 KVDB 与 MMDB需-b BINARY指定二进制、--mmdb指定 MMDB 目录、--conf指定引擎配置validate校验 helper 描述文件是否符合 schema--input-file或--input-dirgenerate-tests依据描述文件生成测试用例文件-o OUTPUT_PATHrun运行生成的用例并校验结果--show-failure只显示失败用例generate-doc生成 helper 文档默认导出markdown到/tmp/documentation5.4 一键跑完所有 helper 测试在src/engine目录下python3 test/setupEnvironment.py -e /tmp/environment engine-helper-test -e /tmp/environment init --mmdb test/helper_tests/mmdb/ --conf test/helper_tests/configuration_files/config.env engine-helper-test -e /tmp/environment validate --input-dir test/helper_tests/helpers_description/ engine-helper-test -e /tmp/environment generate-tests --input-dir test/helper_tests/helpers_description/ -o /tmp/helper_tests engine-helper-test -e /tmp/environment run --input-dir /tmp/helper_tests5.5 如何编写一个 helper 描述文件每个描述文件先经 schema 校验再进入用例生成。必填属性属性说明name被测 helper 函数名helper_type只能是引擎支持的三种之一map、filter、transformationis_variadic是否支持可变数量参数可选属性arguments参数类型/来源/限制、general_restrictions参数间的取值约束、target_fieldfilter/transformation 的目标字段类型与子类型、skipped跳过指定测试套件、test自定义用例。arguments 属性arguments: argument_id: type: any_type # 支持类型见下 generate: any_subset # 类型对应的生成子集 source: any_source # value / reference / both restrictions: allowed: - tany_value支持类型typenumber、string、boolean、array、object。type 可声明多个此时无需generate。各类型的生成子集generatetypegenerate 可选值numberinteger、float、doublestringstring、hexadecimal、ip、regexbooleanbooleanarrayinteger、float、double、string、hexadecimal、ip、regex、booleanobjectobject生成器必须与类型一致例如type: numbergenerate: integer合法而type: numbergenerate: regex非法。来源sourcevalue字面值、reference引用名称以$开头、both两者皆可。限制restrictionsallowed允许值与forbidden禁止值二选一各支持一个值列表restrictions: allowed: - testinggeneral_restrictions 属性用于约束参数之间的取值关系arguments中的argument_id为参数位置标识general_restrictions: - brief: some restriction brief arguments: argument_id: some_value argument_id: some_value details: some restriction detailtarget_field 属性用于 filter 与 transformation 类 helpertarget_field: type: array generate: string也可以声明类型列表此时无需generatetarget_field: type: - number - string - object - boolean - arrayskipped 属性可忽略以下测试套件的输出success_cases、different_type、different_source、different_target_field_type、allowed。test 属性自定义用例仅给值、由生成器决定来源test: - arguments: id_argument: any_value target_field: any_value should_pass: whether or not it should happen expected: [1,2,3,4] description: any description同时指定值与来源适合both型参数test: - arguments: id_argument: source: any_source value: any_value target_field: any_value should_pass: whether or not it should happen expected: any_value description: any description若 helper 是 variadicis_variadic: true参数数量可任意上限 40生成器会尊重最后一个参数的来源与类型。5.6 仓库中的真实示例filter 示例——contains.yml校验字符串包含关系参数searched_value为string且来源both通过skipped: success_cases跳过与 target_field 的自动比较再以test手写成功/失败用例test: - arguments: searched_value: hello target_field: hello wazuh! should_pass: true description: Success contains - arguments: searched_value: hello! target_field: hello wazuh! should_pass: false description: Failure containsmap 示例——int_calculate.yml整数四则运算sum/sub/mul/divoperator用restrictions.allowed限定取值用general_restrictions表达除零非法与64 位整数溢出边界并用test覆盖溢出与除零等边界场景general_restrictions: - arguments: operator: div operand_right: 0 details: Division by zero is not allowed (the function will fail). - details: The limit for a 64-bit integer is 2^63-1 and -2^63. test: - arguments: operator: sum operand_left: 1 operand_right: 9223372036854775807 should_pass: false description: Sum that produces overflow. the limit for a 64-bit integer is exceeded5.7 生成 helper 文档# 单个 helper engine-helper-test -e /tmp/environment generate-doc --input-file test/helper_tests/helpers_description/map/int_calculate.yml -o test/helper_tests/documentation # 某一类 helpermap/filter/transformation engine-helper-test -e /tmp/environment generate-doc --input-dir test/helper_tests/helpers_description/map -o test/helper_tests/documentation # 全部 helper输出到 docs/helpers/ engine-helper-test -e /tmp/environment generate-doc --input-dir test/helper_tests/helpers_description/ -o docs/helpers/六、验收测试吞吐与资源基准压测6.1 原理与流程acceptance_test.sh是面向wazuh-manager-analysisd的自动化基准工具用于衡量不同编排线程数WAZUH_ORCHESTRATOR_THREADS下的事件吞吐与资源占用。对每个线程数脚本依次执行停止 manager若在运行并清理过期的 KVDB 锁以WAZUH_ORCHESTRATOR_THREADSN启动wazuh-manager-analysisd等待引擎就绪日志特征行检测 用curl校验路由启动monitor.py每秒采样 CPU、内存、文件描述符与磁盘 I/O压测前宽限期grace period运行benchmark_tool.go按配置速率发送事件并记录吞吐压测后宽限期停止 monitor 与 analysisd。脚本通过trap保证任何退出路径下子进程monitor、analysisd都被清理压测前还会校验python3与go是否可用、按需安装requirements.txt中的依赖并生成包含 CPU 型号、核心数、内存、OS 版本与测试参数的system_report.txt。6.2 工具与依赖工具用途Python 3monitor.py、graphics_generator.pyGobenchmark_tool.go事件发送器curl引擎路由就绪校验psutilpip进程资源采样matplotlib, pandas, numpypip图表生成Python 依赖缺失时脚本会自动安装。6.3 运行压测# 最小示例单线程、10 秒、不限速率 ./acceptance_test.sh # 完整示例扫描 1/2/4/8 线程 ./acceptance_test.sh \ --threads 1,2,4,8 \ --time 60 \ --rate 0 \ --batch 100 \ --input /path/to/log/files \ --grace 5 \ --results ./resultsCLI 参数一览Flag默认值说明--threads LIST1逗号分隔的待测线程数--time SECS10压测发送时长--rate EPS0目标 EPS0表示不限速--batch SIZE50每个 HTTP 请求携带的事件数--input DIRutils/test_logs含.txt/.log输入文件的目录--output FILE$WAZUH_HOME/logs/standard-wazuh-events-v5/standard-wazuh-events-v5.json观察已处理事件的输出文件--grace SECS5压测前后宽限期--monitor-interval SECS1资源采样间隔--results DIR./results输出 CSV 目录--route NAMEcmsync_standard启动时校验的引擎路由--timeout SECS120等待引擎就绪的最大时长6.4 输出文件格式monitor-NT.csv每采样行一条列说明timestampISO-8601 时间戳cpu_pctCPU 使用率%rss_mb/vms_mb常驻/虚拟内存MBfds打开的文件描述符数read_ops/write_ops累计 I/O 操作数read_bytes/write_bytes累计 I/O 字节数disk_pct磁盘使用率%bench-NT.csv每秒一条列说明timestampISO-8601 时间戳sent累计已发送事件数processed累计已处理事件数输出文件行数system_report.txt日期、内核、CPU 型号/核心数/MHz、内存总量/可用/频率以及本次运行的全部测试参数。6.5 生成对比图表python3 utils/graphics_generator.py -r ./results -o ./chartsFlag默认值说明-r, --results DIR必填结果目录-o, --output DIR./charts图表输出目录--format FMTpng图片格式png、svg、pdf生成的图表包括按线程数分组、按时间对齐的 CPU/RSS/VMS/FD/I/O/磁盘占用与收发事件时序叠加图每个线程数的发送 vs 处理子图总处理事件、平均 EPS 与丢包率loss %的缩放汇总柱状图以及各线程数下平均/峰值 CPU 与 RSS 的资源缩放柱状图。6.6 工具参考benchmark_tool.go通过 Unix socket 向引擎发送事件并记录吞吐。go run utils/benchmark_tool.go -hFlag默认值说明-t60发送时长秒-r1000目标 EPS0不限速-b50批量大小每次请求事件数-i./test_logs日志输入目录-o/var/wazuh-manager/logs/standard-wazuh-events-v5/standard-wazuh-events-v5.json观察的输出文件-Tfalse测试前截断输出文件-csv无CSV 报告输出路径monitor.py按 PID-p/--pid或进程名-n/--name监控进程资源-o指定 CSV 输出默认 stdout-s设置采样间隔--pidfile记录 monitor 自身 PID-d开启调试日志。graphics_generator.py读取结果目录并生成对比图表用法见上文 6.5。七、三类测试的协作关系与最佳实践执行顺序验收测试acceptance_test.sh要求引擎编译完成且go/python3可用但不依赖沙箱环境集成测试与 helper 测试则都要求先用setupEnvironment.py构建沙箱——前者用engine-it init加载配置后以 BDD 方式跑 Feature后者用engine-helper-test init生成 KVDB/MMDB 后执行校验 → 生成用例 → 运行流水线。回归价值helper 描述文件即参数契约 边界用例的声明式来源新增或修改 helper 时只需更新 YAML即可自动扩充测试矩阵与文档这是引擎资产开发中保证 filter/map/transformation 行为稳定的关键机制。性能基线验收测试的bench-NT.csvsent vs processed与monitor-NT.csv资源采样共同构成吞吐、丢包率与资源占用的量化基线可用于评估编排线程数调优WAZUH_ORCHESTRATOR_THREADS对引擎整体表现的影响。无论是为引擎贡献新的 helper、修改路由或命名空间逻辑还是评估引擎在不同线程配置下的性能表现src/engine/test这套沙箱 BDD 集成 声明式 helper 测试 基准压测的完整体系都是验证改动正确性与稳定性的第一道防线。【免费下载链接】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），仅供参考