Supply-chain audit design

The supply-chain audit proves the repository’s dependency controls from committed files alone. An audit that can be fooled (or that passes when it checks nothing) is worse than none, because green then vouches for an unverified state. The principles below keep the audit from passing while a control is violated, and keep it worth running.

For which controls exist and why, see Supply-chain security; for what to do when the audit fails on your PR, see the audit section of the dependency docs.

Principles

1. Prove from committed files alone. The audit reads the lock, manifests, .npmrc, and netlify.toml (never the network or the installed tree), so it is fast, offline, and can’t be swayed by the state it is meant to vet.
2. Allowlist whole shapes; don’t denylist patterns. A denylist regular expression over a config format misses the valid spellings it doesn’t list (quoted, dotted, and inline-table TOML keys all bypass an env-key denylist). Pinning the entire reviewed shape (exact key sets, exact values) is stronger and usually shorter.
3. Parse; don’t line-scan. A format’s parser defines its semantics. A line regular expression mismodels them silently: a context table it doesn’t recognize still means something to Netlify.
4. Exact pins; no prefix or flag matching. Prefix matching accepts an appended && npm install ... rider on a script the audit trusts by name.
5. Fail closed on absence. Every counting check carries a floor assertion, so an empty input can’t pass vacuously; entries missing an expected field fail rather than being skipped.
6. Bind to the identity npm trusts. npm derives a package’s identity from its resolved registry URL, not from the lock key or version field, so the audit binds all three together; checking only the fields npm distrusts green-lights a mismatch npm would act on.
7. One home per invariant. A list asserted in two files drifts; the audit imports shared values from their owning module, and that module’s unit test pins the content.
8. Red-first. A new check is trusted only after a deliberately broken input has made it fail. A false green is worse than red.
9. Assertions name the expected condition and, for routine fires, the fix: the allowScripts assertion names the version a dependency bump must move the entry to, so the failure message is the remediation.
10. State the scope boundary. The surfaces the audit deliberately does not cover are named in the audit and in the dependency docs, so absent coverage is never mistaken for verified coverage.
11. Every check earns its keep. Security comes from the controls’ design and from review, not from accreting assertions: each one taxes contributors and maintainers on every touch. A check belongs here only where it detects something review demonstrably cannot: an opaque, high-authority surface such as the lock, or a semantic too obscure to catch by eye. Where a control already fails closed at runtime, the audit doesn’t re-assert it; when a check’s upkeep cost outgrows its detection value, trimming it is the correct move, not a weakening.

Principles in the audit

One exemplar per principle; the test file is the authoritative inventory of assertions.