Garnet Guard / Rules

Garnet Guard rules

Each finding in a Garnet Guard report carries a rule ID. This page lists every rule; each rule's page says what it checks, why it matters, an example finding, and how to resolve or allowlist it. The normative definitions are in SPEC §6.

Most rules are diff rules: they compare the new version with the version you already trust, and fire only on what changed. A project that never used attestations isn't penalized for not using them. Absolute rules fire on the new version alone.

Severities: block and warn set the verdict; info is reported but counts as a pass. A warning is a reason to look, not a finding that the release is malicious.

Trust

How the release was published: attestations, publisher, workflow, tags, hashes.

ID	Name	Kind	Default	Status
GRN-T001	lost-provenance	diff	warn	0.1
GRN-T002	publisher-changed	diff	warn	0.1
GRN-T003	workflow-changed	diff	warn	0.1
GRN-T004	no-matching-tag	diff	warn	0.1
GRN-T005	outside-trusted-publishing	diff	warn	0.1
GRN-T006	files-uploaded-late	absolute	warn	planned
GRN-T007	invalid-attestation	absolute	block	0.1
GRN-T008	hash-mismatch	absolute	block	0.1

Content

What the release contains that the trusted version didn't.

ID	Name	Kind	Default	Status
GRN-C001	new-pth-file	diff	warn	0.1
GRN-C002	new-build-hook	diff	warn	0.1
GRN-C003	new-import-time-exec	diff	warn (info in test files)	0.1
GRN-C004	new-binary	diff	warn	planned
GRN-C005	obfuscated-blob	diff	warn	planned
GRN-C006	sdist-wheel-mismatch	diff	warn	planned

Known bad

Matches against published malware advisories.

ID	Name	Kind	Default	Status
GRN-K001	known-malicious	absolute	block	0.1

Couldn't check

What Garnet Guard couldn't evaluate, said out loud instead of passed.

ID	Name	Kind	Default	Status
GRN-E001	fetch-failed	absolute	warn	0.1
GRN-E002	parse-failed	absolute	warn	0.1
GRN-E003	budget-exceeded	absolute	warn	0.1
GRN-E004	unpinned-requirement	absolute	info	planned
GRN-E005	unsupported-source	absolute	info	planned

Replays

Example findings marked as replays come from uv run python -m backtest, which runs Garnet Guard against real compromised releases listed in backtest/incidents.toml and a corpus of clean updates. In the current replay, all three incident releases (lightning 2.6.2 and 2.6.3, elementary-data 0.23.3) got a warn from content and tag rules alone, and 0 of 20 clean updates got a warn from a detection rule. Other examples are illustrative and say so.

Rule IDs and links

Rule IDs are permanent: a rule is never renumbered and an ID is never reused. Each page lives at docs/rules/<ID>.md. Its stable link, for findings, garnet explain and the PR comment, is https://github.com/orca-solutions/garnet-guard/blob/main/docs/rules/<ID>.md. When the project has a docs domain, the same files will be served at /rules/<ID> there.