fors33-official/fors33-verifier

# fors33-verifier [](https://github.com/fors33-official/fors33-verifier/actions) [](https://pypi.org/project/fors33-verifier/) [](https://pypi.org/project/fors33-verifier/) [](https://hub.docker.com/r/fors33/fors33-verifier) [](https://hub.docker.com/r/fors33/fors33-verifier) [](https://github.com/fors33-official/fors33-verifier/blob/main/LICENSE) 用于已认证数据段和通用文件完整性基线的独立验证工具。对于机器可读的上下文（LLMs、网络爬虫），请参阅 [LLM_CONTEXT.md](LLM_CONTEXT.md)。确认数据段或目录树是否与发布的哈希值匹配。 ## 安装 ``` pip install fors33-verifier ``` 版本发布通过 `python -m build` 和 `twine upload` 手动发布到 PyPI；GitHub Actions 工作流 `publish-fors33-verifier` **仅**负责构建并推送 Docker 镜像。该工作流**仅在**你使用显式的 **`version`**（不带前缀 `v`，例如 `0.8.0`）和 **`push_latest`** 触发 **`workflow_dispatch`** 时运行——它**不会**在 git tags 上自动运行。 ## 用法 **远程（预签名 URL，完整文件）：** ``` fors33-verifier --url "https://..." --expected-hash ``` **远程（HTTP Range，仅数据段）：** ``` fors33-verifier --url "https://..." --start 0 --end 1048576 --expected-hash ``` **本地完整文件：** ``` fors33-verifier --file /path/to/segment.csv --expected-hash ``` **本地数据段（直接字节范围）：** ``` fors33-verifier --file /path/to/data.csv --start 0 --end 4096 --expected-hash ``` **本地数据段（使用认证记录）：** ``` fors33-verifier --file /path/to/data.csv --record /path/to/attestation_record.json ``` 认证记录 JSON 必须包含 `byte_start`、`byte_end` 和 `hash`。采用节省内存的分块读取方式，因此大文件不会导致 OOM。 **目录验证（清单模式）：** ``` fors33-verifier --mode manifest --file ./baseline.sha256 --root ./root --format json ``` 使用 `--root`（或已废弃的 `--target-dir`）指定要验证的目录。默认情况下会拒绝清单中的 MD5/SHA-1；请对旧版清单使用 `--force-insecure`。 根据校验和清单（GNU/BSD 风格的文本或 JSON）验证目录。输出结构化的偏差报告，包含 `modified`、`created`、`deleted`、`mutated_during_verification` 和 `skipped`。 **附属文件验证：** ``` fors33-verifier --mode sidecars --file ./root --format json ``` 遍历文件树并就地验证 `.f33`、`.sha256`、`.sha512` 和 `.md5` 附属文件。 针对 JSON `.f33` 附属文件的可选 TSA 验证： ``` fors33-verifier --mode manifest --verify-tsa --file ./manifest.json --root ./root --format json ``` 使用 `--verify-tsa` 时，验证器接受 **`predicate.tsa.response_token`**（新的增强格式）或 **`predicate.tsa.rfc3161_token_b64`**（旧版格式）或顶层 **`predicate.rfc3161_token_b64`**（RFC 3161 `TimeStampResp` DER，Base64）和/或旧版 **Ed25519** `predicate.tsa` 块。RFC 令牌通过离线方式检查：PKI 状态为已授权、时间戳令牌上的 CMS 签名，以及基于与主 Ed25519 签名相同的**规范认证字节**（V1/V2 面向行的 payload，或在缺少 `canonical_payload_version` 时的旧版 JSON）的 **message imprint**（来自令牌的哈希 OID）。MD5/SHA-1 印记算法将被拒绝。 **收据验证（独立数据集验证）：** ``` fors33-verifier --verify-receipt receipt.json --root ./dataset ``` 验证包含数据集摘要和 Ed25519 签名的便携式 JSON 收据。收据支持离线验证，无需原始验证守护程序。 **审计包验证（带分离签名的 PDF）：** ``` # Explicit flags fors33-verifier --audit-package report.pdf --sig report.sig --pubkey public_key.pem # Smart routing (自动检测) fors33-verifier --file report.pdf fors33-verifier --file audit_package.zip ``` 验证 PDF 审计包的分离 Ed25519 签名。智能路由会自动检测 ZIP 压缩包和 PDF 文件，并发现同目录下的关联 .sig 和 .pem 文件。 **批量验证（多个审计包）：** ``` # Text output (默认) fors33-verifier --directory /path/to/audit/packages # 用于 CI/CD 集成的 JSON output fors33-verifier --directory /path/to/audit/packages --json # With custom worker count fors33-verifier --directory /path/to/audit/packages --workers 16 ``` 在单个命令中验证多个审计包（PDF、ZIP、密封数据集），采用硬件限制的并发处理。自动发现 PDF 文件、ZIP 压缩包和密封数据集（包含 `fors33-manifest.json` 或 `manifest.json` 的目录）。如果所有包均通过，则返回退出码 0；如果任一包失败，则返回 1。JSON 输出包含针对自动化流水线的每个包结果和汇总统计数据。 ## 旧版 OpenPGP / GnuPG 与 fors33-verifier（关注点分离） 本包刻意保持**狭窄的执行路径**：Ed25519 签名的 JSON `.f33` 认证、标准校验和附属文件（`.sha256`、`.sha512`、`.md5`）以及清单验证。它**不会**解析或验证 **OpenPGP**（`.asc`、分离的 PGP 签名、密钥环）。 对于**旧版 PGP / GnuPG** 构件，请使用您的组织已经信任的工具——例如，使用 **`gpg --verify`** 根据签名者的公钥和分离签名文件进行验证——并将其与 fors33-verifier **结合使用**，以处理**确定性的 `.f33` 供应链认证**和**已发布的哈希基线**。这两者的作用是互补的：GnuPG 回答“这个二进制数据块是否由此 PGP 密钥签名？”；而 fors33-verifier 回答“此文件或文件树是否与我们套件中提供的已认证摘要和密封元数据相匹配？”，而无需将 OpenPGP 引入验证器的依赖项或攻击面。 **清单哈希工作线程**（仅限线程池）： ``` fors33-verifier --mode manifest --workers 8 --file ./manifest.json --root ./root ``` 工作线程数量：优先使用 **正数的 `--workers`**；否则使用 **正数的 `FORS33_WORKERS`**；否则使用 **`default_dpk_worker_count()`**（使用 `cpu_count` 和可选的 `FORS33_DPK_MAX_WORKERS`）。非正值表示自动。硬性上限为 **64**。 **操作员注册表**：当设置 **`F33_KEY_REGISTRY_PATH`** 为非空路径时，该文件必须在验证开始前存在且可读。未设置或为空时，将跳过注册表检查。 **大文件哈希**（`hash_core`）：mmap 窗口使用 `FORS33_MMAP_MIN_MB` / `FORS33_MMAP_MAX_MB`（默认值为 `500` / `4000`），在 Linux 上受 cgroup/RAM 上限限制；可选的 **`FORS33_MMAP_PSI_SOME_AVG10_MAX`** 在 cgroup v2 内存压力 `some avg10` 超过阈值时禁用 mmap。可选的全局读取节流：`set_global_read_bytes_per_second`（用于扩展；已发布的 CLI 未设置它）。 ## 输出 带有时间戳、目标、SHA-256 和状态的系统日志格式。 退出码： - `0`：验证通过 / 无偏差 - `1`：偏差或缺少密封（`[ ERR_MISSING_SEAL ]`） - `2`：调用或参数误用 - `3`：严重的信任故障（例如签名错误、清单受损、无效的 TSA） 清单/附属文件模式支持带有 `--warn-only` 的 `--format json`，以报告偏差而不导致失败。 ## GitHub Action (CI/CD) 在你的工作流中使用 **FORS33 Data Provenance Check**。当哈希不匹配时，该步骤将失败（退出码 1），从而阻止流水线。 **`action.yml`** 中默认的 `image:` 标签**仅**用于快速入门。对于生产或受合规监管的 CI，请**固定**一个 **semver 镜像标签**（例如 `:0.7.0`）或一个**不可变摘要**——切勿将 `:latest` 作为您的合规基线。 ``` - name: Verify data integrity uses: fors33-official/fors33-verifier@v1 # or your tag with: file: ./dist/artifact.bin expected-hash: 'abc123...' ``` 对于 URL 验证（仅限预签名 URL；无文件上传）： ``` - uses: fors33-official/fors33-verifier@v1 with: url: 'https://example.com/presigned.csv' expected-hash: 'abc123...' ``` FORS33 Data Provenance Kit 可在 AWS S3、Snowflake 和本地基础设施上运行。请访问 [fors33.com](https://fors33.com) 或 [GitHub Marketplace](https://github.com/marketplace) 获取许可证。 ## Docker ``` docker run --rm ghcr.io/fors33/fors33-verifier:0.8.0 --url "https://..." --expected-hash # or docker run --rm docker.io/fors33/fors33-verifier:0.8.0 --file /data/file.csv --expected-hash ``` `:latest` 便于探索使用；在生产流水线中请固定一个**版本标签**或**摘要**，以保持运行的可重现性。 ## 仅限 URL 的 API 对于仅验证**预签名 URL**（无文件上传）的托管 API，请使用 `serve` 命令运行镜像。浏览器内验证必须使用客户端的 **Web Crypto API**；文件永远不会离开用户的机器。 ## 系统要求 Python 3.9–3.12。`cryptography` 和 `asn1crypto`（必需）。可选 `blake3` 以加快哈希速度。支持平台：Linux、macOS、Windows。 ## 许可证 MIT 许可证。请参阅 LICENSE 文件。

标签：CLI, DNS 解析, Docker, GitHub Actions, HTTP Range, IT运维安全, JSONLines, pip, PyPI, Python, SHA256, WiFi技术, Zenmap, 不可变审计追踪, 哈希校验, 基线建立, 安全防御评估, 密码学验证, 数字取证, 数据完整性, 数据来源证明, 数据防篡改, 无后门, 自动化脚本, 自动化验证, 自动笔记, 请求拦截, 逆向工具, 防篡改, 零信任, 预签名URL, 高完整性数据