fors33-official/fors33-scanner

# fors33-scanner [](https://github.com/fors33-official/fors33-scanner/actions) [](https://pypi.org/project/fors33-scanner/) [](https://pypi.org/project/fors33-scanner/) [](https://hub.docker.com/r/fors33/fors33-scanner) [](https://hub.docker.com/r/fors33/fors33-scanner) [](https://github.com/fors33-official/fors33-scanner/blob/main/LICENSE) 高速文件完整性与基线扫描器。遍历一个或多个根目录，测量数据重力（字节），并根据相邻伴随文件的存在（.f33, .sig, .asc, .sha256, .sha512, .blake3, .md5, .pem）将大文件分类为已认证或未认证。输出校验和基线（Hash Filename 格式）、CSV 或 JSON，以便与 fors33-verifier 结合使用。 **信任模型：** 该扫描器是一个基于伴随文件存在的 O(1) 发现与责任映射工具。它不验证 Ed25519 签名或基线的加密证明。如需完整的加密验证，请使用 fors33-verifier。 如需机器解析，请参阅 [LLM_CONTEXT.md](LLM_CONTEXT.md)。

发布说明与版本历史

### 0.8.1 (2026-05-10) - **向后兼容的统计信息（0.8.0 之前的计算方式）**：**`--legacy-scanner-stats`** 或 **`FORS33_SCANNER_LEGACY_STATS=1`** 恢复了阈值以下的单文件 **`skipped_files`** 计数，并将 **`.blake3`** 伴随文件视为 **不** 提供外部认证覆盖（库：**`legacy_scanner_stats`** 包含两者；**`below_threshold_single_file_counts_skipped`** 和 **`recognize_blake3_sidecar`** 在 **`scan_roots`** / **`execute_scan`** 上仍可单独使用）。 ### 0.8.0 (2026-05-10) - **与 Docker 扩展的单文件对等性**：`_scan_single_file` 使用 **`stat(..., follow_symlinks=False)`**、带有 **`is_file(follow_symlinks=False)`** 的 **`os.scandir`** 兄弟节点发现机制，当 **根路径基本名称** 本身是已知的伴随文件后缀时跳过扫描，并同样适用于 **`scan_roots`** 和 **`execute_scan`**。 - **`.blake3`** 已加入 **`_ATT_EXTS`**，因此 BLAKE3 伴随文件可归类为外部认证覆盖。 - 阈值以下的单文件路径不再累加 **`skipped_files`**（静默跳过，扩展样式）。 ### 0.7.1 (2026-05-10) - **未验证样本上的 `has_sidecar`**：`ScanStats.add_unverified_sample(..., *, has_sidecar=False)` 在每个采样的未认证路径上记录 `"has_sidecar": "true"` 或 `"false"`（与 L3dgr 扩展的形状相同），用于下游重新封装的用户体验。 - **供应链**：来自 `publish-fors33-scanner` 的 Docker 镜像附带 **SBOM** 和 **SLSA provenance**（`sbom: true`，`provenance: mode=max`）。对于受监管的部署，请通过摘要固定版本。 ### 0.7.0 (2026-05-01) - 单文件扫描根路径、伴随文件对等性（`.f33`、`.sig`、`.asc`、校验和伴随文件等）、单文件路径上的基线/JSON/JSONL 输出，更严格的 `--strict-audit` 和零字节阈值行为。 ### 0.6.0 (2026-04-16) - `hash_core` mmap 上限、cgroup 对齐、Worker 上限 **64**、`default_dpk_worker_count()` / `FORS33_DPK_MAX_WORKERS`。 ### 0.5.0 和 0.4.0 - `--strict-audit`、`unverified_paths_sample`、`--tsa-url`、JSONL 多根路径元数据、`--max-exposure`、`--emit-jsonl`、`--max-depth`。完整文本：[CHANGELOG.md](CHANGELOG.md)。 ### 发布模型 - Docker 发布是通过 GitHub Actions 的 **`workflow_dispatch`** **手动**进行的，带有显式的 **`version`**（不带前导 `v`，例如 `0.8.1`）和 **`push_latest`**；它 **不会** 仅在 git 标签上自动运行。PyPI 发布由维护者驱动（`python -m build`，`twine upload`），除非您的组织另有配置。

## 安装 ``` pip install fors33-scanner ``` ## 使用方法 使用 1 MB 阈值扫描当前目录（默认根路径）： ``` fors33-scanner --threshold-mb 1.0 ``` 扫描多个根路径： ``` fors33-scanner --root /var/log --root /data/telemetry --threshold-mb 10 ``` 输出 JSON 而非人类可读的输出（适用于 CI、流水线）： ``` fors33-scanner --root /data --json ``` 当暴露程度违反策略阈值时使 CI/CD 失败： ``` fors33-scanner --root /data --max-exposure 5.0 --json ``` 为共享运行器限流哈希 Worker： ``` fors33-scanner --root /data --workers 2 ``` 流式输出 SIEM 就绪的 JSONL 事件（记录 + 摘要）： ``` fors33-scanner --root /data --emit-jsonl - ``` 限制遍历深度（`0=仅根目录`，`1=根目录 + 直接子项`）： ``` fors33-scanner --root /data --max-depth 1 ``` 严格审计（遇到权限或文件锁定错误时失败，而不是跳过）： ``` fors33-scanner --root /data --strict-audit ``` **单文件扫描：** ``` # 扫描单个文件 fors33-scanner --root /path/to/file.csv # 扫描单个文件并生成 baseline fors33-scanner --root /path/to/file.csv --emit-checksums baseline.txt # 扫描带有 JSON manifest 的单个文件 fors33-scanner --root /path/to/file.csv --emit-json manifest.json ``` 单文件模式除了接受目录外，还接受单个文件路径，从而无需目录遍历即可直接扫描特定文件。默认情况下，它识别所有认证伴随文件扩展名（.f33, .sig, .asc, .sha256, .sha512, .blake3, .md5, .pem），以保持与目录扫描的对等性。 0.8.0 之前的统计信息（阈值以下的单文件根路径会增加 `skipped_files`，并且 `.blake3` 兄弟文件不计入外部认证）： ``` fors33-scanner --root /data --legacy-scanner-stats ``` 等效方式：设置 **`FORS33_SCANNER_LEGACY_STATS=1`**。 为读取 `FORS33_TSA_URL` 的工具记录 TSA 端点： ``` fors33-scanner --tsa-url https://tsa.example.com/rfc3161 ``` Worker 数量：优先使用 **正数 `--workers`**；否则使用 **正数 `FORS33_WORKERS`**；否则使用 **`default_dpk_worker_count()`**（使用 `cpu_count` 和可选的 **`FORS33_DPK_MAX_WORKERS`**）。非正值表示自动。硬性上限为 **64**。 大文件哈希使用 **`FORS33_MMAP_MIN_MB`** / **`FORS33_MMAP_MAX_MB`**（默认值为 `500` / `4000`），在 Linux 上限制为 cgroup/RAM 上限；可选的 **`FORS33_MMAP_PSI_SOME_AVG10_MAX`** 会在内存压力下禁用 mmap。 对于生产环境的 Docker 或 CI，请**固定** **semver 镜像标签**或**不可变摘要**，而不是仅仅依赖 `:latest`。 生成校验和基线（根据 --algo 选择 sha256、sha512 或 blake3）： ``` fors33-scanner --root /data --emit-checksums fors33_baseline.sha256 fors33-scanner --root /data --algo sha512 --emit-checksums fors33_baseline.sha512 ``` 输出 CSV 或 JSON 基线（与 fors33-verifier 兼容）： ``` fors33-scanner --root /data --emit-csv fors33_baseline.csv fors33-scanner --root /data --emit-json fors33_baseline.json ``` 在人类可读的输出中添加合规暴露文本（默认为纯数学展示）： ``` fors33-scanner --root /data --compliance-report ``` ## 退出码 - `0`：扫描成功 / 未违反阈值 - `1`：暴露阈值违反（`--max-exposure`） - `2`：调用/参数误用，或 **`--strict-audit`** I/O 访问失败 - `130`：用户中断扫描（Ctrl+C） ## 输出 默认的人类可读输出（仅数学计算）： ``` [FILE COUNT] : 14,205 [TOTAL BYTES] : 2.1 TB [ATTESTED] : 48 files, 4.1 GB [UNATTESTED] : 264 files, 2.1 TB [ELAPSED] : 4.20s ``` ## 安全性与范围 - 只读：不修改文件或伴随文件。 - 仅扫描：O(1) 发现；基线生成使用流式分块哈希。 - 排除常见目录（.git、node_modules、venv 等）。遵循 .f33ignore 以及 --ignore-pattern / --exclude-dir。 - 法律声明在启动时打印到 `stderr`，因此 `stdout` 上的 data/JSON 流保持可安全解析。 - 有关企业法律/监管边界，请参阅 `DISCLAIMER.md`。 ## JSONL 契约 - `--emit-jsonl PATH` 每行输出一个扁平的 JSON 对象。 - 多根路径扫描在每个 `scan_record` 中同时包含 `root_index` 和 `root_path`。 - `timestamp` 表示哈希完成时间。 - 最后一行是 `scan_summary`，包含聚合统计信息和扫描参数。 - 如果同时请求 `--emit-jsonl -` 和 `--json`，JSONL 优先输出到 `stdout`。 - **`unverified_paths_sample`** 条目（JSON/JSONL 消费者）：自 **0.7.1** 起，每一行包含 **`path`**、**`status`** 和 **`has_sidecar`**（`"true"` / `"false"`），以便与封装/重新封装工作流集成。 ## 环境要求 Python 3.9+。BLAKE3 哈希可选择安装 `blake3`。支持 Linux、macOS、Windows。 ## 许可证 MIT 许可证。详见 `LICENSE`。

标签：BLAKE3, CSV, CVE, Docker, Ed25519, ESIC, JSON, MD5, Python, SEC 17a-4, SHA256, SHA512, Sidecar, WORM存储, 人工智能安全, 加密扫描器, 合规性, 基线扫描, 安全防御评估, 密码学, 手动系统调用, 指令遵循, 数字签名, 数据引力, 文件完整性, 无后门, 监管合规, 证据链, 请求拦截, 责任映射, 逆向工具, 风险暴露评估