npmguard-cli 0.1.0

package/dist/audit-source.d.ts

@@ -0,0 +1,12 @@
+export interface AuditResult {
+    packageName: string;
+    version: string;
+    verdict: "SAFE" | "WARNING" | "CRITICAL";
+    score: number;
+    capabilities: string[];
+    reportCid?: string;
+    sourceCid?: string;
+}
+export interface AuditSource {
+    getAudit(packageName: string, version: string): Promise<AuditResult | null>;
+}

package/dist/audit-source.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/check.d.ts

@@ -0,0 +1,2 @@
+import type { AuditSource } from "../audit-source.js";
+export declare function checkCommand(projectPath: string, auditSource: AuditSource): Promise<void>;

package/dist/commands/check.js

@@ -0,0 +1,124 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+import ora from "ora";
+import { scanProject } from "../scanner.js";
+function verdictLabel(verdict, score) {
+    switch (verdict) {
+        case "SAFE":
+            return chalk.green(`✅ SAFE (${score})`);
+        case "WARNING":
+            return chalk.yellow(`⚠️  WARNING (${score})`);
+        case "CRITICAL":
+            return chalk.red(`❌ CRITICAL (${score})`);
+        default:
+            return chalk.gray("❓ UNKNOWN");
+    }
+}
+function reportLink(audit) {
+    if (audit.reportCid) {
+        return chalk.gray(`  📄 Report: https://gateway.pinata.cloud/ipfs/${audit.reportCid}`);
+    }
+    return "";
+}
+function npmLink(name, version) {
+    return chalk.gray(`  📦 https://www.npmjs.com/package/${name}/v/${version}`);
+}
+export async function checkCommand(projectPath, auditSource) {
+    const spinner = ora("Scanning project dependencies...").start();
+    const deps = await scanProject(projectPath);
+    spinner.text = `Found ${deps.length} dependencies. Checking audits...`;
+    const table = new Table({
+        head: [
+            chalk.bold("Package"),
+            chalk.bold("Installed"),
+            chalk.bold("Latest"),
+            chalk.bold("NpmGuard Verdict"),
+        ],
+        style: { head: [], border: [] },
+    });
+    let safeCount = 0;
+    let warningCount = 0;
+    let criticalCount = 0;
+    let notAuditedCount = 0;
+    const details = [];
+    for (const dep of deps) {
+        const versionToCheck = dep.latest ?? dep.installed;
+        const audit = await auditSource.getAudit(dep.name, versionToCheck);
+        let verdictCol;
+        if (!dep.hasUpdate) {
+            const currentAudit = await auditSource.getAudit(dep.name, dep.installed);
+            if (currentAudit) {
+                verdictCol = verdictLabel(currentAudit.verdict, currentAudit.score);
+                if (currentAudit.verdict === "SAFE")
+                    safeCount++;
+                else if (currentAudit.verdict === "WARNING") {
+                    warningCount++;
+                    details.push(reportLink(currentAudit));
+                }
+                else if (currentAudit.verdict === "CRITICAL") {
+                    criticalCount++;
+                    details.push(reportLink(currentAudit));
+                }
+            }
+            else {
+                verdictCol = chalk.gray("❓ NOT AUDITED");
+                notAuditedCount++;
+                details.push(npmLink(dep.name, dep.installed));
+            }
+        }
+        else if (audit) {
+            verdictCol = verdictLabel(audit.verdict, audit.score);
+            if (audit.verdict === "SAFE")
+                safeCount++;
+            else if (audit.verdict === "WARNING") {
+                warningCount++;
+                details.push(reportLink(audit));
+            }
+            else if (audit.verdict === "CRITICAL") {
+                criticalCount++;
+                details.push(reportLink(audit));
+            }
+        }
+        else {
+            verdictCol = chalk.gray("❓ NOT AUDITED");
+            notAuditedCount++;
+            details.push(npmLink(dep.name, versionToCheck));
+        }
+        table.push([
+            dep.name,
+            dep.installed,
+            dep.latest ?? dep.installed,
+            verdictCol,
+        ]);
+    }
+    spinner.stop();
+    console.log();
+    console.log(chalk.bold("📦 NpmGuard Dependency Audit"));
+    console.log();
+    console.log(table.toString());
+    console.log();
+    // Summary
+    const parts = [];
+    if (safeCount > 0)
+        parts.push(chalk.green(`${safeCount} safe`));
+    if (warningCount > 0)
+        parts.push(chalk.yellow(`${warningCount} warnings`));
+    if (criticalCount > 0)
+        parts.push(chalk.red(`${criticalCount} critical`));
+    if (notAuditedCount > 0)
+        parts.push(chalk.gray(`${notAuditedCount} not audited`));
+    console.log(`  ${parts.join(" · ")}`);
+    // Show detail links
+    if (details.length > 0) {
+        console.log();
+        for (const d of details) {
+            if (d)
+                console.log(d);
+        }
+    }
+    if (criticalCount > 0) {
+        console.log();
+        console.log(chalk.red.bold(`  ⛔ ${criticalCount} package(s) flagged as CRITICAL — do not update without reviewing the report.`));
+    }
+    console.log();
+}

package/dist/commands/install.d.ts

@@ -0,0 +1,2 @@
+import type { AuditSource } from "../audit-source.js";
+export declare function installCommand(packageSpec: string, auditSource: AuditSource): Promise<void>;

package/dist/commands/install.js

@@ -0,0 +1,78 @@
+import chalk from "chalk";
+import ora from "ora";
+import { execSync } from "node:child_process";
+export async function installCommand(packageSpec, auditSource) {
+    // Parse package@version or just package
+    const atIndex = packageSpec.lastIndexOf("@");
+    let packageName;
+    let requestedVersion = null;
+    if (atIndex > 0) {
+        packageName = packageSpec.slice(0, atIndex);
+        requestedVersion = packageSpec.slice(atIndex + 1);
+    }
+    else {
+        packageName = packageSpec;
+    }
+    const spinner = ora(`Checking audit for ${packageName}...`).start();
+    // Get latest version from npm if not specified
+    if (!requestedVersion) {
+        try {
+            const resp = await fetch(`https://registry.npmjs.org/${packageName}/latest`);
+            if (resp.ok) {
+                const data = await resp.json();
+                requestedVersion = data.version;
+            }
+        }
+        catch {
+            // continue without version
+        }
+    }
+    if (!requestedVersion) {
+        spinner.fail("Could not determine package version.");
+        return;
+    }
+    const audit = await auditSource.getAudit(packageName, requestedVersion);
+    spinner.stop();
+    if (!audit) {
+        console.log();
+        console.log(chalk.gray(`  ❓ ${packageName}@${requestedVersion} has not been audited by NpmGuard.`));
+        console.log(chalk.gray("  Proceeding with standard npm install..."));
+        console.log();
+        execSync(`npm install ${packageSpec}`, { stdio: "inherit" });
+        return;
+    }
+    console.log();
+    console.log(chalk.bold(`  📦 ${packageName}@${requestedVersion}`));
+    console.log();
+    if (audit.verdict === "SAFE") {
+        console.log(chalk.green(`  ✅ SAFE (score: ${audit.score})`));
+        if (audit.capabilities.length > 0) {
+            console.log(chalk.gray(`  Capabilities: ${audit.capabilities.join(", ")}`));
+        }
+        console.log();
+        execSync(`npm install ${packageSpec}`, { stdio: "inherit" });
+    }
+    else if (audit.verdict === "WARNING") {
+        console.log(chalk.yellow(`  ⚠️  WARNING (score: ${audit.score})`));
+        console.log(chalk.yellow(`  Capabilities: ${audit.capabilities.join(", ")}`));
+        if (audit.reportCid) {
+            console.log(chalk.gray(`  Report: https://gateway.pinata.cloud/ipfs/${audit.reportCid}`));
+        }
+        console.log();
+        console.log(chalk.yellow("  Installing with warning..."));
+        console.log();
+        execSync(`npm install ${packageSpec}`, { stdio: "inherit" });
+    }
+    else if (audit.verdict === "CRITICAL") {
+        console.log(chalk.red(`  ❌ CRITICAL (score: ${audit.score})`));
+        console.log(chalk.red(`  Capabilities: ${audit.capabilities.join(", ")}`));
+        if (audit.reportCid) {
+            console.log(chalk.gray(`  Report: https://gateway.pinata.cloud/ipfs/${audit.reportCid}`));
+        }
+        console.log();
+        console.log(chalk.red.bold("  ⛔ Installation blocked. This package has critical security issues."));
+        console.log(chalk.gray("  Use --force to install anyway: npmguard install --force " +
+            packageSpec));
+        console.log();
+    }
+}

package/dist/ens-source.d.ts

@@ -0,0 +1,4 @@
+import type { AuditSource, AuditResult } from "./audit-source.js";
+export declare class ENSAuditSource implements AuditSource {
+    getAudit(packageName: string, version: string): Promise<AuditResult | null>;
+}

package/dist/ens-source.js

@@ -0,0 +1,36 @@
+import { createPublicClient, http } from "viem";
+import { sepolia } from "viem/chains";
+const client = createPublicClient({
+    chain: sepolia,
+    transport: http("https://ethereum-sepolia-rpc.publicnode.com"),
+});
+export class ENSAuditSource {
+    async getAudit(packageName, version) {
+        // 1.14.0 → 1-14-0
+        const versionSlug = version.replace(/\./g, "-");
+        const ensName = `${versionSlug}.${packageName}.npmguard.eth`;
+        try {
+            const [verdict, score, capabilities, reportCid, sourceCid] = await Promise.all([
+                client.getEnsText({ name: ensName, key: "verdict" }),
+                client.getEnsText({ name: ensName, key: "score" }),
+                client.getEnsText({ name: ensName, key: "capabilities" }),
+                client.getEnsText({ name: ensName, key: "reportCid" }),
+                client.getEnsText({ name: ensName, key: "sourceCid" }),
+            ]);
+            if (!verdict)
+                return null;
+            return {
+                packageName,
+                version,
+                verdict: verdict,
+                score: score ? parseInt(score, 10) : 0,
+                capabilities: capabilities ? capabilities.split(",") : [],
+                reportCid: reportCid ?? undefined,
+                sourceCid: sourceCid ?? undefined,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { ENSAuditSource } from "./ens-source.js";
+import { MockAuditSource } from "./mock-source.js";
+import { checkCommand } from "./commands/check.js";
+import { installCommand } from "./commands/install.js";
+const program = new Command();
+program
+    .name("npmguard")
+    .description("Check npm packages against NpmGuard security audits")
+    .version("0.1.0");
+program
+    .command("check")
+    .description("Scan project dependencies and check audit status for available updates")
+    .option("-p, --path <path>", "Path to project directory", ".")
+    .option("--mock", "Use mock data instead of ENS")
+    .action(async (opts) => {
+    const auditSource = opts.mock
+        ? new MockAuditSource()
+        : new ENSAuditSource();
+    const projectPath = resolve(opts.path);
+    await checkCommand(projectPath, auditSource);
+});
+program
+    .command("install <package>")
+    .description("Install a package after checking its NpmGuard audit status")
+    .option("--force", "Install even if flagged as CRITICAL")
+    .option("--mock", "Use mock data instead of ENS")
+    .action(async (pkg, opts) => {
+    const auditSource = opts.mock
+        ? new MockAuditSource()
+        : new ENSAuditSource();
+    await installCommand(pkg, auditSource);
+});
+program.parse();

package/dist/mock-source.d.ts

@@ -0,0 +1,4 @@
+import type { AuditSource, AuditResult } from "./audit-source.js";
+export declare class MockAuditSource implements AuditSource {
+    getAudit(packageName: string, version: string): Promise<AuditResult | null>;
+}

package/dist/mock-source.js

@@ -0,0 +1,50 @@
+// Mock data for demo — simulates what ENS would return
+const MOCK_AUDITS = {
+    "axios@1.14.0": {
+        packageName: "axios",
+        version: "1.14.0",
+        verdict: "SAFE",
+        score: 92,
+        capabilities: ["network"],
+        reportCid: "bafkreia3dgrfewkj6q4sdpqrbxcfuxa47d3ku4uzbauqdk4qo7gok3geoi",
+        sourceCid: "bafybeif372guv6lwfzdx622uyqmtk3bkxuhsozd6j5bmzxgqohe4ste77q",
+    },
+    "axios@1.13.0": {
+        packageName: "axios",
+        version: "1.13.0",
+        verdict: "SAFE",
+        score: 90,
+        capabilities: ["network"],
+        reportCid: "bafkreia3dgrfewkj6q4sdpqrbxcfuxa47d3ku4uzbauqdk4qo7gok3geoi",
+    },
+    "lodash@4.18.1": {
+        packageName: "lodash",
+        version: "4.18.1",
+        verdict: "WARNING",
+        score: 65,
+        capabilities: ["network", "filesystem"],
+        reportCid: "QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX", // mock
+    },
+    "express@5.2.1": {
+        packageName: "express",
+        version: "5.2.1",
+        verdict: "CRITICAL",
+        score: 12,
+        capabilities: ["network", "filesystem", "process_spawn", "binary_download"],
+        reportCid: "QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ", // mock
+    },
+    "chalk@5.6.2": {
+        packageName: "chalk",
+        version: "5.6.2",
+        verdict: "SAFE",
+        score: 98,
+        capabilities: [],
+        reportCid: "QmRf22bZar3WKmojipms22PkXH1MZGmvsqzQtuSvQE3uhm", // mock
+    },
+};
+export class MockAuditSource {
+    async getAudit(packageName, version) {
+        const key = `${packageName}@${version}`;
+        return MOCK_AUDITS[key] ?? null;
+    }
+}

package/dist/scanner.d.ts

@@ -0,0 +1,7 @@
+export interface PackageDep {
+    name: string;
+    installed: string;
+    latest: string | null;
+    hasUpdate: boolean;
+}
+export declare function scanProject(projectPath: string): Promise<PackageDep[]>;

package/dist/scanner.js

@@ -0,0 +1,35 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export async function scanProject(projectPath) {
+    const pkgPath = join(projectPath, "package.json");
+    const raw = await readFile(pkgPath, "utf-8");
+    const pkg = JSON.parse(raw);
+    const allDeps = {
+        ...pkg.dependencies,
+        ...pkg.devDependencies,
+    };
+    const results = [];
+    for (const [name, versionRange] of Object.entries(allDeps)) {
+        // Strip ^, ~, >= etc. to get the installed version
+        const installed = versionRange.replace(/^[\^~>=<]*/, "");
+        // Fetch latest from npm registry
+        let latest = null;
+        try {
+            const resp = await fetch(`https://registry.npmjs.org/${name}/latest`);
+            if (resp.ok) {
+                const data = await resp.json();
+                latest = data.version;
+            }
+        }
+        catch {
+            // Network error — skip
+        }
+        results.push({
+            name,
+            installed,
+            latest,
+            hasUpdate: latest !== null && latest !== installed,
+        });
+    }
+    return results;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "npmguard-cli",
+  "version": "0.1.0",
+  "description": "Check npm packages against NpmGuard security audits on ENS before installing",
+  "bin": {
+    "npmguard-cli": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "npm",
+    "security",
+    "audit",
+    "ens",
+    "ipfs",
+    "supply-chain"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.4.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.1.0",
+    "ora": "^8.2.0",
+    "viem": "^2.34.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0"
+  }
+}