Wazuh 开发环境搭建与 VS Code 调试配置实战指南（基于 docs/dev/setup.md）

Wazuh 开发环境搭建与 VS Code 调试配置实战指南基于 docs/dev/setup.md【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh导读本文基于 Wazuh 官方开发文档 docs/dev/setup.md 编写完整介绍在 Ubuntu 24.04 / Rocky Linux 9 上从零搭建 Wazuh开源统一 XDR 与 SIEM 安全平台C/C 开发环境、为 Windows Agent 准备 MinGW 交叉编译工具链以及如何在 Visual Studio Code 中配置构建任务Build Tasks、GDB 调试配置与部署流水线的全流程。读完本文你将能够独立复现 Wazuh 的源码编译、调试与迭代环境并结合仓库源码理解make TARGET... DEBUG1等关键构建参数在底层是如何生效的。一、工具链准备最低版本要求Wazuh 官方推荐的开发平台为Ubuntu 24.04其核心源码位于仓库 src/ 目录C/C 实现同时包含 framework/Python 框架层与 api/REST API 层。编译源码的最低工具链要求如下工具最低要求用途GNU C/C Compiler13编译 C/C 源码核心守护进程、共享模块GNU Make最新稳定版驱动顶层构建src/MakefileCMake3.18构建子模块src/CMakeLists.txtSELinux Policy Core Utils最新稳定版生成 SELinux 策略模块checkmodule/semodule_packageprocps最新稳定版系统进程/资源信息支持curl最新稳定版构建期下载外部依赖与资源模板CMocka最新稳定版运行 C 单元测试src/unit_tests从仓库 src/Makefile 可以看到构建系统在运行时探测checkmodule与semodule_package是否存在以此决定是否启用USE_SELINUX编译选项这正是工具链清单中 SELinux Policy Core Utils 的用途。版本说明当前仓库 VERSION.json 标识的版本为5.1.0 (alpha0)构建系统会从该文件提取version与stage并注入预处理器宏见 src/CMakeLists.txt。二、按发行版安装工具链2.1 Ubuntu 24.04推荐使用 apt 安装基础编译工具与依赖apt install gcc g make cmake curl procps policycoreutils apt install libcmocka-dev第二条命令安装的是 CMocka 的二进制开发包libcmocka-dev仅对 Linux 目标server / agent的单元测试编译足够Windows Agent 目标的 CMocka 必须从源码用 MinGW 交叉编译见下文。2.2 Rocky Linux 9Rocky 9 默认仓库的 GCC 版本较旧因此需要启用GCC Toolset 13并通过sclSoftware Collections激活dnf install make cmake gcc-toolset-13-gcc-c gcc-toolset-13-gcc procps policycoreutils scl enable gcc-toolset-13 bash # 安装 CMocka需先启用 CRB 仓库 dnf install dnf-plugins-core dnf config-manager --enable crb dnf install libcmocka-devellibcmocka-devel位于 CRBCodeReady Builder仓库中这正是需要config-manager --enable crb的原因。三、Windows Agent 构建要求Linux 上交叉编译Wazuh 的 Windows Agent 可以在 Ubuntu 24.04 上通过MinGW 交叉编译生成前提是安装 MinGW、CMocka 与 Wine 三件套。3.1 安装 MinGW 与 Wineapt install gcc-mingw-w64-i686 g-mingw-w64-i686 wine32注意此处是i68632 位工具链。仓库 src/CMakeLists.txt 为 Windows 交叉编译强制指定了i686-w64-mingw32-ranlib与i686-w64-mingw32-windres而 src/Makefile 在TARGETwinagent时会自动探测i686-w64-mingw32-gcc并设置MING_BASE前缀找不到时直接报错No windows cross-compiler found!。Wine 的作用是作为Windows 可执行文件的运行模拟器当CMAKE_SYSTEM_NAMEWindows且开启UNIT_TEST时CMake 会把wine设置为交叉编译测试的模拟器见 src/CMakeLists.txt否则 Windows 单元测试在 Linux 上无法执行。3.2 从源码编译 MinGW 版 CMocka发行版自带的libcmocka-dev是 Linux 原生库无法链接到 Windows 目标因此必须从源码为 MinGW 构建静态版本git clone -b stable-1.1 https://git.cryptomilk.org/projects/cmocka.git sed -Ei s/(BUILD_SHARED_LIBS .) ON/\1 OFF/ cmocka/DefineOptions.cmake mkdir cmocka/build cd cmocka/build cmake -DCMAKE_C_COMPILERi686-w64-mingw32-gcc \ -DCMAKE_C_LINK_EXECUTABLEi686-w64-mingw32-ld \ -DCMAKE_INSTALL_PREFIX/usr/i686-w64-mingw32/ \ -DCMAKE_SYSTEM_NAMEWindows \ -DCMAKE_BUILD_TYPERelease .. make make install cd ../.. rm -r cmocka关键点说明sed命令将DefineOptions.cmake中的BUILD_SHARED_LIBS改为OFF强制生成静态库交叉环境下运行时加载 DLL 不便安装前缀/usr/i686-w64-mingw32/与 src/CMakeLists.txt 中查找winpthread库的搜索路径一致保证链接阶段能找到库该流程与仓库 docs/dev/test-execution.md 中 Windows 单元测试的 CMocka 构建步骤完全吻合src/unit_tests/Toolchain-win32.cmake 是配套的交叉编译工具链文件。安装完成后即可按 docs/dev/build-sources.md 构建 Windows Agentmake -C src TARGETwinagent deps make -C src TARGETwinagent构建产物位于 src/win32/ 目录顶层 Makefile 的winagent目标还会用 src/win32/unix2dos.pl 把ossec.conf、internal_options.conf、LICENSE等文本转换为 Windows 换行格式见 src/Makefile。四、Visual Studio Code 开发环境官方推荐使用VS Code进行 Wazuh 开发配合 C/C 插件实现 IntelliSense、调试与代码浏览。4.1 推荐扩展扩展标识符用途C/Cms-vscode.cpptoolsIntelliSense、调试、代码浏览C/C Extension Packms-vscode.cpptools-extension-packC 常用扩展合集GitLenseamodio.gitlens增强的 Git 能力与代码历史CMake Toolsms-vscode.cmake-tools扩展 CMake 支持Makefile Toolsms-vscode.makefile-toolsMakefile 的 IntelliSense 与构建支持Remote - SSHms-vscode-remote.remote-ssh通过 SSH 在远程机器上开发WSLms-vscode-remote.remote-wsl在 Windows Subsystem for Linux 中开发仅 Windows仓库中已提供一份贴近真实开发的 VS Code 配置示例位于 src/engine/tools/devContainer/.vscode/可作为参考包含settings.json、launch.json、tasks.json、c_cpp_properties.json。4.2 Workspace 设置.vscode/settings.json在仓库根目录创建或更新.vscode/settings.json以对齐 Wazuh 编码规范{ files.autoSave: afterDelay, files.trimTrailingWhitespace: true, files.insertFinalNewline: true, files.trimFinalNewlines: true, files.simpleDialog.enable: true, editor.acceptSuggestionOnEnter: off, workbench.editor.enablePreview: false, files.associations: { wazuh-manager.conf: xml, ossec.conf: xml, agent.conf: xml }, terminal.integrated.allowChords: false, terminal.integrated.scrollback: 100000, editor.rulers: [80] }关键项解析files.trimTrailingWhitespace保存时删除行尾空白files.insertFinalNewline确保文件以换行符结尾C 源码规范要求editor.rulers: [80]在 80 列处显示辅助线约束行长。仓库引擎模块的配置还额外标注了 90/120 列参考线见 src/engine/tools/devContainer/.vscode/settings.jsonfiles.associations把wazuh-manager.conf、ossec.conf、agent.conf识别为 XML 语法这些是真实的 Wazuh 配置格式仓库中的模板见 etc/wazuh-manager.conf、etc/ossec-agent.conf 与 etc/agent.confterminal.integrated.scrollback: 100000把终端回滚缓冲提高到 10 万行便于回溯长编译输出。4.3 构建任务.vscode/tasks.json把编译动作封装为 VS Code 任务避免手工敲命令。创建或更新.vscode/tasks.json{ version: 2.0.0, tasks: [ { label: build server, type: shell, command: make, args: [TARGETserver, DEBUG1, -j4], options: { cwd: ${workspaceFolder}/src }, group: build, problemMatcher: [$gcc] }, { label: build agent, type: shell, command: make, args: [TARGETagent, DEBUG1, -j4], options: { cwd: ${workspaceFolder}/src }, group: build, problemMatcher: [$gcc] }, { label: build windows agent, type: shell, command: make, args: [TARGETwinagent, -j4], options: { cwd: ${workspaceFolder}/src }, group: build, problemMatcher: [$gcc] } ] }运行方式CtrlShiftPmacOS 为CmdShiftP→ 输入 “Tasks: Run Task” → 选择任务或直接按CtrlShiftB展示全部构建任务。配置项说明DEBUG1编译带调试符号-g且不优化。在 src/Makefile 中DEBUG1会向 CMake 传递-DCMAKE_BUILD_TYPEDebugsrc/CMakeLists.txt 进一步设置CMAKE_CXX_FLAGS_DEBUG -g-j44 个并行编译作业可结合 CPU 核数调整problemMatcher: [$gcc]解析编译器输出把错误/警告显示到 Problems 面板。TARGET 参数在 Makefile 中的语义TARGETserver会被归一化为managersrc/Makefile与agent、winagent一起决定编译哪些模块。从 src/CMakeLists.txt 可见agent 专属模块active-response、logcollector、rootcheck、syscheckd、data_provider等仅在IS_AGENT时编译server 专属模块engine、monitord、os_auth、remoted、wazuh_db等仅在非 agent 时编译。构建入口是build_wazuh_cmake目标src/Makefilecd build cmake .. -DTARGET... make。4.4 调试配置.vscode/launch.json创建或更新.vscode/launch.json以 GDB 交互式调试 Wazuh 守护进程{ version: 0.2.0, configurations: [ { name: Debug wazuh-manager-analysisd, type: cppdbg, request: launch, program: /var/wazuh-manager/bin/wazuh-manager-analysisd, args: [-f], stopAtEntry: false, cwd: ${workspaceFolder}, environment: [], externalConsole: false, MIMode: gdb, setupCommands: [ { description: Enable pretty-printing for gdb, text: -enable-pretty-printing, ignoreFailures: true } ], preLaunchTask: build server, miDebuggerPath: /usr/bin/gdb } ] }开始调试打开要调试的源文件在行号左侧点击设置断点按F5或进入 Run → Start Debugging也可以打开调试面板CtrlShiftD点击播放按钮。配置项说明program要调试的二进制路径。此例为 Manager 的分析引擎wazuh-manager-analysisd对应 src/wazuh_modules 与 src/engine 编译出的分析组件args: [-f]-fforeground让进程前台运行便于 GDB 接管preLaunchTask: build server调试前先执行上文的构建任务确保二进制最新stopAtEntry: true若想停在程序入口可改为true重要前提二进制必须用DEBUG1编译带调试符号否则断点与变量查看不可用。为其他组件添加调试配置例如 remoted{ name: Debug wazuh-manager-remoted, type: cppdbg, request: launch, program: /var/wazuh-manager/bin/wazuh-manager-remoted, args: [-f], preLaunchTask: build server, MIMode: gdb }安装后的可执行文件统一位于/var/wazuh-manager/bin/Manager与/var/ossec/bin/Agent与 docs/dev/run-sources.md 中描述的安装目录一致。4.5 构建后的部署编译产物默认位于src/目录而调试配置指向安装目录/var/wazuh-manager/bin/因此需要把二进制拷贝过去。可新增部署任务{ label: deploy wazuh-manager-analysisd, type: shell, command: sudo, args: [cp, wazuh-manager-analysisd, /var/wazuh-manager/bin/], options: { cwd: ${workspaceFolder}/src }, dependsOn: [build server] }dependsOn保证先构建、后部署。更省事的做法是在调试配置的preLaunchTask中链式引用该部署任务实现“每次调试前自动重新编译并部署”。Wazuh 各组件通常以 root 权限运行拷贝到系统目录需要sudo这一点在调试时同样适用见下文故障排除。五、故障排除Troubleshooting5.1 调试时提示权限拒绝Permission DeniedWazuh 组件普遍需要 root 权限。两种解决方式以 root 运行 VS Code使用独立配置目录避免污染普通用户配置sudo code --user-data-dir/root/.vscode-root --no-sandbox或配置 sudo 免密避免调试会话中反复输入密码。5.2 GDB 未找到GDB Not Foundapt-get install gdb # Ubuntu/Debian yum install gdb # Rocky Linux/RHEL安装后确认launch.json中miDebuggerPath指向实际路径默认/usr/bin/gdb。5.3 编译错误Compilation Errors确认依赖齐全且编译器版本满足要求gcc --version # 应为 13 或更高同时检查是否先执行了make -C src TARGET... deps外部依赖下载与构建见 docs/dev/build-sources.md。顶层 Makefile 维护了EXTERNAL_RES依赖清单src/MakefileManager 目标额外拉取 cpython、rocksdb、protobuf 等数十个库Agent 目标则包含 libdb、lua、rpm 等若启用单元测试模式TEST1src/Makefile 会向 CMake 传递-DUNIT_TESTON此时 CMocka 头文件必须存在如需内存安全检测可以启用FSANITIZE1src/CMakeLists.txt 会为 Debug 构建追加-fsanitizeaddress,leak,undefined标志。5.4 IntelliSense 不工作确认已安装 C/C 扩展ms-vscode.cpptools打开命令面板CtrlShiftP运行 “C/C: Edit Configurations (JSON)”检查compilerPath与includePath是否正确。Wazuh 源码依赖的头文件目录可在 src/CMakeLists.txt 中看到如src/shared/include、src/shared_modules/*/include可据此配置includePath或直接使用 CMake Tools 的compile_commands.json该项目默认开启CMAKE_EXPORT_COMPILE_COMMANDS见 src/CMakeLists.txt。六、环境就绪后的下一步工具链与 IDE 配置完成后可以继续阅读仓库开发文档的其余部分docs/dev/build-sources.mdServer、UNIX Agent、Windows Agent 的完整编译流程与clean系列清理目标docs/dev/run-sources.md从源码安装、启动、停止各组件以及日志与常见运维操作docs/dev/test-execution.md单元测试CMocka/CTest/覆盖率、API 与框架测试pytest、集成测试的执行方式docs/dev/package-generation.md在 Docker 容器中批量生成 rpm/deb 安装包。总结本文完整复现并扩充了 Wazuh 开发环境搭建的全过程从 Ubuntu 24.04 / Rocky Linux 9 的工具链安装、Windows Agent 的 MinGW Wine CMocka 交叉编译环境到 VS Code 的扩展、工作区规范、构建任务与 GDB 调试配置。同时通过 src/Makefile 与 src/CMakeLists.txt 的源码证据解释了TARGET、DEBUG、TEST、FSANITIZE等核心构建参数在底层如何驱动 CMake 与依赖管理帮助你在遇到编译或调试问题时能够快速定位根因。【免费下载链接】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），仅供参考