NPM Safety Wrapper 🛡️

A comprehensive supply-chain security wrapper for npm that protects against malicious packages by enforcing age requirements, monitoring publishing patterns, and blocking known-compromised versions.

🚀 Features

• ⏰ Version Age Gating: Enforce minimum age requirements before allowing package installation
• 👤 Publisher Trust System: Block packages from unknown publishers during cooling-off period
• 🚫 Compromised Package Blocking: Integration with known-compromised package lists
• 📊 Activity Anomaly Detection: Warn on unusual release patterns (configurable thresholds)
• ⚡ Performance Optimized: Parallel resolution, intelligent caching, and lockfile support
• 🔧 CI/CD Ready: Built-in utilities for continuous integration pipelines
• 🎯 Flexible Configuration: Per-package overrides, allowlists, and warning-only mode
• 📝 JSON Logging: Structured logs for monitoring and alerting systems

📋 Requirements

• Bash ≥ 4.0
• Node.js (for JSON parsing)
• npm CLI
• OS: Linux or macOS

🔧 Installation

Quick Install

# Download the wrapper
curl -L https://raw.githubusercontent.com/dhofheinz/npm-safety-wrapper/main/npm-safety-wrapper.sh \
  -o ~/.config/npm-safety.sh

# Add to your shell configuration
echo 'source ~/.config/npm-safety.sh' >> ~/.bashrc
# Or for zsh:
echo 'source ~/.config/npm-safety.sh' >> ~/.zshrc

# Reload shell
source ~/.bashrc

Using Install Script

curl -L https://raw.githubusercontent.com/dhofheinz/npm-safety-wrapper/main/install.sh | bash

📖 Usage

Once installed, the wrapper automatically intercepts npm install commands:

# Normal usage - checks all packages
npm install express

# Install multiple packages
npm install react react-dom @types/react

# Bypass checks once
npm --force install express
# Or use the alias
npm-force install express

# Check package age without installing
npm-check-age express@latest 24

# Validate all dependencies in package.json
npm-check-deps

# View current configuration
npm-status

# Clean cache
npm-safety-cache-clean

⚙️ Configuration

Configure via environment variables in your shell profile:

# Core Settings
export NPM_SAFETY_ENABLED=true              # Enable/disable wrapper
export NPM_SAFETY_WARN_ONLY=false          # Warn instead of blocking
export NPM_MIN_AGE_HOURS=24                # Default minimum age requirement

# Per-Package Overrides
export NPM_MIN_AGE_HOURS_BY_PACKAGE="react:48,@types/node:6,vitest:12"

# Publisher Trust
export NPM_TRUSTED_PUBLISHERS="sindresorhus,tj,isaacs"
export NPM_BLOCK_UNKNOWN_PUBLISHER_HOURS=12

# Activity Monitoring
export NPM_RECENT_DAYS=7
export NPM_WARN_MANY_VERSIONS=5
export NPM_ACTIVITY_WHITELIST="webpack,rollup"

# Allowlists
export NPM_SAFETY_ALLOWLIST_SCOPES="@mycompany,@types"
export NPM_SAFETY_ALLOWLIST_PACKAGES="trusted-internal-pkg"

# Cache Settings
export NPM_SAFETY_CACHE_DIR="$HOME/.cache/npm-safety"
export NPM_SAFETY_CACHE_TTL=300

# Advanced
export NPM_SAFETY_FAIL_CLOSED=false        # Treat verification failures as blocks
export NPM_SAFETY_JSON=true                # Enable JSON logging
export NPM_SAFETY_DEBUG=false              # Debug output

🛡️ Security Model

The wrapper implements defense-in-depth with multiple security layers:

1. Age Verification

New package versions must age for a configured period before installation is allowed. This prevents immediate exploitation of compromised npm accounts.

2. Publisher Trust

Packages from unknown publishers are subject to additional cooling-off periods, while trusted publishers can publish immediately installable versions.

3. Known-Compromised Blocking

Integration with compromised package databases to prevent installation of known-malicious versions.

4. Activity Monitoring

Detects unusual publishing patterns that may indicate account compromise or malicious behavior.

📊 JSON Logging

Enable structured logging for integration with monitoring systems:

export NPM_SAFETY_JSON=true

Example output:

{"event":"block","reason":"age","name":"suspicious-pkg","version":"1.0.0","age_hours":2,"min_hours":24}
{"event":"warn","reason":"activity","name":"hyperactive-pkg","version":"2.0.0","activity":8}
{"event":"safe","name":"express","version":"4.18.0","age_hours":720}

🔍 CI/CD Integration

GitHub Actions Example

name: Security Check
on: [push, pull_request]

jobs:
  check-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3

      - name: Install NPM Safety Wrapper
        run: |
          curl -L https://raw.githubusercontent.com/dhofheinz/npm-safety-wrapper/main/npm-safety-wrapper.sh \
            -o npm-safety.sh

      - name: Check Dependencies
        run: |
          source npm-safety.sh
          npm-check-deps package.json

🧪 Testing

Run the test suite:

./tests/run-tests.sh

🤝 Contributing

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

📝 License

MIT License - see LICENSE file for details.

🔗 Links

• Changelog
• Security Policy
• Examples
• Wiki

⚠️ Disclaimer

This tool provides additional security layers but is not a complete security solution. Always:

• Review your dependencies regularly
• Keep the compromised package list updated
• Monitor security advisories
• Use additional tools like npm audit

🙏 Acknowledgments

• Inspired by the need for better npm supply chain security
• Community feedback and contributions
• The npm security team for their ongoing work