check-compromised-npm-packages/README.md

Scan your project for compromised npm packages

# Check Compromised

A simple Node.js tool to scan your project for compromised npm packages.

## What it does

Scans your `node_modules` and `package-lock.json` for installed package versions and compares them against a known list of compromised versions. Exits with error code 1 if any compromised packages are found.

## Why this tool complements npm audit

`npm audit` is great for finding known vulnerabilities, but it has some limitations with supply chain attacks like the one this tool was created for. This incident involved malicious versions that had no CVE at the time, so audit would report "0 vulnerabilities" while potentially running malicious code.

### Where npm audit falls short

* **Scope**: Focuses on CVEs and known vulnerabilities, not live malicious versions
* **Timing**: There's often a delay before advisories are published, giving malicious packages time to spread
* **Granularity**: Uses range-based detection rather than exact version matching
* **Coverage**: Doesn't catch supply chain techniques like malicious postinstall scripts or token theft

### Where npm audit still helps

* Finding CVE-style vulnerabilities after they're disclosed
* Setting policy gates in CI for known severities  
* Verifying you're not regressing to vulnerable version ranges

## Usage

### Via npx (recommended)
```bash
# Check for compromised packages
npx check-compromised-npm-packages

# Output results as JSON
npx check-compromised-npm-packages --json

# Show the list of known compromised packages
npx check-compromised-npm-packages --list
```

### Local usage
```bash
# Check for compromised packages
node check-compromised.js

# Output results as JSON
node check-compromised.js --json

# Show the list of known compromised packages
node check-compromised.js --list
```

## Setup

Place a `compromised.json` file in your project root with the format, or re-use mine :)

```json
{
  "packages": [
    { "name": "@ctrl/tinycolor", "badVersions": ["4.1.1", "4.1.2"] },
    { "name": "angulartics2", "badVersions": ["14.1.2"] }
  ]
}
```

**Current list of compromised packages:** [compromised.json](https://github.com/Antonhansel/check-compromised-npm-packages/blob/master/compromised.json)

**Sources:**
- [2025-09-16] [Ongoing supply chain attack targets CrowdStrike npm packages](https://socket.dev/blog/ongoing-supply-chain-attack-targets-crowdstrike-npm-packages)
- [2025-11-24] [Shai-Hulud Returns: Over 300 NPM Packages and 27K+ Github Repos infected via Fake Bun Runtime Within Hours](https://helixguard.ai/blog/malicious-sha1hulud-2025-11-24)

## Understanding the threat: Install script vulnerabilities

As documented in the [npm blog](https://blog.npmjs.org/post/141702881055/package-install-scripts-vulnerability), malicious packages can execute scripts during installation that can:

- **Self-replicate**: Include themselves in new packages and publish them to the registry
- **Steal credentials**: Access environment variables, tokens, and other sensitive data
- **Spread laterally**: Compromise other packages owned by the same user
- **Execute arbitrary code**: Run any malicious code during the install process

This is why `--ignore-scripts` is crucial - it prevents these attack vectors from executing during installation.

## Origin

This tool was created in response to the [@ctrl/tinycolor and 40+ NPM packages compromised](https://www.stepsecurity.io/blog/ctrl-tinycolor-and-40-npm-packages-compromised) supply chain attack.

The `compromised.json` file will be updated as more compromised packages are discovered to enhance detection capabilities.