am-i-secure

A Node.js CLI tool to detect malicious npm packages in your project dependencies.

Features

• 🔍 Comprehensive Scanning: Detects malicious packages from lock files (package-lock.json, yarn.lock, pnpm-lock.yaml) and node_modules directory
• 🎯 Known Threats: Checks against a curated list of known malicious packages and versions
• 📊 Detailed Reporting: Shows package name, version, source file, and dependency chain
• 🚨 Security-First: Exits with non-zero status code when threats are detected
• 🎨 Beautiful Output: Color-coded, table-formatted results for easy reading
• ⚡ Fast: Efficient scanning with minimal dependencies

Installation

Global Installation

npm install -g am-i-secure

Use with npx (Recommended)

npx am-i-secure ./your-project-directory

Usage

Basic Usage

# Scan current directory
am-i-secure .

# Scan specific directory
am-i-secure /path/to/your/project

# Use with npx
npx am-i-secure ./my-project

Options

# Verbose output
am-i-secure ./project --verbose

# Recursive scanning (scan subdirectories for lock files)
am-i-secure ./project --recursive

# JSON output (for CI/CD integration)
am-i-secure ./project --json

# Combined options
am-i-secure ./project --recursive --verbose

# Show help
am-i-secure --help

What It Detects

This tool checks for the following known malicious packages and versions:

| Package | Malicious Versions | |---------|-------------------| | eslint-config-prettier | 8.10.1, 9.1.1, 10.1.6, 10.1.7 | | eslint-plugin-prettier | 4.2.2, 4.2.3 | | synckit | 0.11.9 | | @pkgr/core | 0.2.8 | | napi-postinstall | 0.3.1 | | got-fetch | 5.1.11, 5.1.12 | | is | 3.3.1, 5.0.0 |

How It Works

1. Lock File Detection: Automatically detects and parses package-lock.json, yarn.lock, or pnpm-lock.yaml
   • By default, scans only the specified directory
   • With --recursive flag, scans all subdirectories (useful for monorepos)
2. Node Modules Scanning: Scans node_modules directories for installed packages
   • By default, scans only the main node_modules directory
   • With --recursive flag, scans node_modules in all subdirectories
3. Threat Detection: Compares found packages against the known malicious package database
4. Dependency Tracing: Attempts to identify which parent dependency introduced the malicious package
5. Comprehensive Reporting: Generates detailed reports showing all findings

Example Output

📊 Scan Summary:

┌──────────────────────────────┬───────┐
│ Metric                       │ Count │
├──────────────────────────────┼───────┤
│ Lock files scanned           │ 1     │
│ node_modules scanned         │ Yes   │
│ Total packages checked       │ 847   │
│ Malicious packages found     │ 2     │
└──────────────────────────────┴───────┘

🚨 Malicious Packages Found:

┌─────────────────────┬──────────┬─────────────────┬──────────────────┬────────────────────────────────────────┐
│ Package             │ Version  │ Source          │ Introduced By    │ File Path                              │
├─────────────────────┼──────────┼─────────────────┼──────────────────┼────────────────────────────────────────┤
│ eslint-config-pret… │ 8.10.1   │ package-lock.j… │ Direct dependency│ /project/package-lock.json             │
│ synckit             │ 0.11.9   │ node_modules    │ @eslint/eslintrc │ node_modules/synckit/package.json      │
└─────────────────────┴──────────┴─────────────────┴──────────────────┴────────────────────────────────────────┘

🚨 Found 2 malicious package(s)! Your project may be compromised.

Exit Codes

• 0: No malicious packages found
• 1: Malicious packages detected or error occurred

CI/CD Integration

For automated security scanning in CI/CD pipelines:

# Basic scan - single project
npx am-i-secure . --json > security-report.json

# Monorepo scan - check all subdirectories
npx am-i-secure . --recursive --json > security-report.json

# GitHub Actions example
- name: Security Scan
  run: npx am-i-secure . --recursive

# For monorepos, save detailed report
- name: Security Scan with Report
  run: npx am-i-secure . --recursive --json > security-report.json

Programmatic Usage

You can also use this tool programmatically:

const { Scanner, Logger, scanNodeModules, findPackageVersions } = require('am-i-secure');

async function scanProject(projectPath, recursive = false) {
  const logger = new Logger();
  const scanner = new Scanner(projectPath, logger, { recursive });
  
  const results = await scanner.scan();
  return results;
}

// Basic scan
const results = await scanProject('./my-project');

// Recursive scan for monorepos
const results = await scanProject('./my-monorepo', true);

// Direct node_modules scanning
const packages = scanNodeModules('./project', false); // non-recursive
const allPackages = scanNodeModules('./project', true); // recursive

// Find specific package versions
const lodashVersions = findPackageVersions('./project', 'lodash', true);

Requirements

• Node.js 16.0.0 or higher
• npm, yarn, or pnpm project with lock files

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT

Security

If you discover a new malicious package that should be added to our database, please open an issue with the package details and evidence of malicious behavior.

Disclaimer

This tool checks against a curated list of known malicious packages. It should be used as part of a comprehensive security strategy, not as the sole security measure. Always keep your dependencies up to date and follow security best practices.