UUSEC WAF 7.2.6 管理 API 使用详解

目标：系统讲解 UUSEC WAF（南墙）v7.2.6 管理 REST API 的认证方式与各资源域（用户/站点/证书/规则/规则集/系统设置/仪表盘日志）的调用方法，全部请求与响应均为 7.2.6 实测照抄。 选型说明：本组件官方命令行面为 manager.sh 六项菜单（启动/停止/重启/升级/修复/卸载，见 《UUSEC WAF Docker Compose 部署指南》）与 docker compose 命令，功能覆盖生命周期但不触达业务资源；站点、证书、规则等业务管理由 Web 管理台承载，其背后即本篇的管理 REST API（官方 FAQ 明确提供 Api-Token 调用方式），自动化运维按本篇 API 实施。

一、环境信息

• 实验主机：Ubuntu 22.04.4 LTS，x86_64；UUSEC WAF 7.2.6（官方 compose 形态，管理台默认 https://<IP>:4443）
• 客户端工具：curl 7.81+（curl -k 跳过管理台自签名证书校验）、python3（JSON 解析）
• 演示数据：站点 wafdemo.example.com（源站 127.0.0.1:8139，部署篇建立）、管理员 admin
• 敏感值口径：$TOKEN（登录 JWT）与 $API_TOKEN（长效令牌）用变量承载，读取方式见第三章，避免文档落盘密钥
• 版本基线：API 前缀 /api/v1，响应实测均无统一外层信封（资源直返 JSON，逻辑错误以 {"err":"..."} 返回）

二、前置条件

1. UUSEC WAF 已部署且管理台可访问（部署见 《UUSEC WAF Docker Compose 部署指南》；管理台端口/证书说明同）；
2. 具备管理员账号（默认 admin，首次登录后已改密）；
3. 熟悉 curl 与基础 JSON；API 全部走 HTTPS（4443），自签名证书场景统一加 -k；
4. 若以脚本长期调用，建议为脚本单独建立低权限管理员并开启 TOTP 之外的独立令牌管理（api_token 更换行为见第七章 Q2）。

三、API 总览

• 协议与版本：HTTPS，路径前缀 /api/v1；
• 认证方式：两种任选——Authorization: Bearer <JWT>（登录签发，实测 12 小时有效）或 Api-Token: <令牌>（长效，值即系统设置中的 api_token，两者实测均通过）；
• 响应约定：成功直返资源 JSON 或 "OK" 字符串；逻辑错误返回 {"err":"..."}；无认证/令牌错误返回 HTTP 400；未知路径返回 {"message":"Not Found"}；
• 速率约定：官方未公开限流参数；实测登录失败有次数锁定提示（「用户名或密码错误，还剩N次机会」），脚本调用应控制重试节奏。

四、认证与首次调用

4.1 登录取 JWT

# curl -sk -X POST 'https://127.0.0.1:4443/api/v1/users/login' \
      -H 'Content-Type: application/json' \
      -d '{"usr":"admin","pwd":"Q1w2e3r4#"}'
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjEsInVzZXJuYW1lIjoiYWRtaW4iLCJyb2xlIjowLCJleHAiOjE3OTI1NjQ4OTl9.xxxxxx"}

（密码为演示值；生产用强随机密码。开启 TOTP 后登录体需附 "otp":"6位动态码"，实测字段来自登录表单 usr/pwd/otp 三项。）后续调用把令牌放入变量：

# TOKEN=$(curl -sk -X POST 'https://127.0.0.1:4443/api/v1/users/login' \
      -H 'Content-Type: application/json' -d '{"usr":"admin","pwd":"Q1w2e3r4#"}' \
      | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")

4.2 长效 Api-Token 方式

# API_TOKEN=$(python3 -c "import json;print(json.load(open('/opt/waf/waf_config/config.json'))['api_token'])")
# curl -sk 'https://127.0.0.1:4443/api/v1/setting' -H "Api-Token: $API_TOKEN" | head -c 80
{"id":"","addr":":4443","dsn":"root:...@tcp(127.0.0.1:6612)/uuwaf?charset=u...

实测两种认证头可互换；api_token 也可在管理台"系统设置"页查看与更换。

4.3 未认证与错误令牌行为（实测）

# curl -sk 'https://127.0.0.1:4443/api/v1/setting' -o /dev/null -w '%{http_code}\n'
400
# curl -sk 'https://127.0.0.1:4443/api/v1/setting' -H 'Api-Token: WRONG' -o /dev/null -w '%{http_code}\n'
400

⚠️ 注意：认证失败统一返回 400（不是 401），脚本重试逻辑不要按 401 设计；权限不足类业务错误则形如 {"err":"无权访问"}（实测：以普通字段提交 PUT /users 时出现）。

五、各 API 域详解

5.1 用户域 /users

GET /api/v1/users（实测回显，TOTP 密钥部分打码）：

[{"id":1,"usr":"admin","pwd":"","fail":0,"role":0,
  "otp_url":"otpauth://totp/UUSEC%20WAF:admin?algorithm=SHA1&digits=6&issuer=UUSEC%20WAF&period=30&secret=XXXX...",
  "enable_otp":false,"pwd_expiration":0,
  "pwd_expired_at":"2026-10-21T02:42:09+08:00","updated_at":"2026-10-21T02:50:22+08:00"}]

字段含义：role（0 管理员）、fail（连续登录失败计数，实测达上限锁定）、enable_otp/otp_url（TOTP 两步验证，密钥在 otp_url 的 secret 参数中，属高敏感信息）、pwd_expiration/pwd_expired_at（密码有效期策略）。

PUT /api/v1/users（新增：不带 id 且 old_pwd 留空；修改/改密：带 id 与 old_pwd，实测回显 "OK"）：

# 修改 admin 密码（全字段提交）
# curl -sk -X PUT 'https://127.0.0.1:4443/api/v1/users' \
      -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
      -d '{"id":1,"usr":"admin","old_pwd":"#Passw0rd","pwd":"Q1w2e3r4#","role":0,"pwd_expiration":0,"enable_otp":false,"otp":"","otp_url":""}'
"OK"

⚠️ 注意：改密必须携带 old_pwd（实测漏带返回 {"err":"旧密码错误"}）；密码策略强制 8 位以上且含大小写字母、数字、特殊字符（实测 q1w2e3r4 被拒绝）。漏字段提交可能触发 {"err":"无权访问"}，属参数校验失败口径而非真权限问题。

5.2 站点域 /sites

GET /api/v1/sites（实测节选）：

{"sites":[
  {"id":1,"hosts":["*"],"custom_host":"www.uusec.com","mode":true,"scheme":"https",
   "type":"roundrobin","servers":[{"ip":"76.76.21.21","port":443,"weight":1}], ...},
  {"id":2,"hosts":["wafdemo.example.com"],"scheme":"http",
   "servers":[{"ip":"127.0.0.1","port":8139,"weight":1}], ...}]}

id 1 为内置 Default 站点（兜底所有未匹配域名）。站点字段逐项含义见配置参数篇第七章；创建/修改必须全字段提交（实测缺字段会落库 NULL 并导致数据面配置同步失败，error.log 刷 failed to update sites: attempt to get length of a userdata value，详见部署篇 Q2）。

POST /api/v1/sites（创建，实测 "OK"）与 PUT /api/v1/sites（修改，请求体带 "id":2，实测 "OK"）：

# curl -sk -X POST 'https://127.0.0.1:4443/api/v1/sites' \
      -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{
        "hosts":["wafdemo.example.com"],"description":"WAF Demo","mode":true,
        "type":"roundrobin","scheme":"http","ruleset_id":1,
        "ip_whitelist":[],"url_whitelist":[],"custom_host":"","deny_page":"",
        "is_websocket":true,"is_ml":false,"is_cache":false,"force_ssl":false,
        "ip_source":0,"ip_order":2,"ip_header":"",
        "servers":[{"ip":"127.0.0.1","port":8139,"weight":1}]}'
"OK"

DELETE /api/v1/sites（批量删除，请求体 {"keys":[id]}，实测删除后站点列表即时少一项、其余站点回源不受影响）：

# curl -sk -X DELETE 'https://127.0.0.1:4443/api/v1/sites' \
      -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"keys":[3]}'
"OK"

⚠️ 注意：删除语义是「DELETE 方法 + JSON body keys 数组」，不是查询参数（实测 DELETE /sites?id=3 返回 {"err":"empty slice passed to 'in' query"}，站点未被删除）。此 keys 数组模式适用于全部可删资源（站点/证书/规则/规则集/用户）。

5.3 证书域 /certs

GET /api/v1/certs（实测节选）：

[{"id":1,"uid":1,"type":1,"name":"Default","email":"","sni":"[\"*\"]",
  "crt":"-----BEGIN CERTIFICATE-----\n...","key":"-----BEGIN ..."}]

字段：type（1 自签/内置）、sni（域名匹配列表 JSON 字符串）、crt/key（PEM 原文，属高敏感）。新证书经管理台"证书管理"上传或申请 Let's Encrypt（自动续期）；列表与删除（keys 数组）走本域接口。

5.4 规则与规则集域 /rules、/ruleset

GET /api/v1/rules（实测 50 条内置 Lua 规则，节选）：

[{"id":75,"uid":1,"level":4,"name":"React2Shell","phase":0,"type":1,
  "description":"React Server Components 远程代码执行漏洞",
  "content":"if waf.reqHeaders.next_action ~= nil or waf.reqHeaders.rsc_action_id ~= nil then ..."}, ...]

• phase 生效阶段（实测分布：0 阶段 44 条、1 阶段 1 条、2 阶段 5 条）、level 威胁等级、type 1 为 Lua 脚本规则、content 为基于 waf.* API 的 Lua 脚本（规则在管理台发布即生效、无需重启）；
• GET /api/v1/ruleset（实测节选）：{"id":1,"name":"Default","content":"[75,74,73,...]"}——content 即启用规则 ID 列表，站点经 ruleset_id 绑定；规则/规则集的新增与修改为 POST/PUT 全字段，删除为 DELETE + keys 数组。

5.5 系统设置域 /setting

对应 config.json 的 12 项管理面参数（逐字段含义见配置参数篇第五章）。GET 直返全量 JSON（含 dsn 密码与三个密钥，属高敏感，接口最小化暴露）；PUT 全量提交原值或修改值，实测回显 "OK" 且立即生效。

5.6 仪表盘域 /logs/*

GET /api/v1/logs/live（实时统计，实测节选）：

{"atk":"{\"02\":3}","geo":"{}","req":10,
 "usage":{"cpu":6.108786608430151,"mem":31.680980661938037,"disk":36.04339813323201}}

（req 累计请求数、atk 按小时攻击计数、usage 为 WAF 服务器 CPU/内存/磁盘占用率，适合接入监控采集。）

GET /api/v1/logs/total?date=2026-10-21（实测回显 [10,3,1,1]，口径为当日请求总数/攻击总数/涉及站点数/攻击类型数）；

GET /api/v1/logs/top?date=2026-10-21（实测节选）：

{"attackers":[{"id":0,"ct":3,"nm":"127.0.0.1"}],
 "sites":[{"id":0,"ct":3,"nm":"wafdemo.example.com"}],
 "types":[{"id":45,"ct":2,"nm":"常规sql注入检测"},{"id":56,"ct":1,"nm":"XSS跨站脚本攻击"}]}

（攻击源排行/站点排行/规则类型排行，id 对应拦截页展示的规则 ID。）日期参数 date=YYYY-MM-DD；官方另有 /logs/download 导出入口与明细列表页（管理台"攻击日志"），脚本侧以上述三个只读接口为主。

六、分页/过滤/排序通用约定

实测该 API 无统一分页信封：列表域（sites/certs/rules/users）为全量返回，攻击明细的分页与过滤（level/host/url/ip 等条件）由管理台页面承载，管理 API 侧以 logs/top、logs/total 聚合口径为主。自动化巡检建议：站点/规则变更走全量比对（拉取→diff→PUT），监控采集走 logs/live（无参数、低开销）。

七、常见问题

Q1：JWT 过期怎么办？ 重新调用登录接口取新 token（实测有效期 12 小时，字段 jwt_expiration=43200 可在系统设置调整）；长驻脚本建议改用 Api-Token 方式，避免频繁登录触发失败计数。

Q2：api_token 泄露如何处置？ 管理台"系统设置"更换 api_token（或经 PUT /setting 修改），旧令牌立即失效；同一动作更换 jwt_key 可使全部已签发 JWT 失效。生产建议把 api_token 的可见范围收敛到采集器所在主机。

Q3：调用成功但站点不生效？ 检查三点：① 是否全字段提交（缺字段→数据面同步失败，error.log 报 failed to update sites）；② waf_nodes 是否指向正确节点（单机默认 127.0.0.1:4447）；③ 用 logs/top 看站点是否出现在统计里。修复方式按配置参数篇与部署篇的对应章节。

Q4：能否完全脱离管理台做运维？ 可以：业务资源（站点/证书/规则）走本篇 API，生命周期（升级/备份/恢复）走部署篇的 compose 命令与 manager.sh；两者组合即可纯脚本化运维。TOTP 开启后，登录接口需附 otp 字段，交互式管理台扫码绑定（otp_url 为标准 otpauth:// 协议）。

八、参考链接

• 官方仓库：https://github.com/Safe3/uusec-waf
• 官方 FAQ（Api-Token 认证方式出处）：https://waf.uusec.com/#/guide/problems
• 官方文档站：https://waf.uusec.com/
• 本专栏关联篇目：《UUSEC WAF Docker Compose 部署指南》（部署与 manager.sh 生命周期管理）、《UUSEC WAF 7.2.6 配置参数详解》（系统设置与站点/规则参数含义）、《UUSEC WAF 7.2.6 介绍与选型指南》（版本与能力边界）