Wazuh Engine Helper 函数端到端测试工具 engine-helper-test 完全指南【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh导读本文围绕 Wazuh Engine规则引擎中 helper 函数map / filter / transformation 三类的自动化测试工具engine-helper-test展开完整讲解其设计目标、环境搭建、五个子命令init / validate / generate-tests / run / generate-doc的用法以及 YAML 测试描述文件的完整 Schema 编写规范。读完本文你将掌握如何在 Wazuh 仓库中为任意 helper 函数声明参数、自动生成测试用例、批量运行并生成文档并理解该工具与 Engine 实际执行链路decoder、policy、tester session、KVDB、MMDB的对应关系。一、工具定位为 helper 函数做端到端自动化测试在 Wazuh Engine 的资产asset中helper 函数承担事件字段的检查、映射与转换职责是规则处理流水线的基础单元。engine-helper-test正是为这些 helper 函数设计的端到端测试工具它以YAML 文件描述 helper 函数的参数类型、来源、允许值、限制等自动从这些描述中生成对应测试用例并驱动真实的 Engine 实例运行每个测试用例包含四类信息Asset含被测 helper 的资产运行时会构造包含该 helper 的 decoder 资产并注册到 Engine测试条目Test entries若 helper 存在引用reference参数会生成对应条目描述Description说明正在测试的行为预期结果Expected result与测试结果Test result用于自动判定通过/失败。也就是说工具验证的是 helper 在真实 Engine 运行链路中的行为构建期与运行期而非纯 Python 层面的模拟。这一点从源码中的执行流程可以得到印证详见下文“运行原理”一节。工具对应的目录结构如下仓库根目录相对路径 src/engine/test/helper_testshelper_tests/ ├── configuration_files │ └── config.env # Engine 测试用配置含 ENV_PATH_PLACEHOLDER 占位符 ├── engine-helper-test # Python 包可 pip 安装提供 CLI 入口 engine-helper-test ├── helpers_description # 所有 helper 的描述文件按类型分子目录 │ ├── filter/ # 53 个 filter helper │ ├── map/ # 29 个 map helper │ └── transformation/ # 42 个 transformation helper ├── mmdb │ ├── testdb-asn.mmdb # 测试用 ASN 地理数据库 │ └── testdb-city.mmdb # 测试用城市地理数据库 └── README.md三种 helper 类型的描述文件分别位于helpers_description/filter如is_string.yml、regex_match.yml、ip_cidr_match.ymlhelpers_description/map如int_calculate.yml、geoip.yml、downcase.ymlhelpers_description/transformation如parse_json.yml、kvdb_decode_bitmask.yml、split.yml二、安装engine-helper-test是一个 Python 包项目配置见 engine-helper-test/pyproject.toml依赖api-communication、engine-test-utils、pyyaml要求 Python 3.8 及以上。进入 Wazuh 仓库根目录后安装pip install wazuh/src/engine/test/helper_tests/engine-helper-test如需开发/修改工具脚本本身使用可编辑模式并附带 dev 依赖pip install -e wazuh/src/engine/test/helper_tests/engine-helper-test[dev]安装完成后命令行入口engine-helper-test即被注册对应 helper_test/__main__.py 中的main函数。三、CLI 总览与五个子命令主命令统一通过-e/--environment指定环境目录即 Engine 实例的工作目录其余为五个子命令$ engine-helper-test -h usage: engine-helper-test [-h] -e ENVIRONMENT {init,validate,generate-tests,run,generate-doc} ... Utility to perform the helper test on the Engine positional arguments: {init,validate,generate-tests,run,generate-doc} init Update configuration, create kvdbs and mmdbs validate Validates that the helper descriptions comply with the schema generate-tests Generates files containing test cases for a given helper run Runs the generated test cases and validates their results generate-doc Generates files containing documentation for a given helper options: -h, --help show this help message and exit -e ENVIRONMENT, --environment ENVIRONMENT Environment directory3.1 init —— 初始化环境init负责更新配置、创建 KVDB 与 MMDB即把测试运行所需的全部资源铺进环境目录$ engine-helper-test init -h usage: engine-helper-test init [-h] -b BINARY --mmdb MMDB --conf CONF options: -h, --help show this help message and exit -b BINARY, --binary BINARY Path to the binary file --mmdb MMDB Directory path where the as and geo databases are located --conf CONF File path where the engine configuration file is注意init帮助中仍显示-b BINARY但标准流程见下文“运行全部测试”由 setupEnvironment.py 预先将编译产物wazuh-engine复制进环境目录init会直接使用环境内的二进制无需再传-b。各参数含义--mmdbASN 与 Geo 数据库所在目录仓库中即 helper_tests/mmdb--confEngine 配置文件仓库中即 helper_tests/configuration_files/config.env。init的执行逻辑源码 helper_test/initial_state.py可概括为将config.env复制为环境目录下的config.env并把其中ENV_PATH_PLACEHOLDER占位符替换为环境目录绝对路径若目标已存在则先重命名为.bak备份初始化 enrichment storestore/enrichment/geo与store/enrichment/ioc的元数据 JSON复制testdb-asn.mmdb、testdb-city.mmdb到环境的geo/目录并在store/geo/mmdb/0写入带 MD5 哈希与时间戳的元数据创建测试 KVDB 文件tmp/kvdb_test.json内容为{test: {key: value}, test_bitmask: {33: some_data}}启动一次 Engine 再停止验证二进制与配置可用。3.2 validate —— 校验描述文件validate在生成测试用例之前先校验 helper 描述文件是否符合预期格式$ engine-helper-test validate -h usage: engine-helper-test validate [-h] (--input-file INPUT_FILE | --input-dir INPUT_DIR) options: -h, --help show this help message and exit --input-file INPUT_FILE Absolute or relative path where the description of the helper function is located --input-dir INPUT_DIR Absolute or relative path where the directory that contains the descriptions of the auxiliary functions is located--input-file与--input-dir二选一分别针对单个描述文件或整个描述目录目录会递归查找*.yml。校验实现位于 helper_test/test_cases_generator/validate.py 与 validator.py。3.3 generate-tests —— 生成测试用例文件根据描述文件生成包含具体测试用例的文件$ engine-helper-test generate-tests -h usage: engine-helper-test generate-tests [-h] (--input-file INPUT_FILE | --input-dir INPUT_DIR) -o OUTPUT_PATH options: -h, --help show this help message and exit --input-file INPUT_FILE Absolute or relative path where the description of the helper function is located --input-dir INPUT_DIR Absolute or relative path where the directory that contains the descriptions of the auxiliary functions is located -o OUTPUT_PATH, --output-path OUTPUT_PATH Absolute or relative path of the directory where the generated test files will be located生成逻辑位于 helper_test/test_cases_generator/generate.py其中 argument.py、runtime_cases.py、buildtime_cases.py 分别负责参数展开、运行期与构建期用例生成。3.4 run —— 运行测试并校验结果执行生成的测试用例并输出报告$ engine-helper-test run -h usage: engine-helper-test run [-h] (--input-file INPUT_FILE | --input-dir INPUT_DIR) [--show-failure] options: -h, --help show this help message and exit --input-file INPUT_FILE Absolute or relative path to the test case file --input-dir INPUT_DIR Absolute or relative path to the directory containing test case files --show-failure Shows only the failure test cases that occurred--show-failure只展示失败的用例适合调试回归。报告由 helper_test/runner.py 中的generate_report生成包含总用例数、成功数、失败数及逐条详情只要存在失败用例进程即以非零码退出并抛出异常。3.5 generate-doc —— 生成 helper 文档基于描述文件自动生成 helper 函数的文档$ engine-helper-test generate-doc -h usage: engine-helper-test generate-doc [-h] (--input-file INPUT_FILE | --input-dir INPUT_DIR) [--exporter EXPORTER] -o OUTPUT_PATH options: -h, --help show this help message and exit --input-file INPUT_FILE Absolute or relative path where the description of the helper function is located --input-dir INPUT_DIR Absolute or relative path where the directory that contains the descriptions of the auxiliary functions is located --exporter EXPORTER Absolute or relative path of the directory where the generated test files will be located -o OUTPUT_PATH, --output-path OUTPUT_PATH Absolute or relative path of the directory where the generated documentation files will be located默认输出目录为/tmp/documentation默认导出器--exporter为markdown文档生成前会先对输入执行一次validate保证只对合法描述生成文档。文档生成框架位于 helper_test/documentation_generator 目录exporter.py定义导出器接口mark_down_generator.py、html_generator.py、pdf_generator.py提供三种格式实现generate.py负责串联解析、生成与保存。四、运行全部测试的完整流程安装完成后先运行 setupEnvironment.py 在指定位置构建环境。该脚本会复制 schema 到store/schema/{wazuh-logpar-overrides,engine-schema,allowed-fields}创建queue/sockets、kvdb、logs、outputs、content目录从src/external/tzdata复制时区数据库到tzdb/iana将编译产物src/build/engine/wazuh-engine复制为环境目录下的wazuh-engine若未编译会报错提示先编译 Engine。随后按顺序执行cd ./wazuh/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_tests四个步骤各司其职init铺环境 →validate校验描述 →generate-tests产出用例文件 →run驱动 Engine 执行并输出报告。运行原理源码级run子命令的执行链路runner.py展示了一个真实的 Engine 测试场景校验环境目录中存在wazuh-engine二进制、config.env、tmp/kvdb_test.json与输入路径用EngineHandler启动 Engine 实例对每个 YAML 测试文件先create_namespace创建testing命名空间随后在构建期测试build_test与运行期测试run_test之间反复执行 teardown/setup——删除并重建会话session、policy、decoder 资产、integration、KVDB 资源通过resourcePost以固定 UUID 注册被测 decoderdecoder/test/0及其 integrationpolicy 以 integration 为唯一构成tester session 绑定testing命名空间按 helper 类型调用 tester 接口发事件map 校验_helper字段、filter 校验_verification_field字段、transformation 校验_target_field字段及 trace 中的 Success/Failure 结果extract_transformation_result_from_response会从资产 trace 中正则提取结果汇总成功/失败用例并打印报告失败则非零退出。KVDB 同样通过 CM 资源注入见get_helper_test_kvdb_resource内含 Windows Kerberos 状态码与 access mask 位掩码测试数据而非简单读取本地文件——这也解释了process_file中kvdb_path参数“当前未使用”的注释。五、如何编写一个测试描述文件 Schema每个 helper 描述文件在生成用例前都会被严格校验确保其格式与信息完全符合生成器预期。5.1 必填属性属性说明name被测 helper 函数的名称用于构造测试用例helper_type仅能取 Engine 支持的三种类型之一map、filter、transformationis_variadic布尔值表示该 helper 是否接受可变数量的参数5.2 可选属性属性说明arguments描述各参数可接受类型、允许的来源source及取值限制等general_restrictions描述参数之间的取值约束target_field仅用于filter与transformation类型指定 target_field 的具体类型与子类型skipped忽略某个测试套件的结果目前仅支持[success_cases, different_type, different_source, different_target_field_type, allowed]test与基于参数描述自动生成的测试不同允许手工指定具体类型与来源的用例前提是遵守每个参数的定义5.3 arguments 属性arguments接受一个对象列表每个对象的键标识参数值描述该参数的类型、来源及取值限制arguments: argument_id: type: any_type generate: any_subtset source: any_source restrictions: allowed: - tany_value argument_id: type: any_type generate: any_subtset source: any_source类型type支持的 5 种类型number、string、boolean、array、object。type属性可同时声明一个或多个类型若声明了多个类型则不再需要generate属性。子集generate每种类型对应特定的生成器可理解为该类型下的子集number类型子集integer、float、doublestring类型子集string、hexadecimal、ip、regexboolean类型子集booleanarray类型子集integer、float、double、string、hexadecimal、ip、regex、booleanobject类型子集objectgenerate属性声明的生成器必须与声明的类型一致例如# 正确配置 type: number generate: integer# 不允许 type: number generate: regex这一“类型 ↔ 子集”约束在源码中有明确映射见 definition_types/types.py 中的CORRESPONDENCE_BETWEEN_TYPE_SUBSET如number → [number, integer, double, float]、string → [string, hexadecimal, ip, regex]hexadecimal还会被校验为0x开头的合法十六进制串ip会校验 IPv4 各段取值范围regex会被re.compile验证可编译。来源source声明参数接受的值来源三选一value只接受字面值reference只接受引用引用名以$开头both两者皆可限制restrictions定义每个参数的允许或禁止值只能二选一每个均支持一个值列表restrictions: allowed: - testing以下写法不被允许allowed 与 forbidden 不能同时出现restrictions: allowed: - testing forbidden: - testing25.4 general_restrictions 属性用于设置参数之间的取值约束general_restrictions: - brief: some restriction brief arguments: argument_id: some_value argument_id: some_value details: some restriction detail其中argument_id是标识参数在参数列表中位置的数字标识0 起value必须与arguments属性中该参数的取值一致生成器会根据arguments属性中的信息自动完成其余工作。brief与details描述约束摘要与详情供文档与用例描述使用。5.5 target_field 属性用于filter与transformation类型定义 target_field 的类型与对应子类型target_field: type: array generate: string也可以声明类型列表此时不再需要generatetarget_field: type: - number - string - object - boolean - array5.6 skipped 属性忽略从arguments自动生成的某个测试套件的结果支持以下标签各对应一个特定套件skipped: - success_cases - different_type - different_source - different_target_field_type - allowed典型应用场景int_calculate.yml中跳过success_cases与different_type注释说明是因为“生成器可能生成分子为 0 的用例”见 helpers_description/map/int_calculate.yml。5.7 test 属性允许进行自定义测试但必须遵守每个参数已定义的信息。其运作方式是双重的可以只给每个参数一个值由生成器按既有信息自动生成该参数的多种版本也可以手动指定每个参数的具体来源source。后者对同时接受两种来源both的参数很有用——例如需要测试“缺少引用任意后缀”的场景。如果 helper 在is_variadic中被声明为可变参数则可以放置任意数量的参数上限 40 个生成器会尊重最后一个参数的 source 与 type。仅给出值、由生成器决定来源的写法test: - arguments: id_argument: any_value id_argument: any_value target_field: any_value should_pass: whether or not it should happen expected: [1,2,3,4] description: any description同时给出值与来源的写法test: - arguments: id_argument: source: any_source value: any_value 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 descriptionshould_pass声明该用例期望通过还是失败expected声明期望输出description给出测试行为描述。5.8 完整示例解读以 helpers_description/filter/is_string.yml 为例name: is_string metadata: description: | Checks if the value stored in field is of type string. If theyre not, the function evaluates to false. In case of error, the function will evaluate to false. This helper function is typically used in the check stage keywords: - undefined helper_type: filter is_variadic: false target_field: type: string generate: string test: - target_field: key: value should_pass: false description: Not is string - target_field: [1,2,3,4] should_pass: false description: Not is string - target_field: hello should_pass: true description: Is string这里target_field限定为string类型三个手工用例分别验证“对象不是字符串”“数组不是字符串”“字符串通过”。结合上一节的int_calculate.ymlmap 类型、变参、带general_restrictions禁止除零、并针对 64 位整数溢出设计了 8 个test用例可以看出描述文件从“声明式参数”到“边界行为”都能表达。六、如何生成 helper 函数文档文档默认保存到/tmp/documentation默认导出器为markdown。下面的命令以 Engine 目录的绝对路径为例。6.1 为单个 helper 生成文档engine-helper-test -e /tmp/environment generate-doc --input-file test/helper_tests/helpers_description/map/int_calculate.yml -o test/helper_tests/documentation6.2 为某一类型的 helper 生成文档engine-helper-test -e /tmp/environment generate-doc --input-dir test/helper_tests/helpers_description/map -o test/helper_tests/documentation6.3 为所有 helper 生成文档engine-helper-test -e /tmp/environment generate-doc --input-dir test/helper_tests/helpers_description/ -o docs/helpers/文档内容名称、类型、参数、限制、用例描述等由描述文件中的metadata.description、metadata.keywords、arguments、general_restrictions、target_field、test等字段驱动可通过--exporter切换为markdown、html或pdf对应 mark_down_generator.py、html_generator.py、pdf_generator.py。七、实践要点与注意事项先编译 EnginesetupEnvironment.py依赖src/build/engine/wazuh-engine产物未编译会直接报错退出时区数据库依赖src/external/tzdata需先下载外部依赖。占位符替换config.env中的ENV_PATH_PLACEHOLDER会在init时被替换为环境目录绝对路径该文件同时声明了 Engine 运行所需的关键环境变量WAZUH_ENGINE_STANDALONEtrue、store/outputs/kvdb/content/日志路径、API socket、地理数据库路径WAZUH_GEO_DB_PATH、IOC 同步间隔等见 configuration_files/config.env。类型与子集必须一致generate必须落在type的合法子集内源码 types.py 中CORRESPONDENCE_BETWEEN_TYPE_SUBSET是唯一依据。变参上限 40test属性中变参 helper 的用例参数最多 40 个且最后一个参数的 source/type 会被生成器沿用。限制互斥restrictions中allowed与forbidden不可同时出现skipped只支持 5 个固定套件标签。三种 helper 的判定方式不同run 阶段 map 看_helper字段、filter 看_verification_field字段、transformation 看_target_field字段与 trace 中的 Success/Failure编写test用例的expected时应据此设计。环境的隔离与清理每个测试文件执行前后都会重建命名空间资源decoder、integration、policy、session、KVDB保证用例互不污染全部用例失败时进程以非零退出便于 CI 集成。结语engine-helper-test把“描述 helper 函数”与“驱动真实 Engine 验证”两层工作解耦开发者只需按 Schema 编写 YAML 描述即可获得覆盖类型、来源、限制、边界如int_calculate的 64 位溢出的自动化用例以及可发布的 Markdown/HTML/PDF 文档。理解本文介绍的目录结构、五个子命令与 Schema 各属性就能为 Wazuh Engine 中任意 map / filter / transformation helper 建立完整、可回归的端到端测试闭环。相关源码与示例文件均可在仓库 src/engine/test/helper_tests 下找到。【免费下载链接】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），仅供参考