Skip to content

fix: 为媒体服务器 hook 回调增加可选校验密钥,避免伪造回调 (#2238) - #2243

Open
CieveMe wants to merge 4 commits into
648540858:masterfrom
CieveMe:fix/2238-hook-secret-auth
Open

CieveMe wants to merge 4 commits into
648540858:masterfrom
CieveMe:fix/2238-hook-secret-auth

Conversation

@CieveMe

@CieveMe CieveMe commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

关联议题:#2238

问题

/index/hook/** 在安全配置里是免认证的(WebSecurityConfig 的 defaultExcludes),任何人都可以伪造媒体服务器的回调。其中 on_record_mp4 会把请求体里的文件路径原样写入 wvp_cloud_record,之后读取侧按库内路径取文件 —— 回调来源不可信是这条链的起点。

根因

媒体服务器(ZLMediaKit)的 hook 请求不带任何凭据:server/WebHook.cpp 只往 body 里加 mediaServerId / hook_index,然后 POST 到配置里的 URL;官方 conf/config.ini 的 [hook] 段也没有 secret 项。wvp 本来就通过 setServerConfig 把自己拼好的 hook URL 下发给媒体服务器,所以要在 URL 上带一个校验值,成本最低且不需要改媒体服务器。

改动范围

  1. UserSetting 新增 hookSecret(user-settings.hook-secret,默认空字符串)。
  2. 下发 hook 配置时,配置了 hookSecret 就往 hook URL 追加 ?secret=xxx:
    • ZLMMediaServerStatusManager(10 个 hook.on_*)
    • ABLMediaServerStatusManger
  3. 新增 HookSecretFilter:hookSecret 为空时不做任何处理;配置后,/index/hook(及 /index/hook/ 前缀)的请求必须携带同一个 secret,否则返回 401。比较使用常量时间实现,过滤器显式排序在 Spring Security 之前。
  4. 配置说明同步到 src/main/resources/配置详情.yml,docker 部署给了注释示例。

改动文件(6 files / +126 −11):

文件 改动
conf/UserSetting.java 新增 hookSecret
conf/security/HookSecretFilter.java(新增) 校验 /index/hook/** 的 secret
media/zlm/ZLMMediaServerStatusManager.java hook URL 追加 ?secret=
media/abl/ABLMediaServerStatusManger.java 同上
src/main/resources/配置详情.yml 配置项说明
docker/wvp/wvp/application-docker.yml 注释示例

本 PR 选择的方案:A + 放行(保持向后兼容)

密钥来源(横向)与"密钥未配置时如何处理"(纵向)可以组合成四格,本 PR 实现的是 (1) A + 放行;其余三格如果需要,可以快速切换(两个变体补丁已经写好,见文末):

A:独立 user-settings.hook-secret B2:复用 media_server.secret(ZLM 的 API 密钥)
未配置 → 放行 (1) ← 本 PR
改动:新增配置 + 两处 URL 追加 + 过滤器空值放行。
兼容:未配置时行为与今天完全一致;配置后需媒体服务器重新下发一次 hook(在下发前会被 401)。
凭据卫生:好(hook 专用密钥,泄露也调不动 ZLM 的 API)。
升级:加 user-settings.hook-secret(或 USER_SETTINGS_HOOKSECRET)→ 重启 → 重启/重新注册媒体服务器。
(2)
改动:下发改用媒体服务器自己的 secret;过滤器改为"匹配任一已注册媒体服务器的 secret";不新增配置。
兼容:有 secret 的部署默认生效;没有 secret 的部署等于没开——"看起来开了、其实没开"。
凭据卫生:差(见下)。
未配置 → 拒绝 (3)
改动:仅把过滤器空值分支反转(未配置即 401,只告警一次)。
兼容:破坏性——未配置的部署升级后所有 hook 断链(录像完成事件写不进 wvp_cloud_record、设备状态/心跳回调失效),必须先配置再升级。
凭据卫生:好。
(4)
改动:B2 的下发 + 过滤器语义,且未配置/匹配不上时拒绝。
兼容:最严格且默认开启,影响面比 (3) 更大。
凭据卫生:差(同 B2)。

关于 B2 的凭据卫生(必须说明,避免只看到"零配置"的优点):复用 media_server.secret 会把调用媒体服务器 HTTP API 的密钥放进 hook URL;ZLM 在 hook 失败时会把完整 URL + body 打进自己的日志(server/WebHook.cpp:202,本地核实)。日志一旦被采集/转发/贴出,就等于泄漏 API 密钥。A 用的是独立密钥,即使泄漏也调不动 ZLM 的 API。

如果维护者选 (2)/(3)/(4),我可以马上换分支:fix/2238-hook-secret-b2(B2)与 fix/2238-hook-secret-deny(未配置即拒绝)都已实现并编译通过,patch 见 raw/2238/hook-secret-b2.patch、raw/2238/hook-secret-deny.patch。

验证方式

  1. 编译:JDK 21 下 mvn -DskipTests -q compile → exit 0。
  2. 静态核对:
    • 过滤器是 @Component + @Order(Ordered.HIGHEST_PRECEDENCE + 100),会排在 Spring Security 之前;/index/hook/** 在 WebSecurityConfig 里是 permitAll,不会短路过滤器链。
    • 仓库里 hook 地址下发点只有两处(ZLM、ABL),都已覆盖;接收侧只有 ZLMHttpHookListener 与 ABLHttpHookListener,过滤器按 /index/hook 前缀统一覆盖。
    • UserSetting 是 @ConfigurationProperties,密钥只来自配置文件/环境变量,不落库,因此本次改动不需要数据库迁移。

未验证项

  • 未做端到端验证:本机没有可运行的 wvp + ZLM/ABL 环境。需要在真实环境确认:
    1. 不配置 hook-secret 时,不带 secret 的 hook 请求与改动前一致(正常返回);
    2. 配置 hook-secret: testSecret 并重启后:不带 secret 的 /index/hook/on_server_keepalive → 401;带 ?secret=testSecret → 正常返回;
    3. 媒体服务器重新下发配置后,录像完成事件仍能正常写入 wvp_cloud_record。
  • ABL 未验证:只做了与 ZLM 相同的 URL 拼接与编译验证,未在真实 ABL 环境做端到端验收。
  • 未评估"读取侧对库内路径再做一次校验"(读侧只兜一个读取点,挡不住污染本身,建议单独讨论)。

兼容性提示

手工在媒体服务器上直接配过 hook URL(而不是由 wvp 下发)的部署,需要重新下发一次配置才会带上 secret;在重新下发之前,该媒体服务器的 hook 会被 401 拒绝。这是"安全优先"的代价,也是本 PR 选择"未配置即放行"默认值的原因。

可复现命令块(静态核对)

# 1) 编译(JDK 21)
mvn -DskipTests -q compile
# 预期: exit 0

# 2) 过滤器顺序与匹配路径
grep -n "@Order\|HOOK_PATH_PREFIX" src/main/java/com/genersoft/iot/vmp/conf/security/HookSecretFilter.java
# 预期: @Order(Ordered.HIGHEST_PRECEDENCE + 100) 与 HOOK_PATH_PREFIX = "/index/hook"

# 3) hook 路径在安全配置里的现状(permitAll 不会短路过滤器链)
grep -n 'defaultExcludes.add("/index/hook' src/main/java/com/genersoft/iot/vmp/conf/security/WebSecurityConfig.java
# 预期: 命中 /index/hook/** 与 /index/hook/abl/**

# 4) hook URL 下发点(应当只有两处)
grep -rn "getHookSecret()" src/main/java/com/genersoft/iot/vmp/media/
# 预期: 只命中 zlm/ZLMMediaServerStatusManager.java 与 abl/ABLMediaServerStatusManger.java

# 5) 是否需要数据库迁移
grep -rn "hook_secret\|hookSecret\|user_settings\|user-settings\|hook-secret" 数据库/2.7.4/初始化-mysql-2.7.4.sql 数据库/2.7.4-h2/h2-schema.sql
# 预期: 无输出 —— 没有 hook 密钥相关的表/列,密钥只来自配置文件/环境变量 ⇒ 不需要 DDL 迁移

@vercel

vercel Bot commented Sep 26, 2026

Copy link
Copy Markdown

@CieveMe is attempting to deploy a commit to the 648540858's projects Team on Vercel.

A member of the Team first needs to authorize it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant