Soft Awake 🛡️

Advanced NPM Package Security Analysis Tool with AI-Powered Intelligence

Soft Awake is a comprehensive CLI tool that leverages Large Language Models (LLMs) to analyze NPM packages for security vulnerabilities, malware detection, and dependency risks. It provides intelligent recommendations for safer alternatives and helps developers make informed decisions about their project dependencies.

🚀 Features

📋 Table of Contents

🛠️ Installation

Prerequisites

Install from NPM

npm install -g soft-awake

Install from Source

git clone https://github.com/ktfth/soft-awake.git
cd soft-awake
npm install
npm run build
npm link

⚡ Quick Start

  1. Configure your OpenRouter API key:

    soft-awake config set api-key sk-or-v1-your-api-key-here

  2. Analyze a single package:

    soft-awake analyze express

  3. Scan your project's dependencies:

    soft-awake scan package.json --include-dev

📖 Commands

analyze - Analyze NPM Packages

Analyze one or more NPM packages for security vulnerabilities and malware.

soft-awake analyze <packages...> [options]

Arguments:

Options:

Examples:

# Analyze latest version of express
soft-awake analyze express

# Analyze specific version with high severity filter
soft-awake analyze react@18.2.0 --severity high

# Analyze multiple packages with JSON output
soft-awake analyze lodash axios moment --format json

# Deep analysis with custom timeout
soft-awake analyze webpack --depth 10 --timeout 60

scan - Scan package.json Files

Scan a package.json file and analyze all dependencies.

soft-awake scan [package-json-path] [options]

Arguments:

Options:

Examples:

# Scan current directory's package.json
soft-awake scan

# Scan with dev dependencies included
soft-awake scan --include-dev

# Scan specific file excluding test packages
soft-awake scan ./frontend/package.json --exclude "@types/*" "jest"

# Generate HTML report
soft-awake scan --format html --output security-report.html

cache - Manage Analysis Cache

Manage the analysis result cache for improved performance.

soft-awake cache <subcommand> [options]

Subcommands:

Options:

Examples:

# View cache information
soft-awake cache info

# Clean expired entries
soft-awake cache clean

# Clear all cache (with confirmation)
soft-awake cache clear

# Force clear all cache
soft-awake cache clear --force

config - Manage Configuration

Manage tool configuration settings.

soft-awake config <subcommand> [key] [value]

Subcommands:

Configuration Keys:

Examples:

# Set OpenRouter API key
soft-awake config set api-key sk-or-v1-your-api-key-here

# Set cache TTL to 24 hours
soft-awake config set cache-ttl 24

# Get current API key
soft-awake config get api-key

# List all settings
soft-awake config list

withdrawn - Analyze Withdrawn Versions

Analyze potentially withdrawn or removed package versions due to security vulnerabilities.

soft-awake withdrawn <package> [options]

Arguments:

Options:

Examples:

# Analyze debug package for withdrawn versions
soft-awake withdrawn debug

# Verbose analysis with detailed gap information
soft-awake withdrawn express --verbose

# JSON output for programmatic processing
soft-awake withdrawn lodash --format json

# Save report to file
soft-awake withdrawn react --output withdrawn-analysis.txt

What This Command Detects:

⚙️ Configuration

OpenRouter API Key

Soft Awake requires an OpenRouter API key for LLM-powered analysis:

  1. Sign up at OpenRouter.ai
  2. Generate an API key
  3. Configure it: soft-awake config set api-key sk-or-v1-your-key

Environment Variables

You can also set configuration via environment variables:

export SOFT_AWAKE_API_KEY="sk-or-v1-your-api-key"
export SOFT_AWAKE_CACHE_TTL="168"  # 7 days in hours

📋 Usage Examples

Basic Package Analysis

# Quick security check
soft-awake analyze express

# Detailed analysis with full dependency tree
soft-awake analyze express --depth 15 --severity low

# Check specific version
soft-awake analyze react@17.0.2

Project Security Audit

# Full project audit including dev dependencies
soft-awake scan --include-dev --format json --output audit.json

# Production dependencies only
soft-awake scan --exclude "@types/*" "eslint*" "jest"

Batch Analysis

# Analyze multiple related packages
soft-awake analyze react react-dom react-router

# Check all testing frameworks
soft-awake analyze jest mocha chai --severity high

Advanced Reporting

# Generate comprehensive HTML report
soft-awake scan --format html --output security-report.html --include-dev

# JSON output for CI/CD integration
soft-awake analyze $PACKAGE_NAME --format json --severity critical

📄 Output Formats

Text Format (Default)

Human-readable format with color coding and clear sections:

📊 SECURITY REPORT
==================================================

Package: express@4.18.2
Risk Level: MEDIUM
Overall Score: 45/100

🔴 Critical Issues (2):
• Potential ReDoS vulnerability in path-to-regexp
• Outdated dependency with known CVE

🟡 Medium Issues (3):
• Missing security headers configuration
• Deprecated dependency usage
• Insufficient input validation

💡 Recommendations:
• Update to express@4.19.0 or later
• Consider fastify as a more secure alternative
• Implement helmet middleware for security headers

⏱  Analysis time: 2.3s | Cached: No
--------------------------------------------------

JSON Format

Structured data for programmatic processing:

{
  "package": {
    "name": "express",
    "version": "4.18.2",
    "analyzedAt": "2024-01-15T10:30:00Z"
  },
  "security": {
    "overallScore": 45,
    "riskLevel": "MEDIUM",
    "issues": [
      {
        "severity": "CRITICAL",
        "type": "vulnerability",
        "title": "Potential ReDoS vulnerability",
        "description": "...",
        "cve": "CVE-2024-1234"
      }
    ]
  },
  "recommendations": [
    {
      "type": "update",
      "current": "4.18.2",
      "recommended": "4.19.0",
      "reason": "Security patches"
    }
  ]
}

HTML Format

Complete web report with interactive elements and visualizations.

🚦 Exit Codes

Soft Awake uses specific exit codes to indicate analysis results:

CI/CD Integration

Use exit codes for automated security gates:

# Fail CI if critical issues found
soft-awake analyze $PACKAGE --severity critical
if [ $? -eq 1 ]; then
  echo "Critical security issues found!"
  exit 1
fi

🔌 API Integration

OpenRouter Integration

Soft Awake integrates with OpenRouter for LLM-powered analysis:

NPM Registry API

Direct integration with the NPM registry for package metadata:

🛡️ Security Features

Malware Detection

Withdrawn Version Detection

Vulnerability Assessment

Best Practices

🚀 Performance

Caching Strategy

Optimization Features

🤝 Contributing

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

Development Setup

git clone https://github.com/ktfth/soft-awake.git
cd soft-awake
npm install
npm run dev

Testing

# Run all tests
npm test

# Run contract tests
npm run test:contract

# Run with coverage
npm run test:coverage

Building

# Build for production
npm run build

# Build and watch for changes
npm run build:watch

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

🙏 Acknowledgments

Made with ❤️ for a more secure JavaScript ecosystem