npm-scan-plus 1.0.0

package/.eslintrc.json

@@ -0,0 +1,32 @@
+{
+  "env": {
+    "node": true,
+    "es2022": true,
+    "jest": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module",
+    "project": "./tsconfig.json"
+  },
+  "plugins": [
+    "@typescript-eslint"
+  ],
+  "rules": {
+    "no-console": "off",
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "no-case-declarations": "off"
+  },
+  "ignorePatterns": [
+    "dist/",
+    "node_modules/",
+    "coverage/"
+  ]
+}

package/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Code reviewers for this repository
+
+* @cbunt

package/.github/workflows/ci.yml

@@ -0,0 +1,105 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
+      - name: Upload coverage
+        uses: actions/upload-artifact@v4
+        if: matrix.node-version == '20.x'
+        with:
+          name: coverage
+          path: coverage/
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run ESLint
+        run: npm run lint
+
+      - name: Check formatting
+        run: npm run format -- --check
+
+  security:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check for known vulnerabilities
+        run: npm audit --audit-level=moderate

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "none",
+  "printWidth": 100,
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "endOfLine": "lf"
+}

package/FUNDING.yml

@@ -0,0 +1 @@
+github: cbuntingde

package/PLAN.md

@@ -0,0 +1,151 @@
+# npm Security Scanner - Implementation Plan
+
+## Project Overview
+
+**Project name:** npm-scan
+**Type:** Node.js CLI tool with library
+**Core functionality:** Security scanner that detects malicious npm packages, supply chain attacks, and obfuscated code BEFORE installation, plus post-install forensics
+
+## Architecture
+
+### 1. Pre-Install Scanner (npm-scan pre)
+
+Runs BEFORE npm install, intercepts package requests:
+
+```
+User runs: npx npm-scan pre install lodash
+    ↓
+Scanner fetches lodash metadata from npm registry
+    ↓
+Checks against blocklists (known malicious packages)
+    ↓
+Analyzes package publisher reputation
+    ↓
+Checks for reported vulnerabilities
+    ↓
+Reports threat assessment
+    ↓
+Only then runs npm install (if approved)
+```
+
+### 2. Post-Install Scanner (npm-scan post)
+
+Runs AFTER npm install, scans downloaded packages:
+
+```
+User runs: npx npm-scan post
+    ↓
+Scanner walks node_modules/
+    ↓
+For each package:
+  - Detects obfuscated code (base64, hex, eval wrappers)
+  - Checks for suspicious patterns (env exfil, crypto mining)
+  - Analyzes dependency chain for typosquatting
+  - Validates package integrity (hash verification)
+    ↓
+Reports findings
+```
+
+## Technical Implementation
+
+### Core Library Functions
+
+1. **`fetchPackageMetadata(name, registry)`** - Get package info from npm registry
+2. **`checkBlocklist(package)`** - Verify against known malicious blocklists
+3. **`analyzePublisher(publisher)`** - Check publisher reputation
+4. **`detectVulnerabilities(version)`** - Check for known CVEs
+5. **`scanPackageFiles(tarballPath)`** - Extract and analyze package contents
+6. **`detectObfuscation(files)`** - Identify obfuscated code patterns
+7. **`detectSuspiciousPatterns(files)`** - Check for malicious patterns
+8. **`checkTyposquatting(name, deps)`** - Detect typosquatting in dependency tree
+9. **`validateIntegrity(package, tarball)`** - Verify checksums
+
+### CLI Commands
+
+```bash
+# Pre-install scan
+npx npm-scan pre install <package> [--version <version>]
+
+# Post-install scan
+npx npm-scan post [--folder <path>]
+
+# Full scan (both)
+npx npm-scan scan <package> [--full]
+
+# Blocklist management
+npx npm-scan blocklist add <package>
+npx npm-scan blocklist remove <package>
+npx npm-scan blocklist list
+```
+
+### Patterns to Detect
+
+**Obfuscation:**
+- Base64 encoded strings in eval()
+- Hex-encoded code
+- String.fromCharCode() usage with eval
+- Packed/minified with suspicious wrappers
+
+**Malicious behavior:**
+- Network requests to suspicious IPs/domains
+- Environment variable exfiltration
+- File system access beyond package scope
+- Child process spawning
+- Crypto mining detection
+- Credential theft patterns
+- .bash_history, .gitconfig access
+
+**Supply chain attacks:**
+- Typosquatting (lodash vs lodsh)
+- Dependency confusion
+- Unexpected peer dependencies
+- Suspicious postinstall scripts
+
+## File Structure
+
+```
+npm-scan/
+├── src/
+│   ├── lib/
+│   │   ├── registry.ts      # npm registry API client
+│   │   ├── blocklist.ts     # Blocklist management
+│   │   ├── scanner.ts      # Core scanning logic
+│   │   ├── patterns.ts     # Detection patterns
+│   │   └── integrity.ts    # Hash verification
+│   ├── cli/
+│   │   ├── pre.ts          # Pre-install command
+│   │   ├── post.ts         # Post-install command
+│   │   └── index.ts        # CLI entry
+│   └── types.ts
+├── bin/
+│   └── npm-scan
+├── tests/
+│   └── ...
+├── package.json
+├── tsconfig.json
+├── README.md
+└── .npmignore
+```
+
+## Blocklist Sources (MVP)
+
+- npm Advisory DB (via npm audit API)
+- GitHub Advisory Database
+- Known malicious packages (maintained locally)
+- User-defined blocklist
+
+## Integration Options
+
+1. **Standalone CLI:**
+   ```bash
+   npx npm-scan pre install <package>
+   ```
+
+2. **npm hook wrapper:**
+   Place script in PATH before npm to intercept
+
+3. **Git hook integration:**
+   Run in pre-commit hook
+
+4. **CI/CD integration:**
+   Use in pipeline before deployment

package/README.md

@@ -0,0 +1,150 @@
+# npm-scan 🔒
+
+**Security scanner for npm packages** - Pre and post-install scanning for malicious code, supply chain attacks, and obfuscated code.
+
+## Why We Built This
+
+npm package supply chain attacks are increasing at an alarming rate. Recent examples include:
+
+- **TanStack (May 2026)**: Malicious package published to npm registry containing cryptocurrency stealing code distributed to thousands of applications. ([InfoQ](https://www.infoq.com/news/2026/05/tanstack-supply-chain-attack/))
+- **event-stream (2018)**: Maintainer deliberately added malicious code to steal cryptocurrency wallet keys from Copay users
+- **ua-parser-js (2021)**: Compromised package with cryptomining malware affecting millions of downloads
+- **Colors.js / Faker.js (2022)**: Maintainer intentionally sabotaged popular packages
+
+These attacks succeed because:
+- Developers trust npm packages without verification
+- No automated scanning before install
+- Obfuscated code hides malicious intent
+- Typosquatting confuses developers
+
+**npm-scan** was built to automatically detect these threats before they reach your project.
+
+## Features
+
+### Pre-Install Scanning
+- ✅ **Blocklist Check** - Known malicious packages (event-stream, flatmap-stream, etc.)
+- ✅ **Typosquatting Detection** - Similar names to popular packages (lodash vs lodsh)
+- ✅ **Vulnerability Database Check**
+  - OSV (Google's Open Source Vulnerabilities)
+  - GitHub Advisory Database
+  - npm Audit
+- ✅ **License Risk Analysis** - Warns about GPL, proprietary, or missing licenses
+- ✅ **Maintainer Trust Scoring** - Identifies known trusted maintainers
+- ✅ **Repository Validation** - Verifies repo URL matches package
+- ✅ **Package Integrity** - Hash verification from npm registry
+- ✅ **Size Anomaly Detection** - Flags packages > 50MB
+- ✅ **Deprecated Dependencies** - Warns about request, moment, underscore
+
+### Post-Install Scanning
+- ✅ **Obfuscation Detection** - base64, eval(), hex encoding
+- ✅ **Malicious Pattern Detection** - env exfil, shell exec, crypto mining
+- ✅ **Suspicious Scripts** - postinstall, preinstall analysis
+- ✅ **Sensitive Files** - .env, .ssh, credentials detection
+
+## Installation
+
+```bash
+npm install -g npm-scan
+```
+
+Or use without installation:
+
+```bash
+npx npm-scan pre install <package>
+```
+
+## Quick Start: Automatic Wrapper
+
+The **recommended way** to use npm-scan is with the automatic wrapper:
+
+```bash
+# Install a package with automatic pre + post scan
+npm-scan-wrap install lodash
+
+# Install multiple packages
+npm-scan-wrap install lodash axios express
+
+# Install all dependencies from package.json
+npm-scan-wrap install
+```
+
+The wrapper automatically:
+1. 🔍 Pre-install scans each package
+2. 📥 Runs npm install
+3. 🔍 Post-install scans node_modules
+
+## Manual Usage
+
+If you prefer manual control:
+
+### Pre-install scan
+```bash
+npm-scan pre install <package>
+npm-scan pre install axios --version 1.6.0
+npm-scan pre install lodash -V  # verbose output
+```
+
+### Post-install scan
+```bash
+npm-scan post
+npm-scan post --folder ./node_modules
+```
+
+### Blocklist management
+```bash
+npm-scan blocklist list
+npm-scan blocklist add <package>
+npm-scan blocklist remove <package>
+```
+
+## Detection Patterns
+
+### Obfuscation
+- `eval()` with atob/fromCharCode
+- Base64 encoded strings
+- Hex/unicode encoded characters
+
+### Malicious Behavior
+- Environment variable access (KEYS, SECRETS, TOKENS)
+- Network requests to IP addresses or external code hosting
+- Child process execution
+- Crypto mining pool connections
+- Keylogging code
+
+### Suspicious Scripts
+- postinstall/preinstall with complex shell commands
+- curl/wget downloads
+- Packages scanning directories outside scope
+
+## Environment Variables
+
+- `GITHUB_TOKEN` - For higher GitHub Advisory API rate limits
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Test
+npm test
+
+# Lint
+npm run lint
+```
+
+## Security Threats Detected
+
+| Threat Type | Example |
+|------------|---------|
+| Blocklisted | event-stream, flatmap-stream |
+| Typosquatting | lodsh (looks like lodash) |
+| Vulnerabilities | CVE-2021-23337, GHSA-xxxx |
+| Obfuscation | eval(atob(...)) |
+| Malicious Code | process.env.API_KEY exfil |
+| Suspicious Scripts | postinstall: curl ... |
+| Dependency Issues | Deprecated packages, large trees |
+
+## License
+
+MIT

package/bin/npm-scan

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+/**
+ * npm-scan CLI entry point
+ * Pre and post-install security scanner for npm packages
+ */
+
+const { run } = require('../dist/cli/index');
+
+run(process.argv).catch(err => {
+  console.error('npm-scan error:', err.message);
+  process.exit(1);
+});

package/bin/npm-scan-wrap

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+/**
+ * npm-scan wrapper - Automatically scans before and after npm install
+ * Usage: npm-scan-wrap install <packages>
+ *        npm-scan-wrap install
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const SCANNER_PATH = path.join(__dirname, '../dist/cli/index.js');
+
+async function runScanner(args) {
+  return new Promise((resolve, reject) => {
+    const scanner = spawn('node', [SCANNER_PATH, ...args], {
+      stdio: 'inherit',
+      shell: true
+    });
+
+    scanner.on('close', (code) => {
+      resolve(code);
+    });
+    scanner.on('error', reject);
+  });
+}
+
+async function runNpm(args) {
+  return new Promise((resolve, reject) => {
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const install = spawn(npm, args, {
+      stdio: 'inherit',
+      shell: true,
+      env: { ...process.env, NPM_CONFIG_AUDIT: 'false' }
+    });
+
+    install.on('close', (code) => {
+      resolve(code);
+    });
+    install.on('error', reject);
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === 'install') {
+    console.log('\n🔒 npm-scan: Running automatic pre-install scan...\n');
+
+    // Run pre-install scan for all packages being installed
+    const packages = args.slice(1);
+
+    if (packages.length > 0) {
+      // Scan each package
+      for (const pkg of packages) {
+        console.log(`\n📦 Scanning: ${pkg}\n`);
+        await runScanner(['pre', 'install', pkg]);
+      }
+    } else {
+      // Scan package.json dependencies
+      const pkgJsonPath = path.join(process.cwd(), 'package.json');
+      if (fs.existsSync(pkgJsonPath)) {
+        try {
+          const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+          const allDeps = [
+            ...Object.keys(pkgJson.dependencies || {}),
+            ...Object.keys(pkgJson.devDependencies || {})
+          ];
+
+          console.log(`\n📦 Scanning ${allDeps.length} dependencies from package.json...\n`);
+
+          for (const pkg of allDeps) {
+            await runScanner(['pre', 'install', pkg]);
+          }
+        } catch (e) {
+          console.log('Could not read package.json, skipping dependency scan');
+        }
+      }
+    }
+
+    // Run npm install
+    console.log('\n📥 Running npm install...\n');
+    await runNpm(['install', ...args.slice(1)]);
+
+    // Run post-install scan
+    console.log('\n🔍 Running post-install scan...\n');
+    await runScanner(['post']);
+
+    console.log('\n✅ npm-scan: Complete!\n');
+  } else if (args[0] === 'run') {
+    // Just run npm run for scripts
+    await runNpm(args);
+  } else {
+    // Pass through other commands
+    await runNpm(args);
+  }
+}
+
+main().catch(console.error);

package/dist/cli/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI entry point
+ * Pre and post-install npm security scanner
+ */
+/**
+ * Main CLI runner
+ */
+export declare function run(argv: string[]): Promise<void>;
+/**
+ * Print help
+ */
+declare function printHelp(): void;
+export { run, printHelp };
+declare const _default: {
+    run: typeof run;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;GAEG;AACH,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBvD;AAiRD;;GAEG;AACH,iBAAS,SAAS,IAAI,IAAI,CAyBzB;AAED,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;;;;AAC1B,wBAAuB"}