♧ Godown 安全知识树

Spring Boot Swagger2 未加访问控制导致 doc.html 与 v2/api-docs 未授权泄露全量接口

pentest/recon · verified

一句话结论

Spring Boot 项目若用 @EnableSwagger2 + RequestHandlerSelectors.any() / PathSelectors.any() 生成文档,且没有在网关、过滤器或 Docket 上做访问控制,未登录者即可通过 /doc.html、/v2/api-docs 拉取全部 Controller、路径、参数与数据模型,为后续未授权/越权测试提供完整地图。

原理

  • Swagger2 的 Docket 只是文档生成器。apis(RequestHandlerSelectors.any()) 选择所有 Controller,paths(PathSelectors.any()) 选择所有路径;它不会自动附带认证,也不判断调用者身份。
  • 文档相关的 /doc.html(knife4j)、/swagger-ui.html、/v2/api-docs、/swagger-resources 等是独立的 HTTP 端点,是否可达取决于应用的鉴权过滤器是否覆盖它们。常见失误是把文档静态资源当白名单放行,或过滤器只拦业务前缀。
  • 接口清单本身不直接执行操作,但它把“隐藏接口、参数名、HTTP 方法、枚举值、必填字段”一次性暴露,攻击者无需字典即可定位上传、导出、重置密码、批量状态修改等高价值端点,再逐个测试认证与资源级授权。
  • 在前后端分离项目中前端只调用部分接口,文档里往往存在页面上不可见的“孤儿接口”(如统一上传、内部配置),这类接口的鉴权覆盖更容易遗漏。

触发条件

  • 生产环境未关闭 Swagger/knife4j/springdoc,或关闭不彻底只删了 UI 没删 /v2/api-docs。
  • Docket 配置为 any() 全量暴露,未按包/路径收敛。
  • 鉴权过滤器未覆盖 /doc.html、/v2/api-docs、/swagger-resources、/webjars 等路径,或把这些路径加入放行白名单。
  • 文档端点可被外网直接访问(非仅内网/开发环境)。

利用步骤

  1. 用常见字典探测:/doc.html、/swagger-ui.html、/swagger-ui/index.html、/v2/api-docs、/v3/api-docs、/swagger-resources、/swagger-resources/configuration/ui。
  2. 对比状态码与响应体:200 且返回 swagger/openapi JSON 或 HTML 即命中;401/302 说明有网关鉴权,转找白名单路径。
  3. 解析 /v2/api-docs,提取 paths、definitions、tags,按 user、role、upload、export、reset、delete、batch 等关键词筛出高价值接口。
  4. 对每个候选接口去掉 Cookie/Token 直接请求,区分“未授权可用”与“仅泄露文档”;对需要登录的接口,用低权限账号测试资源级越权。
  5. 把文档中的参数名与枚举值直接用于构造请求,减少盲猜,形成完整攻击面清单。

PoC

# 探测文档端点
for p in /doc.html /swagger-ui.html /v2/api-docs /v3/api-docs /swagger-resources; do
  code=$(curl -s -o /dev/null -w '%{http_code}' "https://target.example$p")
  echo "$code $p"
done

# 未授权拉取接口清单
curl -s 'https://target.example/v2/api-docs' > api.json
python -c "import json;d=json.load(open('api.json'));print('\n'.join(sorted(d.get('paths',{}))))"
# 预期:无需任何 Cookie/Token 返回 200,paths 中包含 /user/resetPwd、/supplier/batchSetStatus 等业务接口;
# 若返回 401/302,说明有网关或过滤器保护,需继续找未覆盖的文档子路径。

变体与关联

  • 变体:springdoc-openapi 的 /v3/api-docs、/swagger-ui/index.html;knife4j 的 /doc.html 与 /v2/api-docs?group=...。
  • 变体:只关闭了 UI 但保留 /v2/api-docs;或只对 UI 做了 IP 白名单,API JSON 仍匿名可达。
  • 关联:[[web-generic-auth-swagger-unauth-user-management]](文档暴露叠加接口本身无鉴权时,可直接创建/删除用户)。
  • 关联:[[pentest-recon-error-driven-api-param-discovery]](文档拿不到时用报错迭代参数)。
  • 关联:[[web-generic-auth-multitenant-tenant-header-missing-superadmin]](本类文档泄露可用于定位后续越权接口)。
  • 边界:文档端点被网关统一认证、返回 401/403 时,仅凭本文方法无法获得清单;此时应转向前端打包产物中的 API 路径提取。

检测与防御

  • 修复:生产环境关闭 Swagger/knife4j/springdoc(@Profile("!prod") 或配置开关),或通过网关统一认证并限制来源 IP。
  • 修复:Docket 使用 apis(RequestHandlerSelectors.basePackage(...)) 与明确的 paths 收敛,不发布内部/管理接口。
  • 加固:把文档路径纳入与业务接口相同的鉴权链路,不要长期放在过滤器白名单;对 /v2/api-docs、/v3/api-docs、/swagger-resources 单独做访问控制。
  • 检测:外网对 /doc.html、/v2/api-docs、/swagger-resources 的 200 响应与高频探测;未认证会话访问文档端点;文档 JSON 中出现内部管理路径的告警。