kabiri-labs/overstep

# overstep **基于矩阵驱动的 HTTP API 授权测试。**    overstep 接收一个声明式的**授权矩阵**（即谁被允许做什么） ——并将其转化为具体的 HTTP 测试。它会生成**正向**测试（*应该*成功的访问） 和**负向**测试（*应该*被拒绝的访问），在实际目标上运行它们，并将每一个漏网的负向测试报告为授权漏洞：**BOLA**、**BFLA** 或**权限提升**。对结果进行快照保存，一旦你的授权面发生**漂移**，CI 就会立即失败。 ``` authorization matrix ──► positive + negative tests ──► run ──► findings (subjects × resources) (self / other, per role) (BOLA/BFLA/privesc/drift) ``` ## 为什么使用矩阵？ 大多数授权漏洞并不是因为某个 handler 中缺少了一个 `if` 判断 —— 它们往往是那个没人写下来的表格中的一个*单元格*。“普通用户能否删除另一个用户的订单？”这是一个关于**角色**、**资源**和**所有权范围**交集的问题。overstep 将这个表格明确化并测试每一个单元格： - **BOLA**（越权对象级别授权 / Broken Object Level Authorization）—— 主体访问了*另一个主体*的对象（例如，使用不属于自己的 id 发起 `GET /orders/{id}`）。 - **BFLA**（越权功能级别授权 / Broken Function Level Authorization）—— 主体调用了其角色不具备的功能（例如，以普通用户身份调用 `GET /admin/users`）。 - **权限提升（Privilege escalation）** —— 低权限角色访问了仅限高权限角色访问的内容。 - **授权漂移（Authorization drift）** —— 自上次发布以来发生了更改的授权决定，可通过与已保存的基线进行比对来捕获。 ## 安装 ``` python -m venv .venv && . .venv/bin/activate pip install -e . # or: pip install -e ".[dev]" for tests + demo server ``` ## 快速开始（内置漏洞演示） ``` # 1. 启动存在 intentionally-vulnerable 漏洞的 demo API python -m uvicorn examples.mock_api.server:app --port 8000 # 2. 在另一个 shell 中，针对它运行 matrix overstep run examples/mock_api/matrix.yaml --out out ``` 你会得到类似如下的摘要： ``` overstep summary Tests run 18 Positive / negative 7 / 11 Vulnerabilities 8 BOLA 2 privilege-escalation 6 ``` 以及存放在 `out/` 目录下的报告： | 文件 | 用途 | |---|---| | `report.html` | 人类阅读 | | `findings.json` | 脚本 / 仪表盘 | | `overstep.sarif` | GitHub code scanning | | `junit.xml` | CI 测试报告器 | `overstep run` 在发现漏洞时会以非零状态退出，因此开箱即用即可使流水线失败。 ## 授权矩阵 一个矩阵由三部分组成 —— **主体**（谁）、**资源**（什么）和**策略**（允许列表）。未被明确允许的一切都将被拒绝。 ``` base_url: http://127.0.0.1:8000 roles: [anonymous, user, admin] # least -> most privileged subjects: - { name: alice, role: user, token: alice-token, attributes: { user_id: u1 } } - { name: bob, role: user, token: bob-token, attributes: { user_id: u2 } } - { name: root, role: admin, token: admin-token, attributes: { user_id: u9 } } - { name: anon, role: anonymous, token: null } resources: - name: get_user request: { method: GET, path: "/users/{id}" } type: object # object-level -> BOLA surface owner_param: id # {id} must match the caller's user_id owner_attr: user_id - name: admin_list_users request: { method: GET, path: "/admin/users" } type: function # function-level -> BFLA surface policy: get_user: allow: - { role: user, scope: own } # a user may read only their own object - { role: admin, scope: any } # admins may read anyone's admin_list_users: allow: - { role: admin } # admin-only ``` 由此，overstep 会生成（`overstep plan examples/mock_api/matrix.yaml`）： | 预期结果 | 请求 | 主体 | 变体 | |---|---|---|---| | allow | `GET /users/u1` | alice | self | | **deny** | `GET /users/u2` | alice | other ← BOLA 探测 | | allow | `GET /users/u9` | root | self | | allow | `GET /users/u1` | root | other | | **deny** | `GET /admin/users` | alice | na ← BFLA / 权限提升探测 | | allow | `GET /admin/users` | root | na | ### 自定义条件 对于更细致的规则（如租户隔离、属性匹配），允许规则可以携带一个安全的布尔值 `condition`，该条件基于 `subject` 和 `target` 属性进行求值： ``` policy: get_order: allow: - role: user condition: "subject.tenant == target.tenant" ``` 条件通过受限的 AST 求值器运行 —— 仅支持比较操作、布尔逻辑和属性/索引访问。不支持函数调用，也不支持任意名称。 ### 自定义 Headers 默认情况下，每个主体都使用 `Authorization: Bearer ` 进行身份验证。当 endpoint 需要更多信息时 —— 例如非 Bearer 认证方案、API key 或租户 header —— 可以在**资源**上设置 headers（对所有主体发送）和/或在**主体**上设置 headers（针对特定身份）。主体的 headers 会覆盖资源的 headers，并且显式设置的 `Authorization` header 永远不会被 token 覆盖： ``` resources: - name: get_order request: method: GET path: "/orders/{id}" headers: { Accept: application/json, X-Api-Version: "2" } # every request type: object owner_param: id subjects: - name: alice role: user token: alice-token # -> Authorization: Bearer alice-token headers: { X-Tenant: t1 } # extra per-subject header attributes: { user_id: u1 } - name: svc role: admin headers: { X-API-Key: "abc123" } # custom auth, no bearer token attributes: { user_id: u9 } ``` ### 决定允许还是拒绝（响应匹配器） 默认情况下，`2xx` 状态码表示访问被允许，其他状态码表示被拒绝。但对于那些成功时重定向、返回 `200` 但带有错误主体，或将 `403` 伪装成 `404` 的 API 来说，这种判断是错误的。**响应匹配器** 使得真实信号变得明确。你可以在矩阵全局的 `access:` 下进行设置，和/或在每个资源上进行覆盖： ``` # matrix-wide 默认值 access: allow_status: ["2xx"] # exact codes, ranges ("200-299") or classes ("2xx") deny_body_regex: "access denied|not authorized" # a 200 with this body -> deny treat_redirect_as: deny # how to read a 3xx: deny | allow | status resources: - name: start_export request: { method: POST, path: "/exports" } type: function access: allow_status: [200, 202] # async accept counts as success - name: legacy_login_redirect request: { method: GET, path: "/account" } type: function access: treat_redirect_as: allow # this endpoint 302s on success ``` 求值顺序：`deny_body_regex`（最高优先级，安全失败）→ `allow_body_regex` → 重定向处理 → `allow_status`。Body 匹配模式不区分大小写，并与完整的响应体进行匹配。 ## 命令 | 命令 | 功能 | |---|---| | `overstep run MATRIX` | 生成、执行并报告；发现漏洞时以非零状态退出 | | `overstep snapshot MATRIX` | 将当前决定记录为漂移基线 | | `overstep plan MATRIX` | 打印生成的测试用例（无需网络） | | `overstep validate MATRIX` | 对矩阵进行结构问题检查 | | `overstep scaffold SPEC --fmt openapi\|har` | 生成初始的 `resources:` 代码块 | `run` 标志：`--base`（覆盖 URL）、`--out`、`--baseline`、`--concurrency`、`--insecure` 和 `--fail-on {vuln,drift,any,never}`。 ## CI / CD：捕获授权漂移 将已知良好的状态固化到基线中，然后仅在授权*发生变更*时失败： ``` # once，在 triaging findings 之后 overstep snapshot examples/mock_api/matrix.yaml --out baseline.json # 在每一个 pull request 上 overstep run examples/mock_api/matrix.yaml --baseline baseline.json --fail-on drift ``` 一个从 **deny → allow** 翻转的单元格是一个新出现的漏洞（高严重性）；从 **allow → deny** 则是新的限制（中等严重性）。将 `matrix.yaml` 和 `baseline.json` 置于版本控制之下，授权规则就会像其他代码一样接受审查。有关完整示例，请参见 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)，其中包括将 SARIF 上传到 GitHub code scanning。 ## 从规范引导生成矩阵 不要手动编写资源列表： ``` overstep scaffold openapi.yaml --fmt openapi > resources.snippet.yaml overstep scaffold traffic.har --fmt har > resources.snippet.yaml ``` overstep 会根据类似 id 的路径参数猜测是对象还是功能；你只需要补充策略。 ## 对比 | 功能 | overstep | Burp Autorize / AuthMatrix | Schemathesis | |---|---|---|---| | 将授权矩阵作为代码管理 | ✅ | ⚠️ （按请求，手动） | ❌ | | 正向**和**负向测试 | ✅ | ⚠️ | ⚠️ | | BOLA / BFLA / 权限提升分类 | ✅ | ⚠️ | ❌ | | 用于 CI 的漂移基线 | ✅ | ❌ | ❌ | | SARIF + JUnit 输出 | ✅ | ❌ | ⚠️ | ## crAPI 演示 请参阅 [`examples/crapi`](examples/crapi/README.md) 运行 overstep 对抗 OWASP crAPI，体验真实的 BOLA/BFLA 演示。 ## 许可证 Apache-2.0。

标签：API安全测试, CISA项目, DAST, DevSecOps, LNA, Python, 上游代理, 恶意软件分析, 无后门, 权限测试, 逆向工具