install-guard 1.0.1 → 1.1.2

package/src/checks/deprecation.js

@@ -0,0 +1,24 @@
+/**
+ * Checks for deprecation.
+ */
+export function checkDeprecation(ctx) {
+  const findings = [];
+
+  if (ctx.deprecated) {
+    findings.push({
+      severity: "high",
+      message: typeof ctx.deprecated === "string"
+        ? `Deprecated: ${ctx.deprecated}`
+        : "Package is deprecated",
+      score: 3,
+    });
+  } else {
+    findings.push({
+      severity: "info",
+      message: "Not deprecated",
+      score: 0,
+    });
+  }
+
+  return { id: "deprecation", findings };
+}

package/src/checks/githubVerify.js

@@ -0,0 +1,67 @@
+import { checkGitHubTag } from "../utils/github.js";
+
+/**
+ * Verifies the published version against GitHub releases/tags.
+ */
+export async function checkGithubVerify(ctx) {
+  const findings = [];
+
+  if (!ctx.repository) {
+    findings.push({
+      severity: "high",
+      message: "No repository URL in package metadata",
+      score: 4,
+    });
+    return { id: "github-verify", findings };
+  }
+
+  if (!ctx.repository.includes("github.com")) {
+    findings.push({
+      severity: "medium",
+      message: "Repository is not on GitHub — cannot verify tags",
+      score: 1,
+    });
+    return { id: "github-verify", findings };
+  }
+
+  const result = await checkGitHubTag(ctx.repository, ctx.version);
+
+  if (result.error) {
+    findings.push({
+      severity: "medium",
+      message: `GitHub API: ${result.error}`,
+      score: 1,
+    });
+    return { id: "github-verify", findings };
+  }
+
+  if (!result.tagFound) {
+    findings.push({
+      severity: "high",
+      message: `No GitHub tag found for version ${ctx.version}`,
+      score: 4,
+    });
+  } else {
+    findings.push({
+      severity: "info",
+      message: `GitHub tag found for v${ctx.version}`,
+      score: 0,
+    });
+  }
+
+  if (!result.recentCommits) {
+    findings.push({
+      severity: "medium",
+      message: "No recent commits in the last 90 days",
+      score: 2,
+    });
+  } else {
+    findings.push({
+      severity: "info",
+      message: "Repository has recent activity",
+      score: 0,
+    });
+  }
+
+  return { id: "github-verify", findings };
+}

package/src/checks/index.js

@@ -0,0 +1,8 @@
+export { checkRecentPublish } from "./recentPublish.js";
+export { checkDependencyDiff } from "./dependencyDiff.js";
+export { checkScripts } from "./scripts.js";
+export { checkTyposquat } from "./typosquat.js";
+export { checkMaintainers } from "./maintainers.js";
+export { checkLicense } from "./license.js";
+export { checkGithubVerify } from "./githubVerify.js";
+export { checkDeprecation } from "./deprecation.js";

package/src/checks/license.js

@@ -0,0 +1,35 @@
+const PERMISSIVE = [
+  "MIT", "ISC", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "0BSD", "Unlicense",
+  "CC0-1.0", "BlueOak-1.0.0",
+];
+
+/**
+ * Checks license status.
+ */
+export function checkLicense(ctx) {
+  const findings = [];
+  const raw = ctx.license;
+  const license = typeof raw === "string" ? raw : raw?.type || "Unknown";
+
+  if (license === "Unknown" || license === "UNLICENSED") {
+    findings.push({
+      severity: "high",
+      message: "No license specified",
+      score: 3,
+    });
+  } else if (PERMISSIVE.includes(license)) {
+    findings.push({
+      severity: "info",
+      message: `License: ${license}`,
+      score: 0,
+    });
+  } else {
+    findings.push({
+      severity: "medium",
+      message: `Non-standard license: ${license}`,
+      score: 1,
+    });
+  }
+
+  return { id: "license", findings };
+}

package/src/checks/maintainers.js

@@ -0,0 +1,30 @@
+/**
+ * Analyzes maintainer signals.
+ */
+export function checkMaintainers(ctx) {
+  const findings = [];
+  const maintainers = ctx.currentMaintainers || [];
+  const count = maintainers.length;
+
+  if (count === 0) {
+    findings.push({
+      severity: "high",
+      message: "No maintainers listed",
+      score: 3,
+    });
+  } else if (count === 1) {
+    findings.push({
+      severity: "medium",
+      message: `Single maintainer: ${maintainers[0].name || maintainers[0].email || "unknown"}`,
+      score: 1,
+    });
+  } else {
+    findings.push({
+      severity: "info",
+      message: `${count} maintainers`,
+      score: 0,
+    });
+  }
+
+  return { id: "maintainers", findings };
+}

package/src/checks/recentPublish.js

@@ -0,0 +1,70 @@
+/**
+ * Detects recently published versions.
+ * Supply chain attacks often use hot-off-the-press publishes.
+ */
+export function checkRecentPublish(ctx) {
+  const findings = [];
+
+  if (!ctx.publishedAt) {
+    return { id: "recent-publish", findings };
+  }
+
+  const hoursAgo = (Date.now() - new Date(ctx.publishedAt).getTime()) / (1000 * 60 * 60);
+  const daysAgo = hoursAgo / 24;
+
+  if (hoursAgo < 24) {
+    findings.push({
+      severity: "critical",
+      message: `Version ${ctx.version} was published ${Math.round(hoursAgo)} hours ago`,
+      score: 5,
+    });
+  } else if (daysAgo < 7) {
+    findings.push({
+      severity: "high",
+      message: `Version ${ctx.version} was published ${Math.round(daysAgo)} days ago`,
+      score: 2,
+    });
+  } else {
+    findings.push({
+      severity: "info",
+      message: `Published ${Math.round(daysAgo)} days ago`,
+      score: 0,
+    });
+  }
+
+  // Check for unusual version jumps
+  if (ctx.previousVersion && ctx.version) {
+    const cur = ctx.version.split(".").map(Number);
+    const prev = ctx.previousVersion.split(".").map(Number);
+
+    if (cur.length === 3 && prev.length === 3) {
+      const majorJump = cur[0] - prev[0];
+      const minorJump = cur[1] - prev[1];
+
+      if (majorJump > 1 || (majorJump === 0 && minorJump > 5)) {
+        findings.push({
+          severity: "high",
+          message: `Unusual version jump: ${ctx.previousVersion} → ${ctx.version}`,
+          score: 3,
+        });
+      }
+    }
+  }
+
+  // Rapid publish cadence — multiple versions in 24h is suspicious
+  if (ctx.publishedAt && ctx.previousPublishedAt) {
+    const gap =
+      new Date(ctx.publishedAt).getTime() -
+      new Date(ctx.previousPublishedAt).getTime();
+    const gapHours = gap / (1000 * 60 * 60);
+    if (gapHours > 0 && gapHours < 2) {
+      findings.push({
+        severity: "high",
+        message: `Two versions published within ${Math.round(gapHours * 60)} minutes`,
+        score: 3,
+      });
+    }
+  }
+
+  return { id: "recent-publish", findings };
+}

package/src/checks/scripts.js

@@ -0,0 +1,45 @@
+/**
+ * Detects lifecycle scripts that are common attack vectors.
+ */
+export function checkScripts(ctx) {
+  const findings = [];
+  const scripts = ctx.scripts || {};
+
+  const dangerous = ["preinstall", "install", "postinstall"];
+  const found = dangerous.filter((s) => scripts[s]);
+
+  if (found.length > 0) {
+    findings.push({
+      severity: "critical",
+      message: `Lifecycle scripts found: ${found.join(", ")}`,
+      score: 5,
+    });
+
+    // Inspect script content for red flags
+    for (const name of found) {
+      const cmd = scripts[name];
+      if (
+        cmd.includes("curl ") ||
+        cmd.includes("wget ") ||
+        cmd.includes("eval(") ||
+        cmd.includes("base64") ||
+        cmd.includes("exec(") ||
+        cmd.includes("child_process")
+      ) {
+        findings.push({
+          severity: "critical",
+          message: `Script "${name}" contains suspicious command: ${cmd.slice(0, 80)}`,
+          score: 5,
+        });
+      }
+    }
+  } else {
+    findings.push({
+      severity: "info",
+      message: "No lifecycle scripts",
+      score: 0,
+    });
+  }
+
+  return { id: "scripts", findings };
+}

package/src/checks/typosquat.js

@@ -0,0 +1,77 @@
+const POPULAR_PACKAGES = [
+  "express", "react", "vue", "angular", "lodash", "axios", "moment",
+  "webpack", "babel", "typescript", "eslint", "prettier", "jest",
+  "mocha", "chai", "next", "nuxt", "gatsby", "svelte", "jquery",
+  "underscore", "async", "chalk", "commander", "inquirer", "ora",
+  "nodemon", "dotenv", "cors", "mongoose", "sequelize", "prisma",
+  "socket.io", "passport", "bcrypt", "jsonwebtoken", "uuid",
+  "mysql", "pg", "redis", "mongodb", "fastify", "koa", "hapi",
+  "request", "node-fetch", "got", "cheerio", "puppeteer",
+  "sharp", "multer", "helmet", "morgan", "winston", "debug",
+  "bluebird", "rxjs", "ramda", "date-fns", "dayjs", "zod",
+  "yup", "ajv", "joi", "class-validator", "formik",
+  "tailwindcss", "bootstrap", "sass", "less", "styled-components",
+  "vite", "esbuild", "rollup", "parcel", "turbo",
+  "crypto-js", "crypto", "http-proxy", "http-server",
+];
+
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+
+  return dp[m][n];
+}
+
+/**
+ * Returns the popular package name this looks like, or null.
+ */
+export function checkTyposquatName(name) {
+  const lower = name.toLowerCase().replace(/^@[^/]+\//, ""); // strip scope
+  if (POPULAR_PACKAGES.includes(lower)) return null;
+
+  for (const popular of POPULAR_PACKAGES) {
+    const dist = levenshtein(lower, popular);
+    if (dist > 0 && dist <= 2 && Math.abs(lower.length - popular.length) <= 2) {
+      return popular;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check module: wraps the typosquat check as a pipeline-compatible check.
+ */
+export function checkTyposquat(ctx) {
+  const findings = [];
+  const match = checkTyposquatName(ctx.name);
+
+  if (match) {
+    findings.push({
+      severity: "critical",
+      message: `Package name is suspiciously similar to "${match}"`,
+      score: 5,
+    });
+  } else {
+    findings.push({
+      severity: "info",
+      message: "No typosquatting detected",
+      score: 0,
+    });
+  }
+
+  return { id: "typosquat", findings };
+}

package/src/format.js

@@ -0,0 +1,258 @@
+import chalk from "chalk";
+
+const W = 58;
+const SEPARATOR = chalk.gray("━".repeat(W));
+const THIN_SEP = chalk.gray("─".repeat(W));
+
+function riskBar(score) {
+  const filled = score;
+  const empty = 10 - score;
+  const color =
+    score <= 2 ? chalk.green : score <= 5 ? chalk.yellow : score <= 7 ? chalk.red : chalk.redBright;
+  return color("█".repeat(filled)) + chalk.gray("░".repeat(empty));
+}
+
+function riskLabel(label) {
+  switch (label) {
+    case "LOW":
+      return chalk.green.bold("✅ LOW");
+    case "MEDIUM":
+      return chalk.yellow.bold("⚠  MEDIUM");
+    case "HIGH":
+      return chalk.red.bold("🚨 HIGH");
+    case "CRITICAL":
+      return chalk.redBright.bold("💀 CRITICAL");
+    default:
+      return label;
+  }
+}
+
+function severityIcon(severity) {
+  switch (severity) {
+    case "critical":
+      return chalk.redBright("✘");
+    case "high":
+      return chalk.red("✘");
+    case "medium":
+      return chalk.yellow("⚠");
+    case "info":
+      return chalk.green("✔");
+    default:
+      return chalk.gray("·");
+  }
+}
+
+function severityColor(severity) {
+  switch (severity) {
+    case "critical":
+      return chalk.redBright;
+    case "high":
+      return chalk.red;
+    case "medium":
+      return chalk.yellow;
+    case "info":
+      return chalk.green;
+    default:
+      return chalk.white;
+  }
+}
+
+function timeAgo(dateStr) {
+  if (!dateStr) return "Unknown";
+  const diff = Date.now() - new Date(dateStr).getTime();
+  const hours = Math.floor(diff / (1000 * 60 * 60));
+  if (hours < 1) return "just now";
+  if (hours < 24) return `${hours} hour(s) ago`;
+  const days = Math.floor(hours / 24);
+  if (days === 1) return "1 day ago";
+  if (days < 30) return `${days} days ago`;
+  const months = Math.floor(days / 30);
+  if (months < 12) return `${months} month(s) ago`;
+  const years = Math.floor(days / 365);
+  return `${years} year(s) ago`;
+}
+
+/**
+ * Formats the full pipeline result for CLI display.
+ */
+export function formatPipelineResult(result) {
+  const lines = [];
+
+  lines.push("");
+  lines.push(SEPARATOR);
+  lines.push(
+    chalk.bold(`  📦 ${result.package} `) + chalk.gray(`v${result.version}`)
+  );
+  if (result.description) {
+    lines.push(chalk.gray(`  ${result.description.slice(0, W - 4)}`));
+  }
+  lines.push(SEPARATOR);
+
+  // ── Risk Score ──────────────────────────────
+  lines.push("");
+  lines.push(
+    `  Risk Level: ${riskLabel(result.label)}  ${chalk.bold(`(${result.score}/10)`)}`
+  );
+  lines.push(`  ${riskBar(result.score)}`);
+
+  lines.push("");
+  lines.push(THIN_SEP);
+
+  // ── Package Info ────────────────────────────
+  lines.push("");
+  lines.push(chalk.bold("  📊 Package Info"));
+  lines.push("");
+
+  const info = [
+    ["Downloads (weekly)", result.downloads.toLocaleString()],
+    ["Maintainers", result.maintainers.join(", ") || "None"],
+    ["License", typeof result.license === "string" ? result.license : result.license?.type || "Unknown"],
+    ["Published", timeAgo(result.publishedAt)],
+    ["Dependencies", String(result.dependencyCount)],
+    ["Total Versions", String(result.totalVersions)],
+    ["Repository", result.repository ? "✔" : "✘ None"],
+  ];
+
+  for (const [label, value] of info) {
+    lines.push(`  ${chalk.gray(label.padEnd(22))} ${chalk.white(value)}`);
+  }
+
+  if (result.deprecated) {
+    lines.push("");
+    lines.push(
+      chalk.red.bold(
+        `  ⚠ DEPRECATED: ${typeof result.deprecated === "string" ? result.deprecated : "This package is deprecated"}`
+      )
+    );
+  }
+
+  lines.push("");
+  lines.push(THIN_SEP);
+
+  // ── Findings ────────────────────────────────
+  lines.push("");
+  lines.push(chalk.bold("  🔍 Findings"));
+  lines.push("");
+
+  // Group by severity
+  const critical = result.findings.filter((f) => f.severity === "critical");
+  const high = result.findings.filter((f) => f.severity === "high");
+  const medium = result.findings.filter((f) => f.severity === "medium");
+  const info2 = result.findings.filter((f) => f.severity === "info");
+
+  for (const group of [critical, high, medium, info2]) {
+    for (const f of group) {
+      const icon = severityIcon(f.severity);
+      const color = severityColor(f.severity);
+      lines.push(`  ${icon} ${color(f.message)}`);
+    }
+  }
+
+  // ── Recommendation ──────────────────────────
+  if (result.recommendation) {
+    lines.push("");
+    lines.push(THIN_SEP);
+    lines.push("");
+    lines.push(chalk.bold("  💡 Recommendation"));
+    lines.push("");
+    if (result.label === "CRITICAL" || result.label === "HIGH") {
+      lines.push(chalk.red(`  ⛔ Avoid installing ${result.package}@${result.version}`));
+    }
+    lines.push(
+      chalk.green(
+        `  ✔ Safe alternative: ${result.package}@${chalk.bold(result.recommendation.version)}`
+      )
+    );
+    lines.push(
+      chalk.gray(`    ${result.recommendation.reason}`)
+    );
+  } else if (result.label === "CRITICAL" || result.label === "HIGH") {
+    lines.push("");
+    lines.push(THIN_SEP);
+    lines.push("");
+    lines.push(chalk.bold("  💡 Recommendation"));
+    lines.push("");
+    lines.push(chalk.red(`  ⛔ Avoid installing this version`));
+    lines.push(chalk.gray("    No safe alternative version found"));
+  }
+
+  lines.push("");
+  lines.push(SEPARATOR);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Formats a summary table for scan results.
+ */
+export function formatScanSummary(results) {
+  const lines = [];
+
+  results.sort((a, b) => b.score - a.score);
+
+  lines.push("");
+  lines.push(SEPARATOR);
+  lines.push(chalk.bold("  📋 Dependency Scan Summary"));
+  lines.push(SEPARATOR);
+  lines.push("");
+
+  const nameWidth = Math.max(20, ...results.map((r) => r.package.length + 2));
+
+  lines.push(
+    chalk.gray(
+      "  " +
+        "Package".padEnd(nameWidth) +
+        "Score".padEnd(10) +
+        "Level"
+    )
+  );
+  lines.push(chalk.gray("  " + "─".repeat(nameWidth + 24)));
+
+  for (const r of results) {
+    const name = r.package.padEnd(nameWidth);
+    const score = `${r.score}/10`.padEnd(10);
+    let level;
+    switch (r.label) {
+      case "LOW":
+        level = chalk.green("✅ Low");
+        break;
+      case "MEDIUM":
+        level = chalk.yellow("⚠  Medium");
+        break;
+      case "HIGH":
+        level = chalk.red("🚨 High");
+        break;
+      case "CRITICAL":
+        level = chalk.redBright("💀 Critical");
+        break;
+    }
+
+    const colorFn =
+      r.label === "CRITICAL" || r.label === "HIGH"
+        ? chalk.red
+        : r.label === "MEDIUM"
+          ? chalk.yellow
+          : chalk.white;
+    lines.push(`  ${colorFn(name)}${score}${level}`);
+  }
+
+  lines.push("");
+  lines.push(THIN_SEP);
+
+  const low = results.filter((r) => r.label === "LOW").length;
+  const med = results.filter((r) => r.label === "MEDIUM").length;
+  const high = results.filter((r) => r.label === "HIGH").length;
+  const crit = results.filter((r) => r.label === "CRITICAL").length;
+
+  lines.push(
+    `  ${chalk.bold("Total:")} ${results.length} packages  ` +
+    `${chalk.green(`${low} low`)} · ${chalk.yellow(`${med} medium`)} · ` +
+    `${chalk.red(`${high} high`)} · ${chalk.redBright(`${crit} critical`)}`
+  );
+  lines.push("");
+  lines.push(SEPARATOR);
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/index.js

@@ -1,5 +1,5 @@
 import { analyze } from "./analyze.js";
 
-export async function analyzePackage(pkg) {
-    await analyze(pkg);
+export async function analyzePackage(pkg, version, opts) {
+    return await analyze(pkg, version, opts);
 }