npxconfuse 1.0.0

package/bin/cli.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+/**
+ * npxconfuse — npx confusion vulnerability scanner
+ *
+ * Scans local codebases, GitHub organizations, and web domains for
+ * package names that are unclaimed on the npm registry, enabling
+ * npx confusion and dependency confusion attacks.
+ *
+ * Based on: https://www.landh.tech/blog/20260521-npx-used-confusion-and-its-super-effective/
+ */
+
+import { Command } from "commander";
+import { readFile } from "node:fs/promises";
+import { writeFile } from "node:fs/promises";
+import ora from "ora";
+
+import logger, { setVerbose } from "../src/utils/logger.js";
+
+// Sources
+import { scanLocal } from "../src/sources/local.js";
+import { scanGitHub } from "../src/sources/github.js";
+import { scanWeb } from "../src/sources/web.js";
+
+// Extractors
+import { extractFromPackageJson } from "../src/extractors/package-json.js";
+import { extractFromJsBundle } from "../src/extractors/js-bundle.js";
+
+// Analysis
+import { analyze } from "../src/analyzer.js";
+
+// Formatters
+import { formatTable } from "../src/formatters/table.js";
+import { formatJson } from "../src/formatters/json.js";
+import { formatCsv } from "../src/formatters/csv.js";
+
+// ═══════════════════════════════════════════════════════════════════════
+// CLI Setup
+// ═══════════════════════════════════════════════════════════════════════
+
+const program = new Command();
+
+program
+  .name("npxconfuse")
+  .description(
+    "npx confusion vulnerability scanner — find unclaimed npm package names",
+  )
+  .version("1.0.0")
+  .option("-v, --verbose", "Enable verbose debug output")
+  .option("-o, --output <format>", "Output format: table, json, csv", "table")
+  .option("-c, --concurrency <number>", "Max parallel registry requests", "20")
+  .option("--timeout <ms>", "HTTP timeout in milliseconds", "10000")
+  .option("--save <filepath>", "Save results to a file")
+  .hook("preAction", (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.verbose) setVerbose(true);
+  });
+
+// ─── scan: Local filesystem scanning ─────────────────────────────────
+program
+  .command("scan <path>")
+  .description(
+    "Scan a local directory or file for npx confusion vulnerabilities",
+  )
+  .option("--deep", "Also scan JS bundles (slower, more thorough)")
+  .action(async (targetPath, cmdOpts) => {
+    const opts = { ...program.opts(), ...cmdOpts };
+    logger.banner();
+    logger.section("Phase 1: Discovery");
+
+    const spinner = ora("Scanning local files...").start();
+    try {
+      const files = await scanLocal(targetPath, { deep: opts.deep });
+      spinner.succeed(`Found ${files.length} files to analyze`);
+
+      const extracted = extractAll(files);
+      await runAnalysis(extracted, opts);
+    } catch (err) {
+      spinner.fail(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── github: GitHub organization scanning ────────────────────────────
+program
+  .command("github <org>")
+  .description("Scan a GitHub organization for npx confusion vulnerabilities")
+  .option("--max-repos <number>", "Maximum repos to scan", "1000")
+  .option("--github-enterprise <url>", "GitHub Enterprise base URL")
+  .action(async (org, cmdOpts) => {
+    const opts = { ...program.opts(), ...cmdOpts };
+    logger.banner();
+    logger.section("Phase 1: GitHub Discovery");
+
+    const spinner = ora(`Scanning GitHub org: ${org}...`).start();
+    try {
+      const files = await scanGitHub(org, {
+        maxRepos: parseInt(opts.maxRepos, 10),
+        githubEnterprise: opts.githubEnterprise,
+      });
+      spinner.succeed(`Found ${files.length} files from GitHub`);
+
+      const extracted = extractAll(files);
+      await runAnalysis(extracted, opts);
+    } catch (err) {
+      spinner.fail(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── web: Web domain scanning ────────────────────────────────────────
+program
+  .command("web <domains-file>")
+  .description("Scan web domains for exposed package.json and JS bundles")
+  .action(async (domainsFile, cmdOpts) => {
+    const opts = { ...program.opts(), ...cmdOpts };
+    logger.banner();
+    logger.section("Phase 1: Web Discovery");
+
+    const spinner = ora("Scanning web domains...").start();
+    try {
+      const files = await scanWeb(domainsFile, {
+        concurrency: parseInt(opts.concurrency, 10),
+        timeout: parseInt(opts.timeout, 10),
+      });
+      spinner.succeed(`Found ${files.length} files from web`);
+
+      const extracted = extractAll(files);
+      await runAnalysis(extracted, opts);
+    } catch (err) {
+      spinner.fail(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── check: Direct package name checking ─────────────────────────────
+program
+  .command("check <names-file>")
+  .description("Check a list of package names against the npm registry")
+  .action(async (namesFile, cmdOpts) => {
+    const opts = { ...program.opts(), ...cmdOpts };
+    logger.banner();
+    logger.section("Phase 1: Loading Package Names");
+
+    try {
+      const content = await readFile(namesFile, "utf-8");
+      const names = content
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith("#"));
+
+      logger.info(`Loaded ${names.length} package names from ${namesFile}`);
+
+      // Convert to extraction format
+      const extracted = names.map((name) => ({
+        name,
+        type: name.startsWith("@") ? "dependency-confusion" : "npx-confusion",
+        source: namesFile,
+        context: "direct check",
+      }));
+
+      await runAnalysis(extracted, opts);
+    } catch (err) {
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// ═══════════════════════════════════════════════════════════════════════
+// Shared Pipeline
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Run all extractors on discovered files.
+ */
+function extractAll(files) {
+  logger.section("Phase 2: Extraction");
+  const all = [];
+
+  for (const file of files) {
+    try {
+      let items = [];
+
+      switch (file.type) {
+        case "package-json":
+          items = extractFromPackageJson(file.content, file.filepath);
+          break;
+        case "js-bundle":
+          items = extractFromJsBundle(file.content, file.filepath);
+          break;
+      }
+
+      if (items.length > 0) {
+        logger.debug(
+          `Extracted ${items.length} candidates from ${file.filepath}`,
+        );
+        all.push(...items);
+      }
+    } catch (err) {
+      logger.warn(`Extraction error for ${file.filepath}: ${err.message}`);
+    }
+  }
+
+  logger.info(`Extracted ${all.length} total candidates`);
+  return all;
+}
+
+/**
+ * Run analysis and output results.
+ */
+async function runAnalysis(extracted, opts) {
+  if (extracted.length === 0) {
+    logger.info("No package name candidates found. Nothing to check.");
+    return;
+  }
+
+  logger.section("Phase 3: Registry Analysis");
+
+  const concurrency = parseInt(opts.concurrency, 10);
+
+  const spinner = ora("Checking npm registry...").start();
+  const results = await analyze(extracted, { concurrency });
+  spinner.stop();
+
+  // ─── Output ──────────────────────────────────────────────────────────
+  logger.section("Results");
+
+  let output;
+  switch (opts.output) {
+    case "json":
+      output = formatJson(results);
+      console.log(output);
+      break;
+    case "csv":
+      output = formatCsv(results);
+      console.log(output);
+      break;
+    case "table":
+    default:
+      output = formatTable(results);
+      console.log(output);
+      break;
+  }
+
+  // ─── Save to file if requested ───────────────────────────────────────
+  if (opts.save) {
+    const saveFormat = opts.save.endsWith(".csv")
+      ? "csv"
+      : opts.save.endsWith(".json")
+        ? "json"
+        : opts.output;
+
+    let saveContent;
+    switch (saveFormat) {
+      case "csv":
+        saveContent = formatCsv(results);
+        break;
+      case "json":
+        saveContent = formatJson(results);
+        break;
+      default:
+        saveContent = formatJson(results);
+        break;
+    }
+
+    await writeFile(opts.save, saveContent, "utf-8");
+    logger.success(`Results saved to ${opts.save}`);
+  }
+
+  // Exit with error code if critical findings
+  if (results.summary.critical > 0) {
+    process.exit(2);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Run
+// ═══════════════════════════════════════════════════════════════════════
+
+program.parse();

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "npxconfuse",
+  "version": "1.0.0",
+  "description": "Detect npx confusion vulnerabilities — find unclaimed npm package names in your codebase, GitHub orgs, and web domains before attackers do.",
+  "type": "module",
+  "bin": {
+    "npxconfuse": "./bin/cli.js"
+  },
+  "main": "./src/analyzer.js",
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "echo \"No tests yet — contributions welcome!\" && exit 0"
+  },
+  "keywords": [
+    "npx-confusion",
+    "dependency-confusion",
+    "supply-chain",
+    "security",
+    "vulnerability-scanner",
+    "npm",
+    "bug-bounty",
+    "defcon",
+    "sast"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cybershaykh/npxconfuse"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@octokit/rest": "^21.1.1",
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.1.0",
+    "glob": "^11.0.2",
+    "ora": "^8.2.0",
+    "p-limit": "^6.2.0"
+  }
+}

package/src/analyzer.js

@@ -0,0 +1,167 @@
+import { checkNpmBatch } from "./registries/npm.js";
+import {
+  SEVERITY,
+  FINDING_TYPE,
+  DEFAULT_CONCURRENCY,
+} from "./utils/constants.js";
+import logger from "./utils/logger.js";
+
+/**
+ * Severity sort order (most severe first).
+ */
+const SEVERITY_ORDER = {
+  [SEVERITY.CRITICAL]: 0,
+  [SEVERITY.HIGH]: 1,
+  [SEVERITY.MEDIUM]: 2,
+  [SEVERITY.LOW]: 3,
+  [SEVERITY.INFO]: 4,
+};
+
+/**
+ * Analyze extracted items by checking them against the npm registry.
+ *
+ * @param {Array<{name: string, type: string, source: string, context: string}>} extractedItems
+ * @param {object} options
+ * @param {number} options.concurrency - Max parallel requests
+ * @returns {Promise<{findings: object[], summary: object}>}
+ */
+export async function analyze(extractedItems, options = {}) {
+  const concurrency = options.concurrency || DEFAULT_CONCURRENCY;
+
+  if (extractedItems.length === 0) {
+    return {
+      findings: [],
+      summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0, info: 0 },
+    };
+  }
+
+  // ── 1. Deduplicate: group by name, merge sources/contexts ──
+  const grouped = new Map();
+
+  for (const item of extractedItems) {
+    const key = item.name;
+    if (grouped.has(key)) {
+      const existing = grouped.get(key);
+      existing.sources.add(item.source);
+      existing.contexts.add(item.context);
+      // Keep the most severe type
+      if (typeSeverity(item.type) < typeSeverity(existing.type)) {
+        existing.type = item.type;
+      }
+    } else {
+      grouped.set(key, {
+        name: item.name,
+        type: item.type,
+        sources: new Set([item.source]),
+        contexts: new Set([item.context]),
+      });
+    }
+  }
+
+  logger.info(
+    `Deduplicated to ${grouped.size} unique names from ${extractedItems.length} extractions`,
+  );
+
+  // ── 2. Collect all names for npm check ──
+  const names = [...grouped.keys()];
+
+  // ── 3. Batch check npm registry ──
+  logger.section("Registry Check");
+
+  const npmResults =
+    names.length > 0 ? await checkNpmBatch(names, concurrency) : [];
+
+  // Index results by name
+  const registryResults = new Map();
+  for (const r of npmResults) {
+    registryResults.set(r.name, r);
+  }
+
+  // ── 4. Merge results and assign final severity ──
+  const findings = [];
+
+  for (const [name, item] of grouped) {
+    const regResult = registryResults.get(name);
+    if (!regResult) continue;
+
+    const finding = {
+      name,
+      type: item.type,
+      registry: "npm",
+      status: regResult.status,
+      severity: computeSeverity(item.type, regResult.status),
+      owner: regResult.owner || null,
+      description: regResult.description || null,
+      details: regResult.details || null,
+      weeklyDownloads: regResult.weeklyDownloads ?? null,
+      lastPublish: regResult.lastPublish || null,
+      createdAt: regResult.createdAt || null,
+      sources: [...item.sources],
+      contexts: [...item.contexts],
+    };
+
+    findings.push(finding);
+  }
+
+  // ── 5. Sort by severity ──
+  findings.sort((a, b) => {
+    const severityDiff =
+      (SEVERITY_ORDER[a.severity] ?? 99) - (SEVERITY_ORDER[b.severity] ?? 99);
+    if (severityDiff !== 0) return severityDiff;
+    return a.name.localeCompare(b.name);
+  });
+
+  // ── 6. Build summary ──
+  const summary = {
+    total: findings.length,
+    critical: findings.filter((f) => f.severity === SEVERITY.CRITICAL).length,
+    high: findings.filter((f) => f.severity === SEVERITY.HIGH).length,
+    medium: findings.filter((f) => f.severity === SEVERITY.MEDIUM).length,
+    low: findings.filter((f) => f.severity === SEVERITY.LOW).length,
+    info: findings.filter((f) => f.severity === SEVERITY.INFO).length,
+  };
+
+  return { findings, summary };
+}
+
+/**
+ * Compute the final severity based on finding type and registry status.
+ */
+function computeSeverity(type, status) {
+  if (status === "unclaimed") {
+    if (type === FINDING_TYPE.NPX_CONFUSION) return SEVERITY.CRITICAL;
+    if (type === FINDING_TYPE.BIN_MISMATCH) return SEVERITY.CRITICAL;
+    if (type === FINDING_TYPE.DEPENDENCY_CONFUSION) return SEVERITY.HIGH;
+    return SEVERITY.HIGH;
+  }
+
+  if (status === "claimed") {
+    return SEVERITY.MEDIUM; // potential name clash
+  }
+
+  if (status === "private") {
+    return SEVERITY.INFO;
+  }
+
+  return SEVERITY.INFO; // error or unknown
+}
+
+/**
+ * Get a numeric severity for finding type (lower = more severe).
+ */
+function typeSeverity(type) {
+  switch (type) {
+    case FINDING_TYPE.NPX_CONFUSION:
+      return 0;
+    case FINDING_TYPE.BIN_MISMATCH:
+      return 1;
+    case FINDING_TYPE.DEPENDENCY_CONFUSION:
+      return 2;
+    case FINDING_TYPE.NAME_CLASH:
+      return 3;
+    default:
+      return 4;
+  }
+}
+
+export default analyze;

package/src/extractors/js-bundle.js

@@ -0,0 +1,147 @@
+import { NODE_BUILTINS, FINDING_TYPE } from '../utils/constants.js';
+import { extractFromPackageJson } from './package-json.js';
+import logger from '../utils/logger.js';
+
+/**
+ * Extract package name candidates from compiled JS bundles
+ * (webpack, Vite, Rollup, esbuild output).
+ *
+ * @param {string} content - Raw JS bundle content
+ * @param {string} filepath - Path/URL to the bundle
+ * @returns {Array<{name: string, type: string, source: string, context: string}>}
+ */
+export function extractFromJsBundle(content, filepath) {
+  const results = [];
+  const seen = new Set();
+
+  // ── 1. Try to find embedded package.json ──
+  const pkgJsonPattern = /\{[^{}]*"name"\s*:\s*"(@?[a-zA-Z0-9][\w./-]*)"/g;
+  let pkgMatch;
+  while ((pkgMatch = pkgJsonPattern.exec(content)) !== null) {
+    // Try to extract a valid JSON object starting from this position
+    const start = content.lastIndexOf('{', pkgMatch.index);
+    if (start === -1) continue;
+
+    // Find the matching closing brace (simple depth tracking)
+    let depth = 0;
+    let end = -1;
+    for (let i = start; i < Math.min(content.length, start + 5000); i++) {
+      if (content[i] === '{') depth++;
+      else if (content[i] === '}') {
+        depth--;
+        if (depth === 0) { end = i + 1; break; }
+      }
+    }
+
+    if (end > start) {
+      const candidate = content.slice(start, end);
+      try {
+        const parsed = JSON.parse(candidate);
+        if (parsed.name && (parsed.scripts || parsed.bin || parsed.dependencies)) {
+          logger.debug(`Found embedded package.json in bundle: ${parsed.name}`);
+          const embedded = extractFromPackageJson(candidate, `${filepath} (embedded: ${parsed.name})`);
+          for (const item of embedded) {
+            if (!seen.has(item.name)) {
+              seen.add(item.name);
+              results.push(item);
+            }
+          }
+        }
+      } catch {
+        // Not valid JSON, skip
+      }
+    }
+  }
+
+  // ── 2. require() calls ──
+  const requirePattern = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+  let match;
+  while ((match = requirePattern.exec(content)) !== null) {
+    addCandidate(match[1], seen, results, filepath, 'require()');
+  }
+
+  // ── 3. import ... from "pkg" ──
+  const importFromPattern = /from\s+['"]([^'"]+)['"]/g;
+  while ((match = importFromPattern.exec(content)) !== null) {
+    addCandidate(match[1], seen, results, filepath, 'import from');
+  }
+
+  // ── 4. dynamic import() ──
+  const dynamicImportPattern = /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+  while ((match = dynamicImportPattern.exec(content)) !== null) {
+    addCandidate(match[1], seen, results, filepath, 'dynamic import()');
+  }
+
+  // ── 5. __webpack_require__() ──
+  const webpackPattern = /__webpack_require__\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+  while ((match = webpackPattern.exec(content)) !== null) {
+    addCandidate(match[1], seen, results, filepath, '__webpack_require__');
+  }
+
+  return results;
+}
+
+/**
+ * Validate and add a package name candidate.
+ */
+function addCandidate(raw, seen, results, filepath, context) {
+  const name = raw.trim();
+
+  // Skip if already seen
+  if (seen.has(name)) return;
+
+  // Skip relative paths
+  if (name.startsWith('./') || name.startsWith('../') || name.startsWith('/')) return;
+
+  // Skip URLs
+  if (name.startsWith('http://') || name.startsWith('https://') || name.startsWith('data:')) return;
+
+  // Skip Node.js built-ins
+  if (NODE_BUILTINS.has(name)) return;
+  // Also check without node: prefix
+  if (name.startsWith('node:') && NODE_BUILTINS.has(name.slice(5))) return;
+
+  // Skip things that look like file paths (contain multiple /)
+  // but allow scoped packages like @scope/name
+  if (!name.startsWith('@') && (name.split('/').length > 2)) return;
+  if (name.startsWith('@') && (name.split('/').length > 2)) return;
+
+  // Skip obviously invalid names
+  if (name.length === 0 || name.length > 214) return;
+  if (/\s/.test(name)) return;
+
+  // Validate npm package name format:
+  // - Must start with a letter, digit, or @
+  // - Can only contain lowercase alphanum, hyphens, dots, underscores, tildes
+  // - Must be at least 2 chars for unscoped, 4 chars for scoped (@x/y)
+  // - No uppercase (npm lowercases everything)
+  // - No special chars like +, =, !, etc.
+  const validNpmName = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+  if (!validNpmName.test(name)) return;
+
+  // Skip single-character names (almost always minified variable refs)
+  if (!name.startsWith('@') && name.length < 2) return;
+
+  // For scoped packages, extract just the scope/name part
+  let packageName = name;
+  if (name.startsWith('@')) {
+    // @scope/name or @scope/name/subpath
+    const parts = name.split('/');
+    packageName = `${parts[0]}/${parts[1]}`;
+  } else {
+    // name or name/subpath → just the package name
+    packageName = name.split('/')[0];
+  }
+
+  seen.add(name);
+  seen.add(packageName);
+
+  results.push({
+    name: packageName,
+    type: FINDING_TYPE.DEPENDENCY_CONFUSION,
+    source: filepath,
+    context: `JS bundle ${context}`,
+  });
+}
+
+export default extractFromJsBundle;