AuthzTrace

针对 IDOR/BOLA 漏洞的授权测试。
在 CI 中证明用户 A 无法访问用户 B 的对象。

大多数 API 扫描器可以抓取 endpoint，但它们不知道所有权。它们能看到 `GET /api/invoices/inv_123`，却无法知道 `inv_123` 属于 Alice 且绝不能被 Bob 读取。 AuthzTrace 补充了缺失的业务上下文。你只需声明参与者、对象所有者和 endpoint。AuthzTrace 会生成跨用户攻击矩阵，并在授权中断时使构建失败。 ``` alice owns inv_alice_001 bob owns inv_bob_002 AuthzTrace proves: alice -> alice invoice allowed bob -> alice invoice denied anon -> alice invoice denied ``` ## 快速开始 从 PyPI 安装： ``` pip install authztrace ``` 创建或生成 contract： ``` authztrace init --from openapi.yaml --output authztrace.yaml ``` 针对你的 API 运行： ``` authztrace run -c authztrace.yaml --sarif authztrace.sarif ``` 在 GitHub Actions 中使用： ``` - uses: Asttr0/AuthzTrace@v0.3.1 with: config: authztrace.yaml sarif: authztrace.sarif strict: "true" ``` 退出代码专为 CI 设计： | 代码 | 含义 | |---:|---| | `0` | 通过 | | `1` | 发现 BOLA/数据泄露，或在 `--strict` 模式下出现警告 | | `2` | 设置失败：token 失效、API 无法访问、fixture 无效 | ## Contract 示例 ``` base_url: http://localhost:3000 actors: alice: { auth: { type: bearer, token: "${ALICE_TOKEN}" } } bob: { auth: { type: bearer, token: "${BOB_TOKEN}" } } anon: { auth: { type: none } } resources: invoice: ids: alice: inv_alice_001 bob: inv_bob_002 markers: alice: "Alice private invoice" bob: "Bob private invoice" endpoints: - name: read invoice request: GET /api/invoices/{id} assertions: allow_contains: ["{marker}"] deny_not_contains: ["{marker}"] policy: default: owner-only deny_status: [401, 403, 404] ``` 这个小文件会扩展为每个参与者与对象的交叉检查。所有者必须通过。其他所有人必须被拒绝。被拒绝的响应不得泄露所有者的标记。 ## Endpoint 形态 可以在路径、查询字符串、header、JSON body 和 form body 中测试对象 ID： ``` endpoints: - request: GET /api/invoices/{id} - method: GET path: /api/invoices query: id: "{id}" - method: POST path: /api/invoices/lookup safe: true json: invoice_id: "{id}" ``` 确切的占位符会保留其类型。如果 ID 是数字，`invoice_id: "{id}"` 会发送数字，而不是字符串。 共享或特权 endpoint 可以覆盖仅限所有者的授权： ``` - request: GET /api/admin/invoices/{id} allow: [owner, admin] - request: GET /api/team/invoices/{id} allow: [authenticated] ``` ## 默认安全 AuthzTrace 旨在 CI 中运行，因此除非你主动选择开启，否则它不会执行修改型 endpoint。 | 方法 | 默认操作 | |---|---| | `GET`, `HEAD`, `OPTIONS` | 执行 | | `POST`, `PUT`, `PATCH`, `DELETE` | 跳过 | 将类似读取的 POST endpoint 标记为安全： ``` - method: POST path: /api/search safe: true ``` 仅对一次性测试数据运行不安全的 endpoint： ``` authztrace run -c authztrace.yaml --include-unsafe ``` 被跳过的 endpoint 会报告为 `SKIP`，不计入通过。 ## 可检测内容 | 模式 | 状态 | |---|---| | 水平 IDOR/BOLA | 支持 | | 匿名对象访问 | 支持 | | 路径/查询/header/body 中的 ID | 支持 | | 拒绝响应泄露 | 支持 | | 错误允许的响应 body | 支持 | | 管理员/共享访问规则 | 支持 | | 防止凭证失效导致的误报 | 支持 | | 嵌套的父子所有权 | 计划中 | | 登录流程授权 | 计划中 | | GraphQL BOLA | 计划中 | 完整路线图：[docs/CORPUS.md](docs/CORPUS.md)。 ## 本地演示 ``` git clone https://github.com/Asttr0/AuthzTrace.git cd AuthzTrace pip install -e . pip install -r examples/vulnerable-api/requirements.txt python examples/vulnerable-api/app.py ``` 在另一个终端中： ``` export ALICE_TOKEN=alice-token export BOB_TOKEN=bob-token authztrace run -c examples/authztrace.yaml ``` 针对有漏洞的 API： ``` 12 passed, 6 failed, 0 warnings, 0 errors, 6 skipped, 24 checks categories: bola=6, unsafe_skipped=6 ``` 针对已修复的 API： ``` SECURE=1 python examples/vulnerable-api/app.py ``` ``` 18 passed, 0 failed, 0 warnings, 0 errors, 6 skipped, 24 checks categories: unsafe_skipped=6 ``` ## 输出格式 ``` authztrace run -c authztrace.yaml \ --sarif authztrace.sarif \ --json authztrace.json \ --junit authztrace.xml ``` SARIF 结果包含稳定的指纹，以便 GitHub Code Scanning 可以在多次运行中跟踪发现的问题。 ## 为什么不用普通扫描器？ | 能力 | 通用扫描器 | AuthzTrace | |---|:---:|:---:| | 了解对象所有权 | 否 | 是 | | 测试跨用户访问 | 较弱 | 是 | | 检测到 BOLA 时导致 CI 失败 | 有时 | 是 | | 使用代码旁的 contract | 否 | 是 | | 默认避免修改型 API | 视情况而定 | 是 | 授权属于业务逻辑。AuthzTrace 允许你声明该逻辑，并在每次 pull request 中进行测试。 ## 状态 Alpha 版本，但已可用。PyPI 包、Marketplace Action、SARIF/JSON/JUnit 输出、OpenAPI 入门生成、只读安全、设置预检和易受攻击的演示均已实现端到端运行。 接下来的优先事项： - 登录流程授权 - 嵌套的父子所有权 - GraphQL BOLA 检查 - 针对已接受偏差的基线 ## 许可证 MIT (c) 2026 Mohamed Taha Slimani ([@Asttr0](https://github.com/Asttr0))

标签：API测试, IDOR/BOLA检测, Python, SARif, 安全测试, 授权测试, 攻击性安全, 无后门, 逆向工具