granttrace 2.5.0__tar.gz → 2.5.2__tar.gz

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

@@ -1,5 +1,28 @@
 # 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
+
+- Reject unsafe Merge Patch probes before writes when the original state cannot be restored exactly.
+- Preserve array record associations during BOLA comparison to avoid overstating confirmed authorization bypasses.
+- Harden report target/metadata redaction for known credentials and prevent report outputs from overwriting specification, configuration, or loaded local `$ref` inputs.
+- Improve local and conditional schema resolution plus configuration-to-spec operation validation.
+- Preserve legacy v2.5.0 scalar parameter configurations while applying strict schema-aware normalization and validation for canonical integer, number, and boolean values.
+- Preserve Swagger 2.0 `uniqueItems` parameter constraints during schema extraction so duplicate configured arrays fail validation before requests.
+
 ## 2.5.0 - 2026-10-04
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: granttrace
-Version: 2.5.0
+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
@@ -28,28 +28,36 @@ Dynamic: license-file
 # GrantTrace
 
 ![CI](https://github.com/ysc070528/granttrace/actions/workflows/test.yml/badge.svg)
+[![PyPI](https://img.shields.io/pypi/v/granttrace.svg)](https://pypi.org/project/granttrace/)
 ![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/)
+**源码 / 包元数据版本：2.5.2** · [GitHub Releases](https://github.com/ysc070528/granttrace/releases) · [PyPI](https://pypi.org/project/granttrace/)
+
+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 报告。默认只读；主动写测试须显式开启并配置允许清单与独立读回。
 
-[五分钟体验](#五分钟体验) · [完整示例报告](examples/sample_report.html) · [配置指南](docs/configuration.md) · [命令行与迁移](docs/advanced.md) · [验收记录](VERIFICATION.md) · [发布自检](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="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+。最新发布与可安装版本以 [GitHub Releases](https://github.com/ysc070528/granttrace/releases) 和 [PyPI](https://pypi.org/project/granttrace/) 为准。安装包包含内置 `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
@@ -57,11 +65,38 @@ 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**。
 
-完整离线示例：[HTML 报告](examples/sample_report.html)（下载后用浏览器打开）与 [JSON 结果](examples/sample_result.json)。
+完整离线示例：[HTML 报告](https://github.com/ysc070528/granttrace/blob/main/examples/sample_report.html)（下载后用浏览器打开）与 [JSON 结果](https://github.com/ysc070528/granttrace/blob/main/examples/sample_result.json)。
 
 ## 接入自己的 API
 
@@ -96,22 +131,22 @@ granttrace --spec your-openapi.yaml --target https://authorized-test.example \
 
 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)。
+OpenAPI 和离线验证不能证明资源归属、业务授权策略、合法测试权限、生产读回一致性或实际恢复能力；检查通过只代表配置结构及支持的语义通过当前检查。账户、API Key / Cookie、合法共享和管理员访问见 [配置指南](https://github.com/ysc070528/granttrace/blob/main/docs/configuration.md)，输出与自动化兼容性见 [命令行说明](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md)。支持的数组、布尔值及 `style` / `explode` 编码见 [参数规则](https://github.com/ysc070528/granttrace/blob/main/docs/parameter-serialization.md)。接入实测前请核对 [安全边界](https://github.com/ysc070528/granttrace/blob/main/SECURITY.md)。
 
 ## SARIF 导出
 
-`--export-sarif PATH` 可与 HTML / JSON 同时使用：
+`--export-sarif PATH` 可与 HTML / JSON 同时使用。启动下方仓库 mock 后，在明确授权、可丢弃的本机靶场执行；此命令会发送读取请求，默认 **0 PATCH**：
 
 ```bash
-granttrace --spec your-openapi.yaml --config config.local.json \
+granttrace --spec openapi.json --target http://127.0.0.1:8080 --config config.example.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-导出)。
+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。详见 [兼容说明](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md#sarif-导出)。
 
 ## cURL 复现模板
 
-HTML 确认漏洞卡片可提供安全的 POSIX shell cURL 模板和“复制 cURL”按钮。所有认证值均为 Visitor 占位符，即使使用 `--include-sensitive-evidence` 也不会放入模板。请只在明确授权的测试环境中填入自己的测试凭据；脱敏值需人工补全，信息不足时不提供按钮。离线报告支持复制 fallback，也可直接选择命令文本。详见 [复现说明](docs/advanced.md#curl-复现模板)。
+HTML 确认漏洞卡片可提供安全的 POSIX shell cURL 模板和“复制 cURL”按钮。所有认证值均为 Visitor 占位符，即使使用 `--include-sensitive-evidence` 也不会放入模板。请只在明确授权的测试环境中填入自己的测试凭据；脱敏值需人工补全，信息不足时不提供按钮。离线报告支持复制 fallback，也可直接选择命令文本。详见 [复现说明](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md#curl-复现模板)。
 
 ## 从源码开发 / 运行仓库 mock
 
@@ -148,8 +183,8 @@ python scripts/verify_business_scenarios.py
 python scripts/verify_install.py
 ```
 
-测试直接使用仓库中的 `config.example.json`，无需创建本地凭据文件。[业务场景验收](docs/business-scenarios.md) 单独记录团队共享、管理员读取、跨租户拒绝和故意越权的真值、误报与漏报；[验收记录](VERIFICATION.md) 标明实际测试环境和范围。
+测试直接使用仓库中的 `config.example.json`，无需创建本地凭据文件。[业务场景验收](https://github.com/ysc070528/granttrace/blob/main/docs/business-scenarios.md) 单独记录团队共享、管理员读取、跨租户拒绝和故意越权的真值、误报与漏报；[验收记录](https://github.com/ysc070528/granttrace/blob/main/VERIFICATION.md) 标明实际测试环境和范围。
 
-“没有确认漏洞”不等于系统安全。检查覆盖率、错误、可疑和不确定项；显式授权预期只适用于本次身份与资源组合。仅在具备专用测试账户、独立读回和恢复方案的隔离环境启用写测试。远程 `$ref`、GraphQL、gRPC、自动 OAuth / mTLS 登录以及 POST / PUT 主动测试尚未实现。更多规则与迁移说明见 [操作指南](docs/advanced.md)。
+“没有确认漏洞”不等于系统安全。检查覆盖率、错误、可疑和不确定项；显式授权预期只适用于本次身份与资源组合。仅在具备专用测试账户、独立读回和恢复方案的隔离环境启用写测试。远程 `$ref`、GraphQL、gRPC、自动 OAuth / mTLS 登录以及 POST / PUT 主动测试尚未实现。更多规则与迁移说明见 [操作指南](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md)。
 
 Apache License 2.0。

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

@@ -1,28 +1,36 @@
 # GrantTrace
 
 ![CI](https://github.com/ysc070528/granttrace/actions/workflows/test.yml/badge.svg)
+[![PyPI](https://img.shields.io/pypi/v/granttrace.svg)](https://pypi.org/project/granttrace/)
 ![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/)
+**源码 / 包元数据版本：2.5.2** · [GitHub Releases](https://github.com/ysc070528/granttrace/releases) · [PyPI](https://pypi.org/project/granttrace/)
+
+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 报告。默认只读；主动写测试须显式开启并配置允许清单与独立读回。
 
-[五分钟体验](#五分钟体验) · [完整示例报告](examples/sample_report.html) · [配置指南](docs/configuration.md) · [命令行与迁移](docs/advanced.md) · [验收记录](VERIFICATION.md) · [发布自检](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="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+。最新发布与可安装版本以 [GitHub Releases](https://github.com/ysc070528/granttrace/releases) 和 [PyPI](https://pypi.org/project/granttrace/) 为准。安装包包含内置 `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
@@ -30,11 +38,38 @@ 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**。
 
-完整离线示例：[HTML 报告](examples/sample_report.html)（下载后用浏览器打开）与 [JSON 结果](examples/sample_result.json)。
+完整离线示例：[HTML 报告](https://github.com/ysc070528/granttrace/blob/main/examples/sample_report.html)（下载后用浏览器打开）与 [JSON 结果](https://github.com/ysc070528/granttrace/blob/main/examples/sample_result.json)。
 
 ## 接入自己的 API
 
@@ -69,22 +104,22 @@ granttrace --spec your-openapi.yaml --target https://authorized-test.example \
 
 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)。
+OpenAPI 和离线验证不能证明资源归属、业务授权策略、合法测试权限、生产读回一致性或实际恢复能力；检查通过只代表配置结构及支持的语义通过当前检查。账户、API Key / Cookie、合法共享和管理员访问见 [配置指南](https://github.com/ysc070528/granttrace/blob/main/docs/configuration.md)，输出与自动化兼容性见 [命令行说明](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md)。支持的数组、布尔值及 `style` / `explode` 编码见 [参数规则](https://github.com/ysc070528/granttrace/blob/main/docs/parameter-serialization.md)。接入实测前请核对 [安全边界](https://github.com/ysc070528/granttrace/blob/main/SECURITY.md)。
 
 ## SARIF 导出
 
-`--export-sarif PATH` 可与 HTML / JSON 同时使用：
+`--export-sarif PATH` 可与 HTML / JSON 同时使用。启动下方仓库 mock 后，在明确授权、可丢弃的本机靶场执行；此命令会发送读取请求，默认 **0 PATCH**：
 
 ```bash
-granttrace --spec your-openapi.yaml --config config.local.json \
+granttrace --spec openapi.json --target http://127.0.0.1:8080 --config config.example.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-导出)。
+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。详见 [兼容说明](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md#sarif-导出)。
 
 ## cURL 复现模板
 
-HTML 确认漏洞卡片可提供安全的 POSIX shell cURL 模板和“复制 cURL”按钮。所有认证值均为 Visitor 占位符，即使使用 `--include-sensitive-evidence` 也不会放入模板。请只在明确授权的测试环境中填入自己的测试凭据；脱敏值需人工补全，信息不足时不提供按钮。离线报告支持复制 fallback，也可直接选择命令文本。详见 [复现说明](docs/advanced.md#curl-复现模板)。
+HTML 确认漏洞卡片可提供安全的 POSIX shell cURL 模板和“复制 cURL”按钮。所有认证值均为 Visitor 占位符，即使使用 `--include-sensitive-evidence` 也不会放入模板。请只在明确授权的测试环境中填入自己的测试凭据；脱敏值需人工补全，信息不足时不提供按钮。离线报告支持复制 fallback，也可直接选择命令文本。详见 [复现说明](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md#curl-复现模板)。
 
 ## 从源码开发 / 运行仓库 mock
 
@@ -121,8 +156,8 @@ python scripts/verify_business_scenarios.py
 python scripts/verify_install.py
 ```
 
-测试直接使用仓库中的 `config.example.json`，无需创建本地凭据文件。[业务场景验收](docs/business-scenarios.md) 单独记录团队共享、管理员读取、跨租户拒绝和故意越权的真值、误报与漏报；[验收记录](VERIFICATION.md) 标明实际测试环境和范围。
+测试直接使用仓库中的 `config.example.json`，无需创建本地凭据文件。[业务场景验收](https://github.com/ysc070528/granttrace/blob/main/docs/business-scenarios.md) 单独记录团队共享、管理员读取、跨租户拒绝和故意越权的真值、误报与漏报；[验收记录](https://github.com/ysc070528/granttrace/blob/main/VERIFICATION.md) 标明实际测试环境和范围。
 
-“没有确认漏洞”不等于系统安全。检查覆盖率、错误、可疑和不确定项；显式授权预期只适用于本次身份与资源组合。仅在具备专用测试账户、独立读回和恢复方案的隔离环境启用写测试。远程 `$ref`、GraphQL、gRPC、自动 OAuth / mTLS 登录以及 POST / PUT 主动测试尚未实现。更多规则与迁移说明见 [操作指南](docs/advanced.md)。
+“没有确认漏洞”不等于系统安全。检查覆盖率、错误、可疑和不确定项；显式授权预期只适用于本次身份与资源组合。仅在具备专用测试账户、独立读回和恢复方案的隔离环境启用写测试。远程 `$ref`、GraphQL、gRPC、自动 OAuth / mTLS 登录以及 POST / PUT 主动测试尚未实现。更多规则与迁移说明见 [操作指南](https://github.com/ysc070528/granttrace/blob/main/docs/advanced.md)。
 
 Apache License 2.0。