am-i-secure/README.md

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

# 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

```bash
npm install -g am-i-secure
```

### Use with npx (Recommended)

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

## Usage

### Basic Usage

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

```bash
# 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:

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

```yaml
# 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:

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