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等路径,或把这些路径加入放行白名单。 - 文档端点可被外网直接访问(非仅内网/开发环境)。
利用步骤
- 用常见字典探测:
/doc.html、/swagger-ui.html、/swagger-ui/index.html、/v2/api-docs、/v3/api-docs、/swagger-resources、/swagger-resources/configuration/ui。 - 对比状态码与响应体:200 且返回
swagger/openapiJSON 或 HTML 即命中;401/302 说明有网关鉴权,转找白名单路径。 - 解析
/v2/api-docs,提取paths、definitions、tags,按user、role、upload、export、reset、delete、batch等关键词筛出高价值接口。 - 对每个候选接口去掉 Cookie/Token 直接请求,区分“未授权可用”与“仅泄露文档”;对需要登录的接口,用低权限账号测试资源级越权。
- 把文档中的参数名与枚举值直接用于构造请求,减少盲猜,形成完整攻击面清单。
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 中出现内部管理路径的告警。