install-guard 1.0.1 → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarthak Kumar Sahoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,27 +1,65 @@
+![npm](https://img.shields.io/npm/v/install-guard)
+![downloads](https://img.shields.io/npm/dw/install-guard)
+![license](https://img.shields.io/npm/l/install-guard)
+
 # 🚨 Should You Trust That npm Package Before Installing?
 
-**install-guard** analyzes npm packages and tells you if they are safe to install — before you install them.
+**install-guard** is a supply chain security tool that analyzes npm packages for risks **before** you install them. It detects compromised versions, typosquatting, suspicious dependencies, and more.
 
 ---
 
 <details>
-<summary>Example</summary>
+<summary>📦 See it in action</summary>
 
 ```bash
-npx install-guard install some-random-lib
+$ npx install-guard install some-random-lib
 ```
 
 ```
-📦 Analyzing some-random-lib...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📦 some-random-lib v0.1.3
+  A random utility library
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Risk Level: 💀 CRITICAL  (9/10)
+  █████████░
+
+──────────────────────────────────────────────────────────
+
+  📊 Package Info
+
+  Downloads (weekly)     120
+  Maintainers            unknown-person
+  License                Unknown
+  Published              6 hours ago
+  Dependencies           3
+  Total Versions         2
+  Repository             ✘ None
+
+──────────────────────────────────────────────────────────
 
-Downloads (weekly): 120
-Risk Score: 8/10 🚨 High Risk
+  🔍 Findings
 
-⚠ Very low downloads
-⚠ Uses install scripts
-⚠ Recently published
+  ✘ Version 0.1.3 was published 6 hours ago
+  ✘ Lifecycle scripts found: postinstall
+  ✘ New dep "plain-crypto-js" looks like typosquat of "crypto-js"
+  ✘ New dep "plain-crypto-js" has very low downloads (12/week)
+  ✘ No GitHub tag found for version 0.1.3
+  ✘ No license specified
+  ⚠ Single maintainer: unknown-person
+  ⚠ No recent commits in the last 90 days
 
-❓ Do you still want to install this package? (y/n)
+──────────────────────────────────────────────────────────
+
+  💡 Recommendation
+
+  ⛔ Avoid installing some-random-lib@0.1.3
+  ✔ Safe alternative: some-random-lib@0.1.1
+    No install scripts, published > 7 days ago
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  💀 CRITICAL risk. Are you absolutely sure? (y/n):
 ```
 
 </details>
@@ -30,11 +68,12 @@ Risk Score: 8/10 🚨 High Risk
 
 ## 😬 The Problem
 
-Installing npm packages blindly is risky.
+Supply chain attacks on npm are increasing:
 
-- Malicious packages are published daily
-- Popular packages get compromised
-- `npm audit` only checks known vulnerabilities — not trust
+- Malicious packages are published **daily**
+- Popular packages get compromised (e.g., event-stream, ua-parser-js, colors)
+- Attackers inject postinstall scripts, add typosquatted dependencies, or hijack maintainer accounts
+- `npm audit` only checks **known CVEs** — it can't detect a new attack in progress
 
 You shouldn't have to guess if a package is safe.
 
@@ -42,90 +81,226 @@ You shouldn't have to guess if a package is safe.
 
 ## 🛡️ The Solution
 
-install-guard gives you a **risk score before you install anything**.
+install-guard runs a **modular detection pipeline** with 8 specialized security checks, GitHub verification, dependency diffing, and a weighted risk scorer — all before a single file is downloaded.
 
 ---
 
 ## ⚡ Quick Start
 
-Check a package:
+Analyze any package:
 
 ```bash
 npx install-guard axios
 ```
 
-Safely install a package:
+Analyze a specific version:
+
+```bash
+npx install-guard axios@1.14.0
+```
+
+Safely install with pre-check:
 
 ```bash
 npx install-guard install axios
 ```
 
-Scan your project:
+Scan your entire project:
 
 ```bash
 npx install-guard scan
 ```
 
+Scan with full details per package:
+
+```bash
+npx install-guard scan --verbose
+```
+
+Get JSON output (for CI/CD):
+
+```bash
+npx install-guard axios --json
+```
+
+Skip GitHub checks (faster):
+
+```bash
+npx install-guard axios --skip-github
+```
+
 ---
 
-## 🧠 How Risk Score Works
+## 🧠 Detection Pipeline
+
+install-guard runs **8 isolated checks** through a security pipeline:
+
+| # | Check | What it detects | Risk Weight |
+|---|-------|----------------|-------------|
+| 1 | **Recent Publish** | Version published <24h ago, unusual version jumps, rapid publish cadence | +2 to +5 |
+| 2 | **Dependency Diff** | New/removed deps between versions, deep analysis of each new dep | +3 to +5 |
+| 3 | **Script Analysis** | `preinstall`/`postinstall` hooks, suspicious commands (curl, eval, base64) | +5 |
+| 4 | **Typosquatting** | Package name similar to popular packages (Levenshtein distance) | +5 |
+| 5 | **Maintainer Analysis** | No maintainers, single maintainer | +1 to +3 |
+| 6 | **License Check** | Missing, unknown, or non-permissive licenses | +1 to +3 |
+| 7 | **GitHub Verification** | No matching tag/release, no recent commits in repo | +2 to +4 |
+| 8 | **Deprecation** | Package flagged as deprecated on npm | +3 |
+
+Results are scored and normalized to **0–10** with labels: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`.
+
+### Dependency Diff Engine
+
+When you check a specific version, install-guard compares its dependencies against the previous version. For each **newly added** dependency, it runs sub-analysis:
 
-install-guard analyzes:
+- Download count check
+- Publish age check
+- Typosquatting detection
+- Install script detection
 
-- 📉 Weekly downloads (popularity)
-- 🕒 Last update time
-- ⚠ Install/postinstall scripts
-- 📦 Version activity
+This catches the exact pattern used in real supply chain attacks (e.g., injecting a malicious dependency in a patch release).
 
-Each factor contributes to a **risk score (0–10)**.
+### Safe Version Recommendation
 
-Lower score = safer package.
+If a version is flagged as risky, install-guard scans all previous versions and suggests the latest safe one — no install scripts, published more than 7 days ago.
 
 ---
 
-## 📊 Example Results
+## 📊 Example Output
 
 ### ✅ Safe package
 
 ```
-axios
-Downloads: 20,000,000+
-Risk: 1/10
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📦 axios v1.15.0
+  Promise based HTTP client for the browser and node.js
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Risk Level: ✅ LOW  (1/10)
+  █░░░░░░░░░
+
+  🔍 Findings
+  ✔ Published 6 days ago
+  ✔ No lifecycle scripts
+  ✔ No typosquatting detected
+  ✔ License: MIT
+  ✔ Not deprecated
+  ✔ No dependency changes from previous version
+  ✔ GitHub tag found for v1.15.0
+  ✔ Repository has recent activity
+  ⚠ Single maintainer: jasonsaayman
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
----
+### 🚨 Compromised package (simulated)
 
-### 🚨 Risky package
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📦 evil-lib v2.0.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Risk Level: 💀 CRITICAL  (9/10)
+  █████████░
+
+  🔍 Findings
+  ✘ Version 2.0.0 was published 3 hours ago
+  ✘ Lifecycle scripts found: postinstall
+  ✘ Script "postinstall" contains suspicious command: curl http://...
+  ✘ New dependencies added: plain-crypto-js
+  ✘ New dep "plain-crypto-js" looks like typosquat of "crypto-js"
+  ✘ New dep "plain-crypto-js" has very low downloads (0/week)
+  ✘ No GitHub tag found for version 2.0.0
+
+  💡 Recommendation
+  ⛔ Avoid installing evil-lib@2.0.0
+  ✔ Safe alternative: evil-lib@1.9.2
+    No install scripts, published > 7 days ago
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
+### 📋 Project scan
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📋 Dependency Scan Summary
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Package              Score     Level
+  ────────────────────────────────────────────
+  evil-lib             9/10      💀 Critical
+  old-utils            5/10      ⚠  Medium
+  express              0/10      ✅ Low
+  axios                1/10      ✅ Low
+
+──────────────────────────────────────────────────────────
+  Total: 4 packages  2 low · 1 medium · 0 high · 1 critical
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
-some-lib
-Downloads: 200
-Risk: 8/10
 
-⚠ Low downloads
-⚠ Uses install scripts
+---
+
+## 🏗️ Architecture
+
 ```
+src/
+├── checks/               # Isolated security checks
+│   ├── recentPublish.js  # Publish timing analysis
+│   ├── dependencyDiff.js # Version-to-version dep comparison
+│   ├── scripts.js        # Lifecycle script detection
+│   ├── typosquat.js      # Name similarity analysis
+│   ├── maintainers.js    # Maintainer signals
+│   ├── license.js        # License validation
+│   ├── githubVerify.js   # GitHub tag/release verification
+│   └── deprecation.js    # Deprecation detection
+├── services/
+│   ├── pipeline.js       # Orchestrates all checks
+│   └── scorer.js         # Weighted risk scoring
+├── utils/
+│   ├── registry.js       # npm registry API + caching
+│   ├── github.js         # GitHub API integration
+│   └── cache.js          # File-based cache (15min TTL)
+├── format.js             # CLI output formatter
+├── scan.js               # Project-wide scanner
+├── install.js            # Safe install with prompts
+└── index.js              # Entry point
+```
+
+Each check is **fully isolated** — returns a standardized `{ id, findings[] }` structure. The pipeline runs sync checks immediately and async checks (GitHub, dependency deep-analysis) in parallel.
 
 ---
 
 ## ✨ Features
 
-- 🔍 Analyze any npm package instantly
-- ⚠ Risk scoring (0–10)
-- 🛑 Block risky installs
-- 📦 Project-wide dependency scan
-- ⚡ Zero setup (works with npx)
+- 🔍 **8 security checks** — modular detection pipeline
+- 🔄 **Dependency diff engine** — compares deps between versions
+- 🧠 **Typosquatting detection** — Levenshtein distance against 80+ popular packages
+- 🏷️ **GitHub verification** — checks for matching tags and recent activity
+- ⚠ **Script analysis** — detects dangerous commands in lifecycle scripts
+- 💡 **Safe version suggestions** — recommends the latest clean version
+- 📊 **Weighted risk scoring** — 0–10 with LOW/MEDIUM/HIGH/CRITICAL labels
+- 🛑 **Install blocking** — prompts before installing risky packages
+- 📋 **Project scan** — audit all deps with summary table
+- 🗄️ **File-based caching** — avoids redundant API calls (15min TTL)
+- 📤 **JSON output** — pipe results into CI/CD pipelines
+- ⚡ **Zero config** — works with `npx`, no setup required
 
 ---
 
 ## 🤔 Why not npm audit?
 
-| Feature               | npm audit | install-guard |
-|-----------------------|-----------|------------|
-| Known vulnerabilities | ✅        | ✅         |
-| Trust analysis        | ❌        | ✅         |
-| Pre-install check     | ❌        | ✅         |
-| Install blocking      | ❌        | ✅         |
+| Feature                    | npm audit | install-guard |
+|----------------------------|-----------|---------------|
+| Known CVE vulnerabilities  | ✅        | —             |
+| Supply chain attack detection | ❌     | ✅            |
+| Pre-install analysis       | ❌        | ✅            |
+| Dependency diff            | ❌        | ✅            |
+| Typosquatting detection    | ❌        | ✅            |
+| Script analysis            | ❌        | ✅            |
+| GitHub verification        | ❌        | ✅            |
+| Install blocking           | ❌        | ✅            |
+| Safe version suggestions   | ❌        | ✅            |
+| JSON output for CI         | ✅        | ✅            |
+
+**Use both together** — `npm audit` for known vulnerabilities, `install-guard` for everything else.
 
 ---
 
@@ -139,10 +314,12 @@ npm install -g install-guard
 
 ## 🔮 Roadmap
 
-- 🔍 GitHub activity analysis
-- 🧠 Typosquatting detection
 - 📊 Dependency tree visualization
-- 🔌 CI/CD integration
+- 🔌 CI/CD integration (exit codes for pipelines)
+- 🏷️ `.install-guardrc` config for custom risk thresholds
+- 📝 HTML/CSV report export
+- 🧠 Advanced typosquatting (permutations, homoglyphs, scope confusion)
+- 🔔 Webhook notifications for risky dependencies
 
 ---
 
@@ -154,5 +331,5 @@ PRs welcome! Let's make npm safer together.
 
 ## ⭐ Support
 
-If you find this useful, consider giving it a star ⭐  
+If you find this useful, consider giving it a star ⭐
 It helps others discover the project!

package/bin/cli.js

@@ -8,28 +8,54 @@ const program = new Command();
 
 program
     .name("install-guard")
-    .description("Check npm package risk before installing");
+    .description("Detect supply chain attacks in npm packages before installing")
+    .version("3.0.0");
 
 program
-    .argument("[package]", "package name to analyze")
-    .action(async (pkg) => {
+    .argument("[package]", "package name to analyze (e.g., axios or axios@1.14.1)")
+    .option("--json", "Output results as JSON")
+    .option("--skip-github", "Skip GitHub verification (faster)")
+    .action(async (pkg, opts) => {
         if (!pkg) {
-            console.log("Please provide a package name");
+            program.help();
             return;
         }
-        await analyzePackage(pkg);
+
+        // Support package@version syntax
+        let name = pkg;
+        let version;
+        const atIndex = pkg.lastIndexOf("@");
+        if (atIndex > 0) {
+            name = pkg.slice(0, atIndex);
+            version = pkg.slice(atIndex + 1);
+        }
+
+        await analyzePackage(name, version, {
+            json: opts.json,
+            skipGithub: opts.skipGithub,
+        });
     });
 
 program
     .command("scan")
-    .description("Scan current project dependencies")
-    .action(scanProject);
-    
+    .description("Scan all project dependencies for supply chain risks")
+    .option("-v, --verbose", "Show detailed analysis for each package")
+    .option("--json", "Output results as JSON")
+    .option("--skip-github", "Skip GitHub verification (faster)")
+    .action(async (opts) => {
+        await scanProject({
+            verbose: opts.verbose,
+            json: opts.json,
+            skipGithub: opts.skipGithub,
+        });
+    });
+
 program
-  .command("install <pkg>")
-  .description("Analyze and install package safely")
-  .action(async (pkg) => {
-    const { analyzeAndPrompt } = await import("../src/install.js");
-    await analyzeAndPrompt(pkg);
-  });
+    .command("install <pkg>")
+    .description("Analyze and safely install a package")
+    .action(async (pkg) => {
+        const { analyzeAndPrompt } = await import("../src/install.js");
+        await analyzeAndPrompt(pkg);
+    });
+
 program.parse();

package/package.json

@@ -1,22 +1,31 @@
 {
   "name": "install-guard",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "main": "index.js",
   "bin": {
     "install-guard": "./bin/cli.js"
   },
-  
   "type": "module",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "author": "Sarthak Kumar Sahoo",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SarthakSahoo1407/install-guard.git"
+  },
   "license": "MIT",
-  "description": "Check if an npm package is safe before installing",
+  "description": "Analyze npm packages for security risks before installing",
   "dependencies": {
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "ora": "^9.3.0"
   },
-  "keywords": ["npm", "security", "cli", "dependency", "audit"]
+  "keywords": [
+    "npm",
+    "security",
+    "cli",
+    "dependency",
+    "audit"
+  ]
 }

package/src/analyze.js

@@ -1,34 +1,27 @@
-import chalk from "chalk";
 import ora from "ora";
-import { getPackageData } from "./npm.js";
-import { calculateRisk } from "./score.js";
+import { runPipeline } from "./services/pipeline.js";
+import { formatPipelineResult } from "./format.js";
 
-export async function analyze(pkgName) {
-    const spinner = ora(`Analyzing ${pkgName}...`).start();
+/**
+ * Analyze a package and print results to stdout.
+ * Returns the structured result.
+ */
+export async function analyze(pkgName, version, opts = {}) {
+    const spinner = ora(`Analyzing ${pkgName}${version ? `@${version}` : ""}...`).start();
 
     try {
-        const data = await getPackageData(pkgName);
-        const { score, warnings } = calculateRisk(data);
-
+        const result = await runPipeline(pkgName, version, opts);
         spinner.stop();
 
-        console.log(chalk.bold(`\n📦 ${data.name}`));
-        console.log(`Version: ${data.version}`);
-        console.log(`Downloads (weekly): ${data.downloads.toLocaleString()}`);
-        console.log(`Risk Score: ${score}/10`);
-
-        if (score <= 3) {
-            console.log(chalk.green("✅ Low risk"));
-        } else if (score <= 6) {
-            console.log(chalk.yellow("⚠ Medium risk"));
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
         } else {
-            console.log(chalk.red("🚨 High risk"));
+            console.log(formatPipelineResult(result));
         }
 
-        warnings.forEach((w) => {
-            console.log(chalk.yellow(`⚠ ${w}`));
-        });
+        return result;
     } catch (err) {
-        spinner.fail("Failed to fetch package");
+        spinner.fail(`Failed to analyze "${pkgName}": ${err.message}`);
+        return null;
     }
 }

package/src/checks/dependencyDiff.js

@@ -0,0 +1,114 @@
+import { getDownloads, getRegistryData } from "../utils/registry.js";
+import { checkTyposquatName } from "./typosquat.js";
+
+/**
+ * Compares dependencies between the current and previous version.
+ * Flags newly added dependencies and analyzes them for suspiciousness.
+ */
+export async function checkDependencyDiff(ctx) {
+  const findings = [];
+
+  const current = ctx.dependencies;
+  const previous = ctx.previousDependencies;
+
+  const added = Object.keys(current).filter((d) => !(d in previous));
+  const removed = Object.keys(previous).filter((d) => !(d in current));
+
+  if (added.length === 0 && removed.length === 0) {
+    findings.push({
+      severity: "info",
+      message: "No dependency changes from previous version",
+      score: 0,
+    });
+    return { id: "dependency-diff", findings };
+  }
+
+  if (removed.length > 0) {
+    findings.push({
+      severity: "info",
+      message: `Removed dependencies: ${removed.join(", ")}`,
+      score: 0,
+    });
+  }
+
+  if (added.length > 0) {
+    findings.push({
+      severity: "high",
+      message: `New dependencies added: ${added.join(", ")}`,
+      score: 3,
+    });
+
+    // Deep-analyze each newly added dependency
+    for (const dep of added) {
+      const subFindings = await analyzeSuspiciousDep(dep);
+      findings.push(...subFindings);
+    }
+  }
+
+  return { id: "dependency-diff", findings };
+}
+
+async function analyzeSuspiciousDep(name) {
+  const findings = [];
+
+  // Typosquatting check
+  const typo = checkTyposquatName(name);
+  if (typo) {
+    findings.push({
+      severity: "critical",
+      message: `New dep "${name}" looks like typosquat of "${typo}"`,
+      score: 5,
+    });
+  }
+
+  try {
+    const registry = await getRegistryData(name);
+    const downloads = await getDownloads(name);
+    const latest = registry["dist-tags"]?.latest;
+    const publishTime = registry.time?.[latest];
+
+    // Low downloads
+    if (downloads.downloads < 500) {
+      findings.push({
+        severity: "high",
+        message: `New dep "${name}" has very low downloads (${downloads.downloads}/week)`,
+        score: 4,
+      });
+    }
+
+    // Very new package
+    if (publishTime) {
+      const ageDays =
+        (Date.now() - new Date(publishTime).getTime()) / (1000 * 60 * 60 * 24);
+      if (ageDays < 30) {
+        findings.push({
+          severity: "high",
+          message: `New dep "${name}" is less than 30 days old`,
+          score: 4,
+        });
+      }
+    }
+
+    // Has install scripts
+    const versionData = registry.versions?.[latest];
+    if (
+      versionData?.scripts?.postinstall ||
+      versionData?.scripts?.preinstall ||
+      versionData?.scripts?.install
+    ) {
+      findings.push({
+        severity: "critical",
+        message: `New dep "${name}" has install scripts`,
+        score: 5,
+      });
+    }
+  } catch {
+    findings.push({
+      severity: "high",
+      message: `New dep "${name}" could not be resolved on npm`,
+      score: 4,
+    });
+  }
+
+  return findings;
+}