Garnet Guard

Garnet Guard checks every dependency update against the last release you trusted, and tells you when it looks different in ways that matter.

Trust the last release. Check the next.

Status: alpha. 0.2.0 is on PyPI: pip install garnet-guard. The GitHub Action is a preview. Website, rule pages and replays: garnetguard.dev.

Why

The most damaging supply-chain attacks of 2025–26 did not come from obscure typosquats. They came from packages people already trusted. An attacker took over a maintainer account, a stored publish token or a project's CI, and pushed a new version that looked routine:

• lightning 2.6.2 / 2.6.3 (PyPI, April 2026) was uploaded outside the project's CI, with no matching git tag, and ran its payload at import time.
• elementary-data 0.23.3 (PyPI, April 2026) was published by the project's own hijacked pipeline and added a .pth file that runs on every Python start.
• litellm 1.82.7 / 1.82.8 and telnyx 4.87.1 / 4.87.2 (PyPI, March 2026) were uploaded with publish tokens stolen through a poisoned security scanner in CI, and ran their payloads at import time; litellm 1.82.8 also added a .pth file.
• ultralytics 8.3.41 / 8.3.42 (PyPI, December 2024) were built and signed by the project's own release workflow after its build cache was poisoned; 8.3.45 / 8.3.46 followed days later with a publish token left in CI.
• chalk, debug and the Shai-Hulud worm (npm, September 2025) spread through hijacked accounts to 500+ packages.

Malware feeds caught these only after the fact. Cooldowns only buy time. pip and uv do not verify PyPI's signing attestations at all. But each malicious release differed from the previous good release in ways a machine can check. Garnet checks them.

What it flags

Garnet never runs the code it inspects. It downloads both releases and reads them statically: the sdist and the wheel pip would install, plus one wheel for each other platform and up to 30 wheels uploaded late, to compare with it.

How you'll use it

On Dependabot and Renovate PRs (first release). Add the Garnet Guard Action, and it posts one comment per dependency PR. Updates with nothing worth a look collapse out of the way:

_{A sample comment. The examplelib findings are illustrative; the replays below are real.}

Add it as .github/workflows/garnet-guard.yml:

name: Garnet Guard
on:
  pull_request:
    paths: ["**/uv.lock", "**/poetry.lock", "**/pylock.toml", "**/pylock.*.toml", "**/requirements*.txt", "garnet.toml"]
permissions: {}
jobs:
  garnet-guard:
    runs-on: ubuntu-latest
    permissions:
      contents: read        # read the lockfiles and the base commit
      pull-requests: write  # post or update the comment
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: orca-solutions/garnet-guard@42547f6313420768a2bf5d03e9577a68844496e9 # v0.1.0a1

The example pins the commit tagged v0.1.0a1, the first preview release. Inputs, permissions and the fork-safe two-workflow pattern are in docs/action.md. The Action is a preview.

Locally. garnet check compares two lockfiles, for example your branch against main, and checks every package that changed. Once you've reviewed a finding, an ignore in garnet.toml silences it until a date you choose (docs/policy.md).

In agent hooks (planned). A pre-install hook stops Claude Code or Codex from quietly adding a risky dependency.

Replays of real malicious releases

We fed the original malicious files from 36 compromised PyPI packages (47 malicious releases, December 2024 to September 2026) through garnet diff, using each project's previous release as the baseline. The files are still served by files.pythonhosted.org and are checked against PyPI's published hashes. Nothing was executed. Known-bad feeds were switched off, so these results show only what the release diff found by itself. Git tags are checked as they stood on the day of each upload.

All 47 malicious releases got a warning. Three of them only after fixes that the replay itself prompted (ultralytics 8.3.42, embiggen 0.11.97, mrmustard 0.7.4; see the limits below).

The same replay covers the npm account takeovers of August and September 2025, and event-stream 3.3.6 (2018), which added a dependency that later carried the payload. npm deletes the tarball of a removed version, so these use the registry facts the public write-ups recorded (provenance present or not, the package.json scripts and dependencies) and fetch the previous release and the repository's tags live. The malicious tarballs were not inspected.

Limits, stated plainly:

• Three releases were missed by the rules as first written, and the replay is why they aren't now. ultralytics 8.3.42 was built and published by the project's own release workflow, with valid attestations and its usual git tag, after a GitHub Actions cache-poisoning attack, and its miner runs when a model is downloaded, not at import; no trust or import-time rule sees it. GRN-C007 was written for it: it compares the wheel's Python files with the repository at the release's tag and reports the two that differ. embiggen 0.11.97 was missed because the trusted release shipped only an sdist and the malicious one only a wheel, so content rules had no pair to compare and passed silently; they now compare across kinds. mrmustard 0.7.4 was missed because its payload sits in a function defined inside the function __init__.py calls at import, one step past where GRN-C003 stopped following; it follows that step now. Each fix was checked against the clean corpus before it landed.
• 24 of the 47 releases carry the same June 2026 Hades <name>-setup.pth payload, one release in each of 24 packages. They are 24 instances of one technique, mostly in small projects: four of those packages had a single earlier release, and bramin's trusted release dates from 2020. Counted by technique, the set covers five: a .pth startup hook, code that runs at import, a swapped build backend, a DLL named .py, and a payload that runs on use rather than at import.
• GRN-T001 (lost provenance) fired only for ultralytics 8.3.45 and 8.3.46. ultralytics is the only one of these projects that attested its releases before the attack. PyPI no longer serves provenance for removed releases, so the replay records ultralytics' missing attestations from PyPI's analysis.
• When the attacker controls the project's CI (elementary-data, ultralytics 8.3.41/8.3.42, memoryos), provenance looks normal, and content rules carry the result. memoryos' payload hides behind a logging setup function in another module, and num2words' loads a DLL through getattr(ctypes, "CDLL"); GRN-C003 now follows both, and GRN-C004 (new binary) reports num2words' DLL and memoryos' executables themselves.
• GRN-T004 uses the git tags as they stood when each release was uploaded, recorded with evidence in incidents.toml. Against today's tags it would also report elementary-data 0.23.3 and ultralytics 8.3.42 (both tags were deleted later; GRN-C007 needs the tag, so on today's tags it is GRN-T004 that reports ultralytics 8.3.42), and miss telnyx 4.87.1, gpsea 0.9.14 and uprobe 0.1.3 (all three projects later tagged a real release with that number). It couldn't fire for litellm, embiggen and bramin, which don't tag plain version numbers or don't tag at all; for the nine packages whose metadata links no repository (ensmallen, guardrails-ai, magique, magique-ai, mrmustard, napari-ufish, nucbox, pantheon-toolsets, synago) and ppkt2synergy, whose repository has no tags; or for pyphetools and dreamgen, whose repositories are no longer public (reported as GRN-E001). pantheon-agents has a v0.6.1 tag today that points at a commit from eleven days before the upload; a lightweight tag carries no date of its own, so the replay treats it as already there and the rule stays quiet.
• ensmallen's datasets/ modules are larger than Garnet's parse limit in both releases. It reported that as GRN-E003 and still found the .pth.
• In telnyx 4.87.1 a typo stopped the payload from running. GRN-C003 reads code; it reports what the module calls at import, not whether the call would succeed.
• The content rules recognize a sensitive call by the name it is called under. A listed function handed to another call that runs it later (Thread(target=os.system)), or given a harmless-looking name first (json.dumps = subprocess.Popen), isn't reported yet; #91 tracks the check.
• The litellm 1.82.7 sdist isn't replayed, because no public source gives its URL. Its wheel is, and content rules compare wheels.
• chalk and debug are reported by the missing tag alone: they never used provenance, and the one changed file, index.js, is gone from the registry. GRN-C011 now reads the JavaScript an npm package loads and lists, at info, a new process, network or eval use or obfuscated names; it can't run on these two replays, because there is no file to read.
• The 20 clean updates in clean.toml are a smoke test. The clean-corpus backtests cover 18,181 updates, the last 11 releases of the top 1,000 PyPI packages (9,439) and of the top 1,000 npm packages (8,742): 606 are flagged for a look (3.3%), every warning states something true, but none of those updates is malicious, so each is a false alarm a reviewer has to dismiss. Some show a release doing what the trusted one did, a new way: a setup.py that runs the same command with subprocess.run instead of Popen, or entry points renamed with the same targets. The PyPI report lists the ones the triage found.

Reproduce it with uv run python -m backtest. Incident sources: Snyk on lightning, CSA on elementary-data, PyPI's incident report on litellm and telnyx, PyPI's analysis of ultralytics, The Hacker News on the Hades campaign, StepSecurity on mrmustard, the OSV advisory named on each entry in incidents.toml, the PyPI snapshots in DataDog's malicious-software-packages dataset, and the file hashes in ossf/malicious-packages.

Try it today

garnet diff compares two releases of one PyPI or npm package, and garnet check compares two lockfiles:

pip install garnet-guard   # or run it without installing: uvx garnet-guard check --git-base main
garnet diff requests 2.32.4 2.32.5
garnet diff pypi:lightning 2.6.4 2.6.5 --format json
garnet diff npm:chalk 5.6.0 5.6.2
garnet check --git-base main   # every lockfile here, against the same files on main
garnet check --base old/uv.lock --head uv.lock
garnet policy check            # validate garnet.toml and list its ignores
garnet explain GRN-C003

The replays run from a checkout of this repository:

uv sync
uv run python -m backtest      # replay 52 malicious releases and the clean corpus

garnet check reads uv.lock, poetry.lock, pylock.toml and requirements files. Lines it can't check (not pinned with ==, or from git, a path or a private index) are listed as GRN-E004 or GRN-E005, never skipped. garnet --help lists every option.

The exit code is 0 below --fail-on (default: the policy's fail_on, else block), 1 for warn, 2 for block and 3 if Garnet Guard itself failed.

Ecosystems

Python first (uv.lock, poetry.lock, pylock.toml, pinned requirements.txt). npm is checked by garnet diff npm:<name> <old> <new> (provenance, tags, install scripts, OSV); the npm lockfile parsers (package-lock, pnpm-lock, yarn.lock) follow.

Project

• Vision and founding principles
• v1.0 specification and code design and API
• Architecture: how the engine works.
• Code tour: a plain-language guide to the code as it is today, for new contributors and reviewers.
• Rules: one page per rule ID.
• Threat model: what Garnet catches, what it can't, and how Garnet protects itself.
• Roadmap
• Open core: what's free forever, and what the paid Garnet Guard App adds.
• Questions and ideas: GitHub issues
• Contributing, Governance, Security policy, Code of conduct
• Architecture decision records

License

Apache-2.0. See LICENSE.