接口权限探测 / API Permission Probe

技能文档

---
name: web-api-permission-probe
display_name: 接口权限探测 / API Permission Probe
description: "探测 Web 应用接口层是否真按角色加锁，而不只是隐藏前端菜单：含多角色实测、业务码解析、越权定级。Probe whether a web application's API layer truly enforces role-based access control, instead of only hiding UI menus. Covers verifying real API paths from frontend source, testing endpoints with multiple role tokens, parsing list responses (data.rows plus total versus raw array), and rating permission gaps at the API layer. 触发词：接口权限探测、越权测试、权限审计、菜单隐藏不等于锁、permission probe。"
summary_zh: 探测 Web 应用接口层是否真的按角色加锁，而不只是隐藏前端菜单——含多角色实测、业务码解析与越权定级。
summary_en: "Probe whether a web app's API layer truly enforces role-based access—not just hides UI menus—with multi-role testing, business-code parsing, and privilege-escalation rating."
version: 1.0.0
category: security
tags: [security, permission, api, auth, audit, probe]
---

# web-api-permission-probe

把"Web 应用接口层权限探测"的方法论固化为可复用流程。核心认知：**前端菜单 / 路由隐藏不等于接口层加锁**。很多系统前端只藏按钮，真正防线在后端接口；探测必须验证接口层，而非只看页面能不能看到。

可套到任意带登录态的 Web 系统（订单系统、会员中心、内容平台等），与具体业务无关。

## 简介 / Introduction

**中文**：把"接口层权限探测"方法论固化：核心认知是"前端隐藏 ≠ 接口加锁"。覆盖核准真实接口路径、多角色实测、200 不等于成功、响应结构解析、按接口层定级。可套到任意带登录态的 Web 系统。

**English**: A methodology for probing the API-layer authorization of a web app, built on the key insight that "hiding the UI ≠ locking the endpoint". Covers verifying real API paths, multi-role testing, parsing business codes, and rating gaps at the API layer. Business-agnostic.

## 何时用

- 权限审计 / 越权风险评估
- 验证"某角色看不到的菜单，对应接口是否也调不通"
- 上线前确认敏感接口真的按角色拒绝

## 核心原则

1. **核准真实路径**：探测前读前端 `src/api/*.js`（或后端路由定义）拿真实接口路径，不要凭记忆或文档（文档常未过滤 / 不全）。
2. **多角色实测**：用管理员 / 普通角色 / 无权限角色三种 token 分别调同一接口，比较返回。
3. **看接口层定级**：前端隐藏但接口不锁 = 越权风险，严重度以接口层为准。
4. **200 不等于成功**：框架可能返回 `200 + {code:500}`，必须解析业务码。
5. **先解析响应结构**：分页可能是 `data.rows` + `data.total`（非 records/list）；某些端点 `data` 直接是数组。先识别再断言。
6. **按 path 判重**：同 path 可能多入口，判重按 path 而非 id。

## 分步流程

1. 读前端 api 定义，导出接口清单（path / method / 所需角色）。
2. 准备多角色 token（管理员、普通、匿名）。
3. 对每个敏感接口，逐角色调用，记录 HTTP 状态 + 业务码 + 响应结构。
4. 比对：无权限角色是否返回 403 / 拒绝；若返回 200 + 业务成功 → 越权漏洞。
5. 输出探测报告：接口 × 角色矩阵，标注每项是否真锁。
6. 定级：接口可越权 > 仅前端可见。

## 坑（来自真实事故）

- **只看前端菜单**：菜单隐藏但接口未加接口层权限注解 → 手敲 URL 直接越权。
- **凭文档路径**：文档里的路径未过滤（含无权限注解的端点）→ 调不通误判。
- **HTTP 200 即成功**：框架统一 200 包业务码 → 看到 200 以为通，实际业务 500。
- **判重按 id**：重跑造出同 path 双入口，污染探测样本。
- **用数据范围推断角色**：data_scope 不可靠，必须按 role_key / 接口注解判定。

## 骨架脚本

`scripts/probe_permissions.py`：生成接口 × 角色探测矩阵，提供真实 HTTP 探测函数与响应结构解析（兼容 `data.rows`/`data.total` 与裸数组两种）。改 token / base_url 即可跑，无业务耦合。

## 验收清单

见 `references/acceptance-checklist.md`（7 条，上架 / 改版前必跑）。

## 触发词

接口权限探测、越权测试、权限审计、菜单隐藏不等于锁、permission probe。

使用说明

## 解决什么问题

探测一个 Web 应用的接口层是否真按角色加锁，而不只是"前端藏菜单"。生成 接口×角色 矩阵，按越权风险定级。

## 核心认知

- **菜单/路由授权 ≠ 接口层加锁**：很多系统只藏按钮，真正防线在后端接口；本技能探测接口层。
- **真实路径以 `frontend/src/api/*.js` 为准**：不要相信 Swagger 文档（往往不同步），先 grep 出真实接口路径再实测。
- **业务码必须解析**：HTTP 200 + `{"code":500}` 是常见"假绿"模式，断言必须深到业务码层。
- **多角色 token 实测**：以 admin / 普通用户 / 匿名 三个角色打同一接口，diff 响应。
- **越权风险按接口层定级**：未鉴权返回数据 = 严重；鉴权通过但缺角色 = 中；前端藏路由无法访问 = 中低）。

## 使用方式

1. 收集各角色 token，写入配置（明文密码框则需先登录拿 token）。
2. 配置 `cases/api_list.txt`（接口路径列表）。
3. 跑 `probe_permissions.py`，输出矩阵 CSV + 风险摘要。
4. 复测"严重"等级接口，对照代码确认 @RequiresPermissions / @PreAuthorize 等注解是否到位。

## 适用场景

任意带登录态的 Web 系统：内部 ERP、CRM、客服、工单、内容后台等上线前的权限体检。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。