🛡️ PublishGuard

The last line of defense before your npm token spreads a worm.

PublishGuard is a pre-publish tripwire for npm packages. It runs in your own prepublishOnly hook or CI — right before npm publish — and refuses to publish if it detects the behaviors that self-replicating supply-chain worms (Shai-Hulud–class) use to spread from one compromised package into all the others a maintainer owns.

Every other tool protects the people who install packages. PublishGuard protects the supply itself — it stops your package from becoming the next link in a worm's replication chain.

• 🔒 Zero dependencies. Zero network calls. Pure Node stdlib. A supply-chain tool should not itself be a supply-chain risk.
• 🧬 Baseline-diff detection. Flags lifecycle scripts (postinstall, prepublish, prepare, …) that appeared or changed since your last known-good commit — the #1 worm injection vector.
• 🕵️ Behavioral static analysis. Detects token theft (~/.npmrc, NPM_TOKEN, NODE_AUTH_TOKEN), credential harvesting, self-npm publish, and exfil beacons in what you're about to ship.
• 🚦 Blocks the publish. Exits non-zero so CI/prepublishOnly halts before a compromised artifact ever reaches the registry.
• 📤 SARIF output. Findings ingest natively into GitHub code scanning.

PublishGuard is a defensive tool. It performs static analysis of your own package on your own machine/CI. It never executes package code and never contacts the network.

Why "pre-publish" is the missing layer

Layer	Tools	What they protect
Install-time (consumer)	many scanners	People installing packages
Publish-time (maintainer)	← PublishGuard	The registry / the supply chain itself

Worms like Shai-Hulud are exponential precisely because a single compromised maintainer auto-publishes the worm into every package they control. PublishGuard breaks that replication step.

Quick start

npm install -g @black-lotus/publishguard

publishguard check                      # scan the current package
publishguard baseline                   # snapshot current lifecycle scripts as known-good
publishguard check --sarif out.sarif

Or without installing:

npx @black-lotus/publishguard check

The package is published under the @black-lotus scope; the CLI command is plain publishguard.

Wire it into your package so a publish is blocked if anything looks wormy:

{
  "scripts": {
    "prepublishOnly": "publishguard check --strict"
  }
}

Or drop the GitHub Action into .github/workflows/ (see examples/).

What it detects

Rule	Severity	What it catches
PG001 lifecycle-script-added	CRITICAL	A new install/publish lifecycle script not in your baseline
PG002 lifecycle-script-changed	HIGH	An existing lifecycle script whose body changed
PG003 npm-token-access	CRITICAL	Code reading .npmrc / NPM_TOKEN / NODE_AUTH_TOKEN
PG004 credential-harvest	HIGH	Reads of AWS/GCP/GitHub creds or bulk process.env dump
PG005 self-publish	CRITICAL	Code invoking npm publish / registry publish API
PG006 network-exfil	HIGH	Beacons to raw IPs, webhook.site, known C2 patterns
PG007 obfuscated-payload	MEDIUM	eval/Function/base64-Buffer decode of remote strings

Threat model — what this does and doesn't stop

PublishGuard is a tripwire against automated, non-targeted worms — malware that injects the same replication payload into every package it can reach. That class of attack doesn't adapt per-repository, so a local check it doesn't know about breaks the chain.

It is not a defense against a targeted attacker with commit access: anyone who can edit package.json to inject a lifecycle script can also remove the prepublishOnly hook or regenerate the baseline. For that threat you need protections PublishGuard can't provide — 2FA on npm, provenance/trusted publishing, protected branches, and review requirements. Run PublishGuard in CI (not only locally) so removing the hook is at least visible in the diff.

False positives & suppression

If a line must legitimately contain a flagged string (e.g. you're building security tooling), append a suppression comment — the same idea as eslint-disable-line:

const pattern = /npm publish/; // publishguard-disable-line

PublishGuard eats its own dog food: its detection patterns use this marker, so publishguard check on the PublishGuard repo itself is clean.

License

MIT — use it anywhere, including commercially.