granttrace 2.4.1__tar.gz → 2.5.0__tar.gz

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

@@ -1,5 +1,61 @@
 # 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

{granttrace-2.4.1 → granttrace-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: granttrace
-Version: 2.4.1
+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,8 +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 prep:** v2.4.1 (not yet released)
+**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.
 
@@ -50,42 +49,69 @@ An OpenAPI authorization auditor that compares identities, verifies persisted ch
 
 ## 五分钟体验
 
-需要 Python 3.9+。**v2.4.1 正在准备发布，尚未发布到 PyPI**；当前稳定版 v2.4.0 暂不支持 `demo`。v2.4.1 正式发布到 PyPI 后，首次体验只需：
+需要 Python 3.9+。最新发布与可安装版本以 [GitHub Releases](https://github.com/ysc070528/granttrace/releases) 和 [PyPI](https://pypi.org/project/granttrace/) 为准。安装包包含内置 `granttrace demo`，首次体验只需：
 
 ```bash
-pip install granttrace
-granttrace demo
-```
-
-审查当前发布准备分支时，先安装本轮构建的 wheel，再运行同一条 demo 命令：
-
-```bash
-python -m pip install dist/granttrace-2.4.1-py3-none-any.whl
+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` 仅体验只读身份访问。
+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
 ```
 
-接入自己的 API 时仍默认只读，主动 PATCH 测试必须显式开启并满足 allowlist、独立 readback 和恢复条件。账户、API Key / Cookie、合法共享和管理员访问配置见 [配置指南](docs/configuration.md)。支持的数组、布尔值及 `style` / `explode` 编码见 [参数规则](docs/parameter-serialization.md)。接入实测前请核对 [安全边界](SECURITY.md)。
+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
 

{granttrace-2.4.1 → granttrace-2.5.0}/README.md

@@ -4,8 +4,7 @@
 ![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 prep:** v2.4.1 (not yet released)
+**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.
 
@@ -23,42 +22,69 @@ An OpenAPI authorization auditor that compares identities, verifies persisted ch
 
 ## 五分钟体验
 
-需要 Python 3.9+。**v2.4.1 正在准备发布，尚未发布到 PyPI**；当前稳定版 v2.4.0 暂不支持 `demo`。v2.4.1 正式发布到 PyPI 后，首次体验只需：
+需要 Python 3.9+。最新发布与可安装版本以 [GitHub Releases](https://github.com/ysc070528/granttrace/releases) 和 [PyPI](https://pypi.org/project/granttrace/) 为准。安装包包含内置 `granttrace demo`，首次体验只需：
 
 ```bash
-pip install granttrace
-granttrace demo
-```
-
-审查当前发布准备分支时，先安装本轮构建的 wheel，再运行同一条 demo 命令：
-
-```bash
-python -m pip install dist/granttrace-2.4.1-py3-none-any.whl
+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` 仅体验只读身份访问。
+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
 ```
 
-接入自己的 API 时仍默认只读，主动 PATCH 测试必须显式开启并满足 allowlist、独立 readback 和恢复条件。账户、API Key / Cookie、合法共享和管理员访问配置见 [配置指南](docs/configuration.md)。支持的数组、布尔值及 `style` / `explode` 编码见 [参数规则](docs/parameter-serialization.md)。接入实测前请核对 [安全边界](SECURITY.md)。
+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
 

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

@@ -1,5 +1,143 @@
 # 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，开发版本为