iamsecure 0.1.2 → 0.1.4

package/README.md

@@ -79,7 +79,8 @@ npm run iamsecure
 | 1. Full dependency tree | Parses `package-lock.json` (v1–v3), `yarn.lock` (classic + berry), `pnpm-lock.yaml` (v5–v9), `composer.lock`, `uv.lock`, `poetry.lock`, `Pipfile.lock`, pinned `requirements*.txt`. It records *why* each package is installed (`next › postcss › nanoid`) and whether it's production or dev-only. |
 | 2. Known vulnerabilities | Batch-queries [OSV.dev](https://osv.dev), which aggregates GitHub Advisories, npm, PyPA, Packagist and others, including `MAL-` **malicious package** reports. Picks the fix version from the range that contains your version. |
 | 3. Your own code | Rules for JS/TS, PHP and Python: command/SQL/template injection, SSRF, path traversal, XSS, open redirect, unsafe deserialization, JWT mistakes, disabled TLS, weak crypto, risky Next.js config, secrets exposed through `NEXT_PUBLIC_*`. It also finds hard-coded secrets and `.env` files that are committed or not gitignored. Lightweight taint tracking tells `exec(userInput)` (critical) apart from `exec("ls")` (not reported). |
-| 4. Validate | Context scoring (below), and optionally AI review of the top findings. |
+| 4. How you use it | Works out the **attack surface**: whether anything listens on the network (`listen()`, `createServer`, Express/Fastify/Koa, MCP HTTP transports, web frameworks) or the app is a local CLI or stdio process. Then it traces the **real import graph** from your source files through `node_modules`, so it knows which vulnerable packages your code ever loads, and the chain that loads them (`lib/api.ts → axios → form-data`). For some packages it also checks whether you use the one feature the bug lives in (e.g. multipart bodies for `form-data`). |
+| 5. Validate | Context scoring (below), and optionally AI review of the top findings. |
 
 ## How "real risk" is calculated
 
@@ -91,7 +92,11 @@ risk = severity × exposure × attack vector × exploit intel × reachability  (
 - **Vulnerability class decides the browser discount.** A ReDoS in browser-only code is ×0.2, because an attacker can only freeze their own tab. SSRF and path traversal in the browser are ×0.25. XSS stays ×0.95. Dev/build-only code is ×0.3. Installed-but-never-imported packages are ×0.5. Malicious packages are always 10, because install scripts run on every machine that installs them.
 - **Attack vector.** Advisories that need local access (CVSS `AV:L`) or high privileges score lower.
 - **Exploit intel.** A CVE in [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) (exploited in the wild) gets a floor of 9.0. A high [EPSS](https://www.first.org/epss/) exploitation probability boosts the score.
-- **Reachability.** If your code calls a function the advisory names (`_.template`, `jwt.verify`), the risk goes up. If not, it goes down slightly.
+- **Attack surface.** Server-side code in an app with no network listener (a CLI, or an MCP server on stdio) is ranked as a *local process*. Only the person running it can feed it input, so DoS is ×0.35 and auth bypass ×0.4. If a server framework turns out to be loaded at runtime, the app counts as network-facing even when no `listen()` call was found.
+- **Reachability**, strongest evidence first:
+  - **Module.** The package is installed but nothing your code imports ever loads it (an SDK's optional Express transport that you don't use): ×0.3, and the report names the parts of the parent package you *do* import. Needs `node_modules`, so run `npm ci` first. If `node_modules` doesn't match the lockfile, the result is "unknown", not "never loaded".
+  - **Feature.** The package is loaded, but you never use the feature the bug is in (`src/reach/triggers.js`): ×0.5.
+  - **Symbol.** Your code calls a function the advisory names (`_.template`, `jwt.verify`): the risk goes up. If it doesn't, the risk goes down slightly.
 
 Every adjustment adds a plain-English reason that shows in the terminal, the dashboard and SARIF, so the ranking can be explained.
 
@@ -159,6 +164,7 @@ bin/iamsecure.js          CLI
 src/scan.js               orchestrator → report object
 src/deps/                 lockfile parsers, dependency graph, OSV client, CVSS
 src/code/                 file walker, server/browser classification, rules + taint engine, secrets
+src/reach/                attack surface, import-graph tracing through node_modules, feature triggers
 src/risk/                 exploit intel (KEV/EPSS) and the risk model
 src/ai/                   prompt builder and providers (claude-cli, anthropic, openai, ollama)
 src/report/               terminal and SARIF output
@@ -170,6 +176,8 @@ To try it from a clone of this repo, run `node bin/iamsecure.js /path/to/your/pr
 ## Limitations
 
 - Code rules are pattern- and taint-based, not a full data-flow engine. Taint tracking is per file and name-based, so two variables with the same name in different scopes can cause false positives. Use `--ai` to triage them.
-- The reachability check needs the advisory to name the function. Many advisories don't, and in that case the tool says so.
+- Function-level reachability needs the advisory to name the function. Many advisories don't, and in that case the tool says so.
+- Import tracing follows static `import`/`require` and literal `import()`. It doesn't follow computed `require(variable)`, plugin loaders or TS path aliases, so a package loaded only that way can be marked "never loaded". Each such finding shows its chain, or the lack of one, so you can check it.
+- Attack-surface detection is pattern-based. A listener started in an unusual way can be missed. That's why a loaded server framework always overrides "local".
 - Packages are matched against published advisories. A zero-day nobody has reported yet won't show up.
 - Python and PHP import usage isn't mapped to packages yet. Their runtime dependencies are treated as server-side.

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.2",
+  "version": "0.1.4",
   "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/ai/index.js

@@ -34,6 +34,8 @@ export function buildPrompt(f, report) {
     title: f.title,
     framework: report.project.framework,
     whereItRuns: f.exposure?.label,
+    attackSurface: report.reachability?.surface,
+    moduleReachability: f.reachability,
     scannerSeverity: f.severityScore,
     scannerRisk: f.riskScore,
     scannerReasons: f.reasons,
@@ -82,7 +84,7 @@ export function buildPrompt(f, report) {
   }
 
   parts.push(`Question: is this finding actually exploitable in this codebase, as deployed in production?
-Consider: can an attacker reach it (network-facing route, user input), does the vulnerable code path get used, is input validated or sanitised first, does it only run in the browser or at build time, and what an attacker gains.
+Consider: can an attacker reach it (network-facing route, user input — attackSurface says whether the app listens on the network at all), does the vulnerable code path get used (moduleReachability is traced from the real import graph: "not-loaded" means the package is never loaded, "feature-unused" means it is loaded but the named feature is never used), is input validated or sanitised first, does it only run in the browser or at build time, and what an attacker gains.
 
 Respond with ONLY a JSON object, no markdown:
 {"verdict": "exploitable" | "likely" | "unlikely" | "not_exploitable",

package/src/code/context.js

@@ -7,6 +7,7 @@ const BUILTINS = new Set(builtinModules.flatMap((m) => [m, `node:${m}`]));
 
 export const CONTEXT_LABEL = {
   server: 'runs on server',
+  local: 'local process, no network listener',
   client: 'browser only',
   universal: 'server + browser',
   build: 'build/test only',
@@ -91,7 +92,7 @@ export function extractImports(text) {
       m[0].match(/^import\s+(?:type\s+)?(?:\*\s+as\s+)?([\w$]+)[\s,]/)?.[1] ??
       before.match(/(?:const|let|var)\s+([\w$]+)\s*=\s*require\s*\(\s*['"][^'"]+['"]$/)?.[1] ??
       null;
-    out.push({ pkg, line, binding });
+    out.push({ pkg, spec: m[1], line, binding });
   }
   return out;
 }

package/src/code/index.js

@@ -4,7 +4,7 @@ import { classifyFile, extractImports } from './context.js';
 /**
  * Read the project's source once: classify every code file and index which packages it imports.
  * @returns {{files: {rel:string, kind:string, ext:string, context:string|null}[], texts: Map<string,string>,
- *   contexts: Map<string,string>, usage: Map<string, {file:string,line:number,context:string,binding:string|null}[]>}}
+ *   contexts: Map<string,string>, usage: Map<string, {file:string,line:number,context:string,binding:string|null,spec:string}[]>}}
  */
 export function analyzeSource(project) {
   const files = walkFiles(project.root);
@@ -22,7 +22,7 @@ export function analyzeSource(project) {
     if (!/\.(php|py)$/.test(f.rel)) {
       for (const imp of extractImports(text)) {
         if (!usage.has(imp.pkg)) usage.set(imp.pkg, []);
-        usage.get(imp.pkg).push({ file: f.rel, line: imp.line, context: f.context, binding: imp.binding });
+        usage.get(imp.pkg).push({ file: f.rel, line: imp.line, context: f.context, binding: imp.binding, spec: imp.spec });
       }
     }
   }

package/src/reach/modules.js

@@ -0,0 +1,218 @@
+// Module-level reachability: follow the real import/require graph from your source files into node_modules
+// and record which installed packages actually get loaded at runtime.
+//
+// A package can sit in the lockfile (pulled in by a dependency) without ever being loaded — e.g. an SDK
+// that ships an optional Express-based HTTP transport you never import. This is what tells those apart.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { builtinModules } from 'node:module';
+
+const BUILTINS = new Set(builtinModules.flatMap((m) => [m, `node:${m}`]));
+const EXTS = ['.js', '.cjs', '.mjs', '.json', '.node'];
+const SRC_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+const MAX_MODULES = 30000;
+// Two passes per package: the CommonJS view and the ESM view. Browser/edge builds are never followed.
+const CONDITION_SETS = [new Set(['node', 'require', 'default', 'module-sync']), new Set(['node', 'import', 'default', 'module-sync'])];
+
+// Static imports, re-exports, require() and literal dynamic import(). `import type` / `export type` are skipped.
+const SPEC_RE =
+  /(?:\bimport\s+(type\s+)?(?:[\w*{}\s,$]+?\s+from\s+)?|\bexport\s+(type\s+)?(?:[\w*{}\s,$]+?\s+)?from\s+|\brequire\s*\(\s*|\bimport\s*\(\s*)(['"])([^'"\n]+)\3/g;
+
+export function moduleSpecifiers(text) {
+  const out = [];
+  for (const m of text.matchAll(SPEC_RE)) if (!m[1] && !m[2]) out.push(m[4]);
+  return out;
+}
+
+const statFile = (p) => {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+};
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve a file path the way Node (and TS's `.js` → `.ts` mapping) would. */
+function resolveFile(p, exts) {
+  if (statFile(p)) return p;
+  for (const e of exts) if (statFile(p + e)) return p + e;
+  // TypeScript sources import "./x.js" meaning "./x.ts".
+  const m = p.match(/\.(m|c)?js$/);
+  if (m) for (const e of SRC_EXTS) if (statFile(p.slice(0, -m[0].length) + e)) return p.slice(0, -m[0].length) + e;
+  for (const e of exts) if (statFile(path.join(p, 'index' + e))) return path.join(p, 'index' + e);
+  return null;
+}
+
+/** Pick the target(s) of an `exports` condition object for one condition set. */
+function pickConditions(target, conds) {
+  if (typeof target === 'string') return [target];
+  if (Array.isArray(target)) return target.flatMap((t) => pickConditions(t, conds)).slice(0, 1);
+  if (target && typeof target === 'object') {
+    for (const [k, v] of Object.entries(target)) if (conds.has(k)) return pickConditions(v, conds);
+  }
+  return [];
+}
+
+/** Map a subpath ("." or "./server/mcp.js") through package.json "exports". */
+function resolveExports(exp, sub) {
+  if (typeof exp === 'string' || Array.isArray(exp) || !Object.keys(exp).some((k) => k.startsWith('.'))) exp = { '.': exp };
+  const out = new Set();
+  for (const conds of CONDITION_SETS) {
+    if (exp[sub] !== undefined) {
+      pickConditions(exp[sub], conds).forEach((t) => out.add(t));
+      continue;
+    }
+    // Longest matching "./prefix/*suffix" pattern wins.
+    const pat = Object.keys(exp)
+      .filter((k) => k.includes('*'))
+      .map((k) => [k, ...k.split('*')])
+      .filter(([, pre, post]) => sub.startsWith(pre) && sub.endsWith(post) && sub.length >= pre.length + post.length)
+      .sort((a, b) => b[1].length - a[1].length)[0];
+    if (pat) {
+      const star = sub.slice(pat[1].length, sub.length - pat[2].length);
+      pickConditions(exp[pat[0]], conds).forEach((t) => out.add(t.replaceAll('*', star)));
+    }
+  }
+  return [...out];
+}
+
+/** All on-disk entry files a bare specifier can load, from a given directory. */
+function resolveBare(spec, fromDir, pkgCache) {
+  const parts = spec.split('/');
+  const name = spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+  const sub = spec.slice(name.length);
+  for (let dir = fromDir; ; ) {
+    const pkgDir = path.join(dir, 'node_modules', name);
+    const manifest = pkgCache(pkgDir);
+    if (manifest) {
+      let targets;
+      if (manifest.exports !== undefined) targets = resolveExports(manifest.exports, '.' + sub);
+      else if (sub) targets = ['.' + sub];
+      else targets = [manifest.main ?? 'index.js'];
+      const files = targets.map((t) => resolveFile(path.join(pkgDir, t), EXTS)).filter(Boolean);
+      return { pkgDir, files };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Walk from the project's runtime source files through every module they load.
+ * @param {string} root project root
+ * @param {{rel:string, context:string}[]} entries source files (build/test files are excluded by the caller)
+ * @returns {{available: boolean, loaded: Map<string, {chain: string[]}>, installed: Set<string>, modules: number, truncated: boolean}}
+ *   `loaded` is keyed by "name@version" of every package that gets loaded; `installed` holds every one on disk.
+ */
+export function walkModules(root, entries) {
+  root = path.resolve(root);
+  if (!fs.existsSync(path.join(root, 'node_modules'))) return { available: false, loaded: new Map(), installed: new Set(), modules: 0, truncated: false };
+
+  const manifests = new Map();
+  const pkgCache = (dir) => {
+    if (!manifests.has(dir)) manifests.set(dir, readJson(path.join(dir, 'package.json')));
+    return manifests.get(dir);
+  };
+  /** Nearest package root for a file inside node_modules. */
+  const ownerOf = (file) => {
+    const i = file.lastIndexOf(`${path.sep}node_modules${path.sep}`);
+    if (i === -1) return null;
+    const rest = file.slice(i + 14).split(path.sep);
+    const dir = file.slice(0, i + 14) + (rest[0].startsWith('@') ? rest.slice(0, 2).join(path.sep) : rest[0]);
+    const m = pkgCache(dir);
+    return m?.name && m.version ? { dir, key: `${m.name}@${m.version}`, name: m.name } : null;
+  };
+
+  const parent = new Map(); // file → file that first loaded it (null for entries)
+  const loaded = new Map();
+  const queue = [];
+  for (const e of entries) {
+    const abs = path.join(root, e.rel);
+    if (!parent.has(abs)) parent.set(abs, null), queue.push(abs);
+  }
+
+  const chainOf = (file) => {
+    const files = [];
+    for (let f = file; f; f = parent.get(f)) files.unshift(f);
+    // Collapse to "your file that imports it → pkg → pkg …" for the report.
+    const out = [];
+    let lastSrc = files[0];
+    for (const f of files) {
+      const o = ownerOf(f);
+      if (!o) lastSrc = f;
+      else {
+        if (!out.length) out.push(path.relative(root, lastSrc).split(path.sep).join('/'));
+        if (out.at(-1) !== o.key) out.push(o.key);
+      }
+    }
+    return out;
+  };
+
+  let truncated = false;
+  for (let qi = 0; qi < queue.length; qi++) {
+    if (qi >= MAX_MODULES) {
+      truncated = true;
+      break;
+    }
+    const file = queue[qi];
+    const owner = ownerOf(file);
+    if (owner && !loaded.has(owner.key)) loaded.set(owner.key, { chain: chainOf(file) });
+    if (!/\.([cm]?[jt]sx?)$/.test(file)) continue;
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    const dir = path.dirname(file);
+    for (const spec of moduleSpecifiers(text)) {
+      if (BUILTINS.has(spec) || BUILTINS.has(spec.split('/')[0]) || /^[a-z]+:/i.test(spec)) continue;
+      let targets = [];
+      if (spec.startsWith('.') || spec.startsWith('/')) {
+        const t = resolveFile(path.resolve(dir, spec), owner ? EXTS : [...SRC_EXTS, '.json']);
+        if (t) targets = [t];
+      } else if (!/^[~#@]\//.test(spec)) {
+        targets = resolveBare(spec, dir, pkgCache)?.files ?? [];
+      }
+      for (const t of targets) {
+        if (parent.has(t)) continue;
+        parent.set(t, file);
+        queue.push(t);
+      }
+    }
+  }
+  return { available: true, loaded, installed: installedPackages(root), modules: Math.min(queue.length, MAX_MODULES), truncated };
+}
+
+/** Every "name@version" present on disk, nested copies included — so a stale node_modules isn't read as "never loaded". */
+function installedPackages(root) {
+  const out = new Set();
+  const subdirs = (dir) => {
+    try {
+      return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => path.join(dir, e.name));
+    } catch {
+      return [];
+    }
+  };
+  const visit = (nm) => {
+    for (const entry of subdirs(nm)) {
+      for (const dir of path.basename(entry).startsWith('@') ? subdirs(entry) : [entry]) {
+        const m = readJson(path.join(dir, 'package.json'));
+        if (m?.name && m.version) out.add(`${m.name}@${m.version}`);
+        visit(path.join(dir, 'node_modules'));
+      }
+    }
+  };
+  visit(path.join(root, 'node_modules'));
+  return out;
+}

package/src/reach/surface.js

@@ -0,0 +1,76 @@
+// Attack surface: does this app accept connections from the network, or is it a local process
+// (CLI, stdio MCP server, IDE extension) that only talks to the user who started it?
+//
+// "Runs on the server" is not the same as "reachable by attackers over the internet". A request-parsing
+// DoS in express only matters if something actually calls listen().
+
+const LISTENERS = [
+  { what: 'HTTP server', re: /\b(?:https?|http2)\s*\.\s*create(?:Secure)?Server\s*\(|\bcreateServer\s*\(/ },
+  { what: '.listen() call', re: /\.\s*listen\s*\(\s*(?:[\w$.]*port\b|\d{2,5}\b|process\.env\.)/i },
+  { what: 'Express app', re: /\bexpress\s*\(\s*\)/ },
+  { what: 'Fastify app', re: /\bfastify\s*\(\s*[{)]/i },
+  { what: 'Koa app', re: /\bnew\s+Koa\s*\(/ },
+  { what: 'Hapi server', re: /\bHapi\s*\.\s*server\s*\(/ },
+  { what: 'Hono server', re: /\bserve\s*\(\s*\{[^}]*\bfetch\b/ },
+  { what: 'Bun/Deno server', re: /\b(?:Bun|Deno)\s*\.\s*serve\s*\(/ },
+  { what: 'WebSocket server', re: /\bnew\s+(?:WebSocket\.)?(?:WebSocketServer|Server)\s*\(\s*\{[^}]*\b(?:port|server)\b/ },
+  { what: 'MCP HTTP transport', re: /\bnew\s+(?:StreamableHTTPServerTransport|SSEServerTransport)\s*\(|\bcreateMcpExpressApp\s*\(/ },
+  { what: 'NestJS app', re: /\bNestFactory\s*\.\s*create\s*\(/ },
+  { what: 'Python web server', re: /\buvicorn\.run\s*\(|\bapp\.run\s*\(|\bweb\.run_app\s*\(|\bserve_forever\s*\(/ },
+];
+
+const LOCAL = [
+  { what: 'MCP stdio transport', re: /\bnew\s+StdioServerTransport\s*\(/ },
+  { what: 'reads commands from stdin', re: /\bprocess\.stdin\b/ },
+];
+
+// Frameworks that always serve HTTP even when no file calls listen() itself.
+const NETWORK_FRAMEWORKS = new Set(['next', 'nuxt', 'remix', 'sveltekit', 'astro', 'node-server', 'laravel', 'symfony', 'django', 'fastapi', 'flask']);
+
+/**
+ * @param {{framework: string, manifest: any}} project
+ * @param {{files: {rel:string, kind:string, context?:string}[], texts: Map<string,string>}} src
+ * @returns {{kind: 'network'|'local'|'unknown', evidence: string[]}}
+ *   network = something accepts connections; local = only a CLI/stdio entry point and no listener found.
+ */
+export function detectSurface(project, src) {
+  const listeners = [];
+  const local = [];
+  for (const f of src.files) {
+    if (f.kind !== 'code' || f.context === 'build') continue;
+    const text = src.texts.get(f.rel);
+    if (!text) continue;
+    for (const [list, rules] of [[listeners, LISTENERS], [local, LOCAL]]) {
+      for (const r of rules) {
+        const m = r.re.exec(text);
+        if (m) list.push(`${r.what} in ${f.rel}:${text.slice(0, m.index).split('\n').length}`);
+      }
+    }
+  }
+
+  if (listeners.length) return { kind: 'network', evidence: listeners.slice(0, 3) };
+  if (NETWORK_FRAMEWORKS.has(project.framework)) return { kind: 'network', evidence: [`${project.framework} serves HTTP`] };
+
+  const bin = project.manifest?.bin;
+  if (bin) local.push(`package.json "bin" (${typeof bin === 'string' ? bin : Object.keys(bin).join(', ')})`);
+  // A library with no entry point of its own is "unknown": whoever imports it decides whether it's exposed.
+  if (local.length) return { kind: 'local', evidence: local.slice(0, 3) };
+  return { kind: 'unknown', evidence: [] };
+}
+
+const SERVER_PACKAGES = ['express', 'fastify', 'koa', '@hapi/hapi', 'hono', '@hono/node-server', 'ws', 'socket.io', '@nestjs/core', 'restify', 'polka', 'h3'];
+
+/**
+ * Safety net for listeners the patterns above miss: if a server framework is actually loaded at runtime,
+ * don't call the app local.
+ * @param {ReturnType<typeof detectSurface>} surface
+ * @param {{available: boolean, loaded: Map<string, {chain: string[]}>}|null} modules
+ */
+export function confirmSurface(surface, modules) {
+  if (surface.kind !== 'local' || !modules?.available) return surface;
+  for (const [key, { chain }] of modules.loaded) {
+    const name = key.slice(0, key.lastIndexOf('@'));
+    if (SERVER_PACKAGES.includes(name)) return { kind: 'network', evidence: [`${name} is loaded at runtime (${chain.join(' → ')})`] };
+  }
+  return surface;
+}

package/src/reach/triggers.js

@@ -0,0 +1,31 @@
+// Feature-level reachability for packages that are loaded but only dangerous when you use one feature.
+// axios always loads form-data on Node, yet form-data's bugs only matter when you send multipart bodies.
+//
+// Each entry: the vulnerable package, a description of the feature, and a pattern that shows YOUR code
+// uses it. No match → the package is loaded but the vulnerable path is never exercised (weak-to-moderate
+// evidence: the pattern can miss indirect uses, so the score is reduced, not zeroed).
+
+export const TRIGGERS = {
+  'form-data': {
+    feature: 'multipart/form-data request bodies',
+    re: /\bnew\s+FormData\s*\(|multipart\/form-data|\.\s*(?:postForm|putForm|patchForm|toFormData)\s*\(|\bformSerializer\b/,
+  },
+  'proxy-addr': { feature: 'trust-proxy client IP resolution', re: /['"]trust proxy['"]|\btrustProxy\s*:/ },
+  'tough-cookie': { feature: 'cookie jars', re: /\bCookieJar\b|\bjar\s*:/ },
+};
+
+/**
+ * Does any runtime source file use the feature that makes `pkg`'s advisories exploitable?
+ * @returns {null | {used: boolean, feature: string, where?: string}} null when no trigger is known.
+ */
+export function featureUse(pkg, src) {
+  const t = TRIGGERS[pkg];
+  if (!t || !src) return null;
+  for (const f of src.files) {
+    if (f.kind !== 'code' || f.context === 'build') continue;
+    const text = src.texts.get(f.rel);
+    const m = text && t.re.exec(text);
+    if (m) return { used: true, feature: t.feature, where: `${f.rel}:${text.slice(0, m.index).split('\n').length}` };
+  }
+  return { used: false, feature: t.feature };
+}

package/src/report/sarif.js

@@ -41,7 +41,7 @@ export function toSarif(report) {
       message: { text: [text, ...(f.reasons ?? []).map((r) => `• ${r}`)].join('\n') },
       locations: [{ physicalLocation: { artifactLocation: { uri: where.uri }, region: { startLine: where.line } } }],
       partialFingerprints: { iamsecure: f.id },
-      properties: { riskScore: f.riskScore, severityScore: f.severityScore, exposure: f.exposure?.context, aiVerdict: f.ai?.verdict },
+      properties: { riskScore: f.riskScore, severityScore: f.severityScore, exposure: f.exposure?.context, reachability: f.reachability?.status, aiVerdict: f.ai?.verdict },
     });
   }
 

package/src/report/terminal.js

@@ -29,8 +29,11 @@ const TONE = {
   muted: c.gray,
 };
 const dot = (tone) => TONE[tone]('●');
-const EXPOSURE_TONE = { server: 'critical', universal: 'critical', client: 'medium', build: 'low', unused: 'muted', unknown: 'muted' };
-const EXPOSURE_WORD = { server: 'server', universal: 'server + browser', client: 'browser only', build: 'build/test only', unused: 'not imported', unknown: 'unknown' };
+const EXPOSURE_TONE = { server: 'critical', universal: 'critical', local: 'medium', client: 'medium', build: 'low', unused: 'muted', unknown: 'muted' };
+const EXPOSURE_WORD = { server: 'server', universal: 'server + browser', local: 'local process', client: 'browser only', build: 'build/test only', unused: 'not imported', unknown: 'unknown' };
+const REACH_TONE = { loaded: 'critical', 'feature-unused': 'medium', 'not-loaded': 'low', unknown: 'muted' };
+const REACH_WORD = { loaded: 'loaded', 'feature-unused': 'loaded, feature unused', 'not-loaded': 'never loaded', unknown: 'unknown' };
+const SURFACE_WORD = { network: 'accepts network connections', local: 'local process, no network listener', unknown: 'unknown (no entry point found)' };
 const KIND_WORD = { dependency: 'Dependency', code: 'Code', secret: 'Secret' };
 
 // ── layout helpers (ANSI-aware) ──────────────────────────────────────────────
@@ -136,8 +139,14 @@ function latestPanel(report, width) {
     (report.stats.files != null ? ` and ${report.stats.files} source files` : '') +
     `. Found ${s.total} issue${s.total === 1 ? '' : 's'}: ${kinds.dependency.length} in dependencies, ${kinds.code.length} in your code, ${kinds.secret.length} secret${kinds.secret.length === 1 ? '' : 's'}.` +
     (s.total ? ` After weighing where each one runs, ${s.byRisk.critical} ${s.byRisk.critical === 1 ? 'is' : 'are'} critical here (raw severity says ${s.bySeverity.critical}).` : '');
+  const surface = report.reachability?.surface;
+  const notLoaded = kinds.dependency.filter((f) => f.reachability?.status === 'not-loaded').length;
+  const reach = [];
+  if (surface && report.stats.files != null) reach.push(`Attack surface: ${SURFACE_WORD[surface.kind]}${surface.evidence[0] ? ` (${surface.evidence[0]})` : ''}.`);
+  if (report.reachability?.modules) reach.push(`${notLoaded} of ${kinds.dependency.length} dependency issues are in packages your code never loads.`);
   const right = [
     ...wrap(prose, rightW),
+    ...(reach.length ? wrap(reach.join(' '), rightW).map(c.gray) : []),
     '',
     groupLine('Dependencies', kinds.dependency),
     groupLine('Your code', kinds.code),
@@ -165,6 +174,7 @@ function findingEntry(f, sort, width) {
     `  ${c.gray('Risk')} ${dot(f.risk)} ${c.bold(f.riskScore.toFixed(1))}   ${c.gray('Sev')} ${dot(f.severity)} ${f.severityScore.toFixed(1)}`,
     `  ${c.gray('Runs')} ${dot(EXPOSURE_TONE[ctx])} ${EXPOSURE_WORD[ctx]}`,
   ];
+  if (f.reachability) left.push(`  ${c.gray('Reach')} ${dot(REACH_TONE[f.reachability.status])} ${REACH_WORD[f.reachability.status]}`);
   const tags = [];
   if (f.kind === 'dependency') {
     tags.push(f.package.direct ? 'direct' : 'transitive');

package/src/risk/score.js

@@ -2,26 +2,35 @@
 //
 //   risk = severity × exposure(where it runs, what kind of bug) × attack-vector × exploit-intel × reachability
 //
+// Reachability has three levels, strongest evidence first:
+//   1. module  — is the vulnerable package ever loaded from your code? (real import graph through node_modules)
+//   2. feature — is it loaded but only dangerous when you use one feature you don't use? (reach/triggers.js)
+//   3. symbol  — does your code call the function the advisory names? (direct dependencies)
+//
 // Every multiplier that fires adds a human-readable reason, so the ranking is explainable.
 
 import { levelFromScore } from '../deps/cvss.js';
 import { CONTEXT_LABEL, mergeContexts, frameworkRuntime } from '../code/context.js';
+import { featureUse } from '../reach/triggers.js';
 
-const DEFAULT_WEIGHTS = { server: 1, universal: 1, client: 0.6, build: 0.3, unused: 0.5, unknown: 0.85 };
+// `local` = server-side code with no network listener (CLI, stdio MCP server): only the user who runs it can feed it input.
+const DEFAULT_WEIGHTS = { server: 1, universal: 1, local: 0.6, client: 0.6, build: 0.3, unused: 0.5, unknown: 0.85 };
+const NOT_LOADED = 0.3;
+const FEATURE_UNUSED = 0.5;
 
 /** Vulnerability classes. `client` = how much the bug still matters when the code only runs in a browser. */
 export const VULN_CLASSES = [
-  { id: 'malicious', name: 'malicious code', cwes: [], re: /malicious (code|package)/i, weights: { client: 1, build: 1, unused: 1 } },
-  { id: 'secret', name: 'leaked secret', clientNote: 'anything in client code ships to every visitor', cwes: ['CWE-798'], re: null, weights: { client: 1, server: 0.9, build: 0.8, unknown: 0.9 } },
-  { id: 'rce', name: 'code execution', clientNote: 'code runs in the visitor\'s browser sandbox, not on your server', cwes: ['CWE-94', 'CWE-95', 'CWE-77', 'CWE-78', 'CWE-502', 'CWE-1336'], re: /remote code execution|command injection|code injection|\brce\b|arbitrary code|template injection/i, weights: { client: 0.5 } },
-  { id: 'sqli', name: 'SQL injection', clientNote: 'the browser has no direct database access', cwes: ['CWE-89', 'CWE-943'], re: /sql injection|nosql injection/i, weights: { client: 0.3 } },
-  { id: 'auth', name: 'auth bypass', clientNote: 'your server must enforce auth anyway', cwes: ['CWE-285', 'CWE-287', 'CWE-288', 'CWE-290', 'CWE-306', 'CWE-347', 'CWE-863', 'CWE-639', 'CWE-1390'], re: /authori[sz]ation bypass|authentication bypass|auth bypass|signature (verification|bypass)|forge/i, weights: { client: 0.4 } },
-  { id: 'ssrf', name: 'SSRF', clientNote: 'browser requests can\'t reach your internal network', cwes: ['CWE-918'], re: /\bssrf\b|server-side request forgery/i, weights: { client: 0.25 } },
-  { id: 'path', name: 'path traversal', clientNote: 'the browser has no access to your server\'s filesystem', cwes: ['CWE-22', 'CWE-23', 'CWE-24', 'CWE-73'], re: /path traversal|directory traversal|arbitrary file (read|write)/i, weights: { client: 0.25 } },
-  { id: 'xss', name: 'XSS', clientNote: 'XSS targets exactly this environment', cwes: ['CWE-79', 'CWE-80', 'CWE-116'], re: /cross[- ]site scripting|\bxss\b|html injection/i, weights: { client: 0.95 } },
+  { id: 'malicious', name: 'malicious code', cwes: [], re: /malicious (code|package)/i, weights: { client: 1, build: 1, unused: 1, local: 1 } },
+  { id: 'secret', name: 'leaked secret', clientNote: 'anything in client code ships to every visitor', cwes: ['CWE-798'], re: null, weights: { client: 1, server: 0.9, local: 0.9, build: 0.8, unknown: 0.9 } },
+  { id: 'rce', name: 'code execution', clientNote: 'code runs in the visitor\'s browser sandbox, not on your server', cwes: ['CWE-94', 'CWE-95', 'CWE-77', 'CWE-78', 'CWE-502', 'CWE-1336'], re: /remote code execution|command injection|code injection|\brce\b|arbitrary code|template injection/i, weights: { client: 0.5, local: 0.7 } },
+  { id: 'sqli', name: 'SQL injection', clientNote: 'the browser has no direct database access', cwes: ['CWE-89', 'CWE-943'], re: /sql injection|nosql injection/i, weights: { client: 0.3, local: 0.5 } },
+  { id: 'auth', name: 'auth bypass', clientNote: 'your server must enforce auth anyway', cwes: ['CWE-285', 'CWE-287', 'CWE-288', 'CWE-290', 'CWE-306', 'CWE-347', 'CWE-863', 'CWE-639', 'CWE-1390'], re: /authori[sz]ation bypass|authentication bypass|auth bypass|signature (verification|bypass)|forge/i, weights: { client: 0.4, local: 0.4 } },
+  { id: 'ssrf', name: 'SSRF', clientNote: 'browser requests can\'t reach your internal network', cwes: ['CWE-918'], re: /\bssrf\b|server-side request forgery/i, weights: { client: 0.25, local: 0.5 } },
+  { id: 'path', name: 'path traversal', clientNote: 'the browser has no access to your server\'s filesystem', cwes: ['CWE-22', 'CWE-23', 'CWE-24', 'CWE-73'], re: /path traversal|directory traversal|arbitrary file (read|write)/i, weights: { client: 0.25, local: 0.6 } },
+  { id: 'xss', name: 'XSS', clientNote: 'XSS targets exactly this environment', cwes: ['CWE-79', 'CWE-80', 'CWE-116'], re: /cross[- ]site scripting|\bxss\b|html injection/i, weights: { client: 0.95, local: 0.4 } },
   { id: 'proto', name: 'prototype pollution', clientNote: 'can still be chained into client-side XSS', cwes: ['CWE-1321', 'CWE-915'], re: /prototype pollution/i, weights: { client: 0.65 } },
-  { id: 'redirect', name: 'open redirect', clientNote: 'still usable for phishing', cwes: ['CWE-601'], re: /open redirect/i, weights: { client: 0.7 } },
-  { id: 'dos', name: 'denial of service', clientNote: 'an attacker can only freeze their own tab', cwes: ['CWE-400', 'CWE-1333', 'CWE-770', 'CWE-674', 'CWE-835', 'CWE-407', 'CWE-776', 'CWE-1050', 'CWE-834'], re: /denial[- ]of[- ]service|\bdos\b|redos|regular expression|backtracking|resource exhaustion|uncontrolled resource|infinite loop|memory exhaustion/i, weights: { client: 0.2 } },
+  { id: 'redirect', name: 'open redirect', clientNote: 'still usable for phishing', cwes: ['CWE-601'], re: /open redirect/i, weights: { client: 0.7, local: 0.3 } },
+  { id: 'dos', name: 'denial of service', clientNote: 'an attacker can only freeze their own tab', cwes: ['CWE-400', 'CWE-1333', 'CWE-770', 'CWE-674', 'CWE-835', 'CWE-407', 'CWE-776', 'CWE-1050', 'CWE-834'], re: /denial[- ]of[- ]service|\bdos\b|redos|regular expression|backtracking|resource exhaustion|uncontrolled resource|infinite loop|memory exhaustion/i, weights: { client: 0.2, local: 0.35 } },
   { id: 'leak', name: 'information leak', clientNote: 'only data already sent to the browser is at risk', cwes: ['CWE-200', 'CWE-201', 'CWE-209', 'CWE-359', 'CWE-522', 'CWE-532', 'CWE-312'], re: /credential leak|information (disclosure|exposure)|exposure of sensitive|leaks?\b/i, weights: { client: 0.5 } },
   { id: 'crypto', name: 'weak crypto', clientNote: 'client-side crypto is rarely security-critical', cwes: ['CWE-327', 'CWE-328', 'CWE-330', 'CWE-338', 'CWE-326'], re: /weak (crypto|hash|random)|insecure random|predictable/i, weights: { client: 0.5 } },
 ];
@@ -108,9 +117,10 @@ const round1 = (x) => Math.round(x * 10) / 10;
 /**
  * Compute riskScore/risk/exposure/reasons on every finding (mutates).
  * @param {any[]} findings
- * @param {{src: ReturnType<import('../code/index.js').analyzeSource>|null, framework: string, exploit?: {kev:Map<string,any>, epss:Map<string,any>}}} ctx
+ * @param {{src: ReturnType<import('../code/index.js').analyzeSource>|null, framework: string, exploit?: {kev:Map<string,any>, epss:Map<string,any>},
+ *   surface?: ReturnType<import('../reach/surface.js').detectSurface>, modules?: ReturnType<import('../reach/modules.js').walkModules>}} ctx
  */
-export function scoreFindings(findings, { src, framework, exploit }) {
+export function scoreFindings(findings, { src, framework, exploit, surface, modules }) {
   const runtime = frameworkRuntime(framework);
   for (const f of findings) {
     const reasons = [];
@@ -129,12 +139,17 @@ export function scoreFindings(findings, { src, framework, exploit }) {
       f.kind === 'dependency'
         ? dependencyExposure(f, src, runtime)
         : { context: f.context ?? src?.contexts.get(f.location?.file) ?? 'unknown', evidence: [] };
+    // Server-side code in an app that never opens a port: only the local user can feed it input.
+    if (surface?.kind === 'local' && (exp.context === 'server' || exp.context === 'universal')) exp.context = 'local';
     const weight = { ...DEFAULT_WEIGHTS, ...cls.weights }[exp.context] ?? 1;
     f.exposure = { context: exp.context, label: CONTEXT_LABEL[exp.context], evidence: exp.evidence };
     s *= weight;
-    const why = weight < 1 || exp.context === 'client' ? exposureReason(exp.context, cls, f) : null;
+    const why = weight < 1 || exp.context === 'client' ? exposureReason(exp.context, cls, f, surface) : null;
     if (why) reasons.push(why);
-    else if (f.kind === 'dependency' && exp.evidence.length) reasons.push(`Runs on the server — ${exp.evidence[0]}`);
+    else if (f.kind === 'dependency' && exp.evidence.length) {
+      const net = surface?.kind === 'network' ? ` — and the app accepts network connections (${surface.evidence[0]})` : '';
+      reasons.push(`Runs on the server — ${exp.evidence[0]}${net}`);
+    }
 
     // 2. Attack vector (CVSS)
     const m = adv?.cvss?.metrics;
@@ -168,8 +183,33 @@ export function scoreFindings(findings, { src, framework, exploit }) {
       }
     }
 
-    // 4. Reachability: does our code call the function the advisory names?
-    if (f.kind === 'dependency' && src && f.package.direct && !adv.malicious) {
+    // 4. Module + feature reachability: is the package ever loaded, and is the vulnerable feature used?
+    if (f.kind === 'dependency' && modules?.available && f.package.ecosystem === 'npm' && !adv.malicious && !['build', 'unused'].includes(exp.context)) {
+      const key = `${f.package.name}@${f.package.version}`;
+      const hit = modules.loaded.get(key);
+      if (hit) {
+        const use = featureUse(f.package.name, src);
+        const chain = hit.chain.join(' → ');
+        if (use && !use.used) {
+          s *= FEATURE_UNUSED;
+          f.reachability = { status: 'feature-unused', chain: hit.chain, feature: use.feature };
+          reasons.push(`Loaded at runtime (${chain}), but your code never uses ${use.feature} — the code path this bug is in`);
+        } else {
+          f.reachability = { status: 'loaded', chain: hit.chain, ...(use && { feature: use.feature, where: use.where }) };
+          reasons.push(`Loaded at runtime: ${chain}${use ? ` — and your code uses ${use.feature} (${use.where})` : ''}`);
+        }
+      } else if (!modules.installed.has(key)) {
+        f.reachability = { status: 'unknown' };
+        reasons.push(`Can't check whether it's loaded: ${key} isn't in node_modules (out of sync with ${f.package.lockfile}? run a clean install)`);
+      } else if (!modules.truncated) {
+        s *= NOT_LOADED;
+        f.reachability = { status: 'not-loaded' };
+        reasons.push(notLoadedReason(f, src, modules));
+      }
+    }
+
+    // 5. Symbol reachability: does our code call the function the advisory names?
+    if (f.kind === 'dependency' && src && f.package.direct && !adv.malicious && f.reachability?.status !== 'not-loaded') {
       const uses = src.usage.get(f.package.name) ?? [];
       const symbols = vulnerableSymbols(adv, f.package.name);
       if (uses.length && symbols.length) {
@@ -199,8 +239,22 @@ export function scoreFindings(findings, { src, framework, exploit }) {
   return findings;
 }
 
-function exposureReason(context, cls, f) {
+/** "Never loaded" with the most specific explanation we can give: which parts of the parent you do import. */
+function notLoadedReason(f, src, modules) {
+  const roots = f.package.introducedBy.filter((r) => r !== f.package.name);
+  const specs = [...new Set(roots.flatMap((r) => (src?.usage.get(r) ?? []).filter((u) => u.context !== 'build').map((u) => u.spec)))].filter((s) => !roots.includes(s));
+  const followed = `followed ${modules.modules} modules from your code`;
+  if (!roots.length) return `Never loaded at runtime — none of your code's imports lead to it (${followed})`;
+  if (specs.length) {
+    return `Never loaded at runtime — only parts of ${roots.join(', ')} you don't import use it; you import ${specs.slice(0, 3).join(', ')}${specs.length > 3 ? ', …' : ''} (${followed})`;
+  }
+  return `Never loaded at runtime — ${roots.join(', ')} installs it, but not on any code path your app uses (${followed})`;
+}
+
+function exposureReason(context, cls, f, surface) {
   switch (context) {
+    case 'local':
+      return `No network listener found — runs as a local process (${surface.evidence[0]}), so only the person running it can send it input`;
     case 'client':
       return `Only runs in the browser — ${cls.clientNote ?? `${cls.name} impact is reduced there`}`;
     case 'build':

package/src/scan.js

@@ -6,8 +6,10 @@ 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 { detectSurface, confirmSurface } from "./reach/surface.js";
+import { walkModules } from "./reach/modules.js";
 
-export const VERSION = "0.1.2";
+export const VERSION = "0.1.4";
 
 /**
  * Run a full scan and return a JSON-serialisable report.
@@ -36,11 +38,26 @@ export async function scan(root, opts = {}) {
   }
 
   let src = null;
+  let surface = null;
+  let modules = null;
   if (code) {
     log("Analysing source code…");
     src = analyzeSource(project);
     stats.files = src.contexts.size;
     findings.push(...scanCode(src), ...scanSecrets(src, project.root));
+    surface = detectSurface(project, src);
+
+    if (graphs.some((g) => g.ecosystem === "npm" && g.packages().length)) {
+      log("Tracing which packages your code actually loads…");
+      const entries = src.files.filter((f) => f.kind === "code" && f.context && f.context !== "build");
+      modules = walkModules(project.root, entries);
+      if (!modules.available) {
+        warnings.push("node_modules not found — install dependencies (e.g. `npm ci`) so iamsecure can tell which vulnerable packages your code actually loads.");
+      } else if (modules.truncated) {
+        warnings.push(`Stopped tracing after ${modules.modules} modules; packages not reached by then are not marked as unused.`);
+      }
+      surface = confirmSurface(surface, modules);
+    }
   }
 
   let exploitData;
@@ -51,13 +68,17 @@ export async function scan(root, opts = {}) {
     warnings.push(...exploitData.warnings);
   }
 
-  scoreFindings(findings, { src, framework: project.framework, exploit: exploitData });
+  scoreFindings(findings, { src, framework: project.framework, exploit: exploitData, surface, modules });
 
   return {
     tool: { name: "iamsecure", version: VERSION },
     scannedAt: new Date().toISOString(),
     durationMs: Date.now() - started,
     project: { name: project.name, root: project.root, framework: project.framework },
+    reachability: {
+      surface: surface ?? { kind: "unknown", evidence: [] },
+      modules: modules?.available ? { traced: modules.modules, packagesLoaded: modules.loaded.size, truncated: modules.truncated } : null,
+    },
     sourceFiles: src ? [...src.contexts].slice(0, 400).map(([file, context]) => ({ file, context })) : [],
     stats,
     warnings,

package/src/ui/index.html

@@ -156,6 +156,13 @@ label.chk { display: inline-flex; align-items: center; gap: 6px; font-size: 13.5
 .showmore { text-align: center; margin: 28px 0 0; }
 
 /* ── fix list: one plain-language card per action ─── */
+.safe { margin: 22px 0 8px; border: 1px solid var(--frame); border-radius: 8px; background: var(--panel); }
+.safe > summary { cursor: pointer; padding: 12px 14px; font-weight: 600; }
+.safe > summary .hint { font-weight: 400; margin-left: 6px; }
+.saferow { display: grid; grid-template-columns: minmax(0, 220px) minmax(0, 1fr); gap: 4px 14px; padding: 10px 14px; border-top: 1px solid var(--frame); font-size: 13px; }
+.saferow .reason { color: var(--text); }
+.saferow .hint { grid-column: 2; margin: 0; }
+@media (max-width: 640px) { .saferow { grid-template-columns: minmax(0, 1fr); } .saferow .hint { grid-column: 1; } }
 .listctl { display: flex; justify-content: flex-end; gap: 16px; margin: 4px 0 6px; }
 .listctl button { background: none; border: 0; padding: 0; cursor: pointer; font-size: 13px; color: var(--muted); text-decoration: underline; text-underline-offset: 2px; }
 .card { margin: 8px 0; border-radius: 8px; }
@@ -301,12 +308,13 @@ label.chk { display: inline-flex; align-items: center; gap: 6px; font-size: 13.5
         <button data-v="" class="on">All</button><button data-v="dependency">Dependencies</button><button data-v="code">Code</button><button data-v="secret">Secrets</button>
       </div>
       <select id="exposure" aria-label="Where it runs">
-        <option value="">Runs anywhere</option><option value="server">Server</option><option value="universal">Server + browser</option>
+        <option value="">Runs anywhere</option><option value="server">Server</option><option value="local">Local process</option><option value="universal">Server + browser</option>
         <option value="client">Browser only</option><option value="build">Build/test only</option><option value="unused">Not imported</option>
       </select>
       <label class="chk"><input type="checkbox" id="hideDev"> Hide build/dev-only</label>
       <input type="search" id="q" placeholder="Search package, file, CVE, rule…">
     </div>
+    <p class="hint" id="sorthint"></p>
     <p class="hint" id="hint"></p>
     <div id="list"></div>
   </section>
@@ -338,13 +346,26 @@ const IMPACT = {
 };
 const ACTION = { critical: 'Fix now', high: 'Fix soon', medium: 'Plan a fix', low: 'Low priority', none: 'Info' };
 const WHERE = {
-  server: 'On your server, reachable by attackers over the internet',
+  server: 'On your server',
+  local: 'In a local process (CLI / stdio) with no network listener; only the person running it can send it input',
   universal: "On your server and in visitors' browsers",
   client: "Only in visitors' browsers",
   build: 'Only while building or testing; not shipped to users',
   unused: 'Installed, but your code never imports it',
   unknown: 'Could not tell where this runs',
 };
+function whereText(ctx) {
+  const s = state.report?.reachability?.surface;
+  if ((ctx === 'server' || ctx === 'universal') && s?.kind === 'network') return `${WHERE[ctx]}, and the app accepts connections from the network (${s.evidence[0]})`;
+  return WHERE[ctx];
+}
+const REACH = {
+  loaded: (r) => `Yes: ${r.chain.join(' → ')}${r.where ? `, and your code uses ${r.feature} (${r.where})` : ''}`,
+  'feature-unused': (r) => `It is loaded (${r.chain.join(' → ')}), but your code never uses ${r.feature}, which is where this bug lives`,
+  'not-loaded': () => 'No. It is installed, but nothing your code imports ever loads it',
+  unknown: () => 'Unknown: node_modules does not match the lockfile, so loading could not be traced',
+};
+const reachRow = (f) => (f.reachability ? `<div class="k">Does your code load it?</div><div>${esc(REACH[f.reachability.status](f.reachability))}</div>` : '');
 const cap = (s) => s[0].toUpperCase() + s.slice(1);
 const lvl = (f) => (state.sort === 'severity' ? f.severity : f.risk);
 function cmpVer(a, b) {
@@ -358,7 +379,7 @@ function cmpVer(a, b) {
   }
   return 0;
 }
-const EXPO = { server: ['critical', 'Server'], universal: ['critical', 'Server + browser'], client: ['medium', 'Browser only'], build: ['low', 'Build/test'], unused: ['muted', 'Not imported'], unknown: ['muted', 'Unknown'] };
+const EXPO = { server: ['critical', 'Server'], local: ['medium', 'Local process'], universal: ['critical', 'Server + browser'], client: ['medium', 'Browser only'], build: ['low', 'Build/test'], unused: ['muted', 'Not imported'], unknown: ['muted', 'Unknown'] };
 const KIND = { dependency: 'Dependency', code: 'Code', secret: 'Secret' };
 const ICON = {
   dependency: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M12 3 4 7v10l8 4 8-4V7l-8-4z"/><path d="m4 7 8 4 8-4M12 11v10"/></svg>',
@@ -409,6 +430,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)">
@@ -618,7 +640,8 @@ function pkgCard(g) {
     `${esc(p.name)}@${esc(p.version)}${root ? ` · via ${esc(root)}` : ''}${!p.prod ? ' · dev dependency' : ''}`,
     `<div class="k">What's wrong</div><div>${n === 1 ? 'This version has a known security issue' : `This version has <b>${n} known security issues</b>`}. The worst: “${esc(top.title)}”.</div>
       <div class="k">What could happen</div><div>${esc(IMPACT[top.vulnClass] ?? IMPACT.other)}</div>
-      <div class="k">Where it runs</div><div>${esc(WHERE[ctx])}</div>
+      <div class="k">Where it runs</div><div>${esc(whereText(ctx))}</div>
+      ${reachRow(top)}
       <div class="k">How to fix</div><div>${how}</div>`,
     `Show ${n === 1 ? 'details' : `all ${n} issues and details`}`);
 }
@@ -681,7 +704,7 @@ function singleCard(g) {
     `${esc(f.location.file)} · line ${f.location.line}`,
     `<div class="k">What's wrong</div><div>${wrong}</div>
       <div class="k">What could happen</div><div>${esc(IMPACT[f.vulnClass] ?? IMPACT.other)}</div>
-      <div class="k">Where it runs</div><div>${esc(WHERE[ctx])}</div>
+      <div class="k">Where it runs</div><div>${esc(whereText(ctx))}</div>
       ${f.location.snippet ? `<div class="k">The code</div><div><pre>${esc(f.location.snippet)}</pre></div>` : ''}
       <div class="k">How to fix</div><div>${esc(f.fix)}</div>`,
     'Show details');
@@ -707,14 +730,44 @@ function toggleCard(card, open) {
   btn.textContent = show ? 'Hide details' : btn.dataset.label;
 }
 
+// The single most convincing reason a group is low risk here, strongest evidence first.
+const SAFE_WHY = [/^Never loaded/, /never uses/, /^No network listener/, /^Dev\/build|^In test\/build/, /never imported/, /^Only runs in the browser/, /^AI \(/];
+function safeWhy(g) {
+  const reasons = g.findings[0].reasons ?? [];
+  for (const re of SAFE_WHY) {
+    const hit = reasons.find((r) => re.test(r));
+    if (hit) return hit;
+  }
+  return 'Low risk once adjusted for how this codebase uses it.';
+}
+
+function safeRow(g) {
+  const f = g.findings[0];
+  const target = g.type === 'pkg' ? g.findings.map((x) => x.package.fixedIn).filter(Boolean).sort(cmpVer).at(-1) : null;
+  const subject = g.type === 'pkg' ? `${f.package.name}@${f.package.version}` : `${f.location.file}:${f.location.line}`;
+  const n = g.findings.length;
+  return `<div class="saferow">
+    <div><span class="pill low">${n === 1 ? '1 issue' : `${n} issues`}</span> <code>${esc(subject)}</code></div>
+    <div class="reason">${esc(safeWhy(g))}</div>
+    ${target ? `<p class="hint">Still worth updating to ${esc(target)} when convenient, so scanners stop flagging it.</p>` : ''}
+  </div>`;
+}
+
 function renderFix(list) {
-  const groups = buildGroups(list);
-  state.groupMap = new Map(groups.map((g) => [g.key, g]));
+  const all = buildGroups(list);
+  // Split by REAL risk (even when sorted by raw severity): anything medium or worse needs action.
+  const isSafe = (g) => g.findings.every((f) => f.risk === 'low' || f.risk === 'none');
+  const groups = all.filter((g) => !isSafe(g));
+  const safe = all.filter(isSafe);
+  state.groupMap = new Map(all.map((g) => [g.key, g]));
   const deps = groups.filter((g) => g.type === 'pkg').length;
-  $('#hint').textContent = `${groups.length} things to fix, most urgent first.${deps ? ` Issues in the same package are grouped (${deps} package${deps === 1 ? '' : 's'}), because one update usually fixes all of them.` : ''}`;
-  $('#list').innerHTML = '<div class="listctl"><button type="button" data-all="1">Expand all</button><button type="button" data-all="">Collapse all</button></div>' +
+  $('#hint').textContent = (groups.length ? `${groups.length} thing${groups.length === 1 ? '' : 's'} to fix, most urgent first.` : 'Nothing here needs fixing in this codebase.') +
+    (deps ? ` Issues in the same package are grouped, because one update usually fixes all of them.` : '') +
+    (safe.length ? ` ${safe.length} more ${safe.length === 1 ? 'is' : 'are'} low risk here; see the list at the bottom for why.` : '');
+  $('#list').innerHTML = (groups.length ? '<div class="listctl"><button type="button" data-all="1">Expand all</button><button type="button" data-all="">Collapse all</button></div>' : '') +
     groups.slice(0, state.shown).map((g) => (g.type === 'pkg' ? pkgCard(g) : singleCard(g))).join('') +
-    (groups.length > state.shown ? `<div class="showmore"><button class="btn" id="more">Show ${Math.min(PAGE, groups.length - state.shown)} more of ${groups.length - state.shown}</button></div>` : '');
+    (groups.length > state.shown ? `<div class="showmore"><button class="btn" id="more">Show ${Math.min(PAGE, groups.length - state.shown)} more of ${groups.length - state.shown}</button></div>` : '') +
+    (safe.length ? `<details class="safe"><summary>Low risk in this codebase (${safe.length})<span class="hint">why each one isn't a real threat here</span></summary>${safe.map(safeRow).join('')}</details>` : '');
   $('#more')?.addEventListener('click', () => { state.shown += PAGE; render(); });
   document.querySelectorAll('.card').forEach((c) => {
     c.querySelector('.fbar').onclick = () => openCard(c);
@@ -729,9 +782,10 @@ function renderFix(list) {
 function render() {
   const r = state.report;
   header(r);
-  $('#hint').textContent = state.sort === 'risk'
-    ? 'Worst first: severity adjusted for where the code runs, whether your code reaches it, and whether it is exploited in the wild.'
-    : 'High → low: the raw CVSS score of each advisory or the rule severity, ignoring how your app uses it.';
+  $('#sorthint').textContent = state.sort === 'risk'
+    ? 'Worst first ranks by real risk in this codebase: where the code runs, whether your code loads it, and whether it is exploited in the wild. High → low shows the raw CVSS severity instead (what npm audit shows).'
+    : 'High → low ranks by raw CVSS severity, ignoring how your app uses it (what npm audit shows). Worst first ranks by real risk in this codebase instead.';
+  $('#hint').textContent = '';
   const list = filtered();
   if (!list.length) {
     $('#list').innerHTML = `<div class="empty">${r.findings.length ? 'No findings match these filters.' : '✓ No known vulnerabilities or insecure code patterns found.'}</div>`;

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 };
 }