pkg-guardian/readme.md

A security CLI tool to scan and protect your Node.js projects from compromised npm packages and supply chain attacks.

# 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)

```bash
npm install -g pkg-guardian
```

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

```bash
pkg-guardian
```

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

This scans the **current working directory**.

## Usage

```bash
pkg-guardian [options]
```

Common examples:

```bash
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.