企业官网建设流程全解析

Wazuh 如何用 wpkpack 打包 WPK 供代理远程升级使用？

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

当 Manager 无法访问官方 WPK 仓库（packages.wazuh.com/<major>.x/wpk/），或需要用自签证书发布私有升级包时，就要自己构建 WPK（Wazuh Package Kit）文件。Wazuh 仓库的 packages/wpk 目录提供了完整的构建工具链：generate_wpk_package.sh作为总入口，在容器内调用wpkpack工具，把指定平台的安装包（rpm/deb/apk/msi/pkg）连同升级脚本合并、压缩并用 WPK 证书签名，产出可供 Manager 通过upgrade_custom接口推送到 Agent 的 WPK 文件。

打包前需要理解 WPK 的内部结构

wpkpack.py是真正执行打包的工具，用法为：

wpkpack <pack> <cert> <key> <content> [ <content> ... ]

它的处理流程在 wpkpack.py 中可以看到：先把所有<content>合并成一个带!<size> <path>条目的清单文件，用 gzip 压缩，然后签名——签名文件以WPK256\0魔数开头，依次写入证书内容、RSA（PKCS1v15 + SHA256）签名，最后是压缩后的包体。签名用的证书与私钥分别对应cert和key两个参数。

run.sh（容器内执行的驱动脚本）按平台扩展名决定往 WPK 里打进哪些文件：

这些升级脚本随容器从 Wazuh 仓库指定分支拉取的 tarball 中复制，因此-b参数指定的分支/标签必须与你正在构建的 Agent 版本对应。

准备条件

1. Docker 环境：generate_wpk_package.sh通过构建并运行名为common_wpk_builder的镜像完成打包，镜像定义在 common/Dockerfile（基于 debian:9，安装 git、curl、jq、awscli 和 Python cryptography）。

2. 已构建好的平台安装包：路径形如wazuh_agent_x.x.x.deb/.rpm/.apk/.msi/.pkg，run.sh按后缀判断平台，非这五种后缀会直接报错ERROR: missing package file.。

3. WPK 签名密钥，二选一：

   • 本地密钥目录（-k）：脚本会把该目录挂载到容器的/etc/wazuh。run.sh固定读取容器内${KEYPATH}/wpkcert.pem（证书）和${KEYPATH}/wpkcert.key（私钥），所以本地目录里必须提供这两个文件名的密钥对；
   • AWS Secrets Manager（--aws-wpk-key+--aws-wpk-cert）：容器内用 awscli 拉取密钥写入同样位置。此路径需要宿主机环境变量AWS_ACCESS_KEY_ID与AWS_SECRET_ACCESS_KEY已设置，脚本会把它们传入容器。

   两者都不提供时脚本会报ERROR: Option -k or -wk, -wc must be set.并退出，这是硬性要求。

4. Git 分支或标签名：用于容器内下载对应版本的仓库 tarball 以取得升级脚本。

执行打包

在 packages/wpk 目录下运行总入口脚本：

./generate_wpk_package.sh \ -t linux \ -b <git分支或标签> \ -d ./output \ -pn /path/to/wazuh_agent_x.x.x.deb \ -o wazuh_agent_vX.x.x_linux.wpk \ -k /path/to/keydir \ -c

各参数含义（完整清单见 generate_wpk_package.sh 的--help）：

脚本的实际动作分三步（见脚本内build_container与pack_wpk函数）：先把run.sh和wpkpack.py复制到common/构建目录并docker build出common_wpk_builder镜像；再docker run挂载输出目录、包文件目录和密钥目录执行容器内流程；最后执行clean函数删除刚才复制到common/目录的run.sh、wpkpack.py——注意这个清理会rm -f掉构建目录中的脚本副本，中断（Ctrl-C）时也会触发同样的清理，属于脚本自身行为。

如果构建机有权限访问 AWS Secrets Manager，可以把-k换成：

--aws-wpk-key <secret名称或ARN> \ --aws-wpk-cert <secret名称或ARN> \ --aws-wpk-key-region <region>

验证打包结果

• 容器结束时run.sh会打印PACKED FILE -> /var/local/wazuh/<输出名>，对应宿主机输出目录中的.wpk文件即产物。
• 加了-c时，输出目录中还会生成<输出名>.sha512校验文件。
• 产物应命名为规范格式wazuh_agent_v<VERSION>_<rest>.wpk（例如wazuh_agent_v5.0.0_linux_x86_64.wpk）。远程升级迁移指南 说明：对符合该命名规范的 WPK，agent_upgrade模块会在 Manager 侧执行版本校验；文件名不符合规范时跳过 Manager 侧版本检查，改由 Agent 侧预安装脚本拦截不兼容版本。

将 WPK 投入使用：触发自定义远程升级

构建好的 WPK 要放到Manager上，集群部署时需保证所有集群节点都能访问该文件。Agent Upgrade 配置参考 指出 Manager 下载的 WPK 缓存在/var/wazuh-manager/var/upgrade/，自定义 WPK 一般也放置于此。

方式一：API

curl -k -X PUT "https://localhost:55000/agents/upgrade_custom?pretty=true&agents_list=002&file_path=/var/wazuh-manager/var/upgrade/wazuh_agent_v5.0.0_linux_x86_64.wpk&installer=upgrade.sh" \ -H "Authorization: Bearer $TOKEN"

其中file_path是 WPK 在 Manager 上的路径，installer指定 WPK 内的安装脚本（Linux/macOS 用upgrade.sh，Windows 用upgrade.bat）。

方式二：命令行二进制（会阻塞直到升级完成并直接打印结果）

/var/wazuh-manager/bin/agent_upgrade -a 001 -f /var/wazuh-manager/var/upgrade/wazuh_agent_v5.0.0_linux_x86_64.wpk -x upgrade.sh

升级结果验证

按迁移指南的验证清单逐项确认：

# 查询每个代理的升级结果，期望 "status": "Updated" curl -k -X GET "https://localhost:55000/agents/upgrade_result?pretty=true&agents_list=002" \ -H "Authorization: Bearer $TOKEN"

• GET /agents/<id>返回的版本与目标版本一致；
• 代理连接状态为active；
• 代理侧日志无升级相关报错：grep -i "upgrade" /var/ossec/logs/ossec.log。

WPK 传输过程中，Manager 会依次向代理发送lock_restart、open wb、write（默认 32 KB 分块）、close、sha1校验、upgrade执行安装六条命令（见 Agent Upgrade 模块说明）。若通道中断，模块会报告Send lock restart error、Send write file error、Send verify sha1 error等具体错误。

自签 WPK 与代理侧签名验证的配套要求

wpkpack产物的签名由你提供的wpkcert.pem/wpkcert.key决定，而 Agent 侧默认开启 WPK 签名验证：

<agent-upgrade> <enabled>yes</enabled> <ca_verification>yes</ca_verification> <ca_store>/etc/ssl/certs/ca1.pem</ca_store> </agent-upgrade>

ca_verification默认为yes，关闭它允许安装未验证签名的包（文档明确不推荐）。用自建 CA 签发的 WPK 升级代理时，需要在每个接收升级的 Agent 的ossec.conf中通过可重复的ca_store子项提供你的 CA 证书路径，否则签名验证无法通过。

边界与限制

• 目标平台：-t只接受linux/windows/macos；包类型必须是 rpm、deb、apk、msi、pkg 之一，否则容器内脚本直接报错退出。
• 版本约束（Manager 侧强制）：低于 v3.0.0 的代理被拒绝；从 v4.14.0 以下直接远程升级到 v5.0.0+ 会被拦截（错误信息Direct upgrade to v5.0.0 is not supported. Please upgrade to v4.14.x first），force参数无法绕过该限制，必须先升级到 v4.14.x。
• 5.x 网络前提：5.x 代理只走 TCP 1514 端口回连 Manager。升级前需在代理主机放通到 Manager 1514 的出站 TCP（升级传输本身可走代理现有的 4.x 通道，甚至 UDP），否则代理升级重启后无法重连、显示为disconnected。
• -b与目标版本一致性：容器内按该分支拉取仓库 tarball 复制升级脚本，分支/标签应与所打包 Agent 的版本对应，脚本本身不校验这一点。

构建完成后，产物就是一个可被 Manager 分发、经代理侧签名与 SHA1 双重验证的升级包，按上文upgrade_custom路径即可纳入常规的远程升级流程。

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