API越权漏洞自动化检测实战：Hadrian+Vespasian+crAPI工具链解析

API越权漏洞在OWASP API Security Top 10 2023里占了两个席位——BOLA（对象级授权缺失）排第一，BFLA（功能级授权缺失）排第五。名字听着很学术，翻译成大白话就是水平越权和垂直越权。手动测越权是安全测试里最磨人的工作之一：换一个资源ID可能就是一个漏洞，改一个请求头可能就绕过了权限校验，而传统扫描器对着CVE特征库扫半天也扫不出这类业务逻辑问题。今天我把踩过不少坑之后沉淀下来的这套自动化检测方案完整写出来：用Hadrian做编排，用Vespasian做执行引擎，再用crAPI当靶场，三段式工具链，配合两个普通测试账号，把越权测试从手搓请求变成跑一遍流水线。

如果你正在做API安全测试、渗透测试，或者公司打算在DevSecOps流水线里加一道API安全卡点，这篇文章都适合你。我会从为什么需要这套组合讲起，一路讲到实际跑出报告、解读结果，最后把我在Windows和Linux两种环境里踩过的报错全部列出来。整个过程只面向授权测试和本地靶场，请勿用于未授权系统。

1. 这套工具链想解决什么问题

1.1 越权漏洞难在“逻辑”而不在“特征”

先澄清概念。水平越权指用普通用户身份访问另一个普通用户的私有资源，典型场景是修改订单号遍历他人订单；垂直越权指普通用户调用了管理员角色才能执行的接口，典型场景是普通账号直接调用删除用户的接口。这两种漏洞的共同点是：服务端认证没问题，Token有效且属于当前用户，但授权出了偏差，服务端没有对上“谁”和“操作什么资源”之间的关系。

传统扫描器为什么拿它没办法？因为漏洞不存在于固定的输入特征里，而存在于业务对象的归属关系里。以 /api/vehicle/{id} 为例，在id里塞一个111可能正常，塞一个222就暴露别人的车库，扫描器如果不知道“当前会话是哪个用户、哪些车辆归属于当前用户”这层语义，就永远无法区分这两次返回有什么不同。所以要自动化，就必须先让工具理解API的资源语义，这也是这套工具链的第一个核心设计原则：测试不是盲扫，而是先建模再攻击。

再补一个很多人忽略的点：不少团队会用接口鉴权覆盖率来评估风险，但越权漏洞恰恰容易出现在覆盖率之外。同一个接口，开发时可能写了“当前用户是否有权限操作该资源”的判断，也可能漏了，漏了之后WAF不会报警，因为请求本身是合法用户发起的，状态码大多是200。这必须靠专门的自动化工具，结合多账号、实体替换、差异比对来做逻辑层面的判断。

1.2 Hadrian、Vespasian、crAPI 各自扮演什么角色

我看过不少团队做API自动化安全测试，有的用Postman写脚本，有的用Burp的Intruder手动爆破ID，接口少的时候还能应付，接口一多就维护不动了。这套组合的分工其实更像一个微型团队，各自负责一个明确环节：

从名字能看出来，Hadrian（哈德良）和Vespasian（维斯帕先）都是罗马帝国时期的皇帝，这套工具圈喜欢用罗马皇帝命名。crAPI则完全是自嘲风格，全称Completely Ridiculous API，意思是“一个故意做得很荒谬的API”。把它当靶场非常合适：内置了十几个常见API安全漏洞，还专门设计了车辆、社区、优惠券、维修记录这些业务对象，完美满足越权测试需要的资源归属关系。

可能有朋友会问：Hadrian既然能解析流量建模，能不能直接发请求做检测？可以，但效率不高。Hadrian的设计思路是做判断而不是做请求，它生成的每个测试用例都包含目标URL、方法、Header、Body和预期判定条件，真正的高并发发送、超时重试、Token刷新这类脏活累活交给Vespasian。两者解耦还有个好处：Hadrian可以部署在CI服务器上做策略编排，Vespasian可以单独部署在离目标更近的执行节点上，方便水平扩容。

2. 三件套部署教程：从 Docker 开始

2.1 先确认基础环境，Windows 最容易踩坑

这套工具链的部署难度不高，核心依赖就是Docker和Docker Compose。crAPI官方默认提供docker-compose方式一键拉起整个靶场，Hadrian和Vespasian则依赖Python 3.9以上和一些Python库，用Docker跑也完全可以。

Windows用户需要重点检查一件事：Docker Desktop是否已经正常启动。我遇到过一个很典型的报错，消息是 failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen。这个报错的含义是Docker CLI无法通过Windows命名管道连接到Docker Desktop的Linux引擎，说白了就是Docker Desktop没启动，或者启动到一半卡住了。解决办法很直接：打开Docker Desktop让引擎跑起来，再执行 docker version 看到Server端有输出就说明通了。如果是公司电脑，可能还需要到Docker Desktop的Settings -> Resources里调整内存分配，因为后面一次性要起七八个容器。

Linux用户相对省事，确保已安装docker和docker-compose插件即可。macOS用户注意Apple Silicon芯片的机器要优先使用arm64版本镜像，crAPI的镜像默认支持多架构，一般不用额外操心，但如果拉镜像拉错了平台，可以用 docker pull --platform linux/amd64 强制指定。

2.2 一键拉起 crAPI 靶场

crAPI的部署流程官方写得很简单，但有几个细节新手很容易栽进去。先把代码拉下来：

git clone https://github.com/OWASP/crAPI.git cd crAPI/deploy cp .env.example .env docker compose up -d

第一次启动会拉取大量镜像，耗时取决于网络情况。启动完成后，用 docker compose ps 查看状态，正常情况下会看到web、api、mailhog、mongo、postgres、rabbitmq等容器处于Up状态。Web界面默认在 http://localhost:8888，API基础路径默认是 http://localhost:8889/api。

这里有个非常重要的点：crAPI注册用户需要一个邮箱，但它不会真的发邮件到外网，而是发到内置的MailHog里。MailHog的界面在 http://localhost:8025，SMTP端口是1025。注册完账号后，去MailHog里找到对应邮件，点击验证链接，账号才算是激活状态。我试过直接在crAPI注册页填一个不存在的邮箱，注册接口会返回成功，但后续很多功能无法使用，因为账号状态没有变成verified。所以正确姿势永远是：注册 -> 打开MailHog -> 点验证链接 -> 再登录。

如果本机的8888或8889端口被占用，可以在docker-compose.yml里改端口映射。但要注意：只改宿主机端口还不够，API的base URL也要同步修改，否则前端页面请求API会失败。crAPI的容器内部用nginx做网络配置，不建议新手进容器里改配置，最简单方式是换一台机器或者停掉占用端口的进程。

2.3 安装 Hadrian 和 Vespasian

Hadrian和Vespasian的安装分为源码方式和Docker方式。我推荐在评估阶段直接使用源码方式，方便看日志和调试，批量跑平台的时候再换Docker。源码方式的基本步骤是这样的：

git clone <hadrian项目仓库地址> cd hadrian python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt python hadrian.py --help

git clone <vespasian项目仓库地址> cd vespasian python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt python vespasian.py --help

仓库地址建议直接在GitHub搜索hadrian api scanner和vespasian api engine，优先选star多一些、commit日期比较新的版本。这两个项目在社区里可能存在不同fork，不同版本对OpenAPI版本的支持程度不一样，有的只支持OpenAPI 3.0，有的已经兼容3.1。如果你的业务API是Swagger 2.0，最好先确认工具版本是否支持，或者先用swagger2openapi工具转成OpenAPI 3.0格式再喂给Hadrian。

看到 --help 能正常输出，说明工具安装成功。接下来做一次连通性测试：让Hadrian读取crAPI的OpenAPI定义，让Vespasian尝试访问crAPI的接口。如果这一步通了，整条链路就通了。小提示：先用一个小的OpenAPI文件测试解析，能正确列出所有路径再接入crAPI，先小后大、先验证再全量，这是API自动化工具链的通用原则。

3. 实战一把：自动化越权检测的标准流程

3.1 准备两个测试账号，把业务基线喂给工具

前面说过，越权检测的底层逻辑是多账号、实体替换、差异比对，所以至少需要两个测试账号。我在crAPI里注册两个账号：alice@example.com 和 bob@example.com，密码都设为 Password@123，靶场环境无所谓强度。

登录后，分别给两个账号做一些数据填充操作。这一步很多人忽略，但实际上非常重要。比如alice登录后添加一辆车、发一条社区帖子、创建一个优惠券申请；bob也执行同样的操作。数据填充的意义在于，越权检测需要目标资源存在才算数——如果alice想访问bob的车辆，前提是bob确实有一辆车。没有基础数据，工具再怎么替换ID也只能遇到空响应，大量漏洞被埋没。

数据填完之后，需要采集一份业务基线流量。主流方式有三种：一是让浏览器流量经过Burp Suite抓包，导出HTTP历史记录；二是用Postman的Collection Runner跑一遍关键业务，然后导出Collection；三是直接用Hadrian自带的流量采集模块抓包。我个人的建议是优先用Postman或OpenAPI定义，因为结构化程度高，Hadrian解析后的资源模型准确度也高。Burp导出的流量有时候会有重复请求和噪音，需要先做一次去重。

采集流量时有一个原则：尽量用低权限账号去操作一个完整的业务闭环，包括登录、查询、创建、修改、删除。理想情况下，流量里应该覆盖资源ID出现在URL路径中、资源ID出现在请求体里、资源ID以查询参数形式出现三种情况。Hadrian对这三种形式的支持程度不完全一样，路径参数最容易自动识别，请求体参数需要依赖schema定义，查询参数在部分版本里需要手动配置正则规则。

3.2 配置文件里最关键的几个字段

跑自动化检测之前，需要给Hadrian一个明确的配置文件。我一般用YAML格式，把目标信息、认证信息、用户对、检测开关分开管理。拿我本地的配置举例：

target: name: crapi-local base_url: http://localhost:8889 schema_file: ./openapi/crapi.json auth: token_endpoint: http://localhost:8889/realms/crapi/protocol/openid-connect/token grant_type: password accounts: - user: alice@example.com password: Password@123 role: normal - user: bob@example.com password: Password@123 role: normal resources: path_parameters: ["vehicleId", "postId", "couponId"] body_parameters: ["vehicle_id", "post_id"] checks: horizontal: true vertical: true mass_assignment: false rate_limit: false

token_endpoint指向的URL需要说明一下：crAPI的认证走的是OIDC兼容服务，实际负责颁发Token的端点不是业务API本身，而是独立的认证服务。端口和路径以本机部署后实际抓包为准，配置里的值只是示例。如果这里配错了，Vespasian发送请求时会频繁遇到401，日志里全是认证失败，这时候先调试token_endpoint，别急着怀疑漏洞检测逻辑。

resource列表里的vehicleId、postId这些字段，是告诉Hadrian“这些位置出现的数字要当成资源标识符，需要尝试跨用户替换”。配置得越准确，水平越权的检测效果越好。如果你用的是OpenAPI schema，Hadrian理论上能自动推断资源路径参数，但自动推断在某些情况下会把普通参数也当成资源ID，产生大量无意义请求。保留一份手工维护的资源字段清单，是提高检测精度的关键。

3.3 运行检测：资产发现、实体绑定、越权验证

配置好之后，启动Vespasian执行引擎，让它监听来自Hadrian的任务；然后再启动Hadrian，指定配置文件和输出目录。

# 终端1：启动执行引擎 python vespasian.py --config ./vespasian.yaml --listen 127.0.0.1:7788 # 终端2：启动编排器，跑检测 python hadrian.py --config ./hadrian.yaml --output ./reports/run1

整个检测过程可以拆成三个阶段。第一阶段是资产发现，Hadrian会解析OpenAPI定义，列出所有API路径、方法、参数，按照“资源-动作”的维度建立索引。第二阶段是实体绑定，工具会利用采集的基线流量，把账号A和账号B各自拥有的资源ID记录下来，比如alice有vehicleId=1001，bob有vehicleId=1002。第三阶段才是真正的越权验证，Vespasian拿着bob的token去请求alice的资源路径，同时拿着alice的token去请求bob的资源路径，把响应与基线响应进行比较。

响应比较的规则是Hadrian的核心。它不会简单把“状态码不等于401/403”就判为漏洞，而是会做更细的相似度分析：如果原本alice访问自己的车辆返回200且带有明确的车辆信息，而bob访问alice的车辆也返回200，且响应体结构与基线一致，就判定为疑似水平越权。如果返回的是带错误码的JSON，即便状态码是200，也不会判为漏洞，因为服务端实际上拒绝了访问。

一辆小型API的检测用例通常在几百到几千个，Vespasian默认并发度是10到20个线程，跑起来很快，通常一两分钟就能完成。建议第一次跑把并发度调低一点，比如4，先观察日志输出，确认Token刷新、请求重试这些机制都正常，再逐步提高。跑完之后，输出目录下会生成一个Markdown或HTML格式的报告，里面有每个检测用例的请求、响应、判定结果和复现步骤。

3.4 报告出来后，先别急着数漏洞

拿到报告，我习惯先不看漏洞数量，先看请求成功率。如果报告显示有大量请求因为网络错误或超时而失败，说明执行引擎和目标之间的连通性有问题，这时候报告里所谓的通过或失败都不具备参考价值。先解决日志里的连接错误，再谈漏洞判定。

第二件事是打开几条疑似越权的记录，看证据是否完整。一个合格的越权证据应该包含三个要素：是谁的Token（请求身份）、请求了哪个资源（目标对象）、响应里包含什么（泄露的数据）。如果响应体确实包含了其他用户的车辆信息、邮箱、手机号等敏感字段，那基本可以确认是水平越权，直接进复现环节。复现方法也很简单：用报告里记录的原始请求，在Burp或Postman里重放一遍，确认不是自动化工具产生的误判。

在crAPI靶场里，比较典型的复现路径是：登录bob的账号，拿到bob的access_token，然后请求alice的车辆ID对应的路径，如果响应里出现了alice的车牌号、车型等信息，说明对象级授权缺失被成功利用。这类问题在真实业务里通常是查询接口缺少“当前用户与资源归属关系”的校验，修复方式是在服务端对资源Owner做一次比对。

还要强调一点：自动检测报告只能作为线索和证据索引，最终的漏洞确认一定要有人工参与。工具的价值在于把逐个接口手工替换ID的重复劳动省掉，把可疑点集中在几十条记录里，而不是替代安全人员的判断。尤其是垂直越权，普通用户拿管理接口去请求，存在大量业务场景需要人工确认“这个接口是否真的属于管理功能”。

4. 检测原理与规则设计：让工具少误报

4.1 水平越权（BOLA）的自动化判定逻辑

水平越权的本质是身份与资源错配。自动化判定逻辑通常用三条请求的差异比对实现：

1. 用户A访问自己的资源R_A，得到基线响应Resp_A。
2. 用户B访问自己的资源R_B，得到基线响应Resp_B。
3. 用户B访问用户A的资源R_A，得到探测响应Probe。

如果Probe与Resp_A近似，返回了同样的资源数据，且状态码是200或业务成功码，就说明资源R_A并没有绑定到用户A的授权域，B可以越权访问。但有个很trick的地方：有些接口在越权时也会返回200，响应体里却是错误信息JSON，比如 {"error": "no permission"}。这种情形不能只看状态码，必须对响应体的业务字段做二次分析。

Hadrian在实现上会把响应体做结构化提取，先看HTTP状态码，再看JSON里的status、code、message等字段，最后做相似度计算。自定义规则时的经验是：不要只看状态码，要看业务语义上是否拒绝了当前请求。如果服务端返回200但body里明确写了Permission denied，实际上是被拒绝的，不应该判为漏洞，否则会收获大量误报。

还有一类水平越权不是通过路径参数，而是通过请求体的对象引用。比如POST一个领券接口，请求体里带 vehicle_id，服务端可能只校验了“这个接口是否需要登录”，却没有校验“这辆车是否属于当前用户”。Hadrian检测这类问题的逻辑是：把基线请求体中的资源ID替换成另一个用户的资源ID，然后比较响应。相比路径参数，这类检测更依赖OpenAPI schema里的required字段和参数类型定义，如果schema不完整，工具可能压根识别不出请求体里哪些字段是资源引用，所以能提供完整schema就尽量提供完整schema。

4.2 垂直越权（BFLA）的自动化判定逻辑

垂直越权的自动化检测稍微简单一些，核心思路是身份与动作匹配。检测过程通常这样：先从OpenAPI定义或管理页流量里提取出高风险动作，比如用户管理、权限修改、删除资源、导出数据等；然后用普通账号Token去调用这些动作，如果返回结果中没有出现401、403等禁止访问信号，就判定为疑似垂直越权。

具体到实现，Vespasian会维护一个角色-权限映射表，路径匹配规则可以用正则，比如匹配admin、user、role、permission等关键字的路径归入管理类。但这套启发式规则误报率不低，因为很多真实业务里，管理功能不一定在路径里有admin字样，反而是在请求体或Header里通过角色字段控制。我自己的做法是：先让Hadrian自动跑一遍启发式规则，把垂直越权结果全部标为待确认，再通过人工筛选真正的管理接口，标准化成自定义规则后加入回归集。

一个容易被忽略的检测点：HTTP动词滥用。普通账号可能不能用GET访问别人的资源，但用PUT、PATCH却可以修改别人资源，或者DELETE可以删除别人资源。自动化工具如果只检测GET，会漏掉大量高风险漏洞。建议把同一个资源路径的GET和写操作都纳入越权检测范围。我在crAPI里实测过，很多越权漏洞恰好发生在POST和DELETE方法上，只测GET的结果是全部通过，换成全动词遍历之后立刻暴露真实问题。

4.3 降低误报率的三条经验

经验一：开启响应差异阈值过滤。有些接口会给每个登录用户返回用户特定信息，比如“你好，alice”，即使工具把资源ID替换成bob的ID，响应里依然返回alice自己的信息，这不是越权，而是服务端忽略了传入ID。Hadrian的相似度算法在设计中会重点关注响应中出现的资源特定字段是否跟着变化，初期把差异阈值调高一点，能减少把无状态接口误判为越权的情况。

经验二：对拒绝结果要有统一业务标准。建议在配置文件中维护一个拒绝特征库，把常见拒绝响应全部列进去，包括401、403、404、400加invalid token、forbidden、not found、no permission、insufficient privileges等，凡是命中拒绝特征库的响应都按访问被拒绝处理。这套特征库在不同业务里需要微调，我用过一段时间后沉淀出了一个通用版本，大概20条左右。

经验三：务必区分静态资源与业务资源。API里通常还有静态资源接口或健康检查接口，这些接口没有资源归属概念，不应该进入越权测试范围。如果在配置文件的exclude列表里把这些路径加进去，检测速度和准确率都会提升，还能避免报告里出现大量无意义的疑似越权。

5. 常见报错与排查技巧实录

我把这段时间实际踩过的坑整理成一张速查表，按现象、原因、解决三列列出，方便直接对照：

表格之外，有几个场景值得单独展开。

5.1 Docker Desktop 引擎连接失败的处理

这个报错我见过的次数太多了，尤其Windows环境：failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen。这个npipe路径是Docker CLI和Docker Desktop引擎之间的命名管道，报错时说明CLI找不到引擎。最常见的场景是：用户启动终端后直接敲docker命令，但Docker Desktop还在启动中，引擎未就绪。解决方法是等Docker Desktop的图标变稳定后再操作，或者使用WSL2模式时，在WSL里执行 docker version 看Server是否有输出。如果重启Docker Desktop也无济于事，可以打开任务管理器结束所有Docker相关进程，再重新启动。

还有一个稍隐蔽的情况：公司电脑上同时安装了Docker Desktop和Podman或者Rancher Desktop，Docker CLI默认上下文指向了别的引擎。此时执行 docker context ls 可以查看当前上下文，用 docker context use desktop-linux 切回Docker Desktop。这个技巧虽然简单，但能解决很多莫名其妙的连接问题。

5.2 OpenAPI Schema 校验失败的处理

工具报 api error: 400 invalid schema for function artifact 这类错误时，先按几个方向排查。第一步，确认传给Hadrian的schema文件是否能通过OpenAPI官方校验，直接用在线Swagger Editor打开，或者用openapi-spec-validator这个Python库做校验。第二步，确认schema是OpenAPI 3.0还是3.1，部分工具版本对3.1的某些高级特性支持不完善，会导致解析阶段直接失败。第三步，检查schema里是否有非标准扩展字段或自定义function定义。

从我的经验来看，真实业务团队导出的OpenAPI定义经常会带私有扩展字段，有些是网关或RPC框架自动生成的，比如x-rpc-method、x-router这类。Hadrian解析时如果遇到不能识别的字段，默认是跳过还是一刀切报错，取决于版本。如果报错实在解决不了，可以写一个小清理脚本，把非标准字段剥离，只保留核心的paths、components、securityDefinitions。这样能保证解析成功率，同时不损失关键测试面。

5.3 认证Token过期导致结果不可用

自动化检测跑长任务时，token过期是必然事件。crAPI的access_token有效期很短，如果扫描任务超过有效期，Vespasian需要在任务执行中自动刷新。这个刷新能力要提前在配置里打开refresh_token的接口地址和client凭据，否则任务后半段全部变成401，报告没法用。

我习惯在正式跑检测之前做一个十分钟冒烟测试：让工具不停循环调用一个简单接口跑10分钟，观察中途Token刷新是否正常、刷新后是否立即重试上一次失败的请求。如果冒烟测试里一直有401积累，就说明重试机制配置不对。这个小步骤看似浪费时间，但能避免一次大规模扫描白跑。

5.4 网络与超时设置

如果Hadrian部署在Docker容器里，而目标crAPI也在Docker容器里，两者之间的网络模式需要确认。最简单的做法是用host网络模式，或者让Hadrian容器加入crAPI所在的docker network，这样直接通过容器名访问目标，比如 http://crapi-api:8889。如果用localhost访问，可能会访问到Hadrian容器自身，导致Connection refused。这个坑在微服务部署时非常常见，提前规划好网络拓扑能省很多麻烦。

超时参数一般按目标接口的P95响应时间来设置。先用工具统计一下目标API的平均响应时间，比如都在50ms以内，那把Vespasian的单请求超时设为3秒、重试2次就足够了。如果目标接口有慢查询，响应时间可能到3到5秒，超时要放宽到10秒，否则报告里会充满超时项，同样无法判断漏洞。

6. 写在最后：给准备上手的人

最后分享一点个人实操心得。我第一次跑这套工具链的时候，差点被报告里的海量疑似漏洞淹没，后来发现是基线数据太脏、请求体里塞满了无关字段导致的。现在我的标准流程是：先花半小时准备好干净的两个测试账号和数据，再花十分钟把资源字段配置精确，然后才启动自动化。这一步前置工作看似慢，实际是让整个检测又快又准的关键。

如果公司正准备把API越权检测接入CI流水线，我的建议是先用crAPI把整条链路跑通，产出一份标准报告模板，再拿真实业务API的小规模子集做试点。千万别一上来就对全量生产接口开扫，一方面是授权边界不清晰，另一方面是误报会淹没真正有价值的问题。自动化工具是放大器，你对它投入的准备工作和规则质量，会被成倍放大成检测结果的准确率。

这套Hadrian、Vespasian、crAPI的组合，最终给我带来的价值就是把越权回归从手工一测一整天压缩到了流水线十分钟。按照我个人的习惯，每次跑完报告，还会把新发现的可疑接口补充到资源字段清单里，越跑越准。希望这份实战记录能帮你少踩几个坑，把API安全自动化这件事真正落下来。