🛡️ Secure Dependency Scanner

A comprehensive security scanner for detecting suspicious dependencies, malicious packages, and vulnerabilities in Node.js projects. Protects against supply-chain attacks, typosquatting, and other NPM-based threats.

🔐 How to Verify This Package is Legitimate

⚠️ IMPORTANT: Before installing any security tool, verify it's legitimate!

1. Check the Source

GitHub Repository: https://github.com/fsegall/secure-dep-scanner
Author: Felipe Segall Corrêa (Livre Software Solutions)
Company: https://livresoltech.com
NPM Package: https://www.npmjs.com/package/secure-dep-scanner

2. Verify Package Integrity

# Check package checksum
npm view secure-dep-scanner dist.integrity

# Verify against GitHub release
git clone https://github.com/fsegall/secure-dep-scanner.git
cd secure-dep-scanner
npm pack
# Compare the generated .tgz with the published package

3. Review the Code

Zero Dependencies: This package has no external dependencies to prevent supply-chain attacks
Open Source: All detection logic is transparent and reviewable
Self-Contained: Single file (security-scanner.cjs) with no external calls
No Network Access: The scanner doesn't make network requests during operation

4. Check for Red Flags

✅ No suspicious network calls
✅ No credential collection
✅ No data exfiltration
✅ No obfuscated code
✅ Transparent detection patterns
✅ Reputable author and company

5. Alternative Verification

# Use npx to run without installation
npx secure-dep-scanner --help

# Use built-in verification command
npx secure-dep-scanner --verify

# Review the source code first
curl -s https://raw.githubusercontent.com/fsegall/secure-dep-scanner/main/security-scanner.cjs | head -50

🔒 Security Note: This package is designed to be transparent and safe. If you find anything suspicious, please report it immediately.

🚀 Features

🔍 Dependency Analysis

Scans package.json for suspicious dependencies
Detects typosquatting attacks (malicious package name variations)
Identifies deprecated and vulnerable packages
Flags known malicious packages

🕵️ Content Scanning

Analyzes node_modules for malicious code patterns
Detects suspicious IP addresses and command execution
Scans for known malware signatures
Identifies suspicious file content
TypeScript support: Scans .ts, .tsx, .d.ts files
TypeScript configuration analysis: Reviews tsconfig.json for suspicious settings

🛡️ Vulnerability Detection

Integrates with npm audit for comprehensive vulnerability scanning
Categorizes issues by severity (Critical, High, Medium, Low)
Provides actionable recommendations

🎯 Smart Detection

Whitelist of legitimate packages to reduce false positives
Pattern-based detection for emerging threats
Age-based detection for potential typosquatting

📘 TypeScript Support

TypeScript file scanning: Analyzes .ts, .tsx, .d.ts files for malicious patterns
Configuration analysis: Reviews tsconfig.json for suspicious compiler options
Path mapping detection: Identifies potentially dangerous wildcard path mappings
TypeScript-specific patterns: Detects suspicious TypeScript declarations and augmentations

🎨 Enhanced CLI Experience

Color-coded output for better readability
Progress indicators for long-running scans
Interactive confirmations for critical actions
Multiple output formats (Console, JSON, CSV, HTML)
Configuration file support for custom rules
Quiet mode for automation and CI/CD
Non-interactive mode for scripting

📦 Installation

npm install -g secure-dep-scanner

Or use it directly without installation:

npx secure-dep-scanner

🚀 Quick Start

Navigate to your Node.js project directory and run:

secure-dep-scanner

The scanner will automatically:

Scan your package.json dependencies
Analyze node_modules content
Run npm audit
Generate a comprehensive security report

📋 Usage Examples

Basic Scan

# Scan current directory
secure-dep-scanner

# Or use npx
npx secure-dep-scanner

# Verify package legitimacy first
npx secure-dep-scanner --verify

Advanced Usage

# Output as JSON for automation
secure-dep-scanner --format json

# Save report to file
secure-dep-scanner --output security-report.json

# Generate HTML report
secure-dep-scanner --format html --output report.html

# Generate CSV for analysis
secure-dep-scanner --format csv --output issues.csv

# Quiet mode (suppress output)
secure-dep-scanner --quiet

# Non-interactive mode (no prompts)
secure-dep-scanner --no-interactive

# Combine options
secure-dep-scanner --format json --output report.json --quiet

Programmatic Usage

const SecurityScanner = require('secure-dep-scanner');

const scanner = new SecurityScanner({
  interactive: false,
  outputFormat: 'json',
  quiet: true
});

scanner.scan().then(issues => {
  console.log('Found issues:', issues.length);
});

📊 Sample Output

🛡️ Starting Security Scan...

🔍 Scanning package.json for suspicious dependencies...
🔍 Scanning node_modules for malicious content...
🔍 Running npm audit...

🛡️ SECURITY SCAN REPORT
==================================================
🚨 CRITICAL: 0
🔴 HIGH: 2
🟡 MEDIUM: 1
🟢 LOW: 3
📊 TOTAL: 6

📋 DETAILED ISSUES:
--------------------------------------------------
1. ⚠️ HIGH: Found suspicious pattern "crypto" in package.json
   Package: crypto@1.0.1
2. 🔴 HIGH: crypto@1.0.1 - Deprecated package with vulnerabilities
   Package: crypto@1.0.1

💡 RECOMMENDATIONS:
--------------------------------------------------
⚠️ REVIEW RECOMMENDED:
   - Review suspicious packages
   - Update vulnerable dependencies

⏱️ Scan completed in 1247ms

🎯 What It Detects

🚨 Critical Issues

Known malicious IP addresses
Confirmed malware signatures
Critical security vulnerabilities

⚠️ High Priority

Suspicious package patterns
Deprecated packages with vulnerabilities
Known malicious packages

🔍 Medium Priority

Command execution patterns in suspicious contexts
New packages (potential typosquatting)
Suspicious content patterns

📝 Low Priority

General security recommendations
Audit warnings
Monitoring suggestions

🛡️ Protection Features

Zero Dependencies

No external packages to avoid supply-chain attacks
Self-contained security scanner
Transparent detection logic

Smart Whitelisting

Recognizes legitimate packages
Reduces false positives
Focuses on suspicious content

Real-time Detection

Pattern-based threat detection
Updated with latest threat intelligence
Adaptable to new attack vectors

🔧 Configuration

The scanner works out-of-the-box but you can customize detection patterns by modifying the source code:

// Add custom suspicious patterns
this.suspiciousPatterns.push('your-suspicious-pattern');

// Add blocked packages
this.blockedPackages.add('malicious-package-name');

// Add suspicious IPs
this.suspiciousIPs.add('192.168.1.100');

Configuration Files

The scanner automatically loads configuration from these files (in order):

.secure-dep-scanner.json
.secure-dep-scanner.yaml
.secure-dep-scanner.yml
secure-dep-scanner.json

Example configuration:

{
  "suspiciousPatterns": ["custom-pattern"],
  "blockedPackages": ["malicious-package"],
  "suspiciousIPs": ["192.168.1.100"],
  "interactive": false,
  "quiet": true
}

🚨 Exit Codes

0: No critical issues found
1: Critical security issues detected

📈 Performance

Fast: Typically completes in 1-3 seconds
Lightweight: No external dependencies
Efficient: Smart filtering reduces scan time

🔗 Integration & Automation

CI/CD Integration

# GitHub Actions example
- name: Security Scan
  run: npx secure-dep-scanner --format json --output security-report.json

- name: Check for Critical Issues
  run: |
    if jq '.critical > 0' security-report.json; then
      echo "Critical security issues found!"
      exit 1
    fi

Pre-commit Hooks

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "secure-dep-scanner --quiet"
    }
  }
}

Scheduled Scans

# Add to crontab for daily scans
0 9 * * * cd /path/to/project && secure-dep-scanner --format json --output daily-scan.json

API Integration

const SecurityScanner = require('secure-dep-scanner');

// Custom integration
async function securityCheck() {
  const scanner = new SecurityScanner({
    interactive: false,
    quiet: true
  });
  
  const issues = await scanner.scan();
  
  // Send to security dashboard
  await sendToDashboard(issues);
  
  return issues;
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/livresoltech/secure-dep-scanner.git
cd secure-dep-scanner
npm test

📄 License

MIT License - see LICENSE file for details.

🔗 Links

GitHub: https://github.com/livresoltech/secure-dep-scanner
Issues: https://github.com/livresoltech/secure-dep-scanner/issues
Security: See SECURITY.md for security policy

⚠️ Disclaimer

This tool is provided as-is for educational and security purposes. While we strive for accuracy, no security tool is perfect. Always:

Use multiple security tools
Keep dependencies updated
Follow security best practices
Verify suspicious findings manually

🎉 Support

If you find this tool helpful, consider:

⭐ Starring the repository
🐛 Reporting bugs
💡 Suggesting improvements
🔒 Contributing to security

Made with ❤️ by Livre Software Solutions

⚠️ Why Are Popular Packages Like Lodash Flagged?

This scanner flags any code patterns that are commonly abused in malware, such as use of Function, setTimeout, exec, or suspicious keywords—even in popular packages like Lodash.

This does NOT mean these packages are malicious!
These patterns are flagged so you can review them and make an informed decision.
You can whitelist legitimate packages to reduce noise (see configuration section).

The goal is to surface anything potentially risky, not to automatically label packages as unsafe.

🎭 Real-World Attack Scenarios

Fake Job Position Offering

Attack Vector: Malicious actors post fake job positions on LinkedIn, offering candidates a "coding challenge" or "project to complete."

How It Works:

Attacker creates a fake company profile on LinkedIn
Posts a job opening for a developer position
Sends candidates a "test project" with malicious dependencies
When candidates run npm install, malicious packages execute
Attacker gains access to the candidate's system and potentially their network

Example Scenario:

"Hi! We loved your profile. For the next round, please complete this coding challenge:
https://github.com/fake-company/test-project

Just clone, run 'npm install', and submit your solution!"

How secure-dep-scanner Protects You:

Scans the project's dependencies before installation
Detects suspicious packages and patterns
Warns about potentially malicious code
Prevents execution of harmful packages

Red Flags to Watch For:

Job offers that seem too good to be true
Requests to install and run unknown projects
Projects with suspicious package names
Dependencies that don't match the project's purpose

secure-dep-scanner