supply-scan

Universal npm supply chain attack scanner. Detects compromised packages from 12 known attacks spanning 2018-2026. Zero runtime dependencies.

npx supply-scan

Requires Node.js >= 20

What It Detects

5 Check Categories

1. Compromised Packages — Scans node_modules and lockfiles for known bad versions
2. Malware Files — Checks for RAT payloads, droppers, and artifacts on disk
3. Network Connections — Detects active connections to C2 servers
4. Suspicious Processes — Identifies running malware and persistence mechanisms
5. Package Manager Caches — Scans npm, pnpm, yarn, and bun caches for malicious packages

Supported Package Managers

Usage

Interactive Mode (default)

npx supply-scan

Prompts you to select which attacks to scan for and which directories to scan.

Scan All Attacks

npx supply-scan --all

Scan Specific Attacks

npx supply-scan --rule axios-2026
npx supply-scan --rule axios-2026 --rule chalk-debug-2025

Scan Specific Directory

npx supply-scan --path ~/projects/my-app

CI Mode

npx supply-scan --ci

Non-interactive, outputs "OK" on clean scan. Exit codes:

• 0 — All clear
• 1 — Compromise detected
• 2 — Warnings found

List Available Rules

npx supply-scan --list

Adding New Rules

Each attack is defined as a JSON file in the rules/ directory. To add a new attack, create a new .json file:

{
  "id": "my-attack-2026",
  "name": "My Attack Name",
  "date": "2026-01-01",
  "severity": "critical",
  "description": "Description of the attack",
  "references": ["https://example.com/advisory"],
  "packages": {
    "compromised": {
      "package-name": ["1.0.0", "1.0.1"]
    },
    "malicious": {
      "evil-package": ["0.1.0"]
    }
  },
  "ioc": {
    "files": {
      "darwin": ["/path/to/malware"],
      "linux": ["/tmp/malware"],
      "win32": ["%TEMP%\\malware.exe"]
    },
    "domains": ["evil-c2.com"],
    "ips": ["1.2.3.4"],
    "ports": [8080],
    "processes": ["malware-process"],
    "strings": ["suspicious-string"]
  }
}

No code changes needed — the scanner automatically picks up new rule files. See docs/RULES.md for the complete schema reference.

Architecture

supply-scan/
├── src/                     # TypeScript source
│   ├── index.ts             # CLI entry + interactive prompts
│   ├── scanner.ts           # Scan engine orchestrator
│   ├── ui.ts                # Terminal UI (zero deps, ANSI codes)
│   ├── utils.ts             # Utilities (args, paths, JSON, etc.)
│   ├── types.ts             # TypeScript interfaces
│   └── checks/
│       ├── packages.ts      # Package + lockfile scanner
│       ├── files.ts         # Malware file detector
│       ├── network.ts       # C2 connection checker
│       ├── processes.ts     # Process + persistence scanner
│       └── cache.ts         # Package manager cache scanner
├── rules/                   # Attack definitions (JSON)
├── __tests__/               # Unit tests (Vitest)
├── docs/                    # Rule writing guide
├── .github/workflows/       # CI + publish + dependency review
└── dist/                    # Compiled output (tsup, single file)

Zero runtime dependencies. This is a security scanner — we don't depend on packages that could themselves be compromised.

Contributing

See CONTRIBUTING.md for setup instructions, how to add new attack rules, and PR guidelines.

License

MIT