install-guard 1.0.1 → 1.1.2

package/src/install.js

@@ -1,7 +1,11 @@
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 import readline from "readline";
-import { getPackageData } from "./npm.js";
-import { calculateRisk } from "./score.js";
+import chalk from "chalk";
+import ora from "ora";
+import { runPipeline } from "./services/pipeline.js";
+import { formatPipelineResult } from "./format.js";
+
+const VALID_PKG_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*(@[a-z0-9._^~>=<|-]+)?$/i;
 
 function askQuestion(query) {
     const rl = readline.createInterface({
@@ -18,27 +22,51 @@ function askQuestion(query) {
 }
 
 export async function analyzeAndPrompt(pkgName) {
-    console.log(`\nAnalyzing ${pkgName}...\n`);
+    if (!VALID_PKG_NAME.test(pkgName)) {
+        console.log(chalk.red("\n  ✘ Invalid package name.\n"));
+        return;
+    }
 
-    const data = await getPackageData(pkgName);
-    const { score, warnings } = calculateRisk(data);
+    const spinner = ora(`Analyzing ${pkgName}...`).start();
 
-    console.log(`Risk Score: ${score}/10`);
+    let result;
+    try {
+        result = await runPipeline(pkgName);
+        spinner.stop();
+    } catch (err) {
+        spinner.fail(`Failed to analyze "${pkgName}": ${err.message}`);
+        return;
+    }
 
-    warnings.forEach((w) => console.log(`⚠ ${w}`));
+    console.log(formatPipelineResult(result));
 
-    if (score >= 6) {
+    if (result.label === "CRITICAL") {
         const ans = await askQuestion(
-            "\nHigh risk package. Continue install? (y/n): "
+            chalk.redBright.bold("  💀 CRITICAL risk. Are you absolutely sure? (y/n): ")
         );
-
         if (ans.toLowerCase() !== "y") {
-            console.log("Installation aborted.");
+            console.log(chalk.yellow("\n  Installation aborted.\n"));
+            return;
+        }
+    } else if (result.label === "HIGH") {
+        const ans = await askQuestion(
+            chalk.red.bold("  🚨 HIGH risk package. Continue install? (y/n): ")
+        );
+        if (ans.toLowerCase() !== "y") {
+            console.log(chalk.yellow("\n  Installation aborted.\n"));
+            return;
+        }
+    } else if (result.label === "MEDIUM") {
+        const ans = await askQuestion(
+            chalk.yellow("  ⚠ Medium risk. Continue install? (y/n): ")
+        );
+        if (ans.toLowerCase() !== "y") {
+            console.log(chalk.yellow("\n  Installation aborted.\n"));
             return;
         }
     }
 
-    console.log("\nInstalling...\n");
-
-    execSync(`npm install ${pkgName}`, { stdio: "inherit" });
+    console.log(chalk.green("\n  Installing...\n"));
+    execFileSync("npm", ["install", pkgName], { stdio: "inherit" });
+    console.log(chalk.green(`\n  ✔ ${pkgName} installed successfully.\n`));
 }

package/src/npm.js

@@ -1,27 +1,42 @@
-import axios from "axios";
-
 export async function getPackageData(pkg) {
-  const registryUrl = `https://registry.npmjs.org/${pkg}`;
-  const downloadUrl = `https://api.npmjs.org/downloads/point/last-week/${pkg}`;
+  const encodedPkg = encodeURIComponent(pkg).replace("%40", "@");
+  const registryUrl = `https://registry.npmjs.org/${encodedPkg}`;
+  const downloadUrl = `https://api.npmjs.org/downloads/point/last-week/${encodedPkg}`;
 
   const [registryRes, downloadRes] = await Promise.all([
-    axios.get(registryUrl),
-    axios.get(downloadUrl),
+    fetch(registryUrl).then((r) => {
+      if (!r.ok) throw new Error(`Package "${pkg}" not found on npm`);
+      return r.json();
+    }),
+    fetch(downloadUrl)
+      .then((r) => r.json())
+      .catch(() => ({ downloads: 0 })),
   ]);
 
-  const data = registryRes.data;
-  const latest = data["dist-tags"].latest;
-  const versionData = data.versions[latest];
+  const data = registryRes;
+  const latest = data["dist-tags"]?.latest;
+  if (!latest) throw new Error(`No published version found for "${pkg}"`);
+
+  const versionData = data.versions?.[latest] || {};
+  const timeData = data.time || {};
 
   return {
     name: data.name,
-    maintainers: data.maintainers?.length || 0,
-    lastPublished: data.time?.[latest],
-    hasInstallScript:
-      versionData.scripts?.install ||
-      versionData.scripts?.postinstall ||
-      false,
     version: latest,
-    downloads: downloadRes.data.downloads || 0,
+    description: data.description || "",
+    downloads: downloadRes.downloads || 0,
+    maintainers: data.maintainers || [],
+    license: versionData.license || data.license || "Unknown",
+    lastPublished: timeData[latest],
+    firstPublished: timeData.created,
+    hasInstallScript: !!(
+      versionData.scripts?.install ||
+      versionData.scripts?.preinstall ||
+      versionData.scripts?.postinstall
+    ),
+    deprecated: versionData.deprecated || false,
+    repository: data.repository?.url || versionData.repository?.url || null,
+    dependencies: Object.keys(versionData.dependencies || {}).length,
+    totalVersions: Object.keys(data.versions || {}).length,
   };
 }

package/src/scan.js

@@ -1,15 +1,65 @@
 import fs from "fs";
-import { analyzePackage } from "./index.js";
+import path from "path";
+import chalk from "chalk";
+import ora from "ora";
+import { runPipeline } from "./services/pipeline.js";
+import { formatPipelineResult, formatScanSummary } from "./format.js";
 
-export async function scanProject() {
-    const pkg = JSON.parse(fs.readFileSync("package.json"));
+export async function scanProject({ verbose, json, skipGithub } = {}) {
+    const pkgPath = path.resolve("package.json");
+
+    if (!fs.existsSync(pkgPath)) {
+        console.log(chalk.red("\n  ✘ No package.json found in current directory\n"));
+        process.exit(1);
+    }
+
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
 
     const deps = {
         ...pkg.dependencies,
         ...pkg.devDependencies,
     };
 
-    for (const dep of Object.keys(deps)) {
-        await analyzePackage(dep);
+    const depNames = Object.keys(deps);
+
+    if (depNames.length === 0) {
+        console.log(chalk.yellow("\n  No dependencies found.\n"));
+        return;
+    }
+
+    console.log(chalk.bold(`\n  Scanning ${depNames.length} dependencies...\n`));
+
+    const results = [];
+    const spinner = ora();
+
+    for (const dep of depNames) {
+        spinner.start(`Analyzing ${dep}...`);
+        try {
+            const result = await runPipeline(dep, undefined, { skipGithub: skipGithub !== false });
+            results.push(result);
+
+            if (verbose) {
+                spinner.stop();
+                console.log(formatPipelineResult(result));
+            } else {
+                const icon =
+                    result.label === "CRITICAL" || result.label === "HIGH"
+                        ? "🚨"
+                        : result.label === "MEDIUM"
+                          ? "⚠"
+                          : "✅";
+                spinner.succeed(
+                    `${dep} ${chalk.gray(`(${result.score}/10)`)} ${icon}`
+                );
+            }
+        } catch {
+            spinner.fail(`${dep} - failed to fetch`);
+        }
+    }
+
+    if (json) {
+        console.log(JSON.stringify(results, null, 2));
+    } else {
+        console.log(formatScanSummary(results));
     }
 }

package/src/score.js

@@ -1,47 +1,128 @@
+import { checkTyposquat } from "./typosquat.js";
+
 export function calculateRisk(pkg) {
     let score = 0;
-    const warnings = [];
+    const checks = [];
+    const now = new Date();
 
-    // 🟢 Popularity (VERY IMPORTANT)
-    if (pkg.downloads < 1000) {
+    // ── Downloads ──────────────────────────────────
+    if (pkg.downloads < 100) {
         score += 3;
-        warnings.push("Very low downloads");
-    } else if (pkg.downloads < 10000) {
+        checks.push({ label: "Downloads", status: "fail", detail: `Very low (${pkg.downloads.toLocaleString()}/week)` });
+    } else if (pkg.downloads < 1_000) {
         score += 2;
-        warnings.push("Low downloads");
+        checks.push({ label: "Downloads", status: "warn", detail: `Low (${pkg.downloads.toLocaleString()}/week)` });
+    } else if (pkg.downloads < 10_000) {
+        score += 1;
+        checks.push({ label: "Downloads", status: "warn", detail: `Moderate (${pkg.downloads.toLocaleString()}/week)` });
+    } else {
+        checks.push({ label: "Downloads", status: "pass", detail: `${pkg.downloads.toLocaleString()}/week` });
     }
 
-    // 🟡 Update recency
-    const lastUpdate = new Date(pkg.lastPublished);
-    const now = new Date();
-    const diffMonths = (now - lastUpdate) / (1000 * 60 * 60 * 24 * 30);
+    if (pkg.downloads > 1_000_000) score -= 2;
+    if (pkg.downloads > 5_000_000) score -= 1;
 
-    if (diffMonths > 12) {
-        score += 3;
-        warnings.push("Not updated in over a year");
-    } else if (diffMonths > 6) {
-        score += 1;
-        warnings.push("Not updated recently");
+    // ── Update recency ────────────────────────────
+    if (pkg.lastPublished) {
+        const diffMonths = (now - new Date(pkg.lastPublished)) / (1000 * 60 * 60 * 24 * 30);
+        if (diffMonths > 24) {
+            score += 3;
+            checks.push({ label: "Last Updated", status: "fail", detail: "Not updated in over 2 years" });
+        } else if (diffMonths > 12) {
+            score += 2;
+            checks.push({ label: "Last Updated", status: "warn", detail: "Not updated in over a year" });
+        } else if (diffMonths > 6) {
+            score += 1;
+            checks.push({ label: "Last Updated", status: "warn", detail: "Not updated in 6+ months" });
+        } else {
+            checks.push({ label: "Last Updated", status: "pass", detail: "Recently updated" });
+        }
     }
 
-    // 🔴 Install scripts (HIGH RISK)
+    // ── Install scripts ───────────────────────────
     if (pkg.hasInstallScript) {
         score += 3;
-        warnings.push("Uses install/postinstall scripts");
+        checks.push({ label: "Install Scripts", status: "fail", detail: "Has install/postinstall scripts" });
+    } else {
+        checks.push({ label: "Install Scripts", status: "pass", detail: "No install scripts" });
+    }
+
+    // ── Maintainers ───────────────────────────────
+    const maintainerCount = pkg.maintainers?.length || 0;
+    if (maintainerCount === 0) {
+        score += 2;
+        checks.push({ label: "Maintainers", status: "fail", detail: "No maintainers listed" });
+    } else if (maintainerCount === 1) {
+        score += 1;
+        checks.push({ label: "Maintainers", status: "warn", detail: "Single maintainer" });
+    } else {
+        checks.push({ label: "Maintainers", status: "pass", detail: `${maintainerCount} maintainers` });
+    }
+
+    // ── License ───────────────────────────────────
+    const license = (typeof pkg.license === "string" ? pkg.license : pkg.license?.type) || "Unknown";
+    const permissive = ["MIT", "ISC", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "0BSD", "Unlicense"];
+    if (license === "Unknown" || license === "UNLICENSED") {
+        score += 2;
+        checks.push({ label: "License", status: "fail", detail: "No license specified" });
+    } else if (permissive.includes(license)) {
+        checks.push({ label: "License", status: "pass", detail: license });
+    } else {
+        score += 1;
+        checks.push({ label: "License", status: "warn", detail: `${license} (review recommended)` });
+    }
+
+    // ── Repository ────────────────────────────────
+    if (!pkg.repository) {
+        score += 1;
+        checks.push({ label: "Repository", status: "warn", detail: "No repository URL" });
+    } else {
+        checks.push({ label: "Repository", status: "pass", detail: "Has repository link" });
+    }
+
+    // ── Package age ───────────────────────────────
+    if (pkg.firstPublished) {
+        const ageDays = (now - new Date(pkg.firstPublished)) / (1000 * 60 * 60 * 24);
+        if (ageDays < 30) {
+            score += 2;
+            checks.push({ label: "Package Age", status: "fail", detail: "Published less than 30 days ago" });
+        } else if (ageDays < 180) {
+            score += 1;
+            checks.push({ label: "Package Age", status: "warn", detail: "Published less than 6 months ago" });
+        } else {
+            const years = Math.floor(ageDays / 365);
+            checks.push({ label: "Package Age", status: "pass", detail: years > 0 ? `${years}+ year(s) old` : "6+ months old" });
+        }
+    }
+
+    // ── Dependency count ──────────────────────────
+    if (pkg.dependencies > 20) {
+        score += 1;
+        checks.push({ label: "Dependencies", status: "warn", detail: `${pkg.dependencies} direct dependencies (high)` });
+    } else {
+        checks.push({ label: "Dependencies", status: "pass", detail: `${pkg.dependencies} direct dependencies` });
     }
 
-    // 🟢 High trust signal
-    if (pkg.downloads > 1000000) {
-        score -= 2; // reduce risk
+    // ── Deprecated ────────────────────────────────
+    if (pkg.deprecated) {
+        score += 3;
+        checks.push({
+            label: "Deprecated",
+            status: "fail",
+            detail: typeof pkg.deprecated === "string" ? pkg.deprecated : "Package is deprecated",
+        });
     }
 
-    if (pkg.downloads > 5000000) {
-        score -= 2;
+    // ── Typosquatting ─────────────────────────────
+    const typosquatMatch = checkTyposquat(pkg.name);
+    if (typosquatMatch) {
+        score += 3;
+        checks.push({ label: "Typosquatting", status: "fail", detail: `Name is suspiciously similar to "${typosquatMatch}"` });
     }
 
     // Normalize
-    if (score < 0) score = 0;
-    if (score > 10) score = 10;
+    score = Math.max(0, Math.min(10, score));
+    const level = score <= 3 ? "low" : score <= 6 ? "medium" : "high";
 
-    return { score, warnings };
+    return { score, checks, level };
 }

package/src/services/pipeline.js

@@ -0,0 +1,105 @@
+import { buildContext } from "../utils/registry.js";
+import {
+  checkRecentPublish,
+  checkDependencyDiff,
+  checkScripts,
+  checkTyposquat,
+  checkMaintainers,
+  checkLicense,
+  checkGithubVerify,
+  checkDeprecation,
+} from "../checks/index.js";
+import { computeScore } from "./scorer.js";
+
+/**
+ * Runs the full detection pipeline on a package+version.
+ * Returns structured results consumable by CLI or JSON output.
+ */
+export async function runPipeline(packageName, version, opts = {}) {
+  const ctx = await buildContext(packageName, version);
+
+  // Run sync checks immediately
+  const syncResults = [
+    checkRecentPublish(ctx),
+    checkScripts(ctx),
+    checkTyposquat(ctx),
+    checkMaintainers(ctx),
+    checkLicense(ctx),
+    checkDeprecation(ctx),
+  ];
+
+  // Run async checks in parallel
+  const asyncChecks = [checkDependencyDiff(ctx)];
+
+  if (!opts.skipGithub) {
+    asyncChecks.push(checkGithubVerify(ctx));
+  }
+
+  const asyncResults = await Promise.all(asyncChecks);
+  const allChecks = [...syncResults, ...asyncResults];
+
+  const { score, label, findings } = computeScore(allChecks);
+
+  // Find a safe version recommendation
+  const safeVersion = findSafeVersion(ctx, score);
+
+  return {
+    package: ctx.name,
+    version: ctx.version,
+    previousVersion: ctx.previousVersion,
+    description: ctx.description,
+    downloads: ctx.downloads,
+    maintainers: ctx.currentMaintainers.map((m) => m.name || m.email),
+    license: ctx.license,
+    publishedAt: ctx.publishedAt,
+    repository: ctx.repository,
+    deprecated: ctx.deprecated,
+    totalVersions: ctx.totalVersions,
+    dependencyCount: Object.keys(ctx.dependencies).length,
+
+    score,
+    label,
+    findings,
+    checks: allChecks,
+
+    recommendation: safeVersion,
+  };
+}
+
+/**
+ * Suggests the latest safe version — one that is older, with no install scripts,
+ * and published more than 7 days ago.
+ */
+function findSafeVersion(ctx, currentScore) {
+  if (currentScore <= 3) return null; // current version is fine
+
+  const registry = ctx._registry;
+  const timeData = registry.time || {};
+  const versions = ctx.allVersions.slice().reverse(); // newest first
+  const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
+
+  for (const v of versions) {
+    if (v === ctx.version) continue;
+
+    const vData = registry.versions[v];
+    if (!vData) continue;
+    if (vData.deprecated) continue;
+    if (
+      vData.scripts?.postinstall ||
+      vData.scripts?.preinstall ||
+      vData.scripts?.install
+    )
+      continue;
+
+    const publishTime = new Date(timeData[v] || 0).getTime();
+    if (publishTime > sevenDaysAgo) continue;
+
+    return {
+      version: v,
+      publishedAt: timeData[v],
+      reason: "No install scripts, published > 7 days ago",
+    };
+  }
+
+  return null;
+}

package/src/services/scorer.js

@@ -0,0 +1,36 @@
+/**
+ * Weighted risk scorer.
+ * Takes raw check results and computes a normalized 0-10 score with label.
+ */
+
+// Max raw score (theoretical) — used to normalize
+const MAX_RAW = 50;
+
+export function computeScore(checkResults) {
+  let rawScore = 0;
+  const allFindings = [];
+  let hasCritical = false;
+
+  for (const check of checkResults) {
+    for (const f of check.findings) {
+      allFindings.push({ ...f, checkId: check.id });
+      rawScore += f.score;
+      if (f.severity === "critical") hasCritical = true;
+    }
+  }
+
+  // Normalize to 0-10
+  let score = Math.round((rawScore / MAX_RAW) * 10);
+  score = Math.max(0, Math.min(10, score));
+
+  // Critical findings floor at 7
+  if (hasCritical && score < 7) score = 7;
+
+  let label;
+  if (score <= 2) label = "LOW";
+  else if (score <= 5) label = "MEDIUM";
+  else if (score <= 7) label = "HIGH";
+  else label = "CRITICAL";
+
+  return { score, label, rawScore, findings: allFindings };
+}

package/src/typosquat.js

@@ -0,0 +1,50 @@
+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",
+];
+
+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];
+}
+
+export function checkTyposquat(name) {
+  const lower = name.toLowerCase();
+
+  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;
+}

package/src/utils/cache.js

@@ -0,0 +1,44 @@
+import fs from "fs";
+import path from "path";
+import { createHash } from "crypto";
+
+const CACHE_DIR = path.join(
+  process.env.HOME || process.env.USERPROFILE || "/tmp",
+  ".install-guard-cache"
+);
+const TTL_MS = 15 * 60 * 1000; // 15 minutes
+
+function ensureDir() {
+  if (!fs.existsSync(CACHE_DIR)) {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+  }
+}
+
+function keyToFile(key) {
+  const hash = createHash("sha256").update(key).digest("hex").slice(0, 16);
+  return path.join(CACHE_DIR, `${hash}.json`);
+}
+
+export function getCached(key) {
+  try {
+    const file = keyToFile(key);
+    if (!fs.existsSync(file)) return null;
+    const raw = JSON.parse(fs.readFileSync(file, "utf-8"));
+    if (Date.now() - raw.ts > TTL_MS) {
+      fs.unlinkSync(file);
+      return null;
+    }
+    return raw.data;
+  } catch {
+    return null;
+  }
+}
+
+export function setCache(key, data) {
+  try {
+    ensureDir();
+    fs.writeFileSync(keyToFile(key), JSON.stringify({ ts: Date.now(), data }));
+  } catch {
+    // cache write failures are non-fatal
+  }
+}

package/src/utils/github.js

@@ -0,0 +1,64 @@
+import { getCached, setCache } from "./cache.js";
+
+/**
+ * Extracts owner/repo from a repository URL.
+ */
+function parseRepoUrl(url) {
+  if (!url) return null;
+  // Handles: git+https://github.com/owner/repo.git, https://github.com/owner/repo, etc.
+  const match = url.match(
+    /github\.com[/:]([^/]+)\/([^/.#]+)/
+  );
+  if (!match) return null;
+  return { owner: match[1], repo: match[2] };
+}
+
+async function ghFetch(path) {
+  const headers = { "User-Agent": "install-guard-cli" };
+  // Use token if available to avoid rate limits
+  if (process.env.GITHUB_TOKEN) {
+    headers.Authorization = `token ${process.env.GITHUB_TOKEN}`;
+  }
+  const res = await fetch(`https://api.github.com${path}`, { headers });
+  if (!res.ok) return null;
+  return res.json();
+}
+
+/**
+ * Checks if a given version tag exists on GitHub.
+ * Tries both `v1.2.3` and `1.2.3` tag formats.
+ */
+export async function checkGitHubTag(repoUrl, version) {
+  const repo = parseRepoUrl(repoUrl);
+  if (!repo) return { hasRepo: false, tagFound: false, recentCommits: false };
+
+  const key = `gh-tag:${repo.owner}/${repo.repo}:${version}`;
+  const cached = getCached(key);
+  if (cached) return cached;
+
+  // Try v-prefixed and plain tag
+  const tags = await ghFetch(`/repos/${repo.owner}/${repo.repo}/tags?per_page=100`);
+  if (!tags) {
+    const result = { hasRepo: true, tagFound: false, recentCommits: false, error: "rate-limited or private" };
+    setCache(key, result);
+    return result;
+  }
+
+  const tagNames = tags.map((t) => t.name);
+  const tagFound = tagNames.includes(`v${version}`) || tagNames.includes(version);
+
+  // Check recent commits
+  const commits = await ghFetch(
+    `/repos/${repo.owner}/${repo.repo}/commits?per_page=1`
+  );
+  let recentCommits = false;
+  if (commits && commits.length > 0) {
+    const lastCommitDate = new Date(commits[0].commit?.committer?.date || 0);
+    const daysSinceCommit = (Date.now() - lastCommitDate.getTime()) / (1000 * 60 * 60 * 24);
+    recentCommits = daysSinceCommit < 90;
+  }
+
+  const result = { hasRepo: true, tagFound, recentCommits };
+  setCache(key, result);
+  return result;
+}