🔒 safe-pkg

Security-first package installer with multi-layer vulnerability analysis

safe-pkg is a drop-in replacement for npm install, yarn add, and pnpm add that analyzes packages for security risks before installing them. It combines industry-standard vulnerability scanning with intelligent heuristics and optional AI enhancement to protect your projects from malicious packages.

✨ Features

• 🔍 4-Layer Security Analysis

  • NPM Audit integration for known vulnerabilities
  • Package metadata analysis (downloads, age, maintainers)
  • Suspicious script detection (postinstall hooks, dangerous commands)
  • Heuristic pattern matching (typosquatting, malware signatures)

• 🤖 Optional AI Enhancement

  • Natural language security insights powered by Claude
  • Contextual risk explanations
  • Smart recommendations

• 🎨 Beautiful Terminal UI

  • Color-coded risk levels (🟢 Safe / 🟡 Caution / 🔴 Dangerous)
  • Detailed security reports
  • Interactive confirmation prompts

• 📦 Universal Package Manager Support

  • Auto-detects npm, yarn, or pnpm
  • Seamlessly forwards commands to your package manager
  • Works with existing workflows

• 📊 Project Scanning

  • Analyze all existing dependencies at once
  • Identify risky packages in your codebase
  • Continuous security monitoring

� Screenshots

Security Analysis in Action

Project Dependency Scanning

�🚀 Installation

Global Installation (Recommended)

# Using npm
npm install -g safe-pkg

# Using pnpm
pnpm add -g safe-pkg

# Using yarn
yarn global add safe-pkg

Local Development

git clone https://github.com/joker7blue/safe-install.git
cd safe-install
pnpm install
pnpm build
pnpm link --global

📖 Usage

Install Packages with Security Analysis

# Analyze and install a single package
safe-pkg install express

# Install multiple packages
safe-pkg install react vue lodash

# Save to devDependencies
safe-pkg install -D typescript eslint

# Skip analysis (direct install)
safe-pkg install axios --skip-analysis

Check a Package Without Installing

# Analyze a package before deciding to install
safe-pkg check suspicious-package-name

Scan Existing Project Dependencies

# Scan production dependencies
safe-pkg scan

# Include devDependencies
safe-pkg scan --dev

Help & Options

safe-pkg --help
safe-pkg install --help
safe-pkg scan --help

🔐 Security Layers Explained

1. NPM Audit (40% weight)

• Checks for known CVEs and security advisories
• Identifies critical, high, moderate, and low severity vulnerabilities
• Uses official npm audit database

2. Metadata Analysis (25% weight)

• Weekly download counts (flags packages with <100 downloads)
• Package age (warns about brand new or abandoned packages)
• Maintainer count (flags unmaintained packages)
• License verification

3. Script Detection (25% weight)

• Scans package.json scripts for dangerous commands
• Detects postinstall/preinstall hooks
• Identifies network calls, file system modifications, eval usage
• Flags obfuscated code patterns

4. Heuristic Analysis (10% weight)

• Typosquatting detection (Levenshtein distance from popular packages)
• Suspicious keywords ("hack", "crack", "free-premium")
• Name pattern analysis (excessive hyphens, random characters)
• Known malware signatures

🤖 AI Enhancement (Optional)

Enable AI-powered insights by setting your Anthropic API key:

# Set environment variable
export ANTHROPIC_API_KEY="sk-ant-..."

# Or create a config file
echo '{"anthropicApiKey": "sk-ant-..."}' > ~/.safe-pkgrc

The AI layer provides:

• Natural language security explanations
• Context-aware risk assessment
• Actionable recommendations
• Human-readable insights

📊 Example Output

$ safe-pkg install tiny-package-that-doesnt-exist-12345

ℹ Using package manager: pnpm

🔒 Security Analysis
====================

ℹ Analyzing tiny-package-that-doesnt-exist-12345...

================================================================================
📦 tiny-package-that-doesnt-exist-12345 (unknown)
================================================================================

Risk Score: 6/10
Risk Level:  CAUTION 

Recommendation:
  ⚠️  PROCEED WITH CAUTION - Review security warnings carefully

Warnings: (4)
  🟡 MEDIUM - Low weekly downloads (0)
     Source: metadata
  🟠 HIGH - Package has no maintainers
     Source: metadata
  🟡 MEDIUM - Package has no license
     Source: metadata
  🟡 MEDIUM - Pattern warnings: Excessive hyphens (5)
     Source: heuristic

Analysis Details:
  Audit: 0 vulnerabilities - Score: 0/10
  Metadata: 0 weekly downloads, 0 days old - Score: 8/10
     Maintainers: 0, License: No
  Scripts: Clean - Score: 0/10
  Heuristics: Clean - Score: 1/10
     Patterns: Excessive hyphens (5)

⚠️  Package "tiny-package-that-doesnt-exist-12345" has warnings (score: 6/10). Continue? › (y/N)

⚙️ Configuration

Create a .safe-pkgrc file in your project root or home directory:

{
  "anthropicApiKey": "sk-ant-...",
  "riskThreshold": 7,
  "autoConfirm": false
}

Options:

• anthropicApiKey - Your Anthropic API key for AI insights
• riskThreshold - Minimum risk score to trigger warnings (default: 7)
• autoConfirm - Skip confirmation for safe packages (default: false)

🛠️ Development

# Clone repository
git clone https://github.com/joker7blue/safe-install.git
cd safe-install

# Install dependencies
pnpm install

# Build TypeScript
pnpm build

# Run linter
pnpm check

# Run tests
pnpm test

# Link globally for testing
pnpm link --global

Project Structure

src/
├── cli/            # Command-line interface
├── config/         # Configuration loader
├── detector/       # Package manager detection
├── executor/       # Command execution
├── scanner/        # Security analyzers
│   ├── auditAnalyzer.ts
│   ├── metadataAnalyzer.ts
│   ├── scriptAnalyzer.ts
│   ├── heuristicAnalyzer.ts
│   ├── aiAnalyzer.ts
│   └── analyzePackage.ts
├── scanner-project/  # Project dependency scanning
├── ui/              # Terminal UI components
└── types.ts         # TypeScript definitions

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

📝 License

MIT © Georges Fouejio

🙏 Acknowledgments

• Built with TypeScript
• Styled with Chalk
• CLI powered by Commander.js
• AI enhancement via Anthropic Claude

🔗 Links

• GitHub Repository
• Issue Tracker
• NPM Package (coming soon)

⚠️ Disclaimer

While safe-pkg provides multiple layers of security analysis, no automated tool can guarantee 100% protection against all security threats. Always review package source code for critical applications and report suspicious packages to the npm security team.