NPM Package Network Calls Scanner

A CLI tool for analyzing NPM packages to detect network calls, security issues, and potential vulnerabilities. Built with Commander.js and TypeScript.

Installation

Install dependencies:

npm install

Development

For development with auto-reload:

npm run dev -- [command] [options]

Build the project:

npm run build

Watch mode (rebuild on changes):

npm run watch

Run tests:

npm test

Run tests in watch mode:

npm run test:watch

Usage

Run the CLI in development:

npm run dev -- [command] [options]

Run the built CLI:

npm start -- [command] [options]

Or run the compiled JavaScript directly:

node dist/index.js [command] [options]

Features

• 📦 Download and extract NPM packages from the registry
• 🔍 Analyze packages for network calls and suspicious patterns
• 🛡️ Detect potential security vulnerabilities
• 🔎 Identify typosquatting patterns
• ⚠️ Find suspicious install scripts
• 🌐 Discover network access patterns
• 🔒 Detect obfuscated and minified code

Available Commands

analyze <package>

Analyze a specific NPM package for network calls and security issues.

live

Monitor the npm registry feed in real-time and automatically analyze newly published packages.

Analyze the latest version:

npm run dev -- analyze lodash

Analyze a specific version:

npm run dev -- analyze express -v 4.18.0
npm run dev -- analyze react --version 18.2.0

Example output:

📥 Downloading package: lodash@latest...
   Fetching metadata from NPM registry...
   Resolved 'latest' to version: 4.17.21
   Tarball URL: https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz
   Downloading and extracting package...
   Extracting tarball...
✅ Package downloaded successfully to: /path/to/downloads/lodash-4.17.21

Options:

• -v, --version <version> - Package version to analyze (default: "latest")

Arguments:

• <package> - NPM package name to analyze (required)

---

live - Real-Time Package Monitoring

Monitor the npm registry for newly published packages and analyze them automatically as they're published.

Start live monitoring:

npm run dev -- live
# Or if globally installed:
cli live

What it does:

• Connects to replicate.npmjs.com/registry/_changes API
• Polls for new package publications every 10 seconds
• Automatically fetches and analyzes each new package
• Displays full analysis results (typosquatting, install scripts, network patterns)
• Handles errors with exponential backoff retry
• Tracks statistics (packages analyzed, sequence numbers)
• Resumes from last known sequence on restart

Example output:

🔴 Starting live npm package feed monitor...
📡 Connecting to replicate.npmjs.com...
✅ Connected to npm feed (starting from seq: 12345678)

⏳ Polling for new package publications...
📥 Received 3 change(s) from feed

═══════════════════════════════════════════════════════════════════
🆕 [14:23:15] New package detected: example-package@1.0.0
═══════════════════════════════════════════════════════════════════

📥 Checking package: example-package@1.0.0...
🔍 Analyzing for typosquatting patterns...
🔍 Analyzing install scripts...
🌐 Analyzing network access patterns...
🔬 Analyzing network access patterns (AST - Tier 2)...

✅ Analysis complete for example-package@1.0.0
📊 Total packages analyzed: 1
───────────────────────────────────────────────────────────────────
⏳ Waiting for next package...

Features:

• Polling-based: Uses the npm replicate API with 10-second intervals
• Automatic error recovery: Handles network issues with exponential backoff
• Sequence tracking: Resumes from last known position
• Statistics tracking: Shows total packages analyzed and current sequence
• Graceful shutdown: Press Ctrl+C to stop monitoring

Technical Details:

• Endpoint: https://replicate.npmjs.com/registry/_changes
• Method: HTTP polling with since parameter for incremental updates
• Batch size: 100 changes per request (configurable)
• Poll interval: 10 seconds between requests
• Metadata: Fetches package details from https://registry.npmjs.org/<package>
• Headers: Includes npm-replication-opt-in: true for API transition period

Use cases:

• Security monitoring: Catch suspicious packages as soon as they're published
• Research: Study npm package publication patterns
• Early detection: Identify typosquats or malicious packages in real-time
• Package discovery: See what's being published to npm

---

Global Options

• -V, --version - Output the version number
• -h, --help - Display help for command

Project Structure

.
├── src/
│   ├── index.ts                       # Main CLI entry point
│   ├── packageOperations.ts           # Package download and analysis orchestration
│   ├── typosquatDetection.ts          # Typosquatting detection with Levenshtein distance
│   ├── astNetworkAnalysis.ts          # Tier 2 AST-based network detection
│   ├── obfuscationDetection.ts        # Multi-heuristic obfuscation detection
│   ├── liveFeed.ts                    # Real-time npm feed monitoring
│   ├── networkDetection.test.ts       # Tier 1 network detection tests
│   ├── typosquatDetection.test.ts     # Typosquatting detection tests
│   ├── astNetworkAnalysis.test.ts     # Tier 2 AST analysis tests
│   └── obfuscationDetection.test.ts   # Obfuscation detection tests
├── downloads/                          # Downloaded packages (gitignored)
├── dist/                               # Compiled JavaScript output
├── tsconfig.json                       # TypeScript configuration
├── package.json                        # Project metadata and dependencies
└── README.md                           # Documentation

Making it Executable

To make the CLI globally available:

1. Build the project:

npm run build

2. Make the script executable:

chmod +x dist/index.js

3. Link it globally:

npm link

4. Now you can run it from anywhere:

cli analyze lodash

How It Works

1. Package Download

The tool fetches package metadata from the NPM registry and downloads the tarball to a local downloads/ directory. It handles:

• Version resolution (including "latest")
• Package extraction from tarball
• Cleanup of existing downloads

2. Analysis

The tool analyzes packages for security issues using multiple detection methods:

Install Script Analysis ✅

Detects and flags suspicious install scripts including:

• Remote script downloads and execution (curl/wget piped to bash)
• Use of eval() for arbitrary code execution
• Child process spawning
• Destructive file operations
• Environment variable access
• Base64 encoding (potential obfuscation)
• Global package installation
• Credential references

Network Access Pattern Detection ✅ (Tier 1 + Tier 2)

Tier 1: Fast Static Analysis (Regex)

• Scans package.json for 30+ known networking libraries
• Categorizes libraries by type (HTTP clients, WebSocket libraries, proxy agents)
• Regex-based pattern matching for quick detection
• Finds: fetch(), XMLHttpRequest, http/https imports, axios calls, WebSocket, Socket.IO, network commands, URLs
• Speed: Very fast, suitable for large codebases
• Accuracy: Good, but may have false positives

Tier 2: Deep Static Analysis (AST)

• Parses JavaScript/TypeScript into Abstract Syntax Trees using acorn
• Context-aware detection with variable tracking
• Tracks imports and requires to understand module aliases
• Detects function calls with confidence scoring
• Finds:
  • ES6 imports (import http from 'http')
  • CommonJS requires (const axios = require('axios'))
  • Function calls with tracked variables (axios.get(), http.request())
  • Constructor usage (new XMLHttpRequest(), new WebSocket())
  • Method calls on tracked objects (request.send(), socket.on())
• Speed: Slower, parses all JS/TS files
• Accuracy: Very high, understands code structure
• Confidence Levels:
  • 🎯 High: Tracked imports/requires with known usage
  • 🔍 Medium: Probable network calls without direct import tracking
  • ❓ Low: Ambiguous patterns

Example Output (axios):

🌐 Tier 1 found 4 patterns (regex)
🔬 Tier 2 found 32 patterns (AST)

AST Findings:
🎯 Module Import (3): http, https, http2 - High confidence
🎯 XMLHttpRequest Constructor (1) - High confidence
🔍 Network Method Call (11) - Medium confidence

Typosquatting Detection ✅

Similarity Analysis:

• Uses Levenshtein distance algorithm to measure name similarity
• Compares against 100+ popular NPM packages
• Configurable edit distance threshold (default: 2 characters)
• Fetches real-time download statistics from NPM registry

Pattern Detection:

• Character substitutions (l0dash: o→0, re@ct: a→@)
• Repeated characters (reactttt, expresss)
• Scope manipulation (@typess vs @types)
• Separator variations (lodash-utils vs lodashutils)

Risk Assessment:

• HIGH RISK: Similar name + significantly fewer downloads (100x+ ratio)
• MEDIUM RISK: Similar name but comparable downloads
• Download ratio calculation for severity scoring

Example Detection:

🚨 Package "expres" is similar to "express"
   Edit distance: 1 character(s)
   Downloads: 31,957 vs 196,492,148
   Download ratio: 6148x (popular package has 6149x more downloads)
   🚨 HIGH RISK: This appears to be a typosquat attempt

Obfuscation Detection ✅

Multi-Heuristic Analysis:

• Uses Shannon entropy calculation to detect randomness in code
• Identifies encoded strings (Base64, hex, unicode escapes)
• Detects dynamic code execution patterns
• Analyzes code structure for minification/obfuscation
• Recognizes known obfuscator signatures

Detection Methods:

1. High Entropy Strings

   • Calculates Shannon entropy for identifiers and strings
   • Detects variable names with entropy > 4.8 (indicates randomness)
   • Identifies suspicious string content (entropy > 5.0)
   • Example: _0x4a2b3c, qZmXkRpNwTgH

2. Encoded Strings

   • Base64: Detects long base64-encoded strings (40+ chars)
   • Hex encoding: Identifies 0x and \x hex patterns
   • Unicode escapes: Flags excessive \uXXXX sequences (>20)
   • Attempts to decode and check for executable code

3. Dynamic Execution

   • eval() usage
   • Function() constructor calls
   • Dynamic property access (window['eval'], global['require'])
   • setTimeout/setInterval with string arguments
   • Constructor access patterns

4. Suspicious Structure

   • Very long lines (>500 characters)
   • Minimal whitespace (<5% of file)
   • Excessive string concatenation (>20 instances)
   • Common in minified/obfuscated code

5. Obfuscator Signatures

   • JavaScript Obfuscator: _0x prefix patterns
   • IIFE obfuscation: Immediately Invoked Function Expressions
   • Infinite loops: while(true) with break conditions
   • Array mangling: Obfuscated array initialization

Severity Levels:

• 🚨 HIGH (score > 75): Heavily obfuscated, likely malicious
• ⚠️ MEDIUM (score 50-75): Shows obfuscation signs
• ℹ️ LOW (score < 50): Minor obfuscation indicators

Example Output:

🔍 Obfuscation Analysis: HIGH: Code appears heavily obfuscated
📊 Overall Score: 85/100

🚨 HIGH SEVERITY (2):
   High-entropy identifiers detected
   File: package/index.js
      - Found 12 high-entropy identifiers
      - Average entropy: 5.12
      - Examples: _0x4a2b3c, _0x5d3e4f, _0x6f4a5b

   Dynamic code execution detected
   File: package/lib/core.js
      - Detected patterns: eval() (3x), Function() (2x)
      - These can be used to hide malicious code
      - Combined risk score: 100

3. Reporting

Analysis results will be displayed in the console with detailed findings and recommendations.

Implementation Details

Core Modules

packageOperations.ts - Main analysis orchestration:

• downloadPackage() - Downloads and extracts NPM packages
• findTyposquatPatterns() - Detects typosquatting attempts
• findInstallScriptsPatterns() - Analyzes install scripts
• findNetworkAccessPatterns() - Identifies network calls

typosquatDetection.ts - Typosquatting detection engine:

• levenshteinDistance() - Calculate edit distance between strings
• detectTyposquatting() - Compare package against popular packages
• detectTyposquatPatterns() - Find suspicious character patterns
• fetchPackageDownloads() - Get NPM download statistics

astNetworkAnalysis.ts - Tier 2 AST-based analysis:

• analyzeFileAST() - Parse and analyze single JavaScript file
• analyzeFilesAST() - Batch analyze multiple files
• formatASTFindings() - Display AST findings with confidence levels
• Tracks imports, requires, function calls, and constructors with context

obfuscationDetection.ts - Obfuscation detection engine:

• calculateEntropy() - Shannon entropy calculation for randomness detection
• analyzeFileForObfuscation() - Analyze single file for obfuscation patterns
• generateObfuscationReport() - Create overall obfuscation report for multiple files
• detectHighEntropyStrings() - Identify random-looking identifiers and strings
• detectEncodedStrings() - Find Base64, hex, and unicode-encoded content
• detectDynamicExecution() - Detect eval(), Function(), and similar patterns
• detectSuspiciousStructure() - Analyze code structure (minification, concatenation)
• detectObfuscatorSignatures() - Recognize known obfuscator patterns
• formatObfuscationReport() - Display findings with severity levels

liveFeed.ts - Real-time npm feed monitoring:

• NPMFeedMonitor - Main monitoring class with polling engine
• startLiveFeedMonitor() - Initialize and start feed monitoring
• Polls replicate.npmjs.com changes feed every 10 seconds
• Fetches package metadata from npm registry
• Handles errors with exponential backoff retry
• Automatically analyzes new packages as they're published

Testing

The project includes comprehensive unit tests for all network detection features using Node.js's built-in test runner.

Test Coverage

Network Pattern Detection (36 tests):

• Fetch API detection
• XMLHttpRequest detection
• Node.js http/https module detection
• WebSocket detection
• Axios detection
• Socket.IO detection
• Network command detection (curl, wget)
• URL reference detection
• DNS lookup detection
• TCP/UDP socket detection
• Browser API detection (navigator.sendBeacon, EventSource)
• Edge case handling

Dependency Analysis (9 tests):

• Detection of networking libraries in dependencies
• Support for all dependency types (dependencies, devDependencies, etc.)
• Handling of missing or invalid package.json files

Pattern Validation (3 tests):

• Pattern integrity checks
• Category validation

Typosquatting Detection (42 tests):

• Levenshtein distance calculation (10 tests)
  • Character substitutions, deletions, insertions
  • Edge cases (empty strings, symmetric distance)
• Pattern analysis (20 tests)
  • Character substitution detection (0→o, @→a, etc.)
  • Repeated character detection
  • Scope manipulation detection
  • Separator detection
• Integration tests (10 tests)
  • Real NPM API queries
  • Download statistics fetching
  • Risk categorization
  • Popular package comparison
• Popular packages list validation (4 tests)

AST Network Analysis (34 tests):

• Import/require detection (ES6 and CommonJS)
• Function call detection with variable tracking
• Constructor detection (XMLHttpRequest, WebSocket, etc.)
• Variable alias tracking
• Line number and code context extraction
• Complex real-world scenarios
• Multiple file analysis
• Confidence level validation

Obfuscation Detection (22 tests):

• High entropy identifier detection
• Encoded string detection (Base64, hex, unicode)
• Dynamic execution pattern detection (eval, Function constructor)
• Suspicious code structure analysis (minification, whitespace)
• Known obfuscator signature detection
• Overall report generation with severity scoring
• Edge case handling (empty files, comments-only files)

Total: 146 tests, all passing ✅

Run tests with:

npm test

Test Files

• src/networkDetection.test.ts - Tier 1 regex network detection (48 tests)
• src/typosquatDetection.test.ts - Typosquatting detection (42 tests)
• src/astNetworkAnalysis.test.ts - Tier 2 AST network detection (34 tests)
• src/obfuscationDetection.test.ts - Obfuscation detection (22 tests)

Technologies

• TypeScript - Type-safe development with strict mode enabled
• Commander.js - CLI framework for command parsing
• Node.js Built-in APIs - File system, child process, HTTP fetch
• Node.js Test Runner - Built-in testing framework
• acorn - Fast JavaScript AST parser for Tier 2 analysis
• acorn-walk - AST traversal utilities
• tsx - Fast TypeScript execution for development
• NPM Registry API - Package metadata and download statistics

Development

Adding New Analysis Features

To add a new analysis pattern:

1. Implement your analysis function in src/packageOperations.ts
2. Call it from startAnalysis() function
3. Return findings in a consistent format

Example:

async function findNewPattern(name: string, version: string) {
  const packageDir = join(process.cwd(), 'downloads', `${name}-${version}`);
  // Your analysis logic here
  console.log('🔍 Analyzing for new pattern...');
}

Resources

• Commander.js Documentation
• TypeScript Documentation
• NPM Registry API
• Node.js CLI Best Practices