install-guard 1.0.0

package/README.md

@@ -0,0 +1,158 @@
+# 🚨 Should You Trust That npm Package Before Installing?
+
+**dep-shield** analyzes npm packages and tells you if they are safe to install — before you install them.
+
+---
+
+<details>
+<summary>Example</summary>
+
+```bash
+npx dep-shield install some-random-lib
+```
+
+```
+📦 Analyzing some-random-lib...
+
+Downloads (weekly): 120
+Risk Score: 8/10 🚨 High Risk
+
+⚠ Very low downloads
+⚠ Uses install scripts
+⚠ Recently published
+
+❓ Do you still want to install this package? (y/n)
+```
+
+</details>
+
+---
+
+## 😬 The Problem
+
+Installing npm packages blindly is risky.
+
+- Malicious packages are published daily
+- Popular packages get compromised
+- `npm audit` only checks known vulnerabilities — not trust
+
+You shouldn't have to guess if a package is safe.
+
+---
+
+## 🛡️ The Solution
+
+dep-shield gives you a **risk score before you install anything**.
+
+---
+
+## ⚡ Quick Start
+
+Check a package:
+
+```bash
+npx dep-shield axios
+```
+
+Safely install a package:
+
+```bash
+npx dep-shield install axios
+```
+
+Scan your project:
+
+```bash
+npx dep-shield scan
+```
+
+---
+
+## 🧠 How Risk Score Works
+
+dep-shield analyzes:
+
+- 📉 Weekly downloads (popularity)
+- 🕒 Last update time
+- ⚠ Install/postinstall scripts
+- 📦 Version activity
+
+Each factor contributes to a **risk score (0–10)**.
+
+Lower score = safer package.
+
+---
+
+## 📊 Example Results
+
+### ✅ Safe package
+
+```
+axios
+Downloads: 20,000,000+
+Risk: 1/10
+```
+
+---
+
+### 🚨 Risky package
+
+```
+some-lib
+Downloads: 200
+Risk: 8/10
+
+⚠ Low downloads
+⚠ Uses install scripts
+```
+
+---
+
+## ✨ Features
+
+- 🔍 Analyze any npm package instantly
+- ⚠ Risk scoring (0–10)
+- 🛑 Block risky installs
+- 📦 Project-wide dependency scan
+- ⚡ Zero setup (works with npx)
+
+---
+
+## 🤔 Why not npm audit?
+
+| Feature               | npm audit | dep-shield |
+|-----------------------|-----------|------------|
+| Known vulnerabilities | ✅        | ✅         |
+| Trust analysis        | ❌        | ✅         |
+| Pre-install check     | ❌        | ✅         |
+| Install blocking      | ❌        | ✅         |
+
+---
+
+## 📦 Install globally
+
+```bash
+npm install -g dep-shield
+```
+
+---
+
+## 🔮 Roadmap
+
+- 🔍 GitHub activity analysis
+- 🧠 Typosquatting detection
+- 📊 Dependency tree visualization
+- 🔌 CI/CD integration
+
+---
+
+## 🤝 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

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { analyzePackage } from "../src/index.js";
+import { scanProject } from "../src/scan.js";
+
+const program = new Command();
+
+program
+    .name("dep-shield")
+    .description("Check npm package risk before installing");
+
+program
+    .argument("[package]", "package name to analyze")
+    .action(async (pkg) => {
+        if (!pkg) {
+            console.log("Please provide a package name");
+            return;
+        }
+        await analyzePackage(pkg);
+    });
+
+program
+    .command("scan")
+    .description("Scan current project dependencies")
+    .action(scanProject);
+    
+program
+  .command("install <pkg>")
+  .description("Analyze and install package safely")
+  .action(async (pkg) => {
+    const { analyzeAndPrompt } = await import("../src/install.js");
+    await analyzeAndPrompt(pkg);
+  });
+program.parse();

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "install-guard",
+  "version": "1.0.0",
+  "main": "index.js",
+  "bin": {
+    "npm-guard": "./bin/cli.js"
+  },
+  
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Sarthak Kumar Sahoo",
+  "license": "MIT",
+  "description": "Check if an npm package is safe before installing",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "ora": "^9.3.0"
+  },
+  "keywords": ["npm", "security", "cli", "dependency", "audit"]
+}

package/src/analyze.js

@@ -0,0 +1,34 @@
+import chalk from "chalk";
+import ora from "ora";
+import { getPackageData } from "./npm.js";
+import { calculateRisk } from "./score.js";
+
+export async function analyze(pkgName) {
+    const spinner = ora(`Analyzing ${pkgName}...`).start();
+
+    try {
+        const data = await getPackageData(pkgName);
+        const { score, warnings } = calculateRisk(data);
+
+        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"));
+        } else {
+            console.log(chalk.red("🚨 High risk"));
+        }
+
+        warnings.forEach((w) => {
+            console.log(chalk.yellow(`⚠ ${w}`));
+        });
+    } catch (err) {
+        spinner.fail("Failed to fetch package");
+    }
+}

package/src/index.js

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

package/src/install.js

@@ -0,0 +1,44 @@
+import { execSync } from "child_process";
+import readline from "readline";
+import { getPackageData } from "./npm.js";
+import { calculateRisk } from "./score.js";
+
+function askQuestion(query) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    return new Promise((resolve) =>
+        rl.question(query, (ans) => {
+            rl.close();
+            resolve(ans);
+        })
+    );
+}
+
+export async function analyzeAndPrompt(pkgName) {
+    console.log(`\nAnalyzing ${pkgName}...\n`);
+
+    const data = await getPackageData(pkgName);
+    const { score, warnings } = calculateRisk(data);
+
+    console.log(`Risk Score: ${score}/10`);
+
+    warnings.forEach((w) => console.log(`⚠ ${w}`));
+
+    if (score >= 6) {
+        const ans = await askQuestion(
+            "\nHigh risk package. Continue install? (y/n): "
+        );
+
+        if (ans.toLowerCase() !== "y") {
+            console.log("Installation aborted.");
+            return;
+        }
+    }
+
+    console.log("\nInstalling...\n");
+
+    execSync(`npm install ${pkgName}`, { stdio: "inherit" });
+}

package/src/npm.js

@@ -0,0 +1,27 @@
+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 [registryRes, downloadRes] = await Promise.all([
+    axios.get(registryUrl),
+    axios.get(downloadUrl),
+  ]);
+
+  const data = registryRes.data;
+  const latest = data["dist-tags"].latest;
+  const versionData = data.versions[latest];
+
+  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,
+  };
+}

package/src/scan.js

@@ -0,0 +1,15 @@
+import fs from "fs";
+import { analyzePackage } from "./index.js";
+
+export async function scanProject() {
+    const pkg = JSON.parse(fs.readFileSync("package.json"));
+
+    const deps = {
+        ...pkg.dependencies,
+        ...pkg.devDependencies,
+    };
+
+    for (const dep of Object.keys(deps)) {
+        await analyzePackage(dep);
+    }
+}

package/src/score.js

@@ -0,0 +1,47 @@
+export function calculateRisk(pkg) {
+    let score = 0;
+    const warnings = [];
+
+    // 🟢 Popularity (VERY IMPORTANT)
+    if (pkg.downloads < 1000) {
+        score += 3;
+        warnings.push("Very low downloads");
+    } else if (pkg.downloads < 10000) {
+        score += 2;
+        warnings.push("Low downloads");
+    }
+
+    // 🟡 Update recency
+    const lastUpdate = new Date(pkg.lastPublished);
+    const now = new Date();
+    const diffMonths = (now - lastUpdate) / (1000 * 60 * 60 * 24 * 30);
+
+    if (diffMonths > 12) {
+        score += 3;
+        warnings.push("Not updated in over a year");
+    } else if (diffMonths > 6) {
+        score += 1;
+        warnings.push("Not updated recently");
+    }
+
+    // 🔴 Install scripts (HIGH RISK)
+    if (pkg.hasInstallScript) {
+        score += 3;
+        warnings.push("Uses install/postinstall scripts");
+    }
+
+    // 🟢 High trust signal
+    if (pkg.downloads > 1000000) {
+        score -= 2; // reduce risk
+    }
+
+    if (pkg.downloads > 5000000) {
+        score -= 2;
+    }
+
+    // Normalize
+    if (score < 0) score = 0;
+    if (score > 10) score = 10;
+
+    return { score, warnings };
+}