企业官网建设流程全解析

Wazuh Command 模块（wodle name="command"）配置完全指南：定时执行自定义命令并上报输出

【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh

本指南完整讲解 Wazuh 中<wodle name="command">模块的配置方法、调度语义、校验码验证、事件输出格式与安全最佳实践。该模块在 Agent 端按计划执行自定义命令或脚本，并将输出转发给 Manager 进行规则分析与告警，可用于将自定义监控工具、审计脚本与数据采集器无缝接入 Wazuh 分析管道。读完本文，你将能够独立完成从最小配置、哈希校验、定时调度到故障排查的完整实战部署。

模块定位与工作原理

Command 模块是 Wazuh 的 wodle（wodles 即"监控守护模块"）之一，运行在wazuh-modulesd进程中（Manager 侧对应wazuh-manager-modulesd），用于在主机本地按计划执行操作系统命令，并可选地将命令输出作为事件发送到本地队列供 Manager 分析。它非常适合在没有原生采集器的场景下进行周期性命令遥测，例如磁盘使用率检查、登录异常审计、服务健康探测等。

其工作流程（参见 模块主实现）：

1. wazuh-modulesd从ossec.conf（Agent）或wazuh-manager.conf（Manager，根标签<wazuh_config>）读取<wodle name="command">配置；
2. 根据interval、day、wday、time构建调度计划；
3. 若配置了verify_md5/verify_sha1/verify_sha256，在首次执行前校验可执行文件的校验和；
4. 按timeout超时上限执行命令（底层调用wm_exec）；
5. 当ignore_output为no时，将携带命令元数据与输出的结构化事件写入本地队列，事件使用路由标签command，配置的tag值存放在事件负载内部。

在源码层面，模块上下文WM_COMMAND_CONTEXT定义了start、destroy、dump等钩子，主循环通过共享调度器sched_scan_get_time_until_next_scan计算下一次执行时刻，并支持可中断睡眠以便响应关闭请求（wm_command.h）。

配置文件与 XML 段

• 配置文件：/var/ossec/etc/ossec.conf（Linux/Unix）或C:\Program Files (x86)\ossec-agent\ossec.conf（Windows）；Manager 侧为etc/wazuh-manager.conf。
• XML 段：<wodle name="command">
• 模块属性：Agent-only（配置语义在 Manager 与 Agent 上一致）
• 内部选项前缀：wazuh_command.*

Command wodle 在 Manager 与 Agent 上的配置方式完全相同，且每个<wodle name="command">块相互独立，可以在同一配置文件中定义多个实例。配置解析由 wmodules-command.c 完成，每个子元素都有严格的取值校验：非法取值会导致该模块解析失败（返回OS_INVALID）。

配置参数完整参考

以下参数全部由 XML 解析器逐项校验（可对照 wmodules-command.c 与 模块状态结构体 验证默认值与合法性）：

关键参数底层行为

• command与校验和：从源码看，校验和只作用于从command第一个 token 解析出的可执行文件。模块会拆分命令行 → 解析可执行文件路径 → 校验每个已配置的校验和 → 用解析出的完整路径加原始参数重建完整命令行（full_command），并在每次计划执行前重新校验（除非skip_verification=yes）。参数不参与哈希计算。Windows 上校验时会临时禁用 WOW64 文件系统重定向，以保证解析与校验的是真实文件（wm_command.c）。
• timeout：底层wm_exec若返回WM_ERROR_TIMEOUT，模块记录 "Timeout overtaken" 错误并将exit_code置为-1后继续下一轮调度（wm_command.c）。
• tag缺省行为：若<tag>为空或缺失，模块会记录警告并将事件中的 tags 设为空字符串；日志标签统一为wazuh-modulesd:command（对应宏WM_COMMAND_LOGTAG ARGV0 ":command"）。
• command为空：解析器直接报错返回，配置无法生效。
• 校验和长度：解析器强制 MD5 为 32 字符、SHA1 为 40 字符、SHA256 为 64 字符，长度不符即解析失败。

调度语义：interval、time、day、wday

Command 模块复用 Wazuh 所有 wodle 共享的调度器sched_scan_read/sched_scan_get_time_until_next_scan（schedule_scan.c），因此其调度行为与 AWS、GCP、Azure 等模块一致：

• interval：周期性执行，支持s（秒）、m（分）、h（时）、d（天）、w（周）、M（月）后缀；
• time：指定一天内的HH:MM时刻执行；当间隔不是按天时，会被归一化为1d并给出警告；
• wday：指定星期几执行；当间隔不是按周时，会被归一化为1w并给出警告；
• day：指定每月几号执行；当间隔不是按月时，会被归一化为1M并给出警告；
• day与wday不可同时使用。

run_on_start=yes（默认）时首次执行立即发生；设为no时首次执行会等待下一个调度时刻。调度相关的单元测试覆盖了 interval 各后缀、day/wday/time 的正确与错误取值（test_schedule_scan.c），可作为取值行为的验证依据。

内部选项（Internal Options）

命令模块的额外设置可在etc/internal_options.conf或etc/local_internal_options.conf中配置：

# 允许来自集中配置（agent.conf）的远程命令（0=否，1=是，默认：0） wazuh_command.remote_commands=0

该默认值在仓库 etc/internal_options.conf 中可直接确认。注意：command 模块的内部选项极少，绝大多数配置走 XML；命令输出大小与超时不能通过内部选项配置，而是受系统队列限制（OS_MAXSTR）与 XML<timeout>控制。

集中配置（Centralized Configuration）安全开关：command 模块可以通过agent.conf下发，但远程命令默认关闭。只有当wazuh_command.remote_commands内部选项被启用时，Agent 才会执行来自集中配置的命令 wodle；否则模块记录Remote commands are disabled. Ignoring '<tag>'.并退出该实例（对应 wm_command.c）。相关文档见 Centralized Configuration。

配置示例

默认配置：每 5 分钟执行系统检查脚本

<wodle name="command"> <disabled>no</disabled> <tag>system-check</tag> <command>/usr/local/bin/check.sh</command> <interval>5m</interval> <run_on_start>yes</run_on_start> <timeout>30</timeout> </wodle>

带 SHA256 哈希校验：确保脚本完整性

<wodle name="command"> <disabled>no</disabled> <tag>audit-check</tag> <command>/usr/local/bin/audit.sh</command> <interval>1h</interval> <verify_sha256>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</verify_sha256> <skip_verification>no</skip_verification> <timeout>60</timeout> </wodle>

每日定时执行：凌晨 2 点生成报告

<wodle name="command"> <disabled>no</disabled> <tag>daily-report</tag> <command>/usr/local/bin/report.sh</command> <interval>1d</interval> <time>02:00</time> <timeout>300</timeout> </wodle>

每周执行：每周一凌晨 3 点清理

<wodle name="command"> <disabled>no</disabled> <tag>weekly-cleanup</tag> <command>/usr/local/bin/cleanup.sh</command> <interval>1w</interval> <wday>monday</wday> <time>03:00</time> </wodle>

每月执行：每月 1 日零点备份

<wodle name="command"> <disabled>no</disabled> <tag>monthly-backup</tag> <command>/usr/local/bin/backup.sh</command> <interval>1M</interval> <day>1</day> <time>00:00</time> </wodle>

仅执行不转发输出（只关心副作用）

<wodle name="command"> <disabled>no</disabled> <tag>cache-clear</tag> <command>/usr/local/bin/clear-cache.sh</command> <interval>1h</interval> <ignore_output>yes</ignore_output> </wodle>

高频监控：每 30 秒探测服务

<wodle name="command"> <disabled>no</disabled> <tag>service-monitor</tag> <command>/usr/local/bin/monitor-service.sh</command> <interval>30s</interval> <run_on_start>yes</run_on_start> <timeout>10</timeout> </wodle>

多实例并存：同一配置中定义多个 command wodle

<wodle name="command"> <disabled>no</disabled> <tag>disk-check</tag> <command>/usr/local/bin/disk-check.sh</command> <interval>10m</interval> <timeout>30</timeout> </wodle> <wodle name="command"> <disabled>no</disabled> <tag>network-check</tag> <command>/usr/local/bin/network-check.sh</command> <interval>5m</interval> <timeout>15</timeout> </wodle> <wodle name="command"> <disabled>no</disabled> <tag>security-scan</tag> <command>/usr/local/bin/security-scan.sh</command> <interval>1d</interval> <time>01:00</time> <timeout>600</timeout> </wodle>

命令输出格式与事件结构

命令输出会作为事件转发给 Manager，Manager 可用自定义规则进行分析。经典文本格式：

ossec: output: 'command-tag': <command output>

例如：

ossec: output: 'system-check': Disk usage: 75% ossec: output: 'system-check': Memory available: 2.5GB ossec: output: 'audit-check': WARNING: Unusual login pattern detected

处理要点：

• 命令输出的每一行都会生成独立事件（文本格式）；
• 事件中包含tag值用于标识来源；
• Manager 规则可解析命令输出并产生告警；
• 输出同时记录在 Agent 与 Manager 日志中。

现代结构化事件格式（源码级）

在当前仓库的实现中，当ignore_output为no时，模块实际发送的是一个 JSON 结构化事件（由 wm_command_build_event_payload 构建），字段说明可对照 Command Module README：

{ "event": { "module": "wazuh-wodle-cmd", "start": "2026-05-11T12:00:00Z" }, "tags": ["periodic-whoami"], "process": { "args": [], "name": "whoami", "path": "/usr/bin/whoami", "command_line": "/usr/bin/whoami", "hash": { "sha1": "9746e91bfc629d3a2e1fe6289b549c0452702004" }, "exit_code": 0, "io": { "text": "wazuh\n" } } }

输出截断机制：当输出过大无法放入单条队列消息（受OS_MAXSTR限制）时，模块先尝试截断process.io.text；若仍超限，则发送仅含元数据（输出为空）的事件，并在日志中记录Command output is too long to fit in a single message.。相关行为在单元测试 test_wm_command.c 中有专门覆盖（NORMAL / EMPTY / TRUNCATED / METADATA_ONLY 四种负载场景）。

脚本执行环境

工作目录

命令在 Agent 的工作目录下执行：

• Linux/Unix：/var/ossec/
• Windows：C:\Program Files (x86)\ossec-agent\

用户权限

命令以 Wazuh Agent 的权限运行：

• Linux/Unix：wazuh用户（若 Agent 以 root 运行则为 root）
• Windows：SYSTEM 账户

环境变量

命令可访问标准环境变量；如需要自定义变量，可在包装脚本（wrapper script）中设置后再调用实际脚本。

输出处理

• 标准输出（stdout）：转发给 Manager（除非ignore_output=yes）；
• 标准错误（stderr）：仅在本地记录，不转发给 Manager；
• 退出码：记录用于调试，非零退出码会生成警告日志。

安全注意事项

脚本完整性

生产环境脚本务必启用哈希校验：

# 生成 SHA256 哈希 sha256sum /usr/local/bin/script.sh

将结果写入配置：

<verify_sha256>abc123...</verify_sha256>

校验流程对应源码validate_command_checksums（wm_command.c）：三种哈希逐项比对，任一失败且skip_verification=no时命令被阻止执行。

文件权限

# 属主设为 root（或 wazuh 用户） chown root:root /usr/local/bin/script.sh # 仅属主可读可执行 chmod 700 /usr/local/bin/script.sh

输入校验

若脚本接受参数：

• 校验所有输入以防止注入攻击；
• 避免将用户可控数据直接传给 shell 命令；
• 外部命令一律使用绝对路径。

命令注入防护

存在风险的反例：

# DON'T DO THIS eval "$USER_INPUT"

安全的参数化写法：

# Use parameterized commands /usr/bin/command --option="$VALIDATED_INPUT"

最佳实践清单

• 命令与脚本一律使用绝对路径；
• 实现完善的错误处理；
• 记录脚本所有动作以形成审计轨迹；
• 在预发环境充分测试后再部署生产；
• 定期复查与更新脚本权限；
• 持续监控命令执行日志以发现异常。

性能考量

执行频率选择

• 高频（< 1 分钟）：适合关键服务监控，脚本须执行迅速（建议 < 5 秒），并监控资源消耗；
• 中频（1–30 分钟）：平衡大多数使用场景，可承载较复杂逻辑；
• 低频（小时/天级）：适合资源密集操作、报告与合规检查。

超时设置建议

按预期执行时长匹配：

• 快速检查（< 30 秒）：<timeout>30</timeout>
• 复杂操作（1–5 分钟）：<timeout>300</timeout>
• 长任务（> 5 分钟）：<timeout>600</timeout>

资源使用监控

运行多个 command wodle 时注意观察资源占用：

# 查看正在运行的命令进程 ps aux | grep -E 'wodle|command' # 监控 CPU/内存使用 top -p $(pgrep -d',' wazuh-modulesd)

故障排查

命令未执行

检查配置：

grep -A10 "wodle name=\"command\"" /var/ossec/etc/ossec.conf

检查模块日志：

tail -f /var/ossec/logs/ossec.log | grep command

确认脚本可执行：

ls -l /usr/local/bin/script.sh test -x /usr/local/bin/script.sh && echo "Executable" || echo "Not executable"

确认 wodle 已启用（disabled为no）：

grep -A2 "wodle name=\"command\"" /var/ossec/etc/ossec.conf | grep disabled

哈希校验失败

重新计算哈希：

sha256sum /usr/local/bin/script.sh

与配置中的期望值比对：

# 将计算出的哈希与配置对比 echo "EXPECTED_HASH /usr/local/bin/script.sh" | sha256sum -c

检查脚本是否被修改：

stat /usr/local/bin/script.sh

若脚本更新后忘记同步哈希，也会出现该校验失败；此时应更新配置中的哈希值，或临时设置skip_verification=yes排查。

命令超时

增大超时：

<timeout>300</timeout> <!-- 5 分钟 -->

实测执行耗时：

time /usr/local/bin/script.sh

优化脚本性能：去掉冗余操作、使用高效算法、缓存昂贵计算。

输出未出现

确认ignore_output设置：

<ignore_output>no</ignore_output>

本地直接测试命令输出：

/usr/local/bin/script.sh

在 Manager 上按 tag 检索告警日志：

tail -f /var/wazuh-manager/logs/alerts/alerts.log | grep "command-tag"

权限错误

检查脚本权限：

ls -l /usr/local/bin/script.sh

检查 SELinux 上下文（如适用）：

ls -Z /usr/local/bin/script.sh

修复权限：

chmod 750 /usr/local/bin/script.sh chown root:wazuh /usr/local/bin/script.sh

监控与日常运维

查看命令执行日志

# 查看所有 command wodle 活动 tail -f /var/ossec/logs/ossec.log | grep "wazuh-modulesd:command" # 按 tag 查看特定命令 tail -f /var/ossec/logs/ossec.log | grep "system-check"

查看命令输出

# Agent 本地日志 grep "output:" /var/ossec/logs/ossec.log # Manager 告警日志 tail -f /var/wazuh-manager/logs/alerts/alerts.log | grep "command-tag"

统计执行频率

# 统计某命令执行次数 grep "Executing command" /var/ossec/logs/ossec.log | grep "system-check" | wc -l # 查看最近一次执行时间 grep "Executing command" /var/ossec/logs/ossec.log | grep "system-check" | tail -1

检查错误

# 搜索命令相关错误 grep -i "error\|fail" /var/ossec/logs/ossec.log | grep command # 查看超时事件 grep "timeout" /var/ossec/logs/ossec.log | grep command

常见日志消息速查

高级配置技巧

条件执行

利用包装脚本实现条件执行，例如仅在业务时段（9–17 点）运行：

#!/bin/bash # Only run during business hours (9 AM - 5 PM) hour=$(date +%H) if [ $hour -ge 9 ] && [ $hour -lt 17 ]; then /usr/local/bin/actual-check.sh fi

参数化命令

通过环境变量向命令传递参数：

<wodle name="command"> <disabled>no</disabled> <tag>parametric-check</tag> <command>/usr/local/bin/wrapper.sh</command> <interval>10m</interval> </wodle>

包装脚本：

#!/bin/bash export CHECK_THRESHOLD=80 export CHECK_TYPE=disk /usr/local/bin/actual-check.sh

调试模式

在etc/local_internal_options.conf中开启详细日志（command 模块无专用调试内部选项，可通过wazuh_modules.debug等全局选项调整日志级别），然后观察日志：

tail -f /var/ossec/logs/ossec.log | grep "wazuh-modulesd:command"

延伸阅读

• Command Module 模块概述 — 模块整体介绍、事件格式与集中配置说明
• Log Collector 配置 — 备选方案：对简单命令输出可使用<localfile>+log_format=command
• 集中配置（Centralized Configuration） — 通过agent.conf下发 command wodle 的方法与安全开关
• Agent 配置参考 — Agent 全部配置项
• Manager 配置参考 — Manager 全部配置项

【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh