CLI reference

packguard v0.1.1 · npmjs.com/package/packguard

Commands

npx packguard scan [dir]

Scan the tarball for the npm package in the current directory (or [dir]). Runs npm pack --dry-run, extracts the file list, then checks every file for AI artifacts, source maps with embedded source, and secrets. Exits 0 if clean, 1 if blocked.

npx packguard scan
npx packguard scan ./my-package

packguard install

Appends packguard scan to the prepublishOnly script in package.json. If a prepublishOnly hook already exists, packguard scan is prepended to it. Safe to run multiple times — will not duplicate.

npx packguard install

What gets checked

AI artifact blockblocked

Exact-match against known AI coding assistant paths: .claude/, .cursor/, .codex/, .windsurf/, .copilot/, .aider/, and their state file extensions. Any match is a hard block — exit 1.

Source map detectionwarning

Reads the first 16KB of every .js.map file and checks whether sourcesContent is a non-empty array. Non-empty means original source is embedded and would ship to npm. Flagged as a warning.

Secret scanblocked

Regex matchers for Anthropic keys (sk-ant-*), GitHub tokens (ghp_*, gho_*, ghs_*), AWS access keys (AKIA*), OpenAI keys (sk-*), and Stripe keys. Any match is a hard block.

Entropy scanwarning

Shannon entropy > 4.5 on strings of 20+ characters. Catches unrecognized secrets that don't match a known pattern. Flagged as a warning — review before publishing.

.packguardignore

Create a .packguardignore in your project root to suppress entropy warnings for known-safe files (e.g. vendored base64 assets). Same syntax as .gitignore.

# .packguardignore
# suppress entropy warnings for vendor fonts
vendor/fonts/**
public/icons/spritesheet.svg

Environment variables

PACKGUARD_ORG_TOKEN

Pro org token. Set this in CI or your shell to POST scan results to the org audit log after each scan. Scan metadata only — no file contents.