cognis-digital/archivesnap

# archivesnap **网页快照与变更监控工具。** 捕获页面的规范化快照（可见文本 + 内容哈希 + 时间戳），将快照存储在本地，对比最新快照与上一个快照的差异，并在忽略无关紧要的空格/标记噪音的同时，报告*有意义的*变更。 archivesnap 专为**防御性监控**而构建——用于关注咨询页面、政策页面、状态页面、服务条款更新及类似内容，方便您了解具体措辞何时发生实际变化。它不是用于批量提取的爬虫；网络访问是可选的（opt-in）。 - 仅使用标准库。无第三方运行时依赖。 - Python 3.10+。 - 网络功能被抽象在可注入的获取器（fetcher）之后，因此在测试和从本地文件运行时完全离线。`--live` 标志使用 `urllib` 进行真实抓取。 许可证：COCL 1.0 维护者：Cognis Digital ## 安装 ``` pip install -e ".[dev]" # dev extras add pytest ``` 这将安装 `archivesnap` 控制台命令。 ## 工作原理 1. **规范化（Normalize）。** HTML 被简化为可见文本：`script`/`style`/`head` 内容会被丢弃，移除标签，解码实体，并将空格压缩为稳定的规范形式。两次仅在标记或重排空格上存在差异的捕获将被规范化为相同的文本。 2. **哈希。** 规范化后的文本会生成一个 SHA-256 内容哈希，用于快速进行相等性检查。 3. **存储。** 每个快照都是存储根目录下特定于 URL 目录中的一个 JSON 文件，以捕获时间戳命名。 4. **对比。** 最新快照使用 `difflib` 与前一个快照进行比较。`[0, 1]` 之间的**变更比率**用于衡量变化的程度；一个可配置的**阈值**决定该更改是否*显著*。 ## 命令 ### snapshot 捕获并存储快照。默认离线运行 —— 将其指向本地文件： ``` archivesnap snapshot https://acme.example/advisory \ --store snapshots --from-file examples/policy_v1.html ``` 改为通过网络实时抓取： ``` archivesnap snapshot https://acme.example/advisory --store snapshots --live ``` ### diff 将最新快照与前一个快照进行对比： ``` archivesnap diff https://acme.example/advisory --store snapshots --threshold 0.05 ``` 输出统一差异（unified diff）、变更比率、增加/删除的行数，以及显著性的判定结论。 ### list 列出某个 URL 存储的快照（从旧到新），包含时间戳和短哈希值： ``` archivesnap list https://acme.example/advisory --store snapshots ``` ### watch 在单次运行中检查 JSON 配置文件中的页面列表： ``` archivesnap watch examples/watch.config.json --once ``` 添加 `--fail-on-change`，以便在任何页面发生显著变化时使进程以非零状态退出 —— 非常适合作为 CI/调度程序的门禁： ``` archivesnap watch examples/watch.config.json --once --fail-on-change ``` 添加 `--live` 以通过网络抓取每个页面，而不是从文件读取。 #### watch 配置格式 ``` { "store": "snapshots", "threshold": 0.05, "pages": [ { "url": "https://acme.example/advisory", "from_file": "policy_v2.html" } ] } ``` 相对路径的 `store` 和 `from_file` 会根据存放配置文件的目录进行解析。省略 `from_file` 并传入 `--live` 可通过网络进行抓取。 ## 快速离线演示 ``` # Baseline，然后是一个更改后的版本，接着是 diff： archivesnap snapshot https://acme.example/advisory --store /tmp/snaps --from-file examples/policy_v1.html archivesnap snapshot https://acme.example/advisory --store /tmp/snaps --from-file examples/policy_v2.html archivesnap diff https://acme.example/advisory --store /tmp/snaps ``` 示例测试夹具更改了支持时间（6 PM -> 8 PM）、门户状态（正常 -> 计划内维护）以及联系说明 —— 这是一个在默认阈值之上的显著变化，即使在两个版本之间标记和空格也被重新调整过。 ## 示例目录 - `examples/policy_v1.html` —— 基础咨询页面。 - `examples/policy_v2.html` —— 更新后的咨询页面（及重排的标记）。 - `examples/watch.config.json` —— 单页面的 watch 配置。 ## 开发 ``` PYTHONUTF8=1 python -m pytest # Windows python -m pytest # other platforms ``` 测试涵盖了快照的存储/加载、差异对比与变更比率评分、显著性阈值、使用内存中模拟获取器（fetcher）的 watch 流程，以及 `--fail-on-change` 退出门禁。没有任何测试会访问网络。 ## 范围与意图 archivesnap 旨在对您有权监控的内容进行**合法的、防御性的页面监控**。请尊重每个站点的服务条款和 `robots.txt`，并负责任地对实时抓取进行限速。

标签：Homebrew安装, Python, 内容差异对比, 变更监控, 安全规则引擎, 无后门, 网页快照, 自动化监控, 逆向工具