granttrace 2.4.0__tar.gz → 2.5.0__tar.gz

{granttrace-2.4.0 → granttrace-2.5.0}/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## 2.5.0 - 2026-10-04
+
+### Added
+
+- Export SARIF 2.1.0 with `--export-sarif`, alongside HTML and JSON reports.
+  Only existing CONFIRMED findings produce results: BOLA / IDOR maps to
+  `GT-BOLA-001` / `CWE-639`, and Mass Assignment to `GT-MASS-001` / `CWE-915`.
+  A safely represented OpenAPI file inside the workspace supplies the artifact
+  location for GitHub Code Scanning; no source lines or endpoint files are invented.
+- Add safe cURL reproduction templates and copy buttons to confirmed HTML finding
+  cards. Use the actual tested URL and confirmed injected payload where safe,
+  Visitor credential placeholders, POSIX shell quoting and `curl --globoff`.
+  Clipboard fallback supports offline reports; manual selection works without
+  JavaScript. Real credentials never enter the templates, including when sensitive
+  report evidence is enabled.
+- Guide configuration onboarding from draft generation and manual review through
+  validation, a local dry-run and a read-only first real scan. Distinguish
+  config-only from spec-aware validation, summarize dry-run counts, and format
+  next-step commands safely for POSIX shells or PowerShell.
+
+### Changed
+
+- Align README, configuration and advanced guidance with the first API onboarding
+  flow and the SARIF / cURL outputs, without changing configuration formats.
+- Explain validation scope, warnings and dry-run write eligibility more clearly.
+  An active PATCH configuration is separate from enabling active execution;
+  the recommended first real scan remains read-only.
+- Promote the release source to `2.5.0` across package metadata, runtime version
+  and generated examples; prepare the release checklist and OIDC workflow for
+  the new tag without publishing it during release preparation.
+
+### Security / Safety
+
+- Preserve BOLA / IDOR verdicts and Mass Assignment detection criteria, default
+  read-only auditing, and the existing TLS / HTTP / redirect / proxy boundaries.
+- Active PATCH still requires explicit `--allow-write-tests`, an explicit write
+  allowlist, independent GET readback, original-state snapshots, rollback and
+  rollback verification. Failed recovery still halts further writes.
+- SARIF, cURL templates and onboarding output do not expose real credentials;
+  onboarding also omits configured resource values. Workspace-external specs
+  never expose absolute local paths in SARIF.
+- Validation and dry-run remain offline; dry-run sends zero requests. No active
+  POST / PUT testing or automated OAuth / login is added.
+
+### Quality
+
+- Retain the 486-test baseline, Python 3.9 / 3.12 / 3.14 CI, blocking mypy and Ruff,
+  Runtime dependency audit, CodeQL and the branch-aware coverage gate of 80%.
+- Fresh release-prep acceptance passes all 486 tests with **82.78%** branch-aware
+  local coverage, mypy reporting no issues in 18 source files, Ruff and the runtime
+  dependency audit. All six bundled business scenarios match their expected
+  outcomes; JSON / YAML scans restore the full mock database. A fresh wheel
+  installed outside the checkout passes both demo modes and verifies version
+  `2.5.0`, read-only 0 PATCH, active rollback and local server shutdown. See
+  [VERIFICATION.md](VERIFICATION.md) for the exact scope and remote check results.
+
+## 2.4.1 - 2026-10-03
+
+### Added
+
+- Add `granttrace demo` with packaged OpenAPI, configuration and fictional mock
+  data, so an installed wheel can demonstrate identity comparison, BOLA / IDOR,
+  Mass Assignment, independent readback and rollback verification outside a Git
+  checkout without user credentials or external API access.
+- Start the disposable mock on a dynamic loopback port, close it on completion
+  or failure, and retain HTML / JSON reports in a unique output directory.
+- Add `--output-dir` and optional `--read-only` controls for the built-in demo.
+
+### Changed
+
+- Put the single-command installed-package demo before the source-checkout
+  walkthrough and retain configuration onboarding and safety boundaries. During
+  release preparation, distinguish the upcoming package from the published stable
+  version and do not claim an unpublished PyPI release is available.
+- Give missing spec/config files and offline configuration failures a concise
+  next step; an empty write allowlist still sends no PATCH requests.
+- Promote the 2.4.1.dev0 development package to 2.4.1 consistently across runtime,
+  package metadata and generated reports; update the release acceptance checklist.
+
+### Quality
+
+- Resolve the existing 20 mypy errors in six files using accurate annotations and
+  type narrowing, without new suppression directives or weaker mypy settings.
+- Make mypy a blocking CI check and add a minimum 80% branch-aware coverage gate.
+- Add weekly Dependabot checks for pip dependencies and GitHub Actions, without
+  automatic merging; exclude the release workflow from dependency updates.
+- Verify installed demo resources, source-independent startup, both demo modes,
+  complete database restoration and local server shutdown.
+
+### Security / Safety
+
+- The demo accepts no external target or user credentials. Its active PATCH checks
+  run only against bundled, disposable data on a dynamic `127.0.0.1` server.
+- Keep auditing users' own APIs read-only by default; `granttrace demo --read-only`
+  sends no PATCH requests.
+- Preserve the BOLA / IDOR and Mass Assignment detection criteria, explicit write
+  allowlists, independent GET readback, original-state snapshots and rollback
+  verification. Failed recovery still blocks subsequent writes.
+- Keep the existing `granttrace --spec ...` CLI, TLS / HTTP / redirect / proxy
+  safety boundaries and evidence minimisation unchanged.
+
 ## 2.4.0 - 2026-10-03
 
 ### Added

{granttrace-2.4.0 → granttrace-2.5.0}/CONTRIBUTING.md

@@ -28,7 +28,7 @@ python -m coverage xml
 python -m coverage json
 ```
 
-Mypy is advisory while existing dynamic JSON type issues are tracked:
+Mypy is a blocking CI check and must report zero errors; coverage must be at least 80%:
 
 ```bash
 python -m mypy

{granttrace-2.4.0/granttrace.egg-info → granttrace-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: granttrace
-Version: 2.4.0
+Version: 2.5.0
 Summary: Safety-first OpenAPI authorization auditing tool for BOLA, IDOR and Mass Assignment testing
 Author: GrantTrace contributors
 License-Expression: Apache-2.0
@@ -31,7 +31,7 @@ Dynamic: license-file
 ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
 ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
-**Stable:** [v2.4.0](https://github.com/ysc070528/granttrace/releases/tag/v2.4.0)
+**Release source:** v2.5.0 · [GitHub Releases](https://github.com/ysc070528/granttrace/releases) · [PyPI](https://pypi.org/project/granttrace/)
 
 An OpenAPI authorization auditor that compares identities, verifies persisted changes, and reports restoration evidence.
 
@@ -49,49 +49,96 @@ An OpenAPI authorization auditor that compares identities, verifies persisted ch
 
 ## 五分钟体验
 
-需要 Python 3.9+。在终端中克隆、安装并启动本机演示服务：
+需要 Python 3.9+。最新发布与可安装版本以 [GitHub Releases](https://github.com/ysc070528/granttrace/releases) 和 [PyPI](https://pypi.org/project/granttrace/) 为准。安装包包含内置 `granttrace demo`，首次体验只需：
 
 ```bash
-git clone https://github.com/ysc070528/granttrace.git
-cd granttrace
-python -m pip install -e .
-python mock_server/server.py
+python -m pip install --upgrade granttrace
+granttrace --version
+granttrace demo
 ```
 
-另开终端，进入同一目录执行首次只读扫描：
+安装后可在任意目录运行，无需 clone、准备配置、另开终端或访问外部 API。Demo 自动启动动态端口的 `127.0.0.1` 靶场，比较身份访问、演示 BOLA / IDOR 与 Mass Assignment，并通过独立读回与恢复核验展示 PATCH 测试证据。**主动写操作仅发生在内置、可丢弃的本机靶场**；demo 不接受外部 target 或用户凭据，结束时关闭靶场。
+
+HTML / JSON 报告保留在当前目录的 `granttrace-demo/` 唯一子目录，终端会输出绝对路径，不覆盖已有报告。可选用 `granttrace demo --output-dir PATH` 指定报告父目录，或 `granttrace demo --read-only` 仅体验只读身份访问，发送 **0 PATCH**。
+
+完整离线示例：[HTML 报告](examples/sample_report.html)（下载后用浏览器打开）与 [JSON 结果](examples/sample_result.json)。
+
+## 接入自己的 API
+
+推荐按以下顺序首次接入；前四步只处理本地文件：
+
+1. **生成草稿和清单**：
 
 ```bash
-granttrace --spec openapi.json --target http://127.0.0.1:8080 --config config.example.json --export-json result.local.json
+granttrace --spec your-openapi.yaml --init-config config.local.json
 ```
 
-用浏览器打开默认生成的 **`granttrace_report.html`**：先查看发现与修复建议，再按状态筛选端点、展开证据。预期结果为 **1 个 CONFIRMED、1 个 PUBLIC、1 个 SECURE、2 个 SKIPPED**，确定性覆盖率 **60%**。两个 PATCH 因默认只读而跳过。JSON 结果写入 `result.local.json`；两个本地产物均由 `.gitignore` 忽略。
+2. **人工填写并核对**：打开配置和 checklist，填写不同的 Owner / Visitor 测试账户、可丢弃资源与业务授权预期。候选 PATCH 字段和 GET 路径只是接口合同提示；确认所需读回映射，删除不用的读回草稿，替换全部 `__GRANTTRACE_INPUT__:` 占位值，最后移除 `_granttrace_draft`。草稿未完成时会阻止验证、计划与扫描；`write_allowlist` 默认为空。
 
-在这个可丢弃的本地靶场体验写测试和恢复核验：
+3. **离线验证配置与规范**，检查终端中的 scope、模式、警告和下一步：
 
 ```bash
-granttrace --spec openapi.json --target http://127.0.0.1:8080 --config config.example.json --allow-write-tests --export-json result.local.json
+granttrace --spec your-openapi.yaml --config config.local.json --validate-config
 ```
 
-再次打开 **`granttrace_report.html`**。预期 **2 个 CONFIRMED、1 个 PUBLIC、2 个 SECURE**，确定性覆盖率 **100%**，批量赋值发现的 `rollback_verified` 为 `true`。本次扫描更新同名 HTML / JSON 文件；这些结果只属于内置五个演示端点。
+4. **生成并人工检查本地计划**；dry-run 发送 **0 请求**：
 
-完整离线示例：[HTML 报告](examples/sample_report.html)（下载后用浏览器打开）与 [JSON 结果](examples/sample_result.json)。
+```bash
+granttrace --spec your-openapi.yaml --config config.local.json --dry-run --export-json plan.local.json
+```
 
-## 接入自己的 API
+5. **第一次真实扫描保持只读**：确认计划后，将下例地址替换为已授权的测试目标；这一步会发送读取请求，默认 **0 PATCH**。
+
+```bash
+granttrace --spec your-openapi.yaml --target https://authorized-test.example \
+  --config config.local.json --export-json result.local.json
+```
+
+6. **以后需要时再考虑主动 PATCH**：只有在专用可丢弃资源、独立 GET readback、字段映射、一致性和恢复路径均经人工确认后，才配置明确的 `write_allowlist` 并在真实扫描中单独添加 `--allow-write-tests`。允许清单存在不表示写测试已开启，运行时仍须满足写入与恢复条件。
 
-先从规范生成配置草稿和待填清单：
+OpenAPI 和离线验证不能证明资源归属、业务授权策略、合法测试权限、生产读回一致性或实际恢复能力；检查通过只代表配置结构及支持的语义通过当前检查。账户、API Key / Cookie、合法共享和管理员访问见 [配置指南](docs/configuration.md)，输出与自动化兼容性见 [命令行说明](docs/advanced.md)。支持的数组、布尔值及 `style` / `explode` 编码见 [参数规则](docs/parameter-serialization.md)。接入实测前请核对 [安全边界](SECURITY.md)。
+
+## SARIF 导出
+
+`--export-sarif PATH` 可与 HTML / JSON 同时使用：
 
 ```bash
-granttrace --spec your-openapi.yaml --init-config config.local.json
+granttrace --spec your-openapi.yaml --config config.local.json \
+  --export-json result.local.json --export-sarif granttrace.sarif -o report.html
 ```
 
-填写不同的测试账户、各自资源、授权预期和必要读回信息，再按清单移除草稿标记与全部占位值。草稿未完成时会阻止预检、计划与扫描；写允许清单默认为空。
+SARIF 2.1.0 **只包含 CONFIRMED 的 BOLA / IDOR 与 Mass Assignment**；SUSPICIOUS / INCONCLUSIVE 不升级为漏洞，完整状态仍见 HTML / JSON。SARIF 始终脱敏且不导出原始响应或 headers，不能与 `--dry-run` 同用；各输出路径须独立。当前工作目录内的真实 OpenAPI spec 会作为相对 artifact location，不伪造源码行号，API endpoint 仍放在 message / properties。在 GitHub Actions 中从 checkout 的仓库根目录运行，再用 `upload-sarif` 上传；workspace 外的 spec 省略 location，绝不导出本机绝对路径，其结果无法展示为 GitHub Code Scanning alert。详见 [兼容说明](docs/advanced.md#sarif-导出)。
+
+## cURL 复现模板
+
+HTML 确认漏洞卡片可提供安全的 POSIX shell cURL 模板和“复制 cURL”按钮。所有认证值均为 Visitor 占位符，即使使用 `--include-sensitive-evidence` 也不会放入模板。请只在明确授权的测试环境中填入自己的测试凭据；脱敏值需人工补全，信息不足时不提供按钮。离线报告支持复制 fallback，也可直接选择命令文本。详见 [复现说明](docs/advanced.md#curl-复现模板)。
+
+## 从源码开发 / 运行仓库 mock
+
+需要查看源码或手工运行仓库靶场时：
 
 ```bash
-granttrace --spec your-openapi.yaml --config config.local.json --validate-config
-granttrace --spec your-openapi.yaml --config config.local.json --dry-run --export-json plan.local.json
+git clone https://github.com/ysc070528/granttrace.git
+cd granttrace
+python -m pip install -e .
+python mock_server/server.py
+```
+
+另开终端，进入同一目录执行首次只读扫描：
+
+```bash
+granttrace --spec openapi.json --target http://127.0.0.1:8080 --config config.example.json --export-json result.local.json
+```
+
+用浏览器打开默认生成的 **`granttrace_report.html`**：先查看发现与修复建议，再按状态筛选端点、展开证据。预期结果为 **1 个 CONFIRMED、1 个 PUBLIC、1 个 SECURE、2 个 SKIPPED**，确定性覆盖率 **60%**。两个 PATCH 因默认只读而跳过。JSON 结果写入 `result.local.json`；两个本地产物均由 `.gitignore` 忽略。
+
+在这个可丢弃的本地靶场体验写测试和恢复核验：
+
+```bash
+granttrace --spec openapi.json --target http://127.0.0.1:8080 --config config.example.json --allow-write-tests --export-json result.local.json
 ```
 
-账户、API Key / Cookie、合法共享和管理员访问配置见 [配置指南](docs/configuration.md)。支持的数组、布尔值及 `style` / `explode` 编码见 [参数规则](docs/parameter-serialization.md)。接入实测前请核对 [安全边界](SECURITY.md)。
+再次打开 **`granttrace_report.html`**。预期 **2 个 CONFIRMED、1 个 PUBLIC、2 个 SECURE**，确定性覆盖率 **100%**，批量赋值发现的 `rollback_verified` 为 `true`。本次扫描更新同名 HTML / JSON 文件；这些结果只属于内置五个演示端点。
 
 ## 验证与边界
 

granttrace-2.5.0/README.md

@@ -0,0 +1,128 @@
+# GrantTrace
+
+![CI](https://github.com/ysc070528/granttrace/actions/workflows/test.yml/badge.svg)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-Apache--2.0-green)
+
+**Release source:** v2.5.0 · [GitHub Releases](https://github.com/ysc070528/granttrace/releases) · [PyPI](https://pypi.org/project/granttrace/)
+
+An OpenAPI authorization auditor that compares identities, verifies persisted changes, and reports restoration evidence.
+
+安全优先、证据驱动的 OpenAPI 权限审计工具。检查 BOLA / IDOR 与 Mass Assignment，输出身份对比、持久化变更及恢复核验的 HTML / JSON 报告。默认只读；主动写测试须显式开启并配置允许清单与独立读回。
+
+[五分钟体验](#五分钟体验) · [完整示例报告](examples/sample_report.html) · [配置指南](docs/configuration.md) · [命令行与迁移](docs/advanced.md) · [验收记录](VERIFICATION.md) · [发布自检](docs/release-checklist.md)
+
+## 为什么是 GrantTrace / Why GrantTrace
+
+- **Compare identities**：比较 Owner / Visitor / Anonymous 等身份访问同一资源的结果。
+- **Verify real side effects**：通过独立读回验证状态是否真正持久化，不只看 HTTP 状态码。
+- **Restore safely**：主动 PATCH 测试使用显式 allowlist、原始状态快照、恢复与恢复验证。
+
+<img src="docs/assets/report-preview.png" alt="GrantTrace 报告：身份访问摘要、修复建议和端点筛选" width="900">
+
+## 五分钟体验
+
+需要 Python 3.9+。最新发布与可安装版本以 [GitHub Releases](https://github.com/ysc070528/granttrace/releases) 和 [PyPI](https://pypi.org/project/granttrace/) 为准。安装包包含内置 `granttrace demo`，首次体验只需：
+
+```bash
+python -m pip install --upgrade granttrace
+granttrace --version
+granttrace demo
+```
+
+安装后可在任意目录运行，无需 clone、准备配置、另开终端或访问外部 API。Demo 自动启动动态端口的 `127.0.0.1` 靶场，比较身份访问、演示 BOLA / IDOR 与 Mass Assignment，并通过独立读回与恢复核验展示 PATCH 测试证据。**主动写操作仅发生在内置、可丢弃的本机靶场**；demo 不接受外部 target 或用户凭据，结束时关闭靶场。
+
+HTML / JSON 报告保留在当前目录的 `granttrace-demo/` 唯一子目录，终端会输出绝对路径，不覆盖已有报告。可选用 `granttrace demo --output-dir PATH` 指定报告父目录，或 `granttrace demo --read-only` 仅体验只读身份访问，发送 **0 PATCH**。
+
+完整离线示例：[HTML 报告](examples/sample_report.html)（下载后用浏览器打开）与 [JSON 结果](examples/sample_result.json)。
+
+## 接入自己的 API
+
+推荐按以下顺序首次接入；前四步只处理本地文件：
+
+1. **生成草稿和清单**：
+
+```bash
+granttrace --spec your-openapi.yaml --init-config config.local.json
+```
+
+2. **人工填写并核对**：打开配置和 checklist，填写不同的 Owner / Visitor 测试账户、可丢弃资源与业务授权预期。候选 PATCH 字段和 GET 路径只是接口合同提示；确认所需读回映射，删除不用的读回草稿，替换全部 `__GRANTTRACE_INPUT__:` 占位值，最后移除 `_granttrace_draft`。草稿未完成时会阻止验证、计划与扫描；`write_allowlist` 默认为空。
+
+3. **离线验证配置与规范**，检查终端中的 scope、模式、警告和下一步：
+
+```bash
+granttrace --spec your-openapi.yaml --config config.local.json --validate-config
+```
+
+4. **生成并人工检查本地计划**；dry-run 发送 **0 请求**：
+
+```bash
+granttrace --spec your-openapi.yaml --config config.local.json --dry-run --export-json plan.local.json
+```
+
+5. **第一次真实扫描保持只读**：确认计划后，将下例地址替换为已授权的测试目标；这一步会发送读取请求，默认 **0 PATCH**。
+
+```bash
+granttrace --spec your-openapi.yaml --target https://authorized-test.example \
+  --config config.local.json --export-json result.local.json
+```
+
+6. **以后需要时再考虑主动 PATCH**：只有在专用可丢弃资源、独立 GET readback、字段映射、一致性和恢复路径均经人工确认后，才配置明确的 `write_allowlist` 并在真实扫描中单独添加 `--allow-write-tests`。允许清单存在不表示写测试已开启，运行时仍须满足写入与恢复条件。
+
+OpenAPI 和离线验证不能证明资源归属、业务授权策略、合法测试权限、生产读回一致性或实际恢复能力；检查通过只代表配置结构及支持的语义通过当前检查。账户、API Key / Cookie、合法共享和管理员访问见 [配置指南](docs/configuration.md)，输出与自动化兼容性见 [命令行说明](docs/advanced.md)。支持的数组、布尔值及 `style` / `explode` 编码见 [参数规则](docs/parameter-serialization.md)。接入实测前请核对 [安全边界](SECURITY.md)。
+
+## SARIF 导出
+
+`--export-sarif PATH` 可与 HTML / JSON 同时使用：
+
+```bash
+granttrace --spec your-openapi.yaml --config config.local.json \
+  --export-json result.local.json --export-sarif granttrace.sarif -o report.html
+```
+
+SARIF 2.1.0 **只包含 CONFIRMED 的 BOLA / IDOR 与 Mass Assignment**；SUSPICIOUS / INCONCLUSIVE 不升级为漏洞，完整状态仍见 HTML / JSON。SARIF 始终脱敏且不导出原始响应或 headers，不能与 `--dry-run` 同用；各输出路径须独立。当前工作目录内的真实 OpenAPI spec 会作为相对 artifact location，不伪造源码行号，API endpoint 仍放在 message / properties。在 GitHub Actions 中从 checkout 的仓库根目录运行，再用 `upload-sarif` 上传；workspace 外的 spec 省略 location，绝不导出本机绝对路径，其结果无法展示为 GitHub Code Scanning alert。详见 [兼容说明](docs/advanced.md#sarif-导出)。
+
+## cURL 复现模板
+
+HTML 确认漏洞卡片可提供安全的 POSIX shell cURL 模板和“复制 cURL”按钮。所有认证值均为 Visitor 占位符，即使使用 `--include-sensitive-evidence` 也不会放入模板。请只在明确授权的测试环境中填入自己的测试凭据；脱敏值需人工补全，信息不足时不提供按钮。离线报告支持复制 fallback，也可直接选择命令文本。详见 [复现说明](docs/advanced.md#curl-复现模板)。
+
+## 从源码开发 / 运行仓库 mock
+
+需要查看源码或手工运行仓库靶场时：
+
+```bash
+git clone https://github.com/ysc070528/granttrace.git
+cd granttrace
+python -m pip install -e .
+python mock_server/server.py
+```
+
+另开终端，进入同一目录执行首次只读扫描：
+
+```bash
+granttrace --spec openapi.json --target http://127.0.0.1:8080 --config config.example.json --export-json result.local.json
+```
+
+用浏览器打开默认生成的 **`granttrace_report.html`**：先查看发现与修复建议，再按状态筛选端点、展开证据。预期结果为 **1 个 CONFIRMED、1 个 PUBLIC、1 个 SECURE、2 个 SKIPPED**，确定性覆盖率 **60%**。两个 PATCH 因默认只读而跳过。JSON 结果写入 `result.local.json`；两个本地产物均由 `.gitignore` 忽略。
+
+在这个可丢弃的本地靶场体验写测试和恢复核验：
+
+```bash
+granttrace --spec openapi.json --target http://127.0.0.1:8080 --config config.example.json --allow-write-tests --export-json result.local.json
+```
+
+再次打开 **`granttrace_report.html`**。预期 **2 个 CONFIRMED、1 个 PUBLIC、2 个 SECURE**，确定性覆盖率 **100%**，批量赋值发现的 `rollback_verified` 为 `true`。本次扫描更新同名 HTML / JSON 文件；这些结果只属于内置五个演示端点。
+
+## 验证与边界
+
+```bash
+python -m unittest discover -s tests
+python scripts/verify_business_scenarios.py
+python scripts/verify_install.py
+```
+
+测试直接使用仓库中的 `config.example.json`，无需创建本地凭据文件。[业务场景验收](docs/business-scenarios.md) 单独记录团队共享、管理员读取、跨租户拒绝和故意越权的真值、误报与漏报；[验收记录](VERIFICATION.md) 标明实际测试环境和范围。
+
+“没有确认漏洞”不等于系统安全。检查覆盖率、错误、可疑和不确定项；显式授权预期只适用于本次身份与资源组合。仅在具备专用测试账户、独立读回和恢复方案的隔离环境启用写测试。远程 `$ref`、GraphQL、gRPC、自动 OAuth / mTLS 登录以及 POST / PUT 主动测试尚未实现。更多规则与迁移说明见 [操作指南](docs/advanced.md)。
+
+Apache License 2.0。

{granttrace-2.4.0 → granttrace-2.5.0}/VERIFICATION.md

@@ -1,5 +1,172 @@
 # GrantTrace 验收记录
 
+## 2026-10-04 v2.5.0 发布前验收
+
+这是 **发布前验收**，不表示 v2.5.0 已在 GitHub Release 或 PyPI 发布。
+Base main commit 为
+[`7e40de4d5c2b1ff7e2d8e01b7a36c0366a1d3bec`](https://github.com/ysc070528/granttrace/commit/7e40de4d5c2b1ff7e2d8e01b7a36c0366a1d3bec)，
+Release Prep 分支为 `codex/v2.5.0-release`，源码版本统一为 `2.5.0`。
+v2.5.0 功能已经冻结；本轮只提升正式版本、同步文档与生成示例、扩展历史保留的
+manual release option，并重新执行验收，不新增功能或重构检测代码。
+
+### 已合并的功能与安全范围
+
+- SARIF 2.1.0：`--export-sarif` 只导出 CONFIRMED，BOLA / IDOR 对应
+  `GT-BOLA-001` / `CWE-639`，Mass Assignment 对应 `GT-MASS-001` / `CWE-915`。
+  workspace 内的 OpenAPI spec 提供安全相对 artifact location，不虚构源码行号；
+  外部 spec 不泄漏绝对路径。保留凭据脱敏及 dry-run 禁止 SARIF 的边界。
+- 安全 cURL：confirmed finding 卡片保留凭据占位符、POSIX 引用、`curl --globoff`、
+  已确认的安全 URL / payload / Content-Type，以及离线复制 fallback。
+  `--include-sensitive-evidence` 不解除 cURL 凭据限制。
+- 配置引导：保留草稿阻断、人工核对、config-only / spec-aware 范围区分、离线计划
+  和首次只读扫描建议；allowlist 存在不等于启用 PATCH，引导不展示凭据或资源值。
+- BOLA / IDOR / Mass Assignment 的判定、ConfigValidator、默认只读、显式 write
+  allowlist、独立 GET readback、snapshot、rollback verification、恢复失败停写、
+  TLS / HTTP / redirect / proxy 和 loopback demo 安全边界均未修改。
+  没有新增 POST / PUT 主动测试、自动 OAuth / login 或其他检测能力。
+
+### 本轮实际本地执行
+
+本地 Windows / Python 3.14.5 重新执行，未引用旧功能 PR 的绿灯作为本轮结果：
+
+| 检查 | 实际结果 |
+|---|---|
+| `python -m unittest discover -s tests` | **486 passed**，0 failures / errors / skipped；未删除或跳过测试，仅同步一处当前版本断言 |
+| mypy | `Success: no issues found in 18 source files`，**0 errors** |
+| Ruff | `All checks passed!` |
+| coverage erase / run / report / xml / json | 总覆盖率 **82.78%**；保留 branch-aware source 范围和 `fail_under = 80` |
+| 业务场景 | **6/6** 本机模型符合预期：团队共享、租户管理员为 AUTHORIZED；未共享、跨租户隔离为 SECURE；两种泄漏为 CONFIRMED |
+| 官方 examples 脚本 | 先 `--update-examples`，再不带更新参数复验；JSON / YAML 和完整数据库恢复通过 |
+| read-only example | 1 CONFIRMED、1 PUBLIC、1 SECURE、2 SKIPPED，conclusive coverage 60% |
+| active JSON / YAML | 2 CONFIRMED、1 PUBLIC、2 SECURE，conclusive coverage 100%，Mass Assignment rollback_verified=true |
+| `verify_install.py` | fresh 2.5.0 wheel 在源码目录外的新虚拟环境安装通过；CLI、metadata、JSON/YAML plan、草稿阻断与安装资源通过 |
+| 安装后版本链 | CLI 为 `GrantTrace 2.5.0`；project / runtime / wheel / installed metadata / JSON 均为 `2.5.0`；HTML 为 `v2.5.0`；实际 HTTP User-Agent 为 `GrantTrace/2.5.0` |
+| installed read-only demo | **0 PATCH**，database_restored=true、server_stopped=true |
+| installed active demo | 1 BOLA、1 Mass Assignment CONFIRMED；rollback_verified=true、database_restored=true、server_stopped=true；动态 127.0.0.1 端口正常关闭 |
+| 安装后用户扫描 / 本地计划 | 默认扫描 **0 PATCH**；主动扫描独立读回和完整恢复通过；offline plan requests_sent=0 |
+| pip check / 本地 strict pip-audit | 无依赖冲突；`No known vulnerabilities found`，未忽略漏洞或降低审计要求 |
+| build / twine | 清理已核对的旧构建范围后执行 `python -m build`；2.5.0 wheel / sdist 生成，`twine check --strict` 均 PASSED |
+| wheel / sdist 内容 | Name=granttrace、Version=2.5.0、Python>=3.9、Apache-2.0、PyYAML>=6.0 与 CLI entry point 正确；demo assets、SARIF / cURL / onboarding 模块以及 sdist 的 docs / examples / scripts 完整 |
+| 发行物卫生 | 检查包内文件名与实际主机路径变体，未发现缓存、私有配置、临时报告、.git、真实主机用户名或本机路径；原有虚构 mock 凭据和隐私回归路径 fixture 保留，不将通用 secret scanner 宣称为绝对保证 |
+| 安装后 SARIF 本机扫描 | SARIF 2.1.0 / driver 2.5.0；只读 1 result、主动 2 results，仅 CONFIRMED，两个 rule/CWE 正确；location 为 openapi.json，无伪造行号、凭据或绝对路径；两个输出通过官方 OASIS SARIF 2.1.0 schema |
+| 安装后 cURL 报告 | 2 份 confirmed 模板，BOLA GET / Mass Assignment PATCH；真实测试 URL、application/json、已确认 role=admin payload 与自定义 Visitor 凭据占位符正确，无 demo 原始认证值 |
+| 安装后离线引导 | 实际 init/validate/dry-run：socket / DNS / HTTP 调用计数均为 0；生成空 allowlist 草稿和 checklist、spec-aware 说明及只读下一步，plan requests_sent=0 |
+| 报告复制 fallback | 实际生成的 JavaScript 在 Node 离线 DOM harness 中通过无 Clipboard API 成功/失败与 API reject fallback 三种模式；此验证不是浏览器 UI 验收 |
+
+两个生成示例只由 `scripts/verify_examples.py --update-examples` 更新；版本、时间和
+动态 loopback 端口更新不改变业务结果。构建 SHA-256 只用于 PR branch pre-release
+资产检查；最终 Release 资产必须基于最终合并 / tagged commit 重新构建或核实，不能
+把本轮分支的 hash 当作最终发布 hash。
+
+### 本轮首次远程发布准备验收
+
+[PR #23](https://github.com/ysc070528/granttrace/pull/23) 的 release-prep commit
+`ce84a0b11a5e1450aea7fb6698a5cdaa46e6e86f` 已实际通过
+[GrantTrace CI](https://github.com/ysc070528/granttrace/actions/runs/37192301259) 与
+[CodeQL](https://github.com/ysc070528/granttrace/actions/runs/37192301260)：
+
+| Python job | unittest | branch-aware coverage | business / examples / install |
+|---|---|---|---|
+| 3.9 | 486 passed | 82.77% | 全部成功 |
+| 3.12 | 486 passed | 82.78% | 全部成功 |
+| 3.14 | 486 passed | 82.78% | 全部成功 |
+
+远程 Mypy 为 0 errors（18 个源码文件），Ruff、Runtime dependency audit、
+Analyze Python 和 CodeQL 全部成功；审计未发现已知漏洞。
+三个版本的安装验收均确认 2.5.0 metadata、read-only demo 0 PATCH，以及主动 demo
+rollback_verified / database_restored / server_stopped 均为 true。
+这是上述 commit 的真实执行记录。补入证据后最终 PR HEAD 仍须重新通过门禁，
+最新结果以 PR #23 的 Checks 为准，不将本记录当作合并后的 main 验收。
+
+### 发布工作流与证据边界
+
+release.yml 仅修改 manual default、choices、allowlist 和对应错误说明，支持 v2.5.0
+并保留 v2.4.0 / v2.4.1。YAML 解析、4 段内嵌 Python 编译及 **35 组隔离校验**通过；
+外部 HTTP / git 输出均 mock，0 真实网络调用、0 发布动作。本机没有 actionlint，未下载 binary。
+官方 stable Release、tag/source commit、project/runtime/distribution metadata、SHA256、
+build/publish 分离、`pypi` environment、OIDC 和 v2.4.0 固定 commit 校验保持原样。
+
+PowerShell 引用的本轮单元测试通过；此记录不宣称 PowerShell 7 真实命令执行通过。
+六个业务模型与 demo 只证明所列本机 fixture 结果，不代表生产 API 检测率或零误报。
+所有目标为隔离本机 mock，凭据为虚构数据，不使用真实生产 API 或凭据。
+最终合并后的 main commit 与 CI / CodeQL 仍须由维护者在正式发布前复核。
+本轮 Release Prep PR 保持开放，未合并，未创建 tag / GitHub Release，未发布 PyPI。
+下方 v2.4.1 及更早版本的验收原文完整保留。
+
+## 2026-10-04 v2.4.1 正式发布验收
+
+发布时 final main commit 为
+[`8ba6cb46c9bbd670449989a5bd54fb233543d81f`](https://github.com/ysc070528/granttrace/commit/8ba6cb46c9bbd670449989a5bd54fb233543d81f)。
+[Release Prep PR #18](https://github.com/ysc070528/granttrace/pull/18) 已合并，
+annotated tag `v2.4.1` 最终解析到该 commit。
+
+### 正式发布证据
+
+- [GitHub Release “GrantTrace v2.4.1”](https://github.com/ysc070528/granttrace/releases/tag/v2.4.1)
+  已正式发布，非 draft、非 prerelease。附件包括
+  `granttrace-2.4.1-py3-none-any.whl`、`granttrace-2.4.1.tar.gz` 和 `SHA256SUMS`。
+- [Publish to PyPI 工作流](https://github.com/ysc070528/granttrace/actions/runs/37175522087)
+  成功，[PyPI 2.4.1](https://pypi.org/project/granttrace/2.4.1/) 已可安装。
+  使用 OIDC Trusted Publishing，owner 为 `ysc070528`、repository 为
+  `granttrace`、workflow 为 `release.yml`、environment 为 `pypi`。
+  [PyPI 发布者 provenance](https://pypi.org/integrity/granttrace/2.4.1/granttrace-2.4.1-py3-none-any.whl/provenance)
+  与上述配置一致，未使用 PyPI Token 或用户名/密码。
+- 发布 commit 的 [main CI](https://github.com/ysc070528/granttrace/actions/runs/37137142692)
+  与 [CodeQL](https://github.com/ysc070528/granttrace/actions/runs/37137142656)
+  均成功；Python 3.9 / 3.12 / 3.14 测试通过。
+- `main` Branch Protection 的 required checks 包含 **Mypy**；mypy 是正式
+  blocking 门禁，coverage 的 `fail_under = 80` 保持启用。
+
+### 正式测试与 demo 基线
+
+| 检查 | 实际结果 |
+|---|---|
+| Python 3.9 / 3.12 / 3.14 unittest | 每个版本均 **304 项通过**，0 failures / errors / skipped |
+| mypy | **0 errors**，15 个源码文件无诊断 |
+| Ruff / Runtime dependency audit / CodeQL | 全部 passed |
+| 真实 unittest 总覆盖率（语句与分支） | Python 3.9：**80.85%**；Python 3.12 / 3.14：**80.83%**，均达到 >=80% 门槛 |
+| 正式 wheel 独立安装 | 在源码目录外的新虚拟环境验证，CLI 为 `GrantTrace 2.4.1`，metadata / HTML / JSON / User-Agent 版本一致 |
+| `granttrace demo --read-only` | **0 PATCH**；数据库保持初始状态，`database_restored=true`、`server_stopped=true` |
+| `granttrace demo` | BOLA / IDOR 与 Mass Assignment 演示正常；独立 GET readback、`rollback_verified=true`、`database_restored=true`、`server_stopped=true` |
+| demo 安全范围 | 只使用动态 `127.0.0.1` 靶场，不接受外部 target，不使用用户凭据；完成后服务端口不可连接 |
+
+本次发布未改变 BOLA / IDOR / Mass Assignment 判定语义或安全边界。
+用户 API 扫描仍默认只读；主动 PATCH 仍受显式允许、write allowlist、
+独立 GET readback、状态快照和 rollback verification 限制，恢复失败继续阻断写入。
+验收只使用虚构数据和隔离本机靶场，不访问生产 API 或使用真实生产凭据。
+
+下方“2026-10-03 2.4.1.dev0 内置 demo 验收”及其后的章节均为历史记录；
+其中“当前”“未发布”“advisory”等表述指各轮记录当时的状态，历史原文完整保留。
+
+## 2026-10-03 2.4.1.dev0 内置 demo 验收
+
+本轮仅改善安装后的首次体验，稳定版仍为 v2.4.0，开发版本为
+2.4.1.dev0；本记录不表示开发版已发布。原检测语义、配置验证规则和
+PATCH allowlist / 独立读回 / 回滚限制保持不变，兼容入口保留。
+
+本地 Windows / Python 3.14.5 实际验证结果：
+
+- 完整 unittest 与 coverage 运行均为 **304 项通过**，0 失败、0 错误、
+  0 跳过，其中新增 27 项 demo 测试、9 项首次使用提示测试。
+- 总覆盖率 **80.85%**，语句 **83.78%**，分支 **75.17%**；分别高于
+  之前的 79.66% / 82.66% / 74.02%。
+- 业务场景、JSON / YAML 示例、真实 wheel 安装脚本全部通过；Ruff、
+  pip check 与严格 pip-audit 通过，未发现已知运行依赖漏洞。
+- mypy 仍为 **20 个问题 / 6 个文件**，新增 demo 未增加类型诊断；保持 advisory。
+- 全新虚拟环境在仓库外的空目录安装 wheel，未复制任何仓库文件，
+  `granttrace demo` 成功；环境代理被绕过，靶场只绑定动态 127.0.0.1 端口。
+- 完整 demo 为 **1 BOLA / IDOR + 1 Mass Assignment**；独立 GET 读回、
+  `rollback_verified`、整库恢复与服务器关闭均成功。只读 demo 未发送 PATCH。
+- HTML / JSON 报告保留在唯一 run 子目录，不覆盖旧文件；本地安装验收
+  证据另存于被忽略的 `dist/demo-validation/`。
+- 异常回归包含构造/启动/ready 失败、JSON 与报告错误、真实 PATCH 后
+  KeyboardInterrupt、读回失败后恢复、回滚证据缺失与整库残留；均可靠关闭
+  靶场，恢复失败或证据不足不会显示 demo 成功。
+
+Python 3.9 / 3.12 / 3.14 与 CodeQL 的远程结果以本轮 PR 的实际检查为准。
+本轮只创建 PR 供审查，不合并、不创建 tag、不发布 GitHub Release 或 PyPI。
+以下历史记录完整保留。
+
 ## 2026-10-03 v2.4.0 发布前验收
 
 本轮在已合并 PR #11 的最新 `main`（`4b65e54`）基础上创建