pkg-guardian

Scan Node.js projects for compromised npm packages from the command line. Protect your supply chain with real-time security scanning.

Install (global CLI)

npm install -g pkg-guardian

After installing globally you can run the command from any directory:

pkg-guardian

You can also use the alias scan-compromised for backward compatibility.

This scans the current working directory.

Usage

pkg-guardian [options]

Common examples:

pkg-guardian                         # Scan current directory (uses bundled compromised.txt)
pkg-guardian --path ./some-repo      # Scan a specific repo
pkg-guardian --repos repos.txt       # Scan many repos listed in a file
pkg-guardian --verbose               # Verbose output
pkg-guardian --compromised-url https://your-api/compromised  # Fetch from API (cached for 1 day)

Options

• --path <dir> – scan a single repo directory.
• --repos <file> – scan multiple repos listed in a text file (one path per line).
• --compromised <file> – use a custom compromised list file instead of the bundled one.
• --compromised-url <url> – fetch the compromised list from a remote API endpoint (expects JSON array of package names). The list is cached in compromised.txt with a timestamp and only re-fetched if older than 1 day. Falls back to the bundled file if the fetch fails.
• --output <file> – output report path (default: scan-report.csv).
• --format <csv|json> – output format (default: csv).
• --verbose – extra logging.
• --deep – deep scanning mode for package-lock.json.
• --fail-on-find – exit with code 1 if compromised packages are found (default: true).

Future Roadmap

Managed API Service

As more compromised libraries are discovered, we will provide a managed API service with personalized authentication tokens. This will include:

• Personalized API tokens – Generate your own token for authenticated access to the latest compromised package list.
• Usage tracking – Monitor your API usage and scan history.
• Automatic updates – Keep your local cache up-to-date with the latest security intelligence.
• User-friendly dashboard – Token generation and management interface.

Pre-Install Guard

A key goal of this package is to act as a security guard that runs before any dependency installation. This will help prevent compromised packages from entering your project in the first place.

Planned features:

• Pre-install hooks – Automatically check packages before npm install, yarn add, or pnpm install.
• Real-time protection – Block installation of known compromised packages immediately.
• CI/CD integration – Fail builds automatically if compromised dependencies are detected.
• Proactive security – Catch supply chain attacks before they affect your codebase.

This will transform the tool from a scanner into a proactive defense system against npm supply chain attacks.