{"_id":"@black-lotus/publishguard","_rev":"2-69449294540ac134203da1eee9084c1b","name":"@black-lotus/publishguard","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@black-lotus/publishguard","version":"0.1.0","keywords":["npm","supply-chain","security","malware","worm","shai-hulud","prepublish","postinstall","sarif","devsecops"],"author":{"name":"drkemp187"},"license":"MIT","_id":"@black-lotus/publishguard@0.1.0","maintainers":[{"name":"black-lotus","email":"phippss187@gmail.com"}],"homepage":"https://github.com/drkemp187/publishguard#readme","bugs":{"url":"https://github.com/drkemp187/publishguard/issues"},"bin":{"publishguard":"bin/publishguard.js"},"dist":{"shasum":"b46f60675d06724b91a0f3a118f21315f042527f","tarball":"https://registry.npmjs.org/@black-lotus/publishguard/-/publishguard-0.1.0.tgz","fileCount":6,"integrity":"sha512-aDLb1On3F+OMDiKU0XtArlfO1Q4vYhxTpZ2h26ln+niI5eIeXziPTU12PqlN0pTYE8jwrRctCDf9o2h4H9bAPQ==","signatures":[{"sig":"MEUCIHVoILRby69i76Ypg+e6+ByZXdbQ2OmDEfIDQL6QxCyBAiEAiAdgFu9ixhtQCh5/xBdTJYVhVaJviPDbl/v26gW7S/A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23694},"main":"lib/scanner.js","engines":{"node":">=16"},"gitHead":"8a394fba1cf73eabba1e8756b3ddf12b51b5a3cb","scripts":{"test":"node test/test.js","check":"node bin/publishguard.js check"},"_npmUser":{"name":"black-lotus","email":"phippss187@gmail.com"},"repository":{"url":"git+https://github.com/drkemp187/publishguard.git","type":"git"},"_npmVersion":"10.8.2","description":"Pre-publish worm tripwire for npm — blocks self-replicating supply-chain worms (Shai-Hulud class) before they spread from your package. Zero dependencies, zero network.","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/publishguard_0.1.0_1785045627383_0.053859835453455185","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@black-lotus/publishguard","version":"0.1.1","description":"Pre-publish worm tripwire for npm — blocks self-replicating supply-chain worms (Shai-Hulud class) before they spread from your package. Zero dependencies, zero network.","bin":{"publishguard":"bin/publishguard.js"},"main":"lib/scanner.js","scripts":{"test":"node test/test.js","check":"node bin/publishguard.js check"},"keywords":["npm","supply-chain","security","malware","worm","shai-hulud","prepublish","postinstall","sarif","devsecops"],"author":{"name":"drkemp187"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/drkemp187/publishguard.git"},"engines":{"node":">=16"},"publishConfig":{"access":"public"},"gitHead":"2352e68a58f71420f8dab3a1266babd70e04bdb2","_id":"@black-lotus/publishguard@0.1.1","bugs":{"url":"https://github.com/drkemp187/publishguard/issues"},"homepage":"https://github.com/drkemp187/publishguard#readme","_nodeVersion":"20.20.2","_npmVersion":"11.18.0","dist":{"integrity":"sha512-BxJBSKUUNdLdfe78gjfEcJviQCuE268SxLAerYdSshl4cYhg/yqkQwo5AKY1mc0rQx24FVEdShj6gzIxryq2yw==","shasum":"4d3bb641691418d05b7cbf7767d01a0bb0e5e614","tarball":"https://registry.npmjs.org/@black-lotus/publishguard/-/publishguard-0.1.1.tgz","fileCount":6,"unpackedSize":23694,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@black-lotus%2fpublishguard@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCKJIyNJoQSIKV+jNnSUyOozB8ZcX9dYeCX5bUC/F4+hwIgSkwi3E2vl2MnLVCEV+s4jJH3/4JPnq+TjRG2OPrtujA="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:d6b5f6af-ee2a-4726-9bcf-5b8ef2924172"}},"directories":{},"maintainers":[{"name":"black-lotus","email":"phippss187@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/publishguard_0.1.1_1785047952855_0.7913388126080159"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-26T06:00:27.111Z","modified":"2026-07-26T06:39:13.296Z","0.1.0":"2026-07-26T06:00:27.511Z","0.1.1":"2026-07-26T06:39:12.997Z"},"bugs":{"url":"https://github.com/drkemp187/publishguard/issues"},"author":{"name":"drkemp187"},"license":"MIT","homepage":"https://github.com/drkemp187/publishguard#readme","keywords":["npm","supply-chain","security","malware","worm","shai-hulud","prepublish","postinstall","sarif","devsecops"],"repository":{"type":"git","url":"git+https://github.com/drkemp187/publishguard.git"},"description":"Pre-publish worm tripwire for npm — blocks self-replicating supply-chain worms (Shai-Hulud class) before they spread from your package. Zero dependencies, zero network.","maintainers":[{"name":"black-lotus","email":"phippss187@gmail.com"}],"readme":"# 🛡️ PublishGuard\n\n**The last line of defense before your npm token spreads a worm.**\n\nPublishGuard is a **pre-publish tripwire** for npm packages. It runs in your own\n`prepublishOnly` hook or CI — *right before* `npm publish` — and **refuses to\npublish** if it detects the behaviors that self-replicating supply-chain worms\n(Shai-Hulud–class) use to spread from one compromised package into all the\nothers a maintainer owns.\n\nEvery other tool protects the people who **install** packages. PublishGuard\nprotects the **supply itself** — it stops *your* package from becoming the next\nlink in a worm's replication chain.\n\n- 🔒 **Zero dependencies. Zero network calls.** Pure Node stdlib. A supply-chain\n  tool should not itself be a supply-chain risk.\n- 🧬 **Baseline-diff detection.** Flags lifecycle scripts (`postinstall`,\n  `prepublish`, `prepare`, …) that appeared or changed since your last\n  known-good commit — the #1 worm injection vector.\n- 🕵️ **Behavioral static analysis.** Detects token theft (`~/.npmrc`,\n  `NPM_TOKEN`, `NODE_AUTH_TOKEN`), credential harvesting, self-`npm publish`,\n  and exfil beacons in what you're *about to ship*.\n- 🚦 **Blocks the publish.** Exits non-zero so CI/`prepublishOnly` halts before\n  a compromised artifact ever reaches the registry.\n- 📤 **SARIF output.** Findings ingest natively into GitHub code scanning.\n\n> PublishGuard is a **defensive** tool. It performs static analysis of your own\n> package on your own machine/CI. It never executes package code and never\n> contacts the network.\n\n## Why \"pre-publish\" is the missing layer\n\n| Layer | Tools | What they protect |\n|-------|-------|-------------------|\n| **Install-time** (consumer) | many scanners | People installing packages |\n| **Publish-time** (maintainer) | **← PublishGuard** | The registry / the supply chain itself |\n\nWorms like Shai-Hulud are exponential precisely because a single compromised\nmaintainer auto-publishes the worm into every package they control.\nPublishGuard breaks that replication step.\n\n## Quick start\n\n```bash\nnpm install -g @black-lotus/publishguard\n\npublishguard check                      # scan the current package\npublishguard baseline                   # snapshot current lifecycle scripts as known-good\npublishguard check --sarif out.sarif\n```\n\nOr without installing:\n\n```bash\nnpx @black-lotus/publishguard check\n```\n\nThe package is published under the `@black-lotus` scope; the CLI command is\nplain `publishguard`.\n\nWire it into your package so a publish is **blocked** if anything looks wormy:\n\n```json\n{\n  \"scripts\": {\n    \"prepublishOnly\": \"publishguard check --strict\"\n  }\n}\n```\n\nOr drop the GitHub Action into `.github/workflows/` (see `examples/`).\n\n## What it detects\n\n| Rule | Severity | What it catches |\n|------|----------|-----------------|\n| `PG001` lifecycle-script-added | CRITICAL | A new install/publish lifecycle script not in your baseline |\n| `PG002` lifecycle-script-changed | HIGH | An existing lifecycle script whose body changed |\n| `PG003` npm-token-access | CRITICAL | Code reading `.npmrc` / `NPM_TOKEN` / `NODE_AUTH_TOKEN` |\n| `PG004` credential-harvest | HIGH | Reads of AWS/GCP/GitHub creds or bulk `process.env` dump |\n| `PG005` self-publish | CRITICAL | Code invoking `npm publish` / registry publish API |\n| `PG006` network-exfil | HIGH | Beacons to raw IPs, `webhook.site`, known C2 patterns |\n| `PG007` obfuscated-payload | MEDIUM | `eval`/`Function`/base64-`Buffer` decode of remote strings |\n\n## Threat model — what this does and doesn't stop\n\nPublishGuard is a tripwire against **automated, non-targeted worms** — malware\nthat injects the same replication payload into every package it can reach. That\nclass of attack doesn't adapt per-repository, so a local check it doesn't know\nabout breaks the chain.\n\nIt is **not** a defense against a targeted attacker with commit access: anyone\nwho can edit `package.json` to inject a lifecycle script can also remove the\n`prepublishOnly` hook or regenerate the baseline. For that threat you need\nprotections PublishGuard can't provide — 2FA on npm, provenance/trusted\npublishing, protected branches, and review requirements. Run PublishGuard in CI\n(not only locally) so removing the hook is at least visible in the diff.\n\n## False positives & suppression\n\nIf a line must legitimately contain a flagged string (e.g. you're building\nsecurity tooling), append a suppression comment — the same idea as\n`eslint-disable-line`:\n\n```js\nconst pattern = /npm publish/; // publishguard-disable-line\n```\n\nPublishGuard eats its own dog food: its detection patterns use this marker, so\n`publishguard check` on the PublishGuard repo itself is clean.\n\n## License\n\nMIT — use it anywhere, including commercially.\n","readmeFilename":"README.md"}