npm-guardian

Advanced Supply Chain Security for Node.js

npm-guardian is a comprehensive security toolkit designed to protect Node.js applications from modern supply chain attacks, including worms, credential harvesting, typosquatting, and dependency confusion. It provides multi-layered protection through behavioral analysis, integrity verification, and proactive threat detection.

Features

• Threat Detection Engine: Scans for known malicious packages and suspicious behaviors.
• Package Integrity: Cryptographically verifies package contents and detects tampering.
• Behavioral Monitoring: Monitors runtime network, file, and process activity for anomalies.
• Supply Chain Analysis: Assesses dependency tree risk and verifies package provenance.
• Sandboxing: Safely executes install scripts and new packages in isolation.
• CI/CD Integration: Works with GitHub Actions and other CI tools.
• Zero-Config Default: Sensible defaults, with granular configuration for advanced users.

Installation

npm install --save-dev npm-guardian
npx guardian init # Creates configuration and baseline

Configuration

Create or edit guardian.config.js:

module.exports = {
  protection: {
    level: 'strict', // strict, moderate, permissive
    blockSuspicious: true,
    quarantineUnknown: true
  },
  monitoring: {
    networkTraffic: true,
    fileSystemAccess: true,
    credentialScanning: true,
    processMonitoring: true
  },
  allowlist: [
    '@trusted/package',
    'well-known-library'
  ],
  notifications: {
    slack: 'webhook-url',
    email: '[email protected]'
  }
};

Usage

CLI

npx guardian init
npx guardian audit
npx guardian check-dependencies

Runtime (Recommended)

// Automatic protection
require('npm-guardian/auto-protect');

// Manual protection
const guardian = require('npm-guardian');
guardian.protect({
  onThreatDetected: (threat) => {
    console.log(`Threat detected: ${threat.type}`);
    // Custom handling
  }
});

CI/CD Example (GitHub Actions)

- name: npm Guardian Security Check
  uses: npm-guardian/action@v1
  with:
    fail-on: 'medium'
    report-format: 'sarif'

How It Works

• Pre-Install: Analyzes package reputation, dependency risk, and known vulnerabilities.
• Install-Time: Inspects install scripts, sandboxes risky code, and monitors file access.
• Runtime: Detects anomalous network, file, and process activity; protects credentials.
• Continuous: Periodically verifies integrity and updates threat intelligence.

Roadmap

• Core protection and monitoring
• Machine learning threat detection
• Community threat intelligence sharing
• Integration with major security platforms
• Enterprise features and compliance reporting

License

MIT

Contributing

Pull requests and issues are welcome!

Author

Hadj Hadji