granttrace 2.5.1__tar.gz → 2.5.2__tar.gz

{granttrace-2.5.1 → granttrace-2.5.2}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.5.2 - 2026-10-05
+
+### Maintenance
+
+- Documentation / distribution metadata maintenance release: package the current
+  README for the PyPI project page, retaining the corrected Windows download,
+  unsigned-program notice, macOS / Linux installation and workflow explanation.
+- Align package/runtime versions and Windows portable filenames, launcher,
+  bundled instructions and release workflow metadata at `2.5.2`.
+- No changes to BOLA / IDOR / Mass Assignment detection, the security model,
+  default read-only behavior, CLI semantics or core implementation.
+
 ## 2.5.1 - 2026-10-05
 
 ### Fixed

{granttrace-2.5.1/granttrace.egg-info → granttrace-2.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: granttrace
-Version: 2.5.1
+Version: 2.5.2
 Summary: Safety-first OpenAPI authorization auditing tool for BOLA, IDOR and Mass Assignment testing
 Author: GrantTrace contributors
 License-Expression: Apache-2.0
@@ -32,27 +32,32 @@ 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.5.0](https://github.com/ysc070528/granttrace/releases/tag/v2.5.0) · [PyPI 2.5.0](https://pypi.org/project/granttrace/2.5.0/)
+**源码 / 包元数据版本：2.5.2** · [GitHub Releases](https://github.com/ysc070528/granttrace/releases) · [PyPI](https://pypi.org/project/granttrace/)
 
-源码版本为 **2.5.1**，发布前验收已完成，**Ready for release（未发布）**；尚未创建 v2.5.1 tag / GitHub Release 或发布到 PyPI。
+Windows 便携版已正式提供；已发布版本与下载资产以官方 GitHub Release / PyPI 页面实际列出的版本为准。
 
 An OpenAPI authorization auditor that compares identities, verifies persisted changes, and reports restoration evidence.
 
 安全优先、证据驱动的 OpenAPI 权限审计工具。检查 BOLA / IDOR 与 Mass Assignment，输出身份对比、持久化变更及恢复核验的 HTML / JSON 报告。默认只读；主动写测试须显式开启并配置允许清单与独立读回。
 
-[五分钟体验](#五分钟体验) · [完整示例报告](https://github.com/ysc070528/granttrace/blob/main/examples/sample_report.html) · [配置指南](https://github.com/ysc070528/granttrace/blob/main/docs/configuration.md) · [命令行与迁移](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md) · [验收记录](https://github.com/ysc070528/granttrace/blob/main/VERIFICATION.md) · [发布自检](https://github.com/ysc070528/granttrace/blob/main/docs/release-checklist.md)
+仅对明确获得授权的系统进行测试；主动写测试仅应在可丢弃、隔离的测试资源上启用。
 
-## 为什么是 GrantTrace / Why GrantTrace
+## Windows 用户：解压后双击体验
 
-- **Compare identities**：比较 Owner / Visitor / Anonymous 等身份访问同一资源的结果。
-- **Verify real side effects**：通过独立读回验证状态是否真正持久化，不只看 HTTP 状态码。
-- **Restore safely**：主动 PATCH 测试使用显式 allowlist、原始状态快照、恢复与恢复验证。
+**推荐 Windows 10 / 11（64 位），便携包无需安装 Python。** 从官方 [GitHub Release](https://github.com/ysc070528/granttrace/releases/latest) 选择对应版本下载：
 
-<img src="https://raw.githubusercontent.com/ysc070528/granttrace/v2.5.0/docs/assets/report-preview.png" alt="GrantTrace 报告：身份访问摘要、修复建议和端点筛选" width="900">
+1. 下载 Release 中的 Windows x64 ZIP（2.5.2 对应文件名为 **`GrantTrace-v2.5.2-Windows-x64.zip`**），将整个 ZIP 解压到一个普通文件夹。
+2. 打开解压后的文件夹，双击 **`Start-Demo.bat`**；保留旁边的程序和依赖文件。
+3. 查看自动打开的 HTML 报告；若未打开，按启动器打印的 HTML 路径手动打开。HTML / JSON 保存在解压目录的 `granttrace-demo/session-*/run-*/`。Demo 只使用内置、可丢弃的 `127.0.0.1` 靶场，结束时关闭靶场并核验数据恢复。
 
-## 五分钟体验
+不要直接在 ZIP 内运行启动器。便携包版本以包内 `README.txt` 和 `.\granttrace.exe --version` 为准；程序、启动器和报告在解压目录内使用，不需要修改系统 PATH。维护者的构建与验收步骤见 [Windows 便携包说明](docs/windows-portable.md)。
 
-需要 Python 3.9+。当前已发布稳定版 **v2.5.0**：[PyPI](https://pypi.org/project/granttrace/2.5.0/)。安装包包含内置 `granttrace demo`，首次体验只需：
+Windows 便携程序尚未进行代码签名，部分系统可能显示 Microsoft Defender SmartScreen 或“发布者未知”提示。请只从官方 GitHub Release 下载，并使用同一 Release 的 **`SHA256SUMS.txt`** 核对完整性。
+
+## macOS / Linux 用户：使用 Python 安装
+
+需要 **Python 3.9+**；当前不提供 macOS / Linux standalone binary，Windows ZIP 仅适用于 Windows。
+已有 Python 的 Windows 用户也可沿用此方式：
 
 ```bash
 python -m pip install --upgrade granttrace
@@ -60,6 +65,33 @@ granttrace --version
 granttrace demo
 ```
 
+[Python 五分钟体验](#五分钟体验) · [完整示例报告](https://github.com/ysc070528/granttrace/blob/main/examples/sample_report.html) · [配置指南](https://github.com/ysc070528/granttrace/blob/main/docs/configuration.md) · [命令行与迁移](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md) · [验收记录](https://github.com/ysc070528/granttrace/blob/main/VERIFICATION.md) · [发布自检](https://github.com/ysc070528/granttrace/blob/main/docs/release-checklist.md)
+
+## 为什么是 GrantTrace / Why GrantTrace
+
+- **Compare identities**：比较 Owner / Visitor / Anonymous 等身份访问同一资源的结果。
+- **Verify real side effects**：通过独立读回验证状态是否真正持久化，不只看 HTTP 状态码。
+- **Restore safely**：主动 PATCH 测试使用显式 allowlist、原始状态快照、恢复与恢复验证。
+
+## 10 秒看懂 GrantTrace
+
+```mermaid
+flowchart TD
+    A["OpenAPI Spec + Owner / Visitor / Anonymous"] --> B["GrantTrace"]
+    B --> C["只读身份差异比较（默认）"]
+    C --> R["HTML / JSON（可选 SARIF）"]
+    B -->|显式开启并满足写入安全条件| W["PATCH 测试"]
+    W --> D["独立 GET 读回"]
+    D --> E["恢复并验证"]
+    E --> R
+```
+
+<img src="https://raw.githubusercontent.com/ysc070528/granttrace/v2.5.1/docs/assets/report-preview.png" alt="GrantTrace 报告：身份访问摘要、修复建议和端点筛选" width="900">
+
+## 五分钟体验
+
+使用上方 Windows 启动器或 Python 安装命令，即可体验内置 `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**。

{granttrace-2.5.1 → granttrace-2.5.2}/README.md

@@ -5,27 +5,32 @@
 ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
 ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
-**Stable:** [v2.5.0](https://github.com/ysc070528/granttrace/releases/tag/v2.5.0) · [PyPI 2.5.0](https://pypi.org/project/granttrace/2.5.0/)
+**源码 / 包元数据版本：2.5.2** · [GitHub Releases](https://github.com/ysc070528/granttrace/releases) · [PyPI](https://pypi.org/project/granttrace/)
 
-源码版本为 **2.5.1**，发布前验收已完成，**Ready for release（未发布）**；尚未创建 v2.5.1 tag / GitHub Release 或发布到 PyPI。
+Windows 便携版已正式提供；已发布版本与下载资产以官方 GitHub Release / PyPI 页面实际列出的版本为准。
 
 An OpenAPI authorization auditor that compares identities, verifies persisted changes, and reports restoration evidence.
 
 安全优先、证据驱动的 OpenAPI 权限审计工具。检查 BOLA / IDOR 与 Mass Assignment，输出身份对比、持久化变更及恢复核验的 HTML / JSON 报告。默认只读；主动写测试须显式开启并配置允许清单与独立读回。
 
-[五分钟体验](#五分钟体验) · [完整示例报告](https://github.com/ysc070528/granttrace/blob/main/examples/sample_report.html) · [配置指南](https://github.com/ysc070528/granttrace/blob/main/docs/configuration.md) · [命令行与迁移](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md) · [验收记录](https://github.com/ysc070528/granttrace/blob/main/VERIFICATION.md) · [发布自检](https://github.com/ysc070528/granttrace/blob/main/docs/release-checklist.md)
+仅对明确获得授权的系统进行测试；主动写测试仅应在可丢弃、隔离的测试资源上启用。
 
-## 为什么是 GrantTrace / Why GrantTrace
+## Windows 用户：解压后双击体验
 
-- **Compare identities**：比较 Owner / Visitor / Anonymous 等身份访问同一资源的结果。
-- **Verify real side effects**：通过独立读回验证状态是否真正持久化，不只看 HTTP 状态码。
-- **Restore safely**：主动 PATCH 测试使用显式 allowlist、原始状态快照、恢复与恢复验证。
+**推荐 Windows 10 / 11（64 位），便携包无需安装 Python。** 从官方 [GitHub Release](https://github.com/ysc070528/granttrace/releases/latest) 选择对应版本下载：
 
-<img src="https://raw.githubusercontent.com/ysc070528/granttrace/v2.5.0/docs/assets/report-preview.png" alt="GrantTrace 报告：身份访问摘要、修复建议和端点筛选" width="900">
+1. 下载 Release 中的 Windows x64 ZIP（2.5.2 对应文件名为 **`GrantTrace-v2.5.2-Windows-x64.zip`**），将整个 ZIP 解压到一个普通文件夹。
+2. 打开解压后的文件夹，双击 **`Start-Demo.bat`**；保留旁边的程序和依赖文件。
+3. 查看自动打开的 HTML 报告；若未打开，按启动器打印的 HTML 路径手动打开。HTML / JSON 保存在解压目录的 `granttrace-demo/session-*/run-*/`。Demo 只使用内置、可丢弃的 `127.0.0.1` 靶场，结束时关闭靶场并核验数据恢复。
 
-## 五分钟体验
+不要直接在 ZIP 内运行启动器。便携包版本以包内 `README.txt` 和 `.\granttrace.exe --version` 为准；程序、启动器和报告在解压目录内使用，不需要修改系统 PATH。维护者的构建与验收步骤见 [Windows 便携包说明](docs/windows-portable.md)。
 
-需要 Python 3.9+。当前已发布稳定版 **v2.5.0**：[PyPI](https://pypi.org/project/granttrace/2.5.0/)。安装包包含内置 `granttrace demo`，首次体验只需：
+Windows 便携程序尚未进行代码签名，部分系统可能显示 Microsoft Defender SmartScreen 或“发布者未知”提示。请只从官方 GitHub Release 下载，并使用同一 Release 的 **`SHA256SUMS.txt`** 核对完整性。
+
+## macOS / Linux 用户：使用 Python 安装
+
+需要 **Python 3.9+**；当前不提供 macOS / Linux standalone binary，Windows ZIP 仅适用于 Windows。
+已有 Python 的 Windows 用户也可沿用此方式：
 
 ```bash
 python -m pip install --upgrade granttrace
@@ -33,6 +38,33 @@ granttrace --version
 granttrace demo
 ```
 
+[Python 五分钟体验](#五分钟体验) · [完整示例报告](https://github.com/ysc070528/granttrace/blob/main/examples/sample_report.html) · [配置指南](https://github.com/ysc070528/granttrace/blob/main/docs/configuration.md) · [命令行与迁移](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md) · [验收记录](https://github.com/ysc070528/granttrace/blob/main/VERIFICATION.md) · [发布自检](https://github.com/ysc070528/granttrace/blob/main/docs/release-checklist.md)
+
+## 为什么是 GrantTrace / Why GrantTrace
+
+- **Compare identities**：比较 Owner / Visitor / Anonymous 等身份访问同一资源的结果。
+- **Verify real side effects**：通过独立读回验证状态是否真正持久化，不只看 HTTP 状态码。
+- **Restore safely**：主动 PATCH 测试使用显式 allowlist、原始状态快照、恢复与恢复验证。
+
+## 10 秒看懂 GrantTrace
+
+```mermaid
+flowchart TD
+    A["OpenAPI Spec + Owner / Visitor / Anonymous"] --> B["GrantTrace"]
+    B --> C["只读身份差异比较（默认）"]
+    C --> R["HTML / JSON（可选 SARIF）"]
+    B -->|显式开启并满足写入安全条件| W["PATCH 测试"]
+    W --> D["独立 GET 读回"]
+    D --> E["恢复并验证"]
+    E --> R
+```
+
+<img src="https://raw.githubusercontent.com/ysc070528/granttrace/v2.5.1/docs/assets/report-preview.png" alt="GrantTrace 报告：身份访问摘要、修复建议和端点筛选" width="900">
+
+## 五分钟体验
+
+使用上方 Windows 启动器或 Python 安装命令，即可体验内置 `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**。

{granttrace-2.5.1 → granttrace-2.5.2}/VERIFICATION.md

@@ -1,5 +1,115 @@
 # GrantTrace 验收记录
 
+## 2026-10-05 v2.5.2 文档与分发元数据同步验收
+
+基线为已合并 PR #30 的 main `0b9c117f4e2d6187dc2f1fb64becb68d2e887fc5`，
+分支为 `release/v2.5.2-docs-sync`。这是 documentation / distribution metadata
+maintenance release 准备；只同步版本、当前 README 和 Windows 分发元数据。
+与 v2.5.1 tag / 本轮 main 相比，核心目录只有 `core.__version__` 从
+`2.5.1` 改为 `2.5.2`；BOLA / IDOR / Mass Assignment、安全模型、默认只读、
+CLI 语义与其他产品代码完全不变。唯一测试改动是已有固定版本断言同步。
+
+### 本轮本地实际结果
+
+| 检查 | 结果 |
+|---|---|
+| 全量测试与 configured branch-aware coverage | Windows CPython 3.14.5：560 tests OK，无跳过；85.27%，通过 80% 门槛 |
+| Mypy / Ruff | 18 个源码文件无类型问题；Ruff 全部通过 |
+| Business scenarios | 6/6 通过；误报、漏报、不确定均为 0 |
+| JSON / YAML 示例 | 只读与 active 均通过；数据库完整恢复、rollback 核验和统计等价均通过 |
+| wheel / sdist | `granttrace-2.5.2-py3-none-any.whl` 与 `granttrace-2.5.2.tar.gz` 构建成功；twine strict 均 PASS |
+| README / PyPI long description | wheel METADATA 与 sdist PKG-INFO 的 Markdown 正文均等于当前 README；sdist README 字节相同；无本轮指定的旧发布状态文案 |
+| 包内容 | wheel 的 28 个 RECORD 记录核验通过，23 个产品 / demo 资源文件与源码字节一致；sdist 无 dist、虚拟环境、旧发布资产或本地配置 |
+| 源码外 fresh venv 安装 | CLI、project、wheel、installed metadata / runtime 均为 2.5.2；只读零 PATCH，active / Demo 读回、恢复、服务关闭、JSON / YAML 离线计划均通过 |
+| Windows x64 portable | ZIP 构建成功；两种真实解压路径下的 CLI、active / readonly Demo、YAML dry-run、BAT、恢复与独立 TCP / 进程检查均通过 |
+
+本地 Windows 文件为 `dist/v252-windows/GrantTrace-v2.5.2-Windows-x64.zip`，
+SHA256 为 `4bb273ae13f55f95c6ce4416aee47f3238bc560f6fa4d693507d7a3ce3f665ad`；
+构建 JSON、smoke JSON、SHA256SUMS.txt 与独立 Get-FileHash 一致。
+这是基线 commit 上的预提交工作树构建（`source_tree_dirty=true`），
+不冒充最终 PR HEAD 的构建。Windows 11 x64 实测清除了子进程的 Python PATH / 环境，
+并在源码外运行；未做干净无 Python 虚拟机、人工鼠标双击、浏览器视觉或 SmartScreen 实测。
+
+README 保留 PR #30 的新用户说明，使用通用官方 Release / PyPI 页面并标明源码 / 包元数据
+版本 2.5.2，不提前声称该版本已发布。预览图仍固定在实际存在且未变的 v2.5.1 tag。
+已发布 v2.5.1 的 tag、Release 及其附件、PyPI、Topics、SECURITY.md 均未改动。
+本轮未创建 v2.5.2 tag / GitHub Release，未发布 PyPI，也未执行 workflow_dispatch。
+
+最终新 HEAD 的 CI、CodeQL 和 Windows 工作流以本次 PR 的实际运行记录为准；
+本地与历史绿灯不替代该 HEAD 的远程检查。日志和构建证据只存放于被忽略的 dist。
+下方完整保留各轮历史事实；历史版本的“当前”“未发布”“待添加”均指当时状态。
+
+## 2026-10-05 v2.5.1 公开文档与当前分发状态
+
+本轮基于 main `0214905dc43f2b50cf0c2c93834091f72276e798`，
+只同步文档，不修改产品、测试、Windows 打包逻辑或版本。
+
+- [GitHub v2.5.1 Release](https://github.com/ysc070528/granttrace/releases/tag/v2.5.1)
+  实际存在，Release ID `403394773`，非 draft；现有附件为
+  `GrantTrace-v2.5.1-Windows-x64.zip` 与 `SHA256SUMS.txt`。
+  实际读取校验和，ZIP 的 SHA256 与 GitHub asset digest 一致：
+  `c9cdc2d42305f3160ce2df73cfeddf389c68b8515600eda11420b224c402307e`。
+- [PyPI 2.5.1](https://pypi.org/project/granttrace/2.5.1/) 实际存在 wheel / sdist。
+  页面中的部分发布状态文字来自已发布 wheel / sdist 构建时的历史 README，
+  仍提到 stable v2.5.0 与 Ready for release；不影响包本身和安装使用。
+  当前准确公开状态以 GitHub README 与 v2.5.1 Release 为准。
+  本轮不覆盖 PyPI 2.5.1、不发布 2.5.2，也不改版本。
+- v2.5.1 tag 仍指向 `16a605d245e34dcc1aa6d1449b1195c2ac4c434a`。
+  tag 中的 `docs/assets/report-preview.png` 实际存在；raw 链接返回
+  HTTP 200 / image/png / 99428 bytes，PNG 内容与现有图片完全一致，未修改图片。
+- Topics 已包含现有 API security / authorization / BOLA / IDOR / Mass Assignment 等标签；
+  本轮保持不变。SECURITY.md 已覆盖明确授权、默认只读、PATCH opt-in、恢复与报告敏感数据，保持不变。
+
+本轮只做文档与链接检查，不重新构建、执行扫描或改动已发布资产。
+最终文档提交的现有 CI / CodeQL 以对应 PR HEAD 和运行记录为准，历史绿灯不代用。
+以下各轮验收按当时状态保留；旧“未发布”“待添加资产”不表示当前分发状态。
+
+## 2026-10-05 v2.5.1 Windows 便携分发验收
+
+本轮基于 main `16a605d245e34dcc1aa6d1449b1195c2ac4c434a`，
+分支为 `fix/v2.5.1-windows-portable`，版本保持 **2.5.1**。
+GitHub 的 [v2.5.1 Release](https://github.com/ysc070528/granttrace/releases/tag/v2.5.1)
+已于 `2026-10-05T05:32:19Z` 正式发布（ID `403394773`），本轮开始时 assets 为空。
+[PyPI 2.5.1](https://pypi.org/project/granttrace/2.5.1/) 的 wheel / sdist 也已实际查询确认存在。
+这些是已存在的发布；本轮只准备 Windows ZIP 和校验和，不创建或改动 tag / Release，也不上传 PyPI。
+
+采用 **CPython 3.14.5 x64 / PyInstaller 6.22.3 one-folder**，关闭 UPX，
+固定 UTF-8 输出并包含 `core.demo_assets` 三个 JSON、mock 模块、内嵌 HTML 模板、
+Python / DLL 与许可证。没有修改核心扫描代码、CLI 命令语义、检测规则、默认只读或版本。
+`--version` 保持实际完整输出 **`GrantTrace 2.5.1`**。
+
+本地 Windows 11 x64（10.0.26200）实际验证：
+
+| 检查 | 实际结果 |
+|---|---|
+| 完整 pytest | **560 passed / 860 subtests passed** |
+| Mypy / Ruff | 18 个源码文件 **0 issues**；仓库根目录 Ruff 通过 |
+| 业务场景与原有 examples | **6/6**；只读 / active JSON / active YAML 均通过，完整恢复数据库，未更新示例 |
+| 原有 `verify_install.py` | 本次 wheel 在仓库外 fresh venv 安装，metadata / CLI / runtime 均 2.5.1；Demo、只读 / active 扫描、JSON / YAML 0 请求计划与草稿阻断通过 |
+| EXE `--version` / `--help` | 输出 `GrantTrace 2.5.1`；help 返回 0 |
+| EXE active / read-only Demo | HTML / JSON 生成；active BOLA 1 / Mass Assignment 1，独立 readback、rollback、数据恢复与服务关闭通过；read-only 只发送 GET |
+| ZIP 空格 / 中文路径与启动器 | 真实解压到仓库外，两种路径均通过；子进程不含 Python PATH / Python 环境变量，从空工作目录启动；BAT 正常执行、打印完整报告路径并保留 pause |
+| 独立运行检查 | 每次报告的 loopback 端口均已关闭；可查询的包内进程无残留；YAML dry-run 0 请求，未开启写操作 |
+| BAT 错误路径 | 缺少 EXE 时返回 2，中文错误和暂停提示可见 |
+| 默认报告打开 | 另行不设置 `GRANTTRACE_DEMO_NO_OPEN` 执行 BAT，返回 0，系统打开 HTML 未报告错误 |
+
+自动 BAT 检查通过标准输入模拟按键，并在 CI 抑制打开浏览器；
+不冒称人工鼠标双击、浏览器视觉验收或未安装 Python 的干净虚拟机实测。
+实际 EXE 子进程只使用 ZIP 内 runtime，未从开发环境或源码目录加载依赖。
+本机构建 / 执行未遇安全软件拦截；EXE 未签名，不能保证下载后的 SmartScreen 或其他杀毒软件无提示 / 误报。
+没有关闭安全软件或加入绕过代码。
+
+产物为 `GrantTrace-v2.5.1-Windows-x64.zip` 和 `SHA256SUMS.txt`；
+源码、工具版本、大小和哈希见每次的 `windows-portable-build.json`，
+独立启动与路径证据见 `windows-portable-verification.json`。
+[Windows 构建工作流](https://github.com/ysc070528/granttrace/actions/workflows/windows-package.yml)
+只上传已通过 smoke 的 Actions artifact，不自动修改 Release。
+最新实际 PR HEAD 须独立通过 Windows 构建及原有 CI / CodeQL，
+不得把本轮本地或其他 SHA 的结果代替该 HEAD；最终 SHA / run / ZIP 哈希在 PR 验收报告记录。
+人工确认后才可将同一已验收 ZIP 和校验和添加到既有 v2.5.1 Release。
+
+下方记录按各轮验收当时状态保留；其中“未发布”不表示当前 GitHub / PyPI 2.5.1 状态。
+
 ## 2026-10-05 v2.5.1 Ready for release 收尾验收
 
 本轮基于最新 main

{granttrace-2.5.1 → granttrace-2.5.2}/core/__init__.py

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

{granttrace-2.5.1 → granttrace-2.5.2}/docs/release-checklist.md

@@ -1,4 +1,42 @@
-# v2.5.1 Ready for release 收尾清单
+# v2.5.2 文档与分发元数据同步发布准备
+
+- [x] 从包含 PR #30 最新 README 的 main `0b9c117f4e2d6187dc2f1fb64becb68d2e887fc5` 创建独立分支 `release/v2.5.2-docs-sync`。
+- [x] 项目、runtime、固定版本断言、Windows 启动器 / 说明 / 构建与验证脚本 / artifact 名称同步为 2.5.2。
+- [x] 发布 workflow 只追加 v2.5.2 元数据选项，保留现有触发、历史版本支持和发布门禁。
+- [x] CHANGELOG 明确 documentation / distribution metadata maintenance release；检测逻辑、安全模型、默认只读和 CLI 语义不变。
+- [x] 保留当前 README 的 Windows、SmartScreen、macOS / Linux、Mermaid 和授权说明；long description 不含指定的过时发布文案。
+- [x] 全量 560 tests、85.27% branch-aware coverage、Mypy、Ruff、6 个 business scenarios 和 JSON / YAML 恢复验证通过。
+- [x] 新 wheel / sdist 构建与 twine strict 通过；两者的 long description 均为当前 README，源码外安装验证通过。
+- [x] Windows x64 ZIP 和 SHA256SUMS.txt 构建成功，既有 portable smoke 全部通过；范围与限制见 [本轮验收](../VERIFICATION.md#2026-10-05-v252-文档与分发元数据同步验收)。
+
+最终新 HEAD 的 CI / CodeQL / Windows 工作流结果见本轮 PR，不使用历史结果代替。
+以下发布动作必须等待维护者人工确认，本轮不执行：
+
+- [ ] 人工审查并合并本轮 PR。
+- [ ] 在确认最终 main 与远程检查后创建 v2.5.2 tag / GitHub Release。
+- [ ] 人工确认后发布 PyPI 2.5.2，并核对页面版本、long description 与正式 Windows 附件。
+
+现有 v2.5.1 tag / Release / PyPI 与资产保持不变。下方是对应时点的完整历史记录，
+不是要求重新发布或重复执行历史步骤。
+
+---
+
+# v2.5.1 公开发布与分发状态（历史快照）
+
+- [x] [GitHub v2.5.1 Release](https://github.com/ysc070528/granttrace/releases/tag/v2.5.1) 已正式存在。
+- [x] Release 已提供 `GrantTrace-v2.5.1-Windows-x64.zip` 和 `SHA256SUMS.txt`。
+- [x] [PyPI 2.5.1](https://pypi.org/project/granttrace/2.5.1/) 的 wheel / sdist 已存在。
+- [x] README 已同步 Windows 下载、未签名 / SmartScreen 提示、macOS / Linux Python 安装与 v2.5.1 预览图。
+- [x] PyPI 页面历史 README 状态文字已在 [当前验收记录](../VERIFICATION.md#2026-10-05-v251-公开文档与当前分发状态) 说明；不覆盖已发布包或修改版本。
+- [x] 本轮只修改文档；Topics、SECURITY.md、产品 / 测试 / Windows 打包逻辑、tag、Release 和 PyPI 均保持不变。
+
+最终文档 HEAD 的自动检查以对应 PR 为准；历史检查结果不代替该提交。
+下方完整保留各轮发布准备与验收时点的历史清单，包括当时未勾选的后续动作；
+其中“Ready for release”“未发布”“待添加”不表示当前状态或要求重新执行发布。
+
+---
+
+# v2.5.1 Ready for release 收尾清单（历史）
 
 最新 main 为
 [`c913f19a7331dbd291332f9c7dfb7244f45fb2d3`](https://github.com/ysc070528/granttrace/commit/c913f19a7331dbd291332f9c7dfb7244f45fb2d3)，

granttrace-2.5.2/docs/windows-portable.md

@@ -0,0 +1,73 @@
+# GrantTrace 2.5.2 Windows 便携包
+
+分发文件为 `GrantTrace-v2.5.2-Windows-x64.zip`。用户解压整个 ZIP 后双击
+`Start-Demo.bat` 即可运行内置 demo，无需安装 Python 或修改系统 PATH。
+程序版本为 `GrantTrace 2.5.2`；本次仅同步文档与分发元数据，
+检测规则、身份比较和恢复核验沿用 2.5.1 CLI。
+推荐 Windows 10 / 11（64 位）。启动器自动打开 HTML 并打印确切路径；报告保存在
+解压目录的 `granttrace-demo/session-*/run-*/`，每次运行使用新的目录。
+
+GitHub 已正式发布 [v2.5.1](https://github.com/ysc070528/granttrace/releases/tag/v2.5.1)，
+现已提供 [GrantTrace-v2.5.1-Windows-x64.zip](https://github.com/ysc070528/granttrace/releases/download/v2.5.1/GrantTrace-v2.5.1-Windows-x64.zip)
+和 [SHA256SUMS.txt](https://github.com/ysc070528/granttrace/releases/download/v2.5.1/SHA256SUMS.txt)。
+普通用户以正式 Release 页面实际提供的版本为准；本轮 2.5.2 构建仅用于发布准备，
+不替换现有附件。以下构建工作流只上传 Actions artifact，
+不自动修改 tag / Release 或上传 PyPI。
+
+## 本地构建
+
+构建环境固定为 **CPython 3.14.5 / PyInstaller 6.22.3（Windows x64）**。
+使用独立虚拟环境，从仓库根目录执行；创建环境后先核对 Python 版本。
+采用 PyInstaller
+one-folder 构建，关闭 UPX；ZIP 包含可执行文件、依赖、demo 资源和启动器，
+运行时保留解压目录结构。
+
+```powershell
+py -3.14 -m venv dist/windows-build-env
+.\dist\windows-build-env\Scripts\python.exe --version
+.\dist\windows-build-env\Scripts\python.exe -m pip install -r packaging/windows/requirements-build.txt
+.\dist\windows-build-env\Scripts\python.exe -m pip install --no-build-isolation --no-deps .
+.\dist\windows-build-env\Scripts\python.exe scripts/build_windows_portable.py
+.\dist\windows-build-env\Scripts\python.exe scripts/verify_windows_portable.py --zip dist/GrantTrace-v2.5.2-Windows-x64.zip --output dist/windows-portable-verification.json
+```
+
+最终交付文件为：
+
+- `dist/GrantTrace-v2.5.2-Windows-x64.zip`
+- `dist/SHA256SUMS.txt`：记录 ZIP 的 SHA-256。
+- `dist/windows-portable-build.json`：记录源码 commit、工具版本、EXE / ZIP 大小与哈希。
+- `dist/windows-portable-verification.json`：记录实际验证结果，供维护者复核。
+
+验证时使用 ZIP 解压后的程序，确认 `--version` 输出 `GrantTrace 2.5.2`，
+`--help` 可用，内置 demo 能生成 HTML / JSON 报告，关闭本机服务并完整恢复数据。
+另在含空格和中文的目录双击 `Start-Demo.bat`，确认正常完成且报告可以打开。
+自动验证会实际将 ZIP 解压到仓库外的空格、中文路径，从空目录启动程序；
+子进程 PATH 仅保留 Windows 系统目录，并清除 Python / 虚拟环境变量。
+还核对只读 demo 无 PATCH、YAML 离线计划 0 请求、独立 TCP 端口关闭和可查询的包内进程无残留。
+CI 为避免打开浏览器设置 `GRANTTRACE_DEMO_NO_OPEN=1`；正常双击仍默认打开 HTML。
+暂停保留，自动验证只通过标准输入模拟按键，不隐藏程序或关闭安全软件。
+
+## GitHub Actions 构建产物与独立验收
+
+1. 在 PR 的 Checks 或仓库 Actions 中打开 **GrantTrace Windows portable**
+   工作流（`windows-package.yml`），
+   核对运行对应的 commit SHA，等待该次运行成功。
+2. 下载 **GrantTrace-v2.5.2-Windows-x64** artifact，解开外层 artifact ZIP，取出内部的
+   `GrantTrace-v2.5.2-Windows-x64.zip`、`SHA256SUMS.txt` 和验证 JSON。
+3. 用 `Get-FileHash -Algorithm SHA256` 核对分发 ZIP 与 `SHA256SUMS.txt`，
+   阅读验证 JSON，再将分发 ZIP 完整解压到新的测试目录。
+4. 在没有安装 Python 的 Windows x64 环境双击 `Start-Demo.bat`，
+   核对版本、报告、服务关闭和数据恢复；记录操作系统、commit 和结果。
+
+这些步骤用于维护者验证构建产物，不会替换已经提供的 Release 附件。
+
+本轮 2.5.2 已在 Windows 11 x64（10.0.26200）构建并通过既有自动验证，
+其中浏览器通过 `GRANTTRACE_DEMO_NO_OPEN=1` 抑制。
+原 2.5.1 的默认启动器曾另行在不抑制浏览器打开的条件下返回 0，系统打开 HTML 未报告错误；
+此项保留为历史证据，不代替本轮检查。
+两轮均不是人工鼠标双击、浏览器视觉验收或干净 Windows 虚拟机实测。
+原便携分发 PR #29 已合并。后续提交的自动检查须核对各自实际 HEAD；
+以对应运行的 artifact 和构建 / 验证 JSON 为准，历史结果不代替新的提交。
+
+EXE 未签名，下载后可能出现 SmartScreen 或安全软件提示；不保证所有产品均无误报。
+普通用户只从官方 GitHub Release 下载并核对 `SHA256SUMS.txt`；不关闭或绕过安全软件。

{granttrace-2.5.1 → granttrace-2.5.2/granttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: granttrace
-Version: 2.5.1
+Version: 2.5.2
 Summary: Safety-first OpenAPI authorization auditing tool for BOLA, IDOR and Mass Assignment testing
 Author: GrantTrace contributors
 License-Expression: Apache-2.0
@@ -32,27 +32,32 @@ 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.5.0](https://github.com/ysc070528/granttrace/releases/tag/v2.5.0) · [PyPI 2.5.0](https://pypi.org/project/granttrace/2.5.0/)
+**源码 / 包元数据版本：2.5.2** · [GitHub Releases](https://github.com/ysc070528/granttrace/releases) · [PyPI](https://pypi.org/project/granttrace/)
 
-源码版本为 **2.5.1**，发布前验收已完成，**Ready for release（未发布）**；尚未创建 v2.5.1 tag / GitHub Release 或发布到 PyPI。
+Windows 便携版已正式提供；已发布版本与下载资产以官方 GitHub Release / PyPI 页面实际列出的版本为准。
 
 An OpenAPI authorization auditor that compares identities, verifies persisted changes, and reports restoration evidence.
 
 安全优先、证据驱动的 OpenAPI 权限审计工具。检查 BOLA / IDOR 与 Mass Assignment，输出身份对比、持久化变更及恢复核验的 HTML / JSON 报告。默认只读；主动写测试须显式开启并配置允许清单与独立读回。
 
-[五分钟体验](#五分钟体验) · [完整示例报告](https://github.com/ysc070528/granttrace/blob/main/examples/sample_report.html) · [配置指南](https://github.com/ysc070528/granttrace/blob/main/docs/configuration.md) · [命令行与迁移](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md) · [验收记录](https://github.com/ysc070528/granttrace/blob/main/VERIFICATION.md) · [发布自检](https://github.com/ysc070528/granttrace/blob/main/docs/release-checklist.md)
+仅对明确获得授权的系统进行测试；主动写测试仅应在可丢弃、隔离的测试资源上启用。
 
-## 为什么是 GrantTrace / Why GrantTrace
+## Windows 用户：解压后双击体验
 
-- **Compare identities**：比较 Owner / Visitor / Anonymous 等身份访问同一资源的结果。
-- **Verify real side effects**：通过独立读回验证状态是否真正持久化，不只看 HTTP 状态码。
-- **Restore safely**：主动 PATCH 测试使用显式 allowlist、原始状态快照、恢复与恢复验证。
+**推荐 Windows 10 / 11（64 位），便携包无需安装 Python。** 从官方 [GitHub Release](https://github.com/ysc070528/granttrace/releases/latest) 选择对应版本下载：
 
-<img src="https://raw.githubusercontent.com/ysc070528/granttrace/v2.5.0/docs/assets/report-preview.png" alt="GrantTrace 报告：身份访问摘要、修复建议和端点筛选" width="900">
+1. 下载 Release 中的 Windows x64 ZIP（2.5.2 对应文件名为 **`GrantTrace-v2.5.2-Windows-x64.zip`**），将整个 ZIP 解压到一个普通文件夹。
+2. 打开解压后的文件夹，双击 **`Start-Demo.bat`**；保留旁边的程序和依赖文件。
+3. 查看自动打开的 HTML 报告；若未打开，按启动器打印的 HTML 路径手动打开。HTML / JSON 保存在解压目录的 `granttrace-demo/session-*/run-*/`。Demo 只使用内置、可丢弃的 `127.0.0.1` 靶场，结束时关闭靶场并核验数据恢复。
 
-## 五分钟体验
+不要直接在 ZIP 内运行启动器。便携包版本以包内 `README.txt` 和 `.\granttrace.exe --version` 为准；程序、启动器和报告在解压目录内使用，不需要修改系统 PATH。维护者的构建与验收步骤见 [Windows 便携包说明](docs/windows-portable.md)。
 
-需要 Python 3.9+。当前已发布稳定版 **v2.5.0**：[PyPI](https://pypi.org/project/granttrace/2.5.0/)。安装包包含内置 `granttrace demo`，首次体验只需：
+Windows 便携程序尚未进行代码签名，部分系统可能显示 Microsoft Defender SmartScreen 或“发布者未知”提示。请只从官方 GitHub Release 下载，并使用同一 Release 的 **`SHA256SUMS.txt`** 核对完整性。
+
+## macOS / Linux 用户：使用 Python 安装
+
+需要 **Python 3.9+**；当前不提供 macOS / Linux standalone binary，Windows ZIP 仅适用于 Windows。
+已有 Python 的 Windows 用户也可沿用此方式：
 
 ```bash
 python -m pip install --upgrade granttrace
@@ -60,6 +65,33 @@ granttrace --version
 granttrace demo
 ```
 
+[Python 五分钟体验](#五分钟体验) · [完整示例报告](https://github.com/ysc070528/granttrace/blob/main/examples/sample_report.html) · [配置指南](https://github.com/ysc070528/granttrace/blob/main/docs/configuration.md) · [命令行与迁移](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md) · [验收记录](https://github.com/ysc070528/granttrace/blob/main/VERIFICATION.md) · [发布自检](https://github.com/ysc070528/granttrace/blob/main/docs/release-checklist.md)
+
+## 为什么是 GrantTrace / Why GrantTrace
+
+- **Compare identities**：比较 Owner / Visitor / Anonymous 等身份访问同一资源的结果。
+- **Verify real side effects**：通过独立读回验证状态是否真正持久化，不只看 HTTP 状态码。
+- **Restore safely**：主动 PATCH 测试使用显式 allowlist、原始状态快照、恢复与恢复验证。
+
+## 10 秒看懂 GrantTrace
+
+```mermaid
+flowchart TD
+    A["OpenAPI Spec + Owner / Visitor / Anonymous"] --> B["GrantTrace"]
+    B --> C["只读身份差异比较（默认）"]
+    C --> R["HTML / JSON（可选 SARIF）"]
+    B -->|显式开启并满足写入安全条件| W["PATCH 测试"]
+    W --> D["独立 GET 读回"]
+    D --> E["恢复并验证"]
+    E --> R
+```
+
+<img src="https://raw.githubusercontent.com/ysc070528/granttrace/v2.5.1/docs/assets/report-preview.png" alt="GrantTrace 报告：身份访问摘要、修复建议和端点筛选" width="900">
+
+## 五分钟体验
+
+使用上方 Windows 启动器或 Python 安装命令，即可体验内置 `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**。

{granttrace-2.5.1 → granttrace-2.5.2}/granttrace.egg-info/SOURCES.txt

@@ -36,6 +36,7 @@ docs/business-scenarios.md
 docs/configuration.md
 docs/parameter-serialization.md
 docs/release-checklist.md
+docs/windows-portable.md
 docs/assets/report-preview.png
 examples/README.md
 examples/sample_report.html
@@ -48,9 +49,11 @@ granttrace.egg-info/requires.txt
 granttrace.egg-info/top_level.txt
 mock_server/__init__.py
 mock_server/server.py
+scripts/build_windows_portable.py
 scripts/verify_business_scenarios.py
 scripts/verify_examples.py
 scripts/verify_install.py
+scripts/verify_windows_portable.py
 tests/test_auditor_integration.py
 tests/test_business_authorization.py
 tests/test_cli_report_boundaries.py

{granttrace-2.5.1 → granttrace-2.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "granttrace"
-version = "2.5.1"
+version = "2.5.2"
 description = "Safety-first OpenAPI authorization auditing tool for BOLA, IDOR and Mass Assignment testing"
 readme = "README.md"
 requires-python = ">=3.9"