npxconfuse 1.0.0

package/src/extractors/package-json.js

@@ -0,0 +1,162 @@
+import { FINDING_TYPE } from '../utils/constants.js';
+import logger from '../utils/logger.js';
+
+/**
+ * Extract package/binary name candidates from a package.json file.
+ * This is the PRIMARY extractor for npx confusion vulnerabilities.
+ *
+ * @param {string} content - Raw JSON content of the package.json
+ * @param {string} filepath - Path to the file (for reporting)
+ * @returns {Array<{name: string, type: string, source: string, context: string}>}
+ */
+export function extractFromPackageJson(content, filepath) {
+  const results = [];
+
+  let pkg;
+  try {
+    pkg = JSON.parse(content);
+  } catch (err) {
+    logger.debug(`Failed to parse ${filepath}: ${err.message}`);
+    return results;
+  }
+
+  const packageName = pkg.name || '';
+  const isScoped = packageName.startsWith('@');
+  const repoUrl = pkg.repository?.url || pkg.repository || '';
+
+  // ── 1. npx invocations in scripts (PRIMARY — the core npx confusion vector) ──
+  if (pkg.scripts && typeof pkg.scripts === 'object') {
+    for (const [scriptName, scriptValue] of Object.entries(pkg.scripts)) {
+      if (typeof scriptValue !== 'string') continue;
+
+      // Match npx invocations: npx [flags] <binary-name>
+      // Handles: npx foo, npx --yes foo, npx -y foo, npx --package @scope/pkg foo
+      const npxPattern = /\bnpx\s+((?:--?\w[\w-]*(?:[=\s]\S+)?\s+)*)(\S+)/g;
+      let match;
+
+      while ((match = npxPattern.exec(scriptValue)) !== null) {
+        const flagsPart = match[1].trim();
+        let binaryName = match[2];
+
+        // Skip if the binary name looks like a flag
+        if (binaryName.startsWith('-')) continue;
+
+        // If --package was specified, the actual binary is the next non-flag arg
+        // but the binary name itself is still what gets resolved by npx
+        // We want to flag the binaryName as it will be looked up on the registry
+        if (binaryName.startsWith('.') || binaryName.startsWith('/')) continue;
+
+        results.push({
+          name: binaryName,
+          type: FINDING_TYPE.NPX_CONFUSION,
+          source: filepath,
+          context: `scripts.${scriptName}: npx ${binaryName}`,
+        });
+      }
+    }
+  }
+
+  // ── 2. bin field — binary name ↔ package name mismatch ──
+  if (pkg.bin) {
+    const binEntries = typeof pkg.bin === 'string'
+      ? { [packageName.split('/').pop() || packageName]: pkg.bin }
+      : pkg.bin;
+
+    for (const binName of Object.keys(binEntries)) {
+      // If the package is scoped but the binary is unscoped, this is the
+      // core npx confusion vector: the binary name differs from the package name
+      if (isScoped && !binName.includes('/')) {
+        results.push({
+          name: binName,
+          type: FINDING_TYPE.BIN_MISMATCH,
+          source: filepath,
+          context: `bin field: "${binName}" (package: ${packageName})`,
+        });
+      }
+    }
+  }
+
+  // ── 3. Dependencies — potential dependency confusion targets ──
+  const depFields = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+
+  for (const field of depFields) {
+    if (!pkg[field] || typeof pkg[field] !== 'object') continue;
+
+    for (const depName of Object.keys(pkg[field])) {
+      const depValue = pkg[field][depName];
+
+      // Skip well-known public scopes
+      const publicScopes = new Set([
+        '@types', '@babel', '@rollup', '@eslint', '@typescript-eslint',
+        '@testing-library', '@jest', '@angular', '@vue', '@react-native',
+        '@emotion', '@chakra-ui', '@mui', '@headlessui', '@radix-ui',
+        '@tanstack', '@trpc', '@prisma', '@nestjs', '@nuxt', '@svelte',
+        '@storybook', '@aws-sdk', '@azure', '@google-cloud', '@octokit',
+        '@grpc', '@smithy', '@firebase', '@sentry', '@datadog',
+      ]);
+
+      // Flag scoped packages with potentially private scopes
+      if (depName.startsWith('@')) {
+        const scope = depName.split('/')[0];
+        if (publicScopes.has(scope)) continue;
+
+        // Heuristic: the scope looks internal/private
+        const looksPrivate = isPrivateScope(scope, repoUrl);
+
+        if (looksPrivate) {
+          results.push({
+            name: depName,
+            type: FINDING_TYPE.DEPENDENCY_CONFUSION,
+            source: filepath,
+            context: `${field}: ${depName} (scope "${scope}" looks private)`,
+          });
+        }
+      }
+
+      // Flag file:, link:, or workspace: protocol deps — these are local
+      // and the unscoped name might be claimable
+      if (typeof depValue === 'string' &&
+          (depValue.startsWith('file:') || depValue.startsWith('link:') || depValue.startsWith('workspace:'))) {
+        results.push({
+          name: depName,
+          type: FINDING_TYPE.DEPENDENCY_CONFUSION,
+          source: filepath,
+          context: `${field}: ${depName} (local reference: ${depValue})`,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Heuristic to determine if an npm scope looks private/internal.
+ */
+function isPrivateScope(scope, repoUrl) {
+  // Enterprise GitHub patterns
+  if (typeof repoUrl === 'string') {
+    const enterprisePatterns = [
+      /github\.[a-z]+\.(com|net|org|io)/i,     // github.company.com
+      /gitlab\.[a-z]+\.(com|net|org|io)/i,      // gitlab.company.com
+      /bitbucket\.[a-z]+\.(com|net|org|io)/i,   // bitbucket.company.com
+      /\.internal\b/i,                            // *.internal
+      /\.corp\b/i,                                // *.corp
+      /\.local\b/i,                               // *.local
+    ];
+    if (enterprisePatterns.some(p => p.test(repoUrl))) return true;
+  }
+
+  // Common private scope naming patterns
+  const privatePatterns = [
+    /^@[a-z]+-internal$/i,
+    /^@[a-z]+-private$/i,
+    /^@[a-z]+-corp$/i,
+    /^@internal-/i,
+    /^@private-/i,
+  ];
+
+  return privatePatterns.some(p => p.test(scope));
+}
+
+export default extractFromPackageJson;

package/src/formatters/csv.js

@@ -0,0 +1,39 @@
+/**
+ * Format results as CSV for spreadsheet analysis and reporting.
+ *
+ * @param {{findings: object[], summary: object}} results
+ * @returns {string}
+ */
+export function formatCsv(results) {
+  const headers = ['severity', 'name', 'type', 'registry', 'status', 'owner', 'details', 'sources'];
+  const lines = [headers.join(',')];
+
+  for (const f of results.findings) {
+    const row = [
+      escapeField(f.severity),
+      escapeField(f.name),
+      escapeField(f.type),
+      escapeField(f.registry),
+      escapeField(f.status),
+      escapeField(f.owner || ''),
+      escapeField(f.details || ''),
+      escapeField((f.sources || []).join('; ')),
+    ];
+    lines.push(row.join(','));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Escape a CSV field, quoting if it contains commas, quotes, or newlines.
+ */
+function escapeField(value) {
+  const str = String(value ?? '');
+  if (str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+export default formatCsv;

package/src/formatters/json.js

@@ -0,0 +1,11 @@
+/**
+ * Format results as JSON for piping and automation.
+ *
+ * @param {{findings: object[], summary: object}} results
+ * @returns {string}
+ */
+export function formatJson(results) {
+  return JSON.stringify(results, null, 2);
+}
+
+export default formatJson;

package/src/formatters/table.js

@@ -0,0 +1,144 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+
+/**
+ * Color a severity label.
+ */
+function colorSeverity(severity) {
+  switch (severity) {
+    case "CRITICAL":
+      return chalk.bgRed.white.bold(` ${severity} `);
+    case "HIGH":
+      return chalk.red.bold(severity);
+    case "MEDIUM":
+      return chalk.yellow(severity);
+    case "LOW":
+      return chalk.blue(severity);
+    case "INFO":
+      return chalk.gray(severity);
+    default:
+      return severity;
+  }
+}
+
+/**
+ * Color a status label.
+ */
+function colorStatus(status) {
+  switch (status) {
+    case "unclaimed":
+      return chalk.red.bold("⬤ UNCLAIMED");
+    case "claimed":
+      return chalk.yellow("● claimed");
+    case "private":
+      return chalk.gray("○ private");
+    case "error":
+      return chalk.gray("✖ error");
+    default:
+      return status;
+  }
+}
+
+/**
+ * Format finding type for display.
+ */
+function formatType(type) {
+  switch (type) {
+    case "npx-confusion":
+      return chalk.magenta("npx-confusion");
+    case "bin-mismatch":
+      return chalk.magenta("bin-mismatch");
+    case "dependency-confusion":
+      return chalk.cyan("dep-confusion");
+    case "name-clash":
+      return chalk.yellow("name-clash");
+    default:
+      return type;
+  }
+}
+
+/**
+ * Truncate a string to maxLen characters.
+ */
+function truncate(str, maxLen = 40) {
+  if (!str) return "";
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 1) + "…";
+}
+
+/**
+ * Format results as a rich CLI table.
+ *
+ * @param {{findings: object[], summary: object}} results
+ * @returns {string}
+ */
+export function formatTable(results) {
+  const { findings, summary } = results;
+  const lines = [];
+
+  if (findings.length === 0) {
+    lines.push("");
+    lines.push(chalk.green.bold("  ✔ No vulnerabilities found!"));
+    lines.push("");
+    return lines.join("\n");
+  }
+
+  // Build table
+  const table = new Table({
+    head: [
+      chalk.bold("Severity"),
+      chalk.bold("Package"),
+      chalk.bold("Type"),
+      chalk.bold("Registry"),
+      chalk.bold("Status"),
+      chalk.bold("Details"),
+      chalk.bold("Source"),
+    ],
+    colWidths: [12, 30, 18, 10, 16, 35, 40],
+    wordWrap: true,
+    style: {
+      head: [],
+      border: ["gray"],
+    },
+  });
+
+  for (const f of findings) {
+    const details =
+      f.status === "unclaimed"
+        ? chalk.red.bold("CLAIMABLE — register this name!")
+        : f.details || f.owner || "";
+
+    table.push([
+      colorSeverity(f.severity),
+      chalk.white.bold(f.name),
+      formatType(f.type),
+      f.registry,
+      colorStatus(f.status),
+      truncate(details, 33),
+      truncate(f.sources?.join(", ") || "", 38),
+    ]);
+  }
+
+  lines.push("");
+  lines.push(table.toString());
+  lines.push("");
+
+  // Summary line
+  const parts = [];
+  if (summary.critical > 0)
+    parts.push(chalk.red.bold(`${summary.critical} critical`));
+  if (summary.high > 0) parts.push(chalk.red(`${summary.high} high`));
+  if (summary.medium > 0) parts.push(chalk.yellow(`${summary.medium} medium`));
+  if (summary.low > 0) parts.push(chalk.blue(`${summary.low} low`));
+  if (summary.info > 0) parts.push(chalk.gray(`${summary.info} info`));
+
+  lines.push(
+    `  Found ${chalk.bold(summary.total)} issue(s): ${parts.join(", ")}`,
+  );
+  lines.push(`  Registry checked: npm`);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export default formatTable;

package/src/registries/npm.js

@@ -0,0 +1,185 @@
+/**
+ * NPM Registry Checker
+ *
+ * Queries the public npm registry to determine whether a package name is
+ * unclaimed, claimed by someone else, or private. Used for detecting
+ * npx-confusion and dependency-confusion attack surface.
+ */
+
+import pLimit from 'p-limit';
+import { httpGet } from '../utils/http.js';
+import logger from '../utils/logger.js';
+import { SEVERITY, REGISTRIES, DEFAULT_CONCURRENCY } from '../utils/constants.js';
+
+/**
+ * Encode a package name for safe use in a registry URL.
+ * Scoped packages (e.g. @scope/pkg) need special encoding because
+ * the npm registry expects `@` → `%40` and `/` → `%2f` in the URL path.
+ *
+ * @param {string} name — raw package name
+ * @returns {string} — URL-safe encoded name
+ */
+function encodePackageName(name) {
+  if (name.startsWith('@')) {
+    // Scoped package: @scope/name → %40scope%2fname
+    return name.replace('@', '%40').replace('/', '%2f');
+  }
+  return encodeURIComponent(name);
+}
+
+/**
+ * Fetch the weekly download count for a package from the npm downloads API.
+ * Returns 0 on any failure so callers always get a numeric value.
+ *
+ * @param {string} name — package name (unencoded)
+ * @returns {Promise<number>}
+ */
+async function fetchWeeklyDownloads(name) {
+  try {
+    const url = `https://api.npmjs.org/downloads/point/last-week/${encodePackageName(name)}`;
+    const { status, data } = await httpGet(url, { retries: 1, timeout: 8000 });
+
+    if (status === 200 && data && typeof data.downloads === 'number') {
+      return data.downloads;
+    }
+    return 0;
+  } catch (err) {
+    logger.debug(`Failed to fetch weekly downloads for "${name}": ${err.message}`);
+    return 0;
+  }
+}
+
+/**
+ * Check a single package name against the npm registry.
+ *
+ * @param {string} packageName — the npm package name to check
+ * @returns {Promise<object>} — result object describing the package status
+ */
+export async function checkNpm(packageName) {
+  const name = packageName.trim();
+  const registryUrl = `${REGISTRIES.npm.registry}/${encodePackageName(name)}`;
+
+  logger.debug(`Checking npm registry for "${name}"`);
+
+  let status, data;
+  try {
+    const response = await httpGet(registryUrl);
+    status = response.status;
+    data = response.data;
+  } catch (err) {
+    logger.debug(`npm registry request failed for "${name}": ${err.message}`);
+    return {
+      name,
+      registry: 'npm',
+      status: 'error',
+      severity: SEVERITY.INFO,
+      details: `Could not reach registry: ${err.message}`,
+    };
+  }
+
+  // ── 404 — Package does not exist on npm ──────────────────────────────
+  if (status === 404) {
+    return {
+      name,
+      registry: 'npm',
+      status: 'unclaimed',
+      severity: SEVERITY.CRITICAL,
+      details: 'Package name is not registered on npmjs.com',
+    };
+  }
+
+  // ── 401 / 403 — Scoped package exists but is private ─────────────────
+  if (status === 401 || status === 403) {
+    return {
+      name,
+      registry: 'npm',
+      status: 'private',
+      severity: SEVERITY.INFO,
+      details: 'Scoped package exists but is private',
+    };
+  }
+
+  // ── 200 — Package exists and is publicly readable ────────────────────
+  if (status === 200 && data) {
+    // Extract owner: prefer first maintainer, fall back to author
+    const owner =
+      (Array.isArray(data.maintainers) && data.maintainers.length > 0
+        ? data.maintainers[0].name
+        : null) ||
+      (data.author && typeof data.author === 'object'
+        ? data.author.name
+        : data.author) ||
+      'unknown';
+
+    // Extract description
+    const description = data.description || '';
+
+    // Extract timestamps from the `time` map
+    const timeMap = data.time || {};
+    const lastPublish = timeMap.modified || null;
+    const createdAt = timeMap.created || null;
+
+    // Fetch weekly downloads in parallel-safe manner
+    const weeklyDownloads = await fetchWeeklyDownloads(name);
+
+    return {
+      name,
+      registry: 'npm',
+      status: 'claimed',
+      owner,
+      description,
+      lastPublish,
+      createdAt,
+      weeklyDownloads,
+      severity: SEVERITY.MEDIUM,
+    };
+  }
+
+  // ── Catch-all — unexpected status or unreachable ─────────────────────
+  return {
+    name,
+    registry: 'npm',
+    status: 'error',
+    severity: SEVERITY.INFO,
+    details: `Could not reach registry (HTTP ${status || 0})`,
+  };
+}
+
+/**
+ * Check multiple npm package names in parallel with bounded concurrency.
+ *
+ * @param {string[]} names — array of package names to check
+ * @param {number} [concurrency=20] — maximum concurrent requests
+ * @returns {Promise<object[]>} — array of result objects from checkNpm()
+ */
+export async function checkNpmBatch(names, concurrency = DEFAULT_CONCURRENCY) {
+  if (!names || names.length === 0) {
+    return [];
+  }
+
+  const limit = pLimit(concurrency);
+  const total = names.length;
+  let completed = 0;
+
+  logger.info(`Checking ${total} package(s) against npm registry (concurrency: ${concurrency})`);
+
+  const tasks = names.map(name =>
+    limit(async () => {
+      const result = await checkNpm(name);
+      completed++;
+
+      // Log progress at regular intervals to avoid flooding the console
+      if (completed % 50 === 0 || completed === total) {
+        logger.debug(`npm progress: ${completed}/${total}`);
+      }
+
+      return result;
+    }),
+  );
+
+  const results = await Promise.all(tasks);
+
+  logger.success(`Completed npm registry checks: ${total} package(s)`);
+
+  return results;
+}

package/src/sources/github.js

@@ -0,0 +1,142 @@
+import { Octokit } from "@octokit/rest";
+import pLimit from "p-limit";
+import logger from "../utils/logger.js";
+import { GITHUB_DEFAULTS } from "../utils/constants.js";
+
+/**
+ * Scan a GitHub organization for package.json manifests.
+ *
+ * @param {string} org - GitHub organization name
+ * @param {object} options
+ * @param {number} options.maxRepos - Max repos to scan (default 1000)
+ * @param {number} options.concurrency - Parallel repo scans (default 5)
+ * @param {string} options.githubEnterprise - Base URL for GHE
+ * @returns {Promise<Array<{filepath: string, content: string, type: string}>>}
+ */
+export async function scanGitHub(org, options = {}) {
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) {
+    throw new Error(
+      "GITHUB_TOKEN environment variable is required for GitHub scanning.\n" +
+        'Create one at https://github.com/settings/tokens with "repo" or "public_repo" scope.\n' +
+        "Usage: GITHUB_TOKEN=ghp_xxx npxconfuse github <org>",
+    );
+  }
+
+  const octokitOpts = { auth: token };
+  if (options.githubEnterprise) {
+    octokitOpts.baseUrl = `${options.githubEnterprise}/api/v3`;
+  }
+
+  const octokit = new Octokit(octokitOpts);
+  const maxRepos = options.maxRepos || GITHUB_DEFAULTS.maxRepos;
+  const concurrency = options.concurrency || 5;
+  const limit = pLimit(concurrency);
+
+  logger.info(`Scanning GitHub organization: ${org}`);
+
+  // ── 1. List all repos ──
+  const repos = [];
+  let page = 1;
+
+  while (repos.length < maxRepos) {
+    try {
+      const { data } = await octokit.repos.listForOrg({
+        org,
+        per_page: GITHUB_DEFAULTS.perPage,
+        page,
+        sort: "updated",
+      });
+
+      if (data.length === 0) break;
+      repos.push(...data);
+      page++;
+
+      if (data.length < GITHUB_DEFAULTS.perPage) break;
+    } catch (err) {
+      if (
+        err.status === 403 &&
+        err.response?.headers?.["x-ratelimit-remaining"] === "0"
+      ) {
+        const resetTime =
+          parseInt(err.response.headers["x-ratelimit-reset"], 10) * 1000;
+        const waitMs = Math.max(resetTime - Date.now(), 1000);
+        logger.warn(
+          `GitHub rate limit hit. Waiting ${Math.ceil(waitMs / 1000)}s...`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+        continue;
+      }
+      throw new Error(`Failed to list repos for "${org}": ${err.message}`);
+    }
+  }
+
+  logger.info(`Found ${repos.length} repositories in ${org}`);
+
+  // ── 2. Search each repo for relevant files ──
+  const results = [];
+  let processed = 0;
+
+  const tasks = repos.slice(0, maxRepos).map((repo) =>
+    limit(async () => {
+      try {
+        const repoFiles = await scanRepo(octokit, org, repo.name);
+        results.push(...repoFiles);
+      } catch (err) {
+        logger.debug(`Error scanning ${repo.name}: ${err.message}`);
+      }
+
+      processed++;
+      if (processed % 10 === 0 || processed === repos.length) {
+        logger.info(
+          `Progress: ${processed}/${repos.length} repos scanned (${results.length} files found)`,
+        );
+      }
+    }),
+  );
+
+  await Promise.all(tasks);
+  logger.success(
+    `GitHub scan complete: ${results.length} files from ${repos.length} repos`,
+  );
+
+  return results;
+}
+
+/**
+ * Scan a single repo for package.json
+ */
+async function scanRepo(octokit, org, repoName) {
+  const results = [];
+  const filesToFind = [{ path: "package.json", type: "package-json" }];
+
+  for (const { path, type } of filesToFind) {
+    try {
+      const { data } = await octokit.repos.getContent({
+        owner: org,
+        repo: repoName,
+        path,
+      });
+
+      if (data.type === "file" && data.content) {
+        const content = Buffer.from(data.content, "base64").toString("utf-8");
+        results.push({
+          filepath: `${org}/${repoName}/${path}`,
+          content,
+          type,
+        });
+      }
+    } catch (err) {
+      // 404 is expected — file doesn't exist in this repo
+      if (err.status !== 404) {
+        logger.debug(
+          `Error fetching ${org}/${repoName}/${path}: ${err.message}`,
+        );
+      }
+    }
+  }
+
+  return results;
+}
+
+export default scanGitHub;