granttrace 2.6.0__tar.gz → 2.7.0__tar.gz

{granttrace-2.6.0 → granttrace-2.7.0}/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 2.7.0 - 2026-11-11
+
+### Added
+
+- BOLA on query-style POST operations. A POST is sent only when its `bola`
+  policy declares `read_only: true` and gives the request body; its path,
+  operationId or summary must name a read action (search, query, lookup...)
+  and none of its metadata or concrete path may name a mutation. `body` is
+  sent unchanged by every identity; `identity_bodies` gives the Owner body
+  (repeated by the Visitor's cross request and Anonymous) and an optional
+  `visitor_self` body. Anything else is skipped or inconclusive with zero
+  requests, and a rate-limited POST is never retried.
+- Sensitive-field leads (`detect_sensitive_exposure`, OWASP API3): unmasked
+  sensitive-named Owner values that reach the Visitor at the same JSON path.
+  `CONFIRMED` only with an explicit `deny` policy, a confirmed object-level
+  decision on the same observations and a value that differs from the
+  Visitor's own record; otherwise `SUSPICIOUS`. Values are never reported,
+  and the analysis is bounded on untrusted responses.
+- Role matrix (`identities.roles`): for operations with a `required_role`,
+  one request per configured role, decided with the BFLA evidence standard
+  (valid privileged baseline, clean Anonymous denial, configured protected
+  data in the role's valid response). Shown in the HTML report and the JSON
+  `rbac_matrix`; confirmed violations are exported to SARIF as `GT-BFLA-001`,
+  confirmed sensitive-field findings as `GT-BOPLA-001`.
+
+### Changed
+
+- The Windows portable build, its verifier, its workflow and the packaged
+  README and launcher read the version from `pyproject.toml` and
+  `core/__init__.py` (checked to agree) instead of repeating it. A test fails
+  on any drift.
+
 ## 2.6.0 - 2026-11-09
 
 ### Added

{granttrace-2.6.0 → granttrace-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: granttrace
-Version: 2.6.0
+Version: 2.7.0
 Summary: Evidence-driven, read-only authorization testing for OpenAPI APIs: BOLA/IDOR, broken authentication, BFLA and property-level checks
 Author: GrantTrace contributors
 License-Expression: Apache-2.0
@@ -64,6 +64,18 @@ is in the repository.
 - **Safe by default.** Scans are read-only. GET operations whose paths,
   identifiers or descriptions suggest side effects are skipped before any
   request, and writes against external targets are refused.
+- **Read-only POST, only when you vouch for it.** A query-style POST (search,
+  lookup, query...) is compared across identities only after you declare
+  `read_only: true` and give the request body. Its path, operationId or summary
+  must name a read action and must not name a mutation; otherwise nothing is
+  sent. These checks reduce risk but cannot prove a POST has no side effects.
+- **Sensitive-field leads.** With `detect_sensitive_exposure`, unmasked
+  sensitive-looking Owner fields (phone, salary, credentials...) that reach the
+  Visitor are reported as leads. They are confirmed only on top of a confirmed
+  object-level finding and never from a field name alone.
+- **Role matrix.** Optional `identities.roles` are probed on operations with a
+  `required_role`. A lower role is a violation only when it receives the
+  privileged baseline's configured protected data, not merely an HTTP 200.
 - **Plan before you send.** `--init-config` drafts a configuration and a review
   checklist from the specification, `--validate-config` checks it offline, and
   `--dry-run` shows what would be requested while sending nothing.
@@ -82,8 +94,10 @@ is in the repository.
 | BOLA / IDOR | CWE-639 | Read-only, as Owner, Visitor and Anonymous | Two test accounts and a resource each of them owns |
 | Broken Authentication | CWE-306 | Read-only, on operations the specification protects | `private_data_paths`: Owner values Anonymous must not see |
 | Broken Function Level Authorization | CWE-285 | Read-only | The required role and each identity's role |
+| Role matrix (RBAC) | CWE-285 | Read-only, one request per configured role | `identities.roles`, `required_role` and `private_data_paths` |
+| BOLA on query-style POST | CWE-639 | Declared `read_only: true` POST with a read action in its name | The request `body` (or `identity_bodies`) |
 | Private data in collections | CWE-639 | Read-only, on list endpoints | `private_data_paths` |
-| Property-level authorization (BOPLA) | CWE-200 | Read-only | Per-field rules in `bopla` |
+| Property-level authorization (BOPLA) | CWE-200 | Read-only | Per-field rules in `bopla`; `detect_sensitive_exposure` adds heuristic leads |
 | Mass Assignment | CWE-915 | **Built-in demo only** | – |
 
 Mass assignment testing writes to a resource, so GrantTrace only does it when it
@@ -93,8 +107,8 @@ before any write; the built-in demo, which owns its data, shows the complete
 flow with independent readback and verified rollback.
 
 **Not supported yet:** GraphQL and gRPC; OAuth, OIDC or mTLS login flows
-(configure tokens or headers yourself); API keys in the query string; POST and
-DELETE tests; writes against external APIs.
+(configure tokens or headers yourself); API keys in the query string; POST
+other than declared read-only queries; DELETE tests; writes against external APIs.
 
 ## Install
 

{granttrace-2.6.0 → granttrace-2.7.0}/README.md

@@ -37,6 +37,18 @@ is in the repository.
 - **Safe by default.** Scans are read-only. GET operations whose paths,
   identifiers or descriptions suggest side effects are skipped before any
   request, and writes against external targets are refused.
+- **Read-only POST, only when you vouch for it.** A query-style POST (search,
+  lookup, query...) is compared across identities only after you declare
+  `read_only: true` and give the request body. Its path, operationId or summary
+  must name a read action and must not name a mutation; otherwise nothing is
+  sent. These checks reduce risk but cannot prove a POST has no side effects.
+- **Sensitive-field leads.** With `detect_sensitive_exposure`, unmasked
+  sensitive-looking Owner fields (phone, salary, credentials...) that reach the
+  Visitor are reported as leads. They are confirmed only on top of a confirmed
+  object-level finding and never from a field name alone.
+- **Role matrix.** Optional `identities.roles` are probed on operations with a
+  `required_role`. A lower role is a violation only when it receives the
+  privileged baseline's configured protected data, not merely an HTTP 200.
 - **Plan before you send.** `--init-config` drafts a configuration and a review
   checklist from the specification, `--validate-config` checks it offline, and
   `--dry-run` shows what would be requested while sending nothing.
@@ -55,8 +67,10 @@ is in the repository.
 | BOLA / IDOR | CWE-639 | Read-only, as Owner, Visitor and Anonymous | Two test accounts and a resource each of them owns |
 | Broken Authentication | CWE-306 | Read-only, on operations the specification protects | `private_data_paths`: Owner values Anonymous must not see |
 | Broken Function Level Authorization | CWE-285 | Read-only | The required role and each identity's role |
+| Role matrix (RBAC) | CWE-285 | Read-only, one request per configured role | `identities.roles`, `required_role` and `private_data_paths` |
+| BOLA on query-style POST | CWE-639 | Declared `read_only: true` POST with a read action in its name | The request `body` (or `identity_bodies`) |
 | Private data in collections | CWE-639 | Read-only, on list endpoints | `private_data_paths` |
-| Property-level authorization (BOPLA) | CWE-200 | Read-only | Per-field rules in `bopla` |
+| Property-level authorization (BOPLA) | CWE-200 | Read-only | Per-field rules in `bopla`; `detect_sensitive_exposure` adds heuristic leads |
 | Mass Assignment | CWE-915 | **Built-in demo only** | – |
 
 Mass assignment testing writes to a resource, so GrantTrace only does it when it
@@ -66,8 +80,8 @@ before any write; the built-in demo, which owns its data, shows the complete
 flow with independent readback and verified rollback.
 
 **Not supported yet:** GraphQL and gRPC; OAuth, OIDC or mTLS login flows
-(configure tokens or headers yourself); API keys in the query string; POST and
-DELETE tests; writes against external APIs.
+(configure tokens or headers yourself); API keys in the query string; POST
+other than declared read-only queries; DELETE tests; writes against external APIs.
 
 ## Install
 

{granttrace-2.6.0 → granttrace-2.7.0}/README.zh-CN.md

@@ -30,6 +30,13 @@ Demo 在 `127.0.0.1` 启动一个临时 API，找出其中的 BOLA 和 Mass Assi
   证据不足时判为 `SUSPICIOUS` 或 `INCONCLUSIVE`，不会算作漏洞。
 - **默认安全。** 扫描只读。路径、operationId 或描述带有副作用语义的 GET 在请求前跳过，
   对外部目标的写入一律拒绝。
+- **只读 POST 需由你声明。** 查询类 POST（search、lookup、query 等）只有在你声明 `read_only: true`
+  并提供请求体后才会跨身份比较；其路径、operationId 或 summary 必须表明读取动作且不得表明修改，
+  否则不发送任何请求。这些检查只能降低风险，不能证明 POST 没有副作用。
+- **敏感字段线索。** 开启 `detect_sensitive_exposure` 后，Visitor 收到的未脱敏、名称敏感的 Owner 字段
+  （电话、薪资、凭据等）作为线索报告；只有在对象级越权已确认时才会确认，绝不仅凭字段名确认。
+- **角色矩阵。** 可选的 `identities.roles` 只在配置了 `required_role` 的操作上探测。低权限角色只有拿到
+  特权基线中配置的受保护数据才算违规，单纯的 HTTP 200 不算。
 - **先计划，再发送。** `--init-config` 根据规范生成配置草稿和核对清单，`--validate-config`
   离线校验，`--dry-run` 列出将要发送的请求，但不发送任何请求。
 - **报告可直接用于修复。** 每条结果说明比较了什么；每个确认漏洞附修复方向、复验步骤、
@@ -42,10 +49,12 @@ Demo 在 `127.0.0.1` 启动一个临时 API，找出其中的 BOLA 和 Mass Assi
 | 检查 | CWE | 运行方式 | 需要配置 |
 |---|---|---|---|
 | BOLA / IDOR | CWE-639 | 只读，以 Owner、Visitor、Anonymous 请求 | 两个测试账号及各自拥有的资源 |
+| 查询类 POST 的 BOLA | CWE-639 | 声明 `read_only: true` 且名称表明读取动作的 POST | 请求体 `body`（或 `identity_bodies`） |
 | Broken Authentication | CWE-306 | 只读，针对规范要求认证的操作 | `private_data_paths`：匿名不应看到的 Owner 数据 |
 | Broken Function Level Authorization | CWE-285 | 只读 | 所需角色及各身份的角色 |
+| 角色矩阵（RBAC） | CWE-285 | 只读，每个配置角色一次请求 | `identities.roles`、`required_role` 与 `private_data_paths` |
 | 集合接口私有数据泄露 | CWE-639 | 只读，针对列表接口 | `private_data_paths` |
-| 字段级授权（BOPLA） | CWE-200 | 只读 | `bopla` 中按字段的规则 |
+| 字段级授权（BOPLA） | CWE-200 | 只读 | `bopla` 中按字段的规则；`detect_sensitive_exposure` 提供启发式线索 |
 | Mass Assignment | CWE-915 | **仅内置 demo** | – |
 
 Mass Assignment 测试需要写入资源，GrantTrace 只在能核验资源实际状态并恢复时才执行。
@@ -53,7 +62,7 @@ Mass Assignment 测试需要写入资源，GrantTrace 只在能核验资源实
 自己持有数据的内置 demo 展示完整流程，包括独立读回和已核验的恢复。
 
 **暂不支持：** GraphQL 和 gRPC；OAuth、OIDC、mTLS 登录流程（请自行配置 token 或 header）；
-查询字符串中的 API key；POST、DELETE 测试；对外部 API 的写入。
+查询字符串中的 API key；声明为只读的查询以外的 POST；DELETE 测试；对外部 API 的写入。
 
 ## 安装
 

{granttrace-2.6.0 → granttrace-2.7.0}/SECURITY.md

@@ -9,8 +9,14 @@ cannot independently verify an external API's authoritative resource state, so
 even with `--allow-write-tests`, an explicit write allowlist, readback mappings
 and `consistency: "strong"`, allowlisted PATCH and PUT checks are reported as
 `INCONCLUSIVE` (`unverified_state_authority`) and send nothing. The built-in demo,
-which owns its data, is the only place the full flow runs. POST and DELETE are
-never sent as tests.
+which owns its data, is the only place the full flow runs. DELETE is never sent.
+A POST is sent only for the read-only BOLA comparison, and only when the
+operation's policy declares `read_only: true` with an explicit request body, its
+path, operationId or summary names a read action, and neither its metadata nor
+its concrete path names a mutation. These checks refuse obviously
+state-changing operations but cannot prove that a POST has no side effects:
+declare `read_only` only for operations you have confirmed change nothing. A
+POST is never retried.
 
 Where the flow does run, every operation must be in the explicit write
 allowlist, and active checks require a JSON request schema plus a configured GET

{granttrace-2.6.0 → granttrace-2.7.0}/VERIFICATION.md

@@ -3,6 +3,51 @@
 Detailed historical release verification records are archived in
 [release verification history](docs/history/release-verification-history.md).
 
+## v2.7.0 pre-release acceptance - 2026-11-11
+
+Status: **accepted for release; v2.7.0 is not published.** Release candidate:
+commit `750a801` (head of PR #90: main `9fc560c`, the merge of #84, plus the
+release date, the publishing workflow's manual choice and release-specific
+documentation); the commit after it adds only this record. PyPI's latest is
+2.6.0; there is no `v2.7.0` tag or Release.
+
+Environment: Linux x86_64 container; CPython **3.13.18** for coverage, linting,
+acceptance scripts and the build, plus CPython **3.9.25** and **3.14.6**; PyYAML
+**6.0.3**, pytest **9.2.0** (**8.4.2** on 3.9), coverage **7.17.2**, Ruff
+**0.17.4**, Mypy **2.4.1**, build **1.6.1**, Twine **7.0.0**, setuptools
+**84.2.1**, wheel **0.48.0**. The Windows package was built and checked by the
+GitHub-hosted `windows-2025` runner; no Windows host was used locally.
+
+| Check | Result |
+|---|---|
+| CI on main after #84 (`9fc560c`) | GrantTrace CI [run 42918318210](https://github.com/ysc070528/granttrace/actions/runs/42918318210) (Ruff, Mypy, tests on 3.9 / 3.12 / 3.14, runtime dependency audit), Windows x64 portable [run 42918318200](https://github.com/ysc070528/granttrace/actions/runs/42918318200) and CodeQL [run 42918318197](https://github.com/ysc070528/granttrace/actions/runs/42918318197): all passed |
+| Full regression suite | 1322 passed and 2402 subtests passed on CPython 3.13.18 and 3.14.6; 1322 passed on 3.9.25; full unittest passed |
+| Branch-aware coverage | 89.95% combined (statements 7281 / 7922, branches 3474 / 4034 = 86.12%); required minimum 80% |
+| Acceptance scripts | PR42 adversarial; PR43 integration (89 tests, source `750a801`, clean tree); authorization coverage, authoritative and generic HTTP; business scenarios 6 / 6; JSON / YAML examples; installation |
+| Wheel / sdist | Isolated `python -m build` from `git archive`; `twine check --strict` passed for both. Wheel: 43 files; sdist: 195 files; no caches, local configurations or build output. Metadata: `Version: 2.7.0`, the unchanged `Summary`, `Requires-Python: >=3.9`, `Requires-Dist: PyYAML>=6.0` |
+| Clean installations | The wheel in new virtual environments on CPython 3.9.25, 3.13.18 and 3.14.6, and the sdist on 3.13.18, each outside the checkout: `granttrace --version` prints `GrantTrace 2.7.0` and `core` loads from `site-packages`; `granttrace demo` exits 0 with BOLA and mass assignment confirmed, rollback verified, the database restored and the server stopped. `scripts/verify_install.py --wheel` passed on the built wheel: versions consistent, 0 PATCH in read-only and external active scans (the external active scan is blocked without state authority), 0 requests for the offline plan |
+| Version consistency | `pyproject.toml`, `core.__version__`, CLI, HTML and JSON reports and the HTTP User-Agent say 2.7.0. The Windows build and verification scripts, the Windows workflow's ZIP and artifact names and the packaged README and launcher derive it through `scripts/source_version.py`; the publishing workflow's manual choices include v2.7.0 |
+| Windows x64 portable | Built from `9fc560c` (clean tree) in run 42918318200 on Windows Server 2025 with Python 3.14.5 and PyInstaller 6.22.3: `GrantTrace-v2.7.0-Windows-x64.zip`, 10,747,513 bytes, SHA256 `a05d6288b85577e6e4bee1a12c9910c8922e564cfa0cf475f96e180832bc1a90`. `scripts/verify_windows_portable.py` passed: extraction to paths with spaces and Chinese characters outside the checkout, no Python on the child PATH, `--version` and `--help`, active and read-only demos, an offline YAML plan with 0 requests, `Start-Demo.bat`, the loopback port closed and no package process left. The artifact host was not reachable from this environment, so the ZIP was not downloaded and rehashed here, and no one double-clicked it on a clean Windows machine |
+| 2.7.0 detectors | Read-only POST, role matrix and sensitive-field checks are covered by `tests/test_v27_hardening.py`, including real HTTP to a loopback server. VAmPI and crAPI were not re-run for this candidate; the read-only GET/HEAD decisions are unchanged (a 200,000-endpoint differential against 2.6.0 found no difference) |
+| Secrets | A pattern scan of all 194 tracked files found no keys, tokens or JWTs; the only match is a dummy private-key marker in a redaction test. GitHub secret scanning is not enabled for the repository |
+| Documentation | Relative links, anchors and links to this repository: 0 problems. `SECURITY.md` describes when a read-only POST is sent; release-specific pages updated in #90 |
+
+Local candidate hashes, built from `750a801` in the container:
+
+```text
+8efe69a82a953310156424bfb2451f6bee842d2e4655445f25daacddba9fe303  granttrace-2.7.0-py3-none-any.whl
+2c72b227652da135275c17036f58232e051efa53f325aa24ca7ea60c7f183b92  granttrace-2.7.0.tar.gz
+```
+
+The publishing workflow builds the uploaded distributions from the tag. The
+Release's Windows ZIP and `SHA256SUMS.txt` come from the Windows workflow run on
+the release commit itself; their hashes differ from the build above because the
+build records its source commit.
+
+Still to do: CI on the release commit, then the tag, the GitHub Release with the
+Windows assets, PyPI publishing and the post-release checks in the
+[release checklist](docs/release-checklist.md), including a clean Windows machine.
+
 ## v2.6.0 pre-release acceptance - 2026-11-08
 
 Status: **accepted for release; v2.6.0 is not published.** Release candidate:

{granttrace-2.6.0 → granttrace-2.7.0}/api_sentinel.py

@@ -671,6 +671,7 @@ def _export_reports(args: argparse.Namespace, auditor: APISentinelAuditor, spec_
     )
     report_target = ("[BOPLA TARGET OMITTED]" if auditor.bopla_config else
                      sanitize_url(args.target, secret_values=auditor.secret_values()))
+    report_rbac = auditor.rbac_matrix_record()
     SecurityReportGenerator.generate(
         stats=report_stats,
         findings=report_findings,
@@ -679,23 +680,27 @@ def _export_reports(args: argparse.Namespace, auditor: APISentinelAuditor, spec_
         output_path=args.output,
         reproduction_templates=reproduction_templates,
         secret_values=auditor.secret_values(),
+        rbac_matrix=report_rbac,
     )
     print(f"[OK] HTML report: {args.output}")
 
     if args.export_json:
         _ensure_parent(args.export_json)
         with open(args.export_json, "w", encoding="utf-8") as handle:
+            json_payload = {
+                "tool_version": __version__,
+                "report_schema_version": 2,
+                "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "elapsed_seconds": round(elapsed, 3),
+                "target": report_target,
+                "stats": report_stats,
+                "results": report_results,
+                "findings": report_findings,
+            }
+            if report_rbac:
+                json_payload["rbac_matrix"] = report_rbac
             json.dump(
-                {
-                    "tool_version": __version__,
-                    "report_schema_version": 2,
-                    "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
-                    "elapsed_seconds": round(elapsed, 3),
-                    "target": report_target,
-                    "stats": report_stats,
-                    "results": report_results,
-                    "findings": report_findings,
-                },
+                json_payload,
                 handle,
                 indent=2,
                 ensure_ascii=False,

{granttrace-2.6.0 → granttrace-2.7.0}/config.schema.json

@@ -28,6 +28,17 @@
         },
         "anonymous": {
           "$ref": "#/definitions/anonymous_identity"
+        },
+        "roles": {
+          "type": "object",
+          "description": "Additional named roles for the RBAC matrix. Names must not reuse owner, visitor, anonymous or roles; probes run only for operations with an explicit required_role.",
+          "propertyNames": {
+            "pattern": "^[a-zA-Z0-9_.-]+$",
+            "not": {"enum": ["owner", "visitor", "anonymous", "roles"]}
+          },
+          "additionalProperties": {
+            "$ref": "#/definitions/role_identity"
+          }
         }
       }
     },
@@ -72,6 +83,39 @@
     }
   },
   "definitions": {
+    "role_identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": ["string", "integer", "null"],
+          "description": "Resource identifier associated with this role identity"
+        },
+        "role": {
+          "type": ["string", "null"],
+          "description": "Role compared with required_role (defaults to the role's key)"
+        },
+        "token": {
+          "type": ["string", "null"],
+          "description": "Bearer token or Authorization header value for this role"
+        },
+        "headers": {
+          "type": "object",
+          "description": "Arbitrary authentication or session headers for this role",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "parameters": {
+          "type": "object",
+          "description": "Role-bound parameters"
+        },
+        "body": {
+          "description": "Request body this role sends to a read-only POST instead of the Owner body; ignored for GET",
+          "type": ["object", "array", "string", "number", "null"]
+        }
+      }
+    },
     "authenticated_identity": {
       "type": "object",
       "additionalProperties": false,
@@ -379,6 +423,28 @@
           "type": "string",
           "minLength": 1,
           "description": "Operator-verified role of the configured Visitor identity. Role comparison is exact, without inferring a role hierarchy."
+        },
+        "read_only": {
+          "type": "boolean",
+          "description": "POST only: declares the operation side-effect free so the BOLA audit may send it. Its path, operationId or summary must also name a read action (search, query, lookup...) and must not name a mutation."
+        },
+        "body": {
+          "description": "POST only: literal JSON request body sent unchanged by Owner, Visitor and Anonymous. It is never reinterpreted as a per-identity map.",
+          "type": ["object", "array", "string", "number"]
+        },
+        "identity_bodies": {
+          "type": "object",
+          "description": "POST only, instead of body: 'owner' selects the Owner's object and is also sent by the Visitor's cross request and Anonymous; optional 'visitor_self' selects the Visitor's own object.",
+          "additionalProperties": false,
+          "required": ["owner"],
+          "properties": {
+            "owner": {"type": ["object", "array", "string", "number"]},
+            "visitor_self": {"type": ["object", "array", "string", "number"]}
+          }
+        },
+        "detect_sensitive_exposure": {
+          "type": "boolean",
+          "description": "Heuristic lead for unmasked sensitive-named Owner fields returned to the Visitor (OWASP API3). CONFIRMED only with expected_visitor_access 'deny', a confirmed object-level decision and a value that differs from the Visitor's own record; otherwise SUSPICIOUS."
         }
       }
     }

{granttrace-2.6.0 → granttrace-2.7.0}/core/__init__.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
 """GrantTrace core package."""
 
-__version__ = "2.6.0"
+__version__ = "2.7.0"