docker-wazuh-agent 中文技术文档

镜像概述与主要用途

Wazuh 是一款免费、开源且企业级的安全监控解决方案，提供威胁检测、完整性监控、事件响应和合规性检查功能。docker-wazuh-agent 是封装了 Wazuh Agent 的 Docker 镜像，内置自动注册功能，可无缝集成 Wazuh 服务器。该镜像设计灵活，既支持作为独立 Docker 容器运行，也可部署为 Kubernetes DaemonSet，适用于各类环境的安全监控需求。

核心功能与特性

核心功能

1. 容器化部署
   Wazuh Agent 被封装为 Docker 镜像，提升跨环境的可移植性和部署便捷性。

2. 自动注册机制
   支持与 Wazuh 服务器自动注册，简化部署流程，无需手动配置。

3. 多环境兼容

   • 独立部署：可作为 standalone 容器运行，适用于无编排工具的环境。
   • Kubernetes 集成：支持部署为 Kubernetes DaemonSet，在集群节点间自动扩展，实现全节点安全覆盖。

使用场景与适用范围

• 独立 Docker 环境：需对单机或小规模 Docker 部署进行安全监控的场景。
• Kubernetes 集群：需对集群内所有节点进行统一安全监控的场景，通过 DaemonSet 确保每个节点均部署 Agent。
• 自动化运维环境：需减少手动配置步骤，通过自动注册实现 Agent 快速接入 Wazuh 服务器的场景。

版本信息

DockerHub 镜像

配置参数说明

环境变量

使用方法

Docker 独立运行

简单运行（需提前配置环境变量）

docker run --rm opennix/wazuh-agent:latest

高级用法（指定环境变量和挂载卷）

docker run -d --name wazuh-agent \
  -v /:/rootfs:ro \  # 只读挂载主机根目录，用于完整性监控
  --net host \       # 使用主机网络，确保 Agent 能与服务器通信
  --hostname ${HOSTNAME} \  # 设置容器主机名
  -e JOIN_MANAGER_MASTER_HOST=172.17.0.1 \  # Wazuh 主服务器 IP
  -e JOIN_MANAGER_WORKER_HOST=172.17.0.1 \  # Wazuh 工作节点 IP
  -e JOIN_MANAGER_USER=api-user \           # Wazuh API 用户名
  -e JOIN_MANAGER_PASSWORD=api-pass \       # Wazuh API 密码
  -v /etc/os-release:/etc/os-release \      # 挂载主机 OS 信息
  -v /var/run/docker.sock:/var/run/docker.sock \  # 监控 Docker 容器
  opennix/wazuh-agent:latest

docker-compose 部署

生成证书（单节点环境）

docker compose -f tests/single-node/generate-indexer-certs.yml run --rm generator

启动服务（包含 Wazuh 服务器和 3 个 Agent）

docker compose up -d

使用 Makefile

Makefile 提供快捷命令，支持构建、运行、推送镜像等操作：

make help                           # 查看命令帮助
make build-minideb                  # 构建基于 Minideb 的 Agent 镜像
make build-amazon-linux             # 构建基于 Amazon Linux 的 Agent 镜像
make build-ubuntu                   # 构建基于 Ubuntu 的 Agent 镜像
make docker-run                     # 运行 Minideb 版本的 Agent 容器
make docker-push-minideb            # 推送 Minideb 镜像到仓库
make docker-push-amazon-linux       # 推送 Amazon Linux 镜像到仓库
make docker-push-ubuntu             # 推送 Ubuntu 镜像到仓库
make run-local                      # 启动包含所有 Agent 类型的本地 Docker Compose 栈

Kubernetes DaemonSet 部署

配置环境变量

在 wazuh-daemon-sets.yaml 中设置环境变量，示例：

env:
  - name: JOIN_MANAGER_MASTER_HOST
    value: "wazuh.wazuh.svc.cluster.local"  # Wazuh 服务器集群内域名
  - name: JOIN_MANAGER_WORKER_HOST
    value: "wazuh-workers.wazuh.svc.cluster.local"  # Wazuh 工作节点域名
  - name: JOIN_MANAGER_PROTOCOL
    value: "https"
  - name: NODE_NAME
    valueFrom:
      fieldRef:
        fieldPath: spec.nodeName  # 自动获取节点名称
  - name: JOIN_MANAGER_USER
    valueFrom:
      secretKeyRef:
        name: wazuh-api-cred  # 从 Secret 获取 API 用户名
        key: username
  - name: JOIN_MANAGER_PASSWORD
    valueFrom:
      secretKeyRef:
        name: wazuh-api-cred  # 从 Secret 获取 API 密码
        key: password
  - name: JOIN_MANAGER_API_PORT
    value: "55000"
  - name: JOIN_MANAGER_PORT
    value: "1514"

应用 DaemonSet

kubectl apply -f wazuh-daemon-sets.yaml  # 部署到 wazuh 命名空间

本地构建镜像

基于默认基础镜像（Minideb）

默认构建 Wazuh Agent v4.3.10-1：

docker build . -t wazuh-agent:latest

基于其他基础镜像

• Amazon Linux：

  docker build -f images/Dockerfile.amazonlinux . -t wazuh-agent:amazonlinux
  

• Ubuntu 24.04：

  docker build -f images/Dockerfile.ubuntu . -t wazuh-agent:ubuntu
  

自定义 Agent 版本

通过 --build-arg AGENT_VERSION 指定版本，例如构建 v4.4.5-1：

docker build . -t wazuh-agent:4.4.5 --build-arg AGENT_VERSION=4.4.5-1

注意事项

• 详细配置选项和自定义方法请参考 Wazuh 官方文档。
• 生产环境中建议通过 Kubernetes Secret 或 Docker 环境变量文件管理敏感信息（如 API 密码）。
• 挂载主机目录时需确保只读权限（:ro），避免 Agent 对主机系统造成意外修改。

免责声明

本软件由版权持有人及贡献者按"原样"提供，不承担任何明示或暗示的担保，包括但不限于适销性和特定用途适用性的暗示担保。在任何情况下，版权持有人或贡献者均不对任何直接、间接、偶然、特殊、惩戒性或后果性损害（包括但不限于替代商品或服务的采购；使用、数据或利润损失；或业务中断）承担责任，无论其原因如何，也无论责任理论如何（合同、严格责任或侵权（包括疏忽或其他）），即使已被告知此类损害的可能性。