install-guard 1.1.1 → 1.1.2

package/README.md

@@ -4,7 +4,7 @@
 
 # 🚨 Should You Trust That npm Package Before Installing?
 
-**install-guard** analyzes npm packages for security risks and tells you if they're safe — **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.
 
 ---
 
@@ -16,41 +16,50 @@ $ npx install-guard install some-random-lib
 ```
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   📦 some-random-lib v0.1.3
   A random utility library
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  Risk Score: 8/10  🚨 High Risk
-  ████████░░
+  Risk Level: 💀 CRITICAL  (9/10)
+  █████████░
 
-─────────────────────────────────────────────────
+──────────────────────────────────────────────────────────
 
   📊 Package Info
 
-  Downloads (weekly)    120
-  Maintainers           1
-  License               Unknown
-  Last Published        3 days ago
-  Dependencies          14
-  Versions              2
+  Downloads (weekly)     120
+  Maintainers            unknown-person
+  License                Unknown
+  Published              6 hours ago
+  Dependencies           3
+  Total Versions         2
+  Repository             ✘ None
 
-─────────────────────────────────────────────────
+──────────────────────────────────────────────────────────
 
-  🔍 Security Checks
+  🔍 Findings
 
-  ✘ Downloads:        Very low (120/week)
-  ✔ Last Updated:     Recently updated
-  ✘ Install Scripts:  Has install/postinstall scripts
-  ⚠ Maintainers:      Single maintainer
-  ✘ License:          No license specified
-  ⚠ Repository:       No repository URL
-  ✘ Package Age:      Published less than 30 days ago
-  ✔ Dependencies:     14 direct dependencies
+  ✘ 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
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+──────────────────────────────────────────────────────────
 
-  ⚠ High risk package. Continue install? (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>
@@ -59,11 +68,12 @@ $ npx install-guard install some-random-lib
 
 ## 😬 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**
+- 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.
 
@@ -71,19 +81,25 @@ You shouldn't have to guess if a package is safe.
 
 ## 🛡️ The Solution
 
-install-guard gives you a **risk score before you install anything**, powered by 10+ security checks.
+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
 
-Analyze a package:
+Analyze any package:
 
 ```bash
 npx install-guard axios
 ```
 
-Safely install with a risk check:
+Analyze a specific version:
+
+```bash
+npx install-guard axios@1.14.0
+```
+
+Safely install with pre-check:
 
 ```bash
 npx install-guard install axios
@@ -95,122 +111,196 @@ Scan your entire project:
 npx install-guard scan
 ```
 
-Scan with detailed output per package:
+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 runs **10+ security checks** on every package:
+- Download count check
+- Publish age check
+- Typosquatting detection
+- Install script detection
 
-| Check | What it detects |
-|-------|----------------|
-| 📉 **Downloads** | Low popularity = higher risk |
-| 🕒 **Last Updated** | Abandoned packages |
-| ⚠ **Install Scripts** | `preinstall` / `postinstall` hooks (common attack vector) |
-| 👥 **Maintainers** | Single or no maintainers |
-| 📜 **License** | Missing or non-permissive licenses |
-| 🔗 **Repository** | No source code link |
-| 📅 **Package Age** | Brand new packages (< 30 days) |
-| 📦 **Dependencies** | High dependency count |
-| 🚫 **Deprecated** | Flagged as deprecated on npm |
-| 🧠 **Typosquatting** | Names suspiciously similar to popular packages |
+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)**. Lower = safer.
+### Safe Version Recommendation
+
+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 v1.7.2
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📦 axios v1.15.0
+  Promise based HTTP client for the browser and node.js
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  Risk Score: 1/10  ✅ Low Risk
+  Risk Level: ✅ LOW  (1/10)
   █░░░░░░░░░
 
-  🔍 Security Checks
-  ✔ Downloads:       44,392,817/week
-  ✔ Last Updated:    Recently updated
-  ✔ Install Scripts: No install scripts
-  ✔ Maintainers:     3 maintainers
-  ✔ License:         MIT
-  ✔ Repository:      Has repository link
-  ✔ Package Age:     9+ year(s) old
-  ✔ Dependencies:    8 direct dependencies
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🔍 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
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-### 🚨 Risky package
+### 🚨 Compromised package (simulated)
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  📦 some-lib v0.1.0
-
-  Risk Score: 8/10  🚨 High Risk
-  ████████░░
-
-  🔍 Security Checks
-  ✘ Downloads:       Very low (83/week)
-  ✘ Install Scripts: Has install/postinstall scripts
-  ✘ License:         No license specified
-  ⚠ Maintainers:     Single maintainer
-  ⚠ Repository:      No repository URL
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📦 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              Risk        Status
+  Package              Score     Level
   ────────────────────────────────────────────
-  some-lib             8/10        🚨 High Risk
-  old-utils            5/10        ⚠  Medium
-  express              0/10        ✅ Safe
-  axios                1/10        ✅ Safe
-
-─────────────────────────────────────────────────
-  Summary: 2 safe · 1 medium · 1 high risk
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  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
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## 🏗️ 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
 
-- 🔍 **Deep analysis** — 10+ security checks per package
-- 🧠 **Typosquatting detection** — catches lookalike package names
-- ⚠ **Risk scoring (0–10)** — instant safety assessment
-- 🛑 **Block risky installs** — prompts before installing medium/high risk packages
-- 📋 **Project-wide scan** — audit all dependencies in one command
-- 📊 **Summary table** — sorted by risk with safe/medium/high breakdown
-- ⚡ **Zero setup** — works instantly with `npx`
-- 🎨 **Beautiful CLI output** — color-coded, easy to read
+- 🔍 **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      | ❌        | ✅            |
-| Typosquatting check   | ❌        | ✅            |
-| License analysis      | ❌        | ✅            |
-| Maintainer check      | ❌        | ✅            |
-| Package age check     | ❌        | ✅            |
+| 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.
 
 ---
 
@@ -224,12 +314,12 @@ npm install -g install-guard
 
 ## 🔮 Roadmap
 
-- 🔍 GitHub activity analysis
-- 🧠 Advanced typosquatting (permutations, homoglyphs)
 - 📊 Dependency tree visualization
 - 🔌 CI/CD integration (exit codes for pipelines)
-- 🏷️ `.install-guardrc` config for custom thresholds
-- 📝 JSON/CSV report export
+- 🏷️ `.install-guardrc` config for custom risk thresholds
+- 📝 HTML/CSV report export
+- 🧠 Advanced typosquatting (permutations, homoglyphs, scope confusion)
+- 🔔 Webhook notifications for risky dependencies
 
 ---
 
@@ -243,16 +333,3 @@ PRs welcome! Let's make npm safer together.
 
 If you find this useful, consider giving it a star ⭐
 It helps others discover the project!
-
----
-
-## 🤝 Contributing
-
-PRs welcome! Let's make npm safer together.
-
----
-
-## ⭐ Support
-
-If you find this useful, consider giving it a star ⭐  
-It helps others discover the project!

package/bin/cli.js

@@ -8,25 +8,46 @@ const program = new Command();
 
 program
     .name("install-guard")
-    .description("Analyze npm packages for security risks before installing")
-    .version("2.0.0");
+    .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) {
             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 all project dependencies for risks")
+    .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 });
+        await scanProject({
+            verbose: opts.verbose,
+            json: opts.json,
+            skipGithub: opts.skipGithub,
+        });
     });
 
 program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "install-guard",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "main": "index.js",
   "bin": {
     "install-guard": "./bin/cli.js"
@@ -10,6 +10,10 @@
     "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": "Analyze npm packages for security risks before installing",
   "dependencies": {

package/src/analyze.js

@@ -1,19 +1,25 @@
 import ora from "ora";
-import { getPackageData } from "./npm.js";
-import { calculateRisk } from "./score.js";
-import { formatAnalysis } from "./format.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 result = calculateRisk(data);
-
+        const result = await runPipeline(pkgName, version, opts);
         spinner.stop();
-        console.log(formatAnalysis(data, result));
 
-        return { data, result };
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        } else {
+            console.log(formatPipelineResult(result));
+        }
+
+        return result;
     } catch (err) {
         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;
+}