iamsecure 0.1.0 → 0.1.3

package/README.md

@@ -1,14 +1,61 @@
 # iamsecure
 
-Find vulnerable dependencies and insecure code in your project, then rank them in two ways:
+[![npm version](https://img.shields.io/npm/v/iamsecure?color=d93a2b&label=npm)](https://www.npmjs.com/package/iamsecure)
+[![license: MIT](https://img.shields.io/badge/license-MIT-2f7fd8)](https://github.com/Ravindrabisht12/iamsecure/blob/main/LICENSE)
+![zero dependencies](https://img.shields.io/badge/dependencies-0-12a03b)
+![node >= 18](https://img.shields.io/badge/node-%E2%89%A518-339933)
+
+**Find vulnerable dependencies and insecure code, ranked by how dangerous they are in *your* app, not just by CVSS.**
+
+```bash
+npx iamsecure        # scan the current folder
+npx iamsecure --ui   # open the dashboard
+```
+
+<p align="center">
+  <img src="docs/images/terminal.png" alt="iamsecure terminal report" width="680">
+</p>
+
+Every finding is ranked in two ways:
 
 - **Real risk (worst first)** is the default. It shows how dangerous each issue is for *this* codebase.
 - **Severity (high → low)** is the raw CVSS / rule severity, the same thing `npm audit` shows.
 
-The two rankings differ a lot in practice. On a deliberately vulnerable Next.js app, 51 issues are "high" by severity but only 27 are high by real risk. A 9.8 CVE in a dev-only CLI tool drops to *low*. An 8.1 lodash advisory rises to *critical* because your API route calls the exact `_.template` function the advisory names.
+The two rankings differ a lot in practice. A 9.8 CVE in a dev-only CLI tool drops to *low*. An 8.1 lodash advisory rises to *critical* because your API route calls the exact `_.template` function the advisory names.
 
 It has **zero runtime dependencies** and needs only Node ≥ 18. A security scanner shouldn't add 300 packages to your supply chain.
 
+### Example: OWASP Juice Shop
+
+A scan of [OWASP Juice Shop](https://github.com/juice-shop/juice-shop), a deliberately vulnerable Node.js app:
+
+| | critical | high | medium | low |
+|---|---|---|---|---|
+| By raw severity | 16 | 51 | 44 | 2 |
+| **By real risk** | **16** | **40** | **44** | **13** |
+
+It covered 1,181 packages and 377 source files in about 5 seconds, and found the app's planted SQL injection in `routes/login.ts`, its `eval`, its path traversal routes and 11 hard-coded secrets.
+
+Twelve "high" findings dropped to medium or low:
+- Nine are in `tar`, which is installed but never imported anywhere.
+- The rest are in a dev-only build tool and a test file.
+
+One "high" `jsonwebtoken` advisory rose to *critical*, because the server's auth code imports that package.
+
+## Dashboard
+
+`npx iamsecure --ui` opens a local dashboard. Its **Fix list** groups every issue into one action, explains it in plain language (what's wrong, what could happen, where it runs, how to fix) and gives the exact install command.
+
+<p align="center">
+  <img src="docs/images/dashboard.png" alt="iamsecure dashboard: fix list" width="820">
+</p>
+
+The **Dependency tree** shows which of your direct dependencies brings in each vulnerable package. Its search answers "why is this installed?".
+
+<p align="center">
+  <img src="docs/images/dependency-tree.png" alt="iamsecure dependency tree" width="820">
+</p>
+
 ## Quick start
 
 ```bash

package/bin/iamsecure.js

@@ -121,13 +121,18 @@ try {
     }
   }
   if (values.ui) {
-    const { url } = await serveDashboard(report, {
+    const { url, replaced } = await serveDashboard(report, {
       port: Number(values.port),
       open: !values['no-open'],
       rescan: runScan,
       aiProvider: values.ai ?? null,
       analyze: values.ai ? makeAnalyzer({ provider: values.ai, model: values['ai-model'] }) : undefined,
     });
+    if (replaced) console.log(c.dim(`\nStopped the previous dashboard (${replaced.root}) and took over port ${replaced.port}.`));
+    const port = Number(new URL(url).port);
+    if (port !== Number(values.port)) {
+      console.log(c.yellow(`\n⚠ Port ${values.port} is busy by another app, using ${port}.`));
+    }
     console.log(`\n${c.bold('Dashboard:')} ${c.cyan(url)}  ${c.dim('(Ctrl+C to stop)')}`);
   }
 } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iamsecure",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Scan a codebase for vulnerable dependencies and insecure code, ranked by real-world risk \u2014 with an optional AI second opinion.",
   "author": "Ravindra Bisht",
   "repository": {

package/src/code/engine.js

@@ -43,9 +43,20 @@ export function taintedNames(code, lang) {
   return names;
 }
 
+/**
+ * The sink and its arguments: up to the `)` that closes the call (works without semicolons),
+ * or to the end of the line for sinks that aren't calls (`el.innerHTML = …`, `echo …`).
+ */
 function argsAfter(window, idx) {
-  // Text from the sink onwards, roughly up to the end of the call/statement.
-  return window.slice(idx).split(/;\s*(\n|$)/)[0];
+  const open = window.indexOf('(', idx);
+  const lineEnd = window.indexOf('\n', idx);
+  if (open === -1 || (lineEnd !== -1 && open > lineEnd)) return window.slice(idx, lineEnd === -1 ? undefined : lineEnd);
+  let depth = 0;
+  for (let i = open; i < window.length; i++) {
+    if (window[i] === '(') depth++;
+    else if (window[i] === ')' && --depth === 0) return window.slice(idx, i + 1);
+  }
+  return window.slice(idx);
 }
 
 const DYNAMIC = /\$\{|['"`]\s*\+|\+\s*['"`\w$]|\(\s*[\w$.[\]]+\s*[,)]|\(\s*\w+\s*\(|=\s*[\w$.[\]()]+\s*;?\s*$|\$\w+|\bf['"]|%\s*\(|\.format\(/;

package/src/report/terminal.js

@@ -1,3 +1,4 @@
+import os from 'node:os';
 import { sortFindings } from '../scan.js';
 
 const useColor = (process.stdout.isTTY || !!process.env.FORCE_COLOR) && !process.env.NO_COLOR;
@@ -209,7 +210,9 @@ export function printReport(report, { sort = 'risk', limit = 30, min } = {}) {
   out.push(c.gray('━'.repeat(width)));
   const fw = report.project.framework;
   const brand = `  ${c.bold('iamsecure')} ${c.gray('v' + report.tool.version)}`;
-  const where = c.gray(ellipsisStart(report.project.root, Math.max(10, width - 30)));
+  const home = os.homedir();
+  const shown = report.project.root.startsWith(home) ? '~' + report.project.root.slice(home.length) : report.project.root;
+  const where = c.gray(ellipsisStart(shown, Math.max(10, width - 30)));
   out.push(brand + ' '.repeat(Math.max(2, width - vlen(brand) - vlen(where) - 2)) + where);
   out.push(c.gray('━'.repeat(width)));
   out.push('');

package/src/scan.js

@@ -1,13 +1,13 @@
-import { loadProject } from './project.js';
-import { loadGraphs, scanDependencies, treeStats } from './deps/index.js';
-import { LEVELS } from './deps/cvss.js';
-import { analyzeSource } from './code/index.js';
-import { scanCode } from './code/engine.js';
-import { scanSecrets } from './code/secrets.js';
-import { loadExploitData } from './risk/exploit.js';
-import { scoreFindings } from './risk/score.js';
+import { loadProject } from "./project.js";
+import { loadGraphs, scanDependencies, treeStats } from "./deps/index.js";
+import { LEVELS } from "./deps/cvss.js";
+import { analyzeSource } from "./code/index.js";
+import { scanCode } from "./code/engine.js";
+import { scanSecrets } from "./code/secrets.js";
+import { loadExploitData } from "./risk/exploit.js";
+import { scoreFindings } from "./risk/score.js";
 
-export const VERSION = '0.1.0';
+export const VERSION = "0.1.3";
 
 /**
  * Run a full scan and return a JSON-serialisable report.
@@ -37,14 +37,14 @@ export async function scan(root, opts = {}) {
 
   let src = null;
   if (code) {
-    log('Analysing source code…');
+    log("Analysing source code…");
     src = analyzeSource(project);
     stats.files = src.contexts.size;
     findings.push(...scanCode(src), ...scanSecrets(src, project.root));
   }
 
   let exploitData;
-  const cves = [...new Set(findings.flatMap((f) => (f.advisory ? [f.advisory.id, ...f.advisory.aliases] : [])).filter((id) => id.startsWith('CVE-')))];
+  const cves = [...new Set(findings.flatMap((f) => (f.advisory ? [f.advisory.id, ...f.advisory.aliases] : [])).filter((id) => id.startsWith("CVE-")))];
   if (exploit && cves.length) {
     log(`Checking ${cves.length} CVEs against CISA KEV + EPSS…`);
     exploitData = await loadExploitData(cves);
@@ -54,7 +54,7 @@ export async function scan(root, opts = {}) {
   scoreFindings(findings, { src, framework: project.framework, exploit: exploitData });
 
   return {
-    tool: { name: 'iamsecure', version: VERSION },
+    tool: { name: "iamsecure", version: VERSION },
     scannedAt: new Date().toISOString(),
     durationMs: Date.now() - started,
     project: { name: project.name, root: project.root, framework: project.framework },
@@ -62,20 +62,20 @@ export async function scan(root, opts = {}) {
     stats,
     warnings,
     summary: summarize(findings),
-    findings: sortFindings(findings, 'risk'),
+    findings: sortFindings(findings, "risk"),
     tree: graphs.map(serializeGraph),
   };
 }
 
-export function sortFindings(findings, by = 'risk') {
-  const primary = by === 'severity' ? 'severityScore' : 'riskScore';
-  const secondary = by === 'severity' ? 'riskScore' : 'severityScore';
+export function sortFindings(findings, by = "risk") {
+  const primary = by === "severity" ? "severityScore" : "riskScore";
+  const secondary = by === "severity" ? "riskScore" : "severityScore";
   return [...findings].sort((a, b) => b[primary] - a[primary] || b[secondary] - a[secondary] || a.title.localeCompare(b.title));
 }
 
 export function summarize(findings) {
   const count = (field) => Object.fromEntries(LEVELS.slice(0, 4).map((l) => [l, findings.filter((f) => f[field] === l).length]));
-  return { total: findings.length, bySeverity: count('severity'), byRisk: count('risk') };
+  return { total: findings.length, bySeverity: count("severity"), byRisk: count("risk") };
 }
 
 /** Compact tree for the dashboard: direct deps and the vulnerable packages beneath them. */
@@ -84,8 +84,6 @@ function serializeGraph(g) {
     ecosystem: g.ecosystem,
     lockfile: g.lockfile,
     roots: g.roots.map((r) => ({ name: r.name, key: r.key, dev: r.dev, workspace: r.workspace })),
-    nodes: Object.fromEntries(
-      [...g.nodes.values()].filter((n) => !n.local).map((n) => [n.key, { deps: [...n.deps], prod: !!n.prod }]),
-    ),
+    nodes: Object.fromEntries([...g.nodes.values()].filter((n) => !n.local).map((n) => [n.key, { deps: [...n.deps], prod: !!n.prod }])),
   };
 }

package/src/ui/index.html

@@ -4,7 +4,7 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>iamsecure report</title>
-<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%23143d59' d='M12 2 4 5v6c0 5 3.4 9.7 8 11 4.6-1.3 8-6 8-11V5l-8-3z'/%3E%3C/svg%3E">
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%23142b3b' d='M12 2 4 5v6c0 5 3.4 9.7 8 11 4.6-1.3 8-6 8-11V5l-8-3z'/%3E%3Cpath fill='none' stroke='%23fff' stroke-width='2.2' d='m8.5 12 2.5 2.5 4.5-5'/%3E%3C/svg%3E">
 <style>
 :root {
   --bg: #ffffff; --strip: #0f2b3d; --text: #142b3b; --muted: #5b6b78; --faint: #8795a1;
@@ -409,6 +409,7 @@ function groupRow(name, list) {
 function header(r) {
   const s = r.summary;
   const p = r.stats.packages;
+  document.title = `${r.project.name} — iamsecure`;
   $('#crumb').innerHTML = `<span>Projects</span><span class="sep">›</span><span>${esc(r.project.name)}</span>`;
   $('#counters').innerHTML = LEVELS.map((l) => `
     <button class="counter ${l} ${s.byRisk[l] ? 'has' : ''} ${state.level === l ? 'on' : ''}" data-level="${l}" title="Show only ${l} (real risk)">
@@ -821,7 +822,7 @@ function nodeHtml(g, key, path, { root = null } = {}) {
   const belowOnly = under.size - (v ? 1 : 0);
   const kids = kidsOf(g, key, path);
   const node = g.nodes[key];
-  const worst = v ? v.worst : worstOf(under);
+  const worst = worstOf(under); // the card edge shows the worst issue anywhere in this branch
   const bits = [
     kids.length ? `<button class="tv-tog" type="button" aria-expanded="false" aria-label="Show what ${esc(name)} depends on">›</button>` : '<span class="tv-leaf"></span>',
     dot(v ? v.worst : under.size ? 'muted' : 'ok'),

package/src/ui/server.js

@@ -1,8 +1,11 @@
 import http from 'node:http';
+import net from 'node:net';
 import fs from 'node:fs';
+import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { cacheDir } from '../util/cache.js';
 
 const PAGE = fileURLToPath(new URL('./index.html', import.meta.url));
 
@@ -14,16 +17,64 @@ function openBrowser(url) {
   } catch {}
 }
 
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Each running dashboard records {pid, port, secret, root} in a user-only file, so a newer run can
+// ask it to stop. Only someone who can read that file knows the secret, so websites can't do it.
+const lockFile = (port) => path.join(cacheDir, `dashboard-${port}.json`);
+
+function portFree(port) {
+  return new Promise((resolve) => {
+    const probe = net.createServer();
+    probe.once('error', () => resolve(false));
+    probe.listen(port, '127.0.0.1', () => probe.close(() => resolve(true)));
+  });
+}
+
+/** Ask the dashboard holding `port` to shut down. Returns its lock info if it stopped, else null. */
+async function stopPrevious(port) {
+  let info;
+  try {
+    info = JSON.parse(fs.readFileSync(lockFile(port), 'utf8'));
+  } catch {
+    return null; // not one of ours (or from a version without this feature)
+  }
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/shutdown`, {
+      method: 'POST',
+      headers: { 'x-iamsecure-shutdown': info.secret },
+      signal: AbortSignal.timeout(2000),
+    });
+    if (!res.ok) return null;
+  } catch {
+    return null;
+  }
+  for (let i = 0; i < 40; i++) {
+    if (await portFree(port)) return info;
+    await sleep(100);
+  }
+  return null;
+}
+
 function listen(server, port, attempts = 20) {
+  // One 'listening' handler that reads the port actually bound. (A callback per attempt would
+  // also fire for the failed attempts and report the busy port — opening another dashboard.)
   return new Promise((resolve, reject) => {
-    const tryPort = (p, left) => {
-      server.once('error', (err) => {
-        if (err.code === 'EADDRINUSE' && left > 0) tryPort(p + 1, left - 1);
-        else reject(err);
-      });
-      server.listen(p, '127.0.0.1', () => resolve(p));
+    let p = port;
+    const onError = (err) => {
+      if (err.code === 'EADDRINUSE' && attempts-- > 0) server.listen(++p, '127.0.0.1');
+      else {
+        server.off('listening', onListening);
+        reject(err);
+      }
+    };
+    const onListening = () => {
+      server.off('error', onError);
+      resolve(server.address().port);
     };
-    tryPort(port, attempts);
+    server.on('error', onError);
+    server.once('listening', onListening);
+    server.listen(p, '127.0.0.1');
   });
 }
 
@@ -36,7 +87,14 @@ function listen(server, port, attempts = 20) {
 export async function serveDashboard(initialReport, { port = 4477, open = true, rescan, analyze, aiProvider = null } = {}) {
   let report = initialReport;
   const token = crypto.randomBytes(16).toString('hex');
+  const shutdownSecret = crypto.randomBytes(24).toString('hex');
   let busy = false;
+  let lockPath = null;
+  const removeLock = () => {
+    try {
+      if (lockPath && JSON.parse(fs.readFileSync(lockPath, 'utf8')).pid === process.pid) fs.unlinkSync(lockPath);
+    } catch {}
+  };
 
   const server = http.createServer(async (req, res) => {
     const host = (req.headers.host ?? '').split(':')[0];
@@ -62,6 +120,15 @@ export async function serveDashboard(initialReport, { port = 4477, open = true,
         .replace('__IAMSECURE_AI__', JSON.stringify(aiProvider));
       return send(200, html, 'text/html; charset=utf-8');
     }
+    if (req.method === 'POST' && url.pathname === '/api/shutdown') {
+      if (req.headers['x-iamsecure-shutdown'] !== shutdownSecret) return send(403, { error: 'forbidden' });
+      send(200, { ok: true });
+      console.log('\nThis dashboard was replaced by a newer `iamsecure --ui` run. Stopping.');
+      removeLock();
+      server.close();
+      setTimeout(() => process.exit(0), 100);
+      return;
+    }
     if (!url.pathname.startsWith('/api/')) return send(404, { error: 'not found' });
     if (req.headers['x-iamsecure-token'] !== token) return send(401, { error: 'bad token' });
 
@@ -90,8 +157,24 @@ export async function serveDashboard(initialReport, { port = 4477, open = true,
     }
   });
 
+  // Replace an older iamsecure dashboard on the same port instead of piling up new ones.
+  const replaced = (await portFree(port)) ? null : await stopPrevious(port);
+
   const actual = await listen(server, port);
+  lockPath = lockFile(actual);
+  try {
+    fs.mkdirSync(cacheDir, { recursive: true });
+    fs.writeFileSync(lockPath, JSON.stringify({ pid: process.pid, port: actual, secret: shutdownSecret, root: report.project.root, startedAt: new Date().toISOString() }), { mode: 0o600 });
+  } catch {}
+  process.once('exit', removeLock);
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.once(sig, () => {
+      removeLock();
+      process.exit(sig === 'SIGINT' ? 130 : 0);
+    });
+  }
+
   const url = `http://localhost:${actual}/`;
   if (open) openBrowser(url);
-  return { url, server };
+  return { url, server, replaced };
 }