🔒 ScanPack

Dependency scanner to detect unknown or malicious packages in Node.js and Bun projects.

🎯 Features

• ✅ Validates all dependencies in package.json
• 🔍 Checks if packages exist on npm
• ⚠️ Detects known malicious packages
• 🛡️ Automatically detects npm security holding packages (removed packages)
• 📊 Generates detailed dependency report
• 🚀 Supports Node.js and Bun projects
• ⚡ Dynamic batch processing for optimal performance
• 📈 Progress bar for visual feedback
• 🚫 Ignore specific packages (.scanpackignore or --ignore)
• 🔄 Rate limiting protection
• 🤖 CI/CD mode for clean pipeline output
• 🗑️ Auto-remove dangerous dependencies (-rd / --remove-dangerous)
• 🔗 GitHub Actions integration

📦 Installation

npm install -g scanpack
# or
bun add -g scanpack

🚀 Usage

As CLI

# Scan current project
scanpack

# Scan a specific project
scanpack /path/to/project

# JSON output
scanpack --json

# Verbose mode (more details)
scanpack --verbose

# CI/CD mode (minimal output, no colors)
scanpack --ci

# Ignore specific packages
scanpack --ignore "internal-pkg,legacy-lib"

# Rate limiting (requests per second)
scanpack --rate-limit 5

# Remove dangerous dependencies automatically
scanpack -rd
# or
scanpack --remove-dangerous

# Show help
scanpack --help

Ignoring Packages

You can ignore packages in two ways:

1. Command line flag:

   scanpack --ignore "package1,package2"

2. .scanpackignore file (in project root):

   # Comments start with #
   internal-package
   @company/private-lib
   legacy-lib

As Module

import { PackageReader, DependencyValidator } from 'scanpack';

// Read dependencies
const dependencies = PackageReader.readDependencies('./my-project');

// Scan dependencies
const report = await DependencyValidator.validateDependencies(dependencies);

console.log(report);

📊 Example Output

🔍 Scanning dependencies...

📦 Found 25 dependencies

📊 Validation Summary:

  Total: 25
  ✓ Valid: 23
  ✗ Invalid: 2
  ⚠ Malicious: 1
  ? Unknown: 1

⚠️  Problematic Dependencies:

  ✗ [email protected]
    Type: devDependency
    ⚠️  Package banned from npm for containing malicious scripts

  ✗ [email protected]
    Type: dependency
    ⚠️  Security holding package - original package was removed by npm for security reasons

  ? [email protected]
    Type: dependency
    ⚠️  Package not found on npm

🔧 Exit Codes

• 0: All dependencies are valid
• 1: Found malicious dependencies
• 2: Found unknown dependencies (but not malicious)

⚙️ Options

| Option | Description | |--------|-------------| | -v, --verbose | Show detailed information and debug logs | | -j, --json | Output results in JSON format | | -c, --ci | CI/CD mode: minimal output, no colors, no progress bar | | -i, --ignore <packages> | Comma-separated list of packages to ignore | | -r, --rate-limit <number> | Maximum requests per second to npm registry (default: 10) | | -rd, --remove-dangerous | Automatically remove dangerous dependencies from package.json | | -h, --help | Display help information |

🛡️ Malicious Packages Detection

The scanner uses multiple methods to detect malicious packages:

1. Known malicious packages list: Maintains a curated list of known malicious packages in src/malicious-packages.json
2. Suspicious patterns: Detects packages matching suspicious naming patterns (regex-based)
3. Security holding packages: Automatically detects npm security holding packages (packages removed by npm for security reasons, marked as 0.0.1-security)

You can add new packages to the known malicious list by editing src/malicious-packages.json. See CONTRIBUTING.md for more details.

📝 Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Test CLI locally
npm run cli

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

🤝 Contributing

Contributions are welcome! Feel free to:

• Add new malicious packages to the list
• Improve detection of suspicious patterns
• Add new features

📄 License

MIT

🔗 Links

• GitHub Repository