Wazuh 4.14.9 常用 CLI 命令详解
系统讲清 Wazuh 4.14.9 server 端 /var/ossec/bin 工具：wazuh-control/agent_control/manage_agents/agent_groups/wazuh-logtest 等逐条实测回显，manager REST API curl 认证、agent、统计、规则查询全流程，含 token 失效、agents_list 形态等实测排障。
Wazuh 4.14.9 常用 CLI 命令详解
目标：系统讲清 Wazuh 4.14.9 server（manager）端
/var/ossec/bin下常用命令行工具的用法——服务管理、agent 管理、注册密钥、规则排错、组管理，以及 manager REST API 的 curl 直调，每条命令配实测回显。全文在 Ubuntu 22.04 实测环境（manager v4.14.9 + agent 4.14.9-1）逐条执行验证。
一、环境信息
本文实测环境：
- 操作系统：Ubuntu 22.04 LTS（x86_64，内核 6.8）
- Wazuh 版本：manager v4.14.9（revision rc2，实测
/var/ossec/bin/wazuh-control info -v/info -r） - 部署方式：Docker Compose 三组件栈（部署过程见 《Wazuh 4.14.9 Docker Compose 部署指南》）；容器内
/var/ossec/bin工具集与系统包部署完全一致，裸机/系统包部署时在服务器本地直接执行下述命令即可，Compose 环境则在命令前加docker compose exec wazuh.manager - 已注册 agent：ID 001（wazuh-agent-host，Ubuntu 22.04，Active）
- API 账号：
wazuh-wui（Compose 栈内置，默认密码MyS3cr37P450r.*-）
二、前置条件
- manager 运行中：
/var/ossec/bin/wazuh-control status核心守护进程 running。 - 命令执行身份：容器内默认 root；系统包部署时工具位于
/var/ossec/bin，root 或 ossec 用户均可执行（读写 client.keys 的命令需 root）。 - REST API 直调需 manager 的 55000 端口可达（Compose 默认映射宿主 55000）。
- 网络检测常用 nc：
apt install -y netcat-openbsd（agent 主机上验证 1514/1515 连通性）。
三、工具总览
/var/ossec/bin 实测目录清单（28 个可执行，按用途归类）：
| 分类 | 工具 | 用途 |
|---|---|---|
| 服务管理 | wazuh-control | manager 总控：start/stop/restart/status/info |
| agent 管理 | agent_control | 远程查/管 agent（列表、详情、重启、AR） |
| agent 管理 | agent_groups | agent 组管理（建组、进组、查组） |
| agent 管理 | agent_upgrade | 远程升级 agent |
| 注册管理 | manage_agents | agent 注册/密钥（增删查导入） |
| 注册管理 | wazuh-authd | 注册服务守护进程（一般不手动跑） |
| 规则排错 | wazuh-logtest | 交互式规则测试（dev 调规则利器） |
| 规则排错 | wazuh-regex | OS_Regex 正则快速验证 |
| 规则排错 | wazuh-analysisd / wazuh-remoted / wazuh-syscheckd 等 | 各守护进程本体（启动报错时手动前台跑排错） |
| 数据/凭据 | wazuh-keystore | 读写内部凭据库（密码列簇） |
| 数据/凭据 | wazuh-db | agent 数据库维护（socket 客户端） |
| 数据/凭据 | clear_stats | 重置性能统计计数器 |
| 配置校验 | verify-agent-conf | 校验 shared agent.conf 语法 |
| 配置校验 | wazuh-apid | API 服务进程（-t 测配置） |
| 集群 | cluster_control | 集群节点状态查询 |
| 集成 | integrator（wazuh-integratord） | Slack/VirusTotal/PagerDuty 外发集成 |
| 其他 | wazuh-modulesd / wazuh-monitord / wazuh-execd / wazuh-maild | 各功能守护进程本体 |
查看版本三连（实测）：
/var/ossec/bin/wazuh-control info -v # 版本号
/var/ossec/bin/wazuh-control info -r # revision
v4.14.9
---
rc2
四、核心 CLI 分类详解
4.1 服务管理：wazuh-control
标准用法（实测 -h 输出）：
Usage: /var/ossec/bin/wazuh-control [-j] {start|stop|restart|status|info [-v -r -t]}
-j Use JSON output.
四个动作的实测回显：
/var/ossec/bin/wazuh-control status # 进程状态
/var/ossec/bin/wazuh-control restart # 全量重启引擎
status 实测回显（15 个守护进程逐行，not running 为功能未启用的正常现象）：
wazuh-clusterd not running...
wazuh-modulesd is running...
wazuh-monitord is running...
wazuh-logcollector is running...
wazuh-remoted is running...
wazuh-syscheckd is running...
wazuh-analysisd is running...
wazuh-maild not running...
wazuh-execd is running...
wazuh-db is running...
wazuh-authd is running...
wazuh-agentlessd not running...
wazuh-integratord not running...
wazuh-csyslogd not running...
wazuh-apid is running...
restart 实测回显（需要数秒，全部 daemon 起完返回）：
Completed.
-j 全局 JSON 开关（脚本化监控用，实测）：
/var/ossec/bin/wazuh-control -j status
{"error":0,"data":[{"daemon":"wazuh-clusterd","status":"stopped"},{"daemon":"wazuh-modulesd","status":"running"},{"daemon":"wazuh-monitord","status":"running"},{"daemon":"wazuh-logcollector","status":"running"},{"daemon":"wazuh-remoted","status":"running"},{"daemon":"wazuh-syscheckd","status":"running"},{"daemon":"wazuh-analysisd","status":"running"},{"daemon":"wazuh-maild","status":"stopped"},{"daemon":"wazuh-execd","status":"running"},{"daemon":"wazuh-db","status":"running"},{"daemon":"wazuh-authd","status":"running"},{"daemon":"wazuh-agentlessd","status":"stopped"},{"daemon":"wazuh-integratord","status":"stopped"},{"daemon":"wazuh-csyslogd","status":"stopped"},{"daemon":"wazuh-apid","status":"running"}]}
💡 技术拓展：
status里not running不等于故障——clusterd（集群默认关闭）、maild（邮件告警未配）、agentlessd/integratord/csyslogd（对应功能未启用）都是配置使然。排错时真正的判断标准是「running 的进程是否稳定」，用wazuh-control status前后对比，或盯/var/ossec/logs/ossec.log。
4.2 agent 管理：agent_control
标准用法（实测 -h）：
Wazuh agent_control: Control remote agents.
Available options:
-h This help message.
-l List available (active or not) agents.
-lc List active agents only.
-ln List disconnected agents only.
-i <id> Extracts information from an agent.
-R -a Restart all agents.
-R -u <id> Restart the specified agent.
-r -a Runs the integrity/rootkit checking on all agents now.
-r -u <id> Runs the integrity/rootkit checking on one agent now.
-s Changes the output to CSV (comma delimited).
-j Changes the output to JSON .
Available options for active response:
-b <ip> Blocks the specified ip address.
-f <ar> -a Used with -b, specifies which response to run. Apply AR on all agents.
-f <ar> -u <id> Used with -b, specifies which response to run. Apply AR on specified agent.
-L List available active responses.
列表与过滤（实测三种形态）：
/var/ossec/bin/agent_control -l # 全部
/var/ossec/bin/agent_control -lc # 仅 Active
/var/ossec/bin/agent_control -s -l # CSV 输出
Wazuh agent_control. List of available agents:
ID: 000, Name: wazuh.manager (server), IP: 127.0.0.1, Active/Local
ID: 001, Name: wazuh-agent-host, IP: any, Active
单 agent 详情（实测 -i 001，节选）：
/var/ossec/bin/agent_control -i 001
Agent ID: 001
Agent Name: wazuh-agent-host
IP address: any
Status: Active
Operating system: Ubuntu | 22.04.5 LTS | Jammy Jellyfish
Client version: Wazuh v4.14.9
Configuration Profile: ubuntu, ubuntu22, ubuntu22.04
...
Syscheck last started at: Tue Oct 20 03:08:22 2026
Syscheck last ended at: Tue Oct 20 03:08:23 2026
Rootcheck last started at: Tue Oct 20 03:08:22 2026
Rootcheck last ended at: Tue Oct 20 03:08:23 2026
（运维常用点：Syscheck last started/ended 直接核对 FIM 扫描窗口。）
远程触发扫描（实测安全，只令 agent 立即跑一轮 syscheck/rootcheck）：
/var/ossec/bin/agent_control -r -u 001
主动响应状态（实测 -L，默认模板未启用 AR 时列表为空）：
Wazuh agent_control. Available active responses:
手动封禁 IP（需先在 ossec.conf 启用 firewall-drop 响应，否则实测报错）：
/var/ossec/bin/agent_control -b 10.0.0.99 -f firewall-drop -u 001
⚠️
-b直接对目标 agent 执行封禁脚本，用前确认对应<active-response>已配置（配置方法见《Wazuh 4.14.9 配置参数详解》5.8 节），默认配置下该命令无效果。
4.3 注册管理：manage_agents
标准用法（实测 -h）：
Wazuh v4.14.9 - Wazuh Inc. (info@wazuh.com)
http://www.wazuh.com
manage_agents -[Vhlj] [-a <ip> -n <name>] [-F sec] [-e id] [-r id] [-i id] [-f file]
-V Version and license message.
-h This help message.
-j Use JSON output.
-l List available agents.
-L Disable agents limit.
-a <ip> Add new agent.
-n <name> Name for new agent.
-e <id> Extracts key for an agent (Manager only).
-r <id> Remove an agent (Manager only).
-i <key> Import authentication key (Agent only).
列表 / 添加 / 提取密钥 / 删除（实测四连，新 agent 名 test-agent-02）：
/var/ossec/bin/manage_agents -l
/var/ossec/bin/manage_agents -a any -n test-agent-02
/var/ossec/bin/manage_agents -e 002
/var/ossec/bin/manage_agents -r 002
添加实测回显（非交互 stdin 下自动确认）：
Confirm adding it?(y/n):
Agent added with ID 002.
提取密钥实测回显（key 是 base64 串，agent 侧 -i <key> 导入离线注册用）：
Agent 'test-agent-02' (002) key:
MDAxIHRlc3QtYWdlbnQtMDIgYW55IGE3N2UwYTNl...（实测样例已脱敏截断）
删除实测回显：
Confirm deleting it?(y/n):
Agent '002' removed.
排障实录：-a 有两种正确形态——交互式 -a（依次问 name/IP/确认）与非交互式 -a <ip> -n <name>。实测用 printf "name\nip\ny\n" | manage_agents -a 喂入时因 readline 缓冲行为可能解析失败直接打印 usage，改用 -a any -n <name> 参数形态最稳。自动化场景更推荐走 REST API（见 5.3）。
4.4 组管理：agent_groups 与配置校验：verify-agent-conf
agent_groups 用法（实测 --help）：-l 列组、-c 列组内配置文件、-a 建组/进组、-s 查 agent 所属组、-S 查同步状态、-r 移除，配合 -i <id>、-g <group>。
实测三连：
/var/ossec/bin/agent_groups -l
/var/ossec/bin/agent_groups -s -i 001
/var/ossec/bin/verify-agent-conf
Groups: [default]
The agent 'wazuh-agent-host' with ID '001' belongs to groups: default.
verify-agent-conf: Verifying [etc/shared/default/agent.conf]
verify-agent-conf: OK
（default 组是内置组，所有未分组 agent 自动归属；verify-agent-conf 校验各组 shared 的 agent.conf 语法，改完中心化配置必跑一次。）
wazuh-apid 的配置测试模式（实测，配置正确时静默、退出码 0）：
/var/ossec/bin/wazuh-apid -t; echo "exit=$?"
exit=0
4.5 规则排错：wazuh-logtest 与 wazuh-regex
wazuh-logtest 是规则开发的排错主力：把任意一行日志喂给运行中的 analysisd，实时回显 pre-decoding → decoding → rule matching 三阶段结果。用法（实测 -h）：-V 版本、-d 调试、-U rule:alert:decoder 指定期望命中的直接测试、-l location 指定事件位置、-q 静默。交互式会话里逐行输入日志、用 Ctrl+C 退出（注意：输入字母 q 会被当作日志处理，实测 Phase 1/2 对 'q' 走了解码流程）。
实测会话（喂入 sshd 失败日志）：
/var/ossec/bin/wazuh-logtest
Oct 20 11:25:01 wazuh-agent-host sshd[12346]: Failed password for admin from 10.0.0.99 port 51235 ssh2
实测输出（三阶段全量）：
Starting wazuh-logtest v4.14.9 (rc2)
Type one log per line
**Phase 1: Completed pre-decoding.
full event: 'Oct 20 11:25:01 wazuh-agent-host sshd[12346]: Failed password for admin from 10.0.0.99 port 51235 ssh2'
timestamp: 'Oct 20 11:25:01'
program_name: 'sshd'
hostname: 'wazuh-agent-host'
**Phase 2: Completed decoding.
name: 'sshd'
parent: 'sshd'
dstuser: 'admin'
srcip: '10.0.0.99'
srcport: '51235'
**Phase 3: Completed filtering (rules).
id: '5760'
level: '5'
description: 'sshd: authentication failed.'
groups: '['"'"'sshd'"'"', '"'"'authentication_failed'"'"']'
firedtimes: '1'
mail: 'False'
（Phase 2 的 srcip/dstuser 由 sshd 解码器抽出；Phase 3 命中 5760。改了规则后必须重启 manager，logtest 才会加载新规则集——实测详见配置篇 5.10。）
wazuh-regex 验证 OS_Regex 语法（规则里 <match>/<regex> 用同一套语法）：
echo "test line with 12345 number" | /var/ossec/bin/wazuh-regex "\d+"
实测回显（+ 前缀行是匹配命中后的回显）：
+OSRegex_Execute: test line with 12345 number
+OS_Regex : test line with 12345 number
4.6 其他工具速查
| 命令 | 实测说明 |
|---|---|
| wazuh-keystore | 内部凭据库读写（-f <列簇> -k <键> 查值，API 密码等加密存储） |
| wazuh-db | agent 元数据/摘要数据库的底层维护客户端，日常排障少用 |
| clear_stats | 重置 manager 性能统计计数器（GET /manager/stats 前清零基线） |
| cluster_control | 集群节点查询；单机（cluster disabled）实测返回 ERROR: Cluster is not running. |
| agent_upgrade | 远程升级 agent 版本（-a <id> -v <version>，配合 API 走升级通道） |
| wazuh-authd | 注册服务本体；前台调试跑 -d 看注册握手细节 |
| integrator | Slack/VirusTotal 等外发集成的调度器，配置启用后 status 才会 running |
| wazuh-monitord / wazuh-execd 等 | 守护进程本体；怀疑某进程异常时用 <binary> -d 前台跑直接看输出 |
五、manager REST API（curl 逐条实测）
API 默认监听 55000，自签 HTTPS。所有 GET/PUT/POST 均需 Bearer token（约 900 秒有效期，过期重取；manager 重启后旧 token 立即失效——实测拿到过 {"title":"Unauthorized","detail":"Invalid token"}）。
5.1 认证与调用骨架
TOKEN=$(curl -s -u wazuh-wui:MyS3cr37P450r.*- -k -X POST "https://localhost:55000/security/user/authenticate" | python3 -c 'import json,sys;print(json.load(sys.stdin)["data"]["token"])')
echo ${#TOKEN}
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/<端点>"
实测回显（JWT token 长度）：
404
5.2 agent 相关端点
# agent 列表（分页/过滤）
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/agents?pretty=true&limit=5"
# 单 agent 详情（注意参数形态）
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/agents?agents_list=001&pretty=true"
# 状态汇总
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/agents/summary/status?pretty=true"
GET /agents 实测回显（节选，含 000 与 001）：
{
"data": {
"affected_items": [
{
"os": { "name": "Amazon Linux", "platform": "amzn", ... },
"name": "wazuh.manager",
"version": "Wazuh v4.14.9",
"status": "active",
"id": "000",
"manager": "wazuh.manager"
},
{
"os": { "name": "Ubuntu", "version": "22.04.5 LTS", ... },
"id": "001",
"name": "wazuh-agent-host",
"ip": "10.89.60.5",
"status": "active",
...
}
],
...
}
}
GET /agents/summary/status 实测回显（全文）：
{
"data": {
"connection": {
"active": 1,
"disconnected": 0,
"never_connected": 0,
"pending": 0,
"total": 1
},
"configuration": {
"synced": 1,
"not_synced": 0,
"total": 1
}
},
"error": 0
}
⚠️ 单 agent 详情的正确形态是
GET /agents?agents_list=001。实测GET /agents/001（路径拼接形态）返回 404——这是 4.x REST 约定与直觉不同的一处。
5.3 注册/删除 agent（API 方式）
# 注册新 agent（等价 manage_agents -a）
curl -s -k -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"api-agent","ip":"any"}' "https://localhost:55000/agents?pretty=true"
# 彻底删除（purge 清 client.keys 记录）
curl -s -k -X DELETE -H "Authorization: Bearer $TOKEN" "https://localhost:55000/agents?agents_list=002&purge=true&pretty=true"
（删除实测见 4.3 的 manage_agents 部分；API 注册回显里 data.affected_items[].id 即新 agent ID，后续 agent_control -i <id> 或 GET /agents?agents_list=<id> 核对。）
5.4 manager 状态、统计与配置
# 进程状态
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/manager/status?pretty=true"
# manager 元信息
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/manager/info?pretty=true"
# analysisd 统计
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/manager/stats/analysisd?pretty=true"
# 读运行中配置（global 段）
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/manager/configuration?section=global&pretty=true"
GET /manager/status 实测回显（节选）：
{
"data": {
"affected_items": [
{
"wazuh-clusterd": "stopped",
"wazuh-modulesd": "running",
"wazuh-remoted": "running",
"wazuh-analysisd": "running",
"wazuh-apid": "running",
...
}
],
"total_affected_items": 1
},
"error": 0
}
GET /manager/info 实测回显（节选）：
"path": "/var/ossec",
"type": "server",
"version": "v4.14.9",
"max_agents": "unlimited",
GET /manager/stats/analysisd 实测回显（节选，事件吞吐与规则命中统计）：
"events": {
"processed": 1938,
"received_breakdown": { "syscheck": 45, "syslog": 6, "others": 1887 },
"decoded_breakdown": { ... }
},
"alerts": {
"alerts_size": 31,
"size": 31
}
GET /manager/configuration?section=global 实测回显（节选——注意 logall: yes 是实测环境为验证而开启的，生产应 no）：
"global": {
"jsonout_output": "yes",
"alerts_log": "yes",
"logall": "yes",
"logall_json": "yes",
"email_notification": "no",
...
"agents_disconnection_time": "10m",
5.5 规则、解码器与 SCA 查询
# 规则/解码器总量
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/rules?limit=1&pretty=true" | grep total_affected_items
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/decoders?limit=1&pretty=true" | grep total_affected_items
# CDB 列表
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/lists?pretty=true&limit=5"
# agent 的 SCA 扫描结果
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/sca/001?pretty=true"
实测回显（规则 4514 条 / 解码器 1576 个）：
"total_affected_items": 4514
"total_affected_items": 1576
GET /lists 实测回显（节选）：
"items": [ "audit-keys", "amazon/aws-s3-events", "security-eventchannel", ... ],
GET /sca/001 实测回显（节选，Ubuntu 22.04 agent 首扫）：
"name": "CIS Ubuntu Linux 22.04 LTS Benchmark v2.0.0.",
"pass": 78, "fail": 80, "invalid": 49, "total_checks": 207, "score": 49
六、生产配置模板
日常运维的组合拳（按场景记忆）：
# ① 晨检三连：引擎健康 / agent 掉线核对 / 告警尾行
/var/ossec/bin/wazuh-control status
/var/ossec/bin/agent_control -ln
tail -5 /var/ossec/logs/alerts/alerts.json
# ② 改规则/解码器后的验证闭环
/var/ossec/bin/wazuh-control restart # 或 docker compose up -d --force-recreate wazuh.manager
grep -iE "duplicat|error" /var/ossec/logs/ossec.log | tail -3
/var/ossec/bin/wazuh-logtest # 喂真实日志验证新规则
# ③ 新 agent 上线四连（agent 主机）
nc -zv <manager-ip> 1515 && nc -zv <manager-ip> 1514 # 连通性
# 安装与注册（部署篇 4.6 节）
/var/ossec/bin/agent_control -l # 状态翻转 Active
/var/ossec/bin/agent_control -i 001 # 核对 OS/版本/扫描窗口
# ④ agent 批量运维（组下发）
/var/ossec/bin/agent_groups -a -g web-prod -i 002 -q # 加入组
/var/ossec/bin/verify-agent-conf # 校验组配置
/var/ossec/bin/agent_control -r -u 002 # 立即触发扫描
# ⑤ API 批处理（token 复用，90 秒内连发）
curl -s -k -H "Authorization: Bearer $TOKEN" "https://localhost:55000/agents/summary/status"
七、常见问题
Q1：wazuh-control restart 卡住或报错？
restart 依次重启全部守护进程，正常数秒完成并输出 Completed.（实测）。若卡住，看 /var/ossec/logs/ossec.log 尾部——最常见是 ossec.conf/ruleset XML 语法错误导致 analysisd 起不来；把对应进程前台跑（如 /var/ossec/bin/wazuh-analysisd -d）能直接看到解析错误行。
Q2：agent_control -l 里 agent 状态不对怎么判断网络还是服务问题？
Never connected=1515/1514 不通（nc 验证，部署篇 FAQ Q4）；disconnected=keepalive 断（agent 进程挂了或 notify_time/掉线阈值联动配置问题，配置篇 5.13）；Active 但无告警=采集/规则问题（logtest 复现，配置篇 Q4）。
Q3：manage_agents 添加报 Invalid agent name 或超限？
agent 名只允许字母数字与连字符/下划线等安全字符；默认有 agent 总数上限（API 实测 max_agents: unlimited 为无限制，但老配置可能设置限额，超限报错时核对 ossec.conf <global> 段与授权）。
Q4：API 一直 401？
三个原因按序排查：账号密码错（Compose 部署核对 API_PASSWORD）；token 过期（重取，实测 900 秒有效期）；manager 重启过（旧 token 全失效，实测拿到 Invalid token）。取 token 本身 401 则是 security/user/authenticate 的 basic auth 凭据问题。
Q5：GET /agents/001 为什么 404？
4.x 的 REST 约定用查询参数形态：GET /agents?agents_list=001（实测路径形态返回 404，见 5.2 注记）。类似地删除/分组操作都用 agents_list 参数。
Q6：logtest 里按 q 退不出？
wazuh-logtest 的交互输入就是「日志行」，字母 q 会被当作日志解码（实测 Phase 1/2 走了 'q' 的流程）；退出用 Ctrl+C，或改用 -q 静默模式从管道喂数据。
八、参考链接
- Wazuh API 官方参考：https://documentation.wazuh.com/current/user-manual/api/reference.html
- wazuh-control 手册：https://documentation.wazuh.com/current/user-manual/reference/tools/wazuh-control.html
- agent_control 手册：https://documentation.wazuh.com/current/user-manual/reference/tools/agent-control.html
- manage_agents 手册：https://documentation.wazuh.com/current/user-manual/reference/tools/manage-agents.html
- wazuh-logtest 手册：https://documentation.wazuh.com/current/user-manual/reference/tools/wazuh-logtest.html
- agent_groups 手册：https://documentation.wazuh.com/current/user-manual/reference/tools/agent-groups.html
- 本平台配置篇：《Wazuh 4.14.9 配置参数详解》
- 本平台部署篇：《Wazuh 4.14.9 Docker Compose 部署指南》