kirograph 0.17.0 → 0.19.0

package/dist/mcp/tools.js

@@ -46,6 +46,18 @@ const MAX_OUTPUT = 15e3;
 function truncate(s) {
   return s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + "\n\u2026[truncated]" : s;
 }
+function estimateFileTokens(projectRoot, filePaths) {
+  let total = 0;
+  for (const fp of filePaths) {
+    try {
+      const fullPath = path.isAbsolute(fp) ? fp : path.join(projectRoot, fp);
+      const stat = fs.statSync(fullPath);
+      total += Math.round(stat.size / 4);
+    } catch {
+    }
+  }
+  return total;
+}
 function clampLimit(value, defaultValue) {
   const n = typeof value === "number" ? value : defaultValue;
   return Math.max(1, Math.min(100, Math.round(n)));
@@ -357,6 +369,77 @@ const tools = [
       }
     }
   },
+  {
+    name: "kirograph_read",
+    description: 'Read a file with caching and multiple modes. First read returns full content; subsequent reads of unchanged files return a compact "cached" marker (~13 tokens). Supports modes: full, map, signatures, diff, lines, imports, exports.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "File path to read (absolute or relative to project root)" },
+        mode: {
+          type: "string",
+          description: 'Read mode: "full" (default), "map" (structure overview), "signatures" (function signatures), "diff" (changes since last read), "lines" (line range), "imports", "exports"',
+          enum: ["full", "map", "signatures", "diff", "lines", "imports", "exports"],
+          default: "full"
+        },
+        start: { type: "number", description: "Start line (for lines mode)" },
+        end: { type: "number", description: "End line (for lines mode)" },
+        noCache: { type: "boolean", description: "Force fresh read, bypass cache (default: false)", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["path"]
+    }
+  },
+  {
+    name: "kirograph_budget",
+    description: "Show current session context budget usage. Returns tokens consumed, remaining budget, and utilization percentage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reset: { type: "boolean", description: "Reset session budget counters (default: false)", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_flows",
+    description: "Trace execution flows from entry points (routes, handlers, main functions) through the call graph. Returns ordered call chains sorted by criticality.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        entryPoint: { type: "string", description: "Symbol name to trace from, or omit to auto-detect entry points" },
+        maxFlows: { type: "number", description: "Max number of flows to return (default 10)" },
+        maxDepth: { type: "number", description: "Max call chain depth (default 10)" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_communities",
+    description: "Detect code communities (clusters of related symbols) using graph-based community detection. Shows which code belongs together and how communities are coupled.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        resolution: { type: "number", description: "Resolution parameter (default 1.0, higher = more communities)" },
+        limit: { type: "number", description: "Max communities to return (default 15)" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_refactor",
+    description: 'Refactoring assistant. Use mode "rename" to preview all locations that reference a symbol (rename preview). Use mode "suggest" for community-driven refactoring suggestions.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        mode: { type: "string", description: 'Mode: "rename" (preview references) or "suggest" (refactoring suggestions)', enum: ["rename", "suggest"] },
+        symbol: { type: "string", description: "Symbol name (required for rename mode)" },
+        limit: { type: "number", description: "Max results (default 10)" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["mode"]
+    }
+  },
   // ── Memory tools (require enableMemory=true) ────────────────────────────────
   {
     name: "kirograph_mem_search",
@@ -372,6 +455,7 @@ const tools = [
         },
         limit: { type: "number", description: "Max results (default: 10)", default: 10 },
         sessionId: { type: "string", description: "Filter to specific session" },
+        asOf: { type: "number", description: "Query facts valid at this timestamp (epoch ms). Filters out expired/superseded observations." },
         projectPath: { type: "string", description: "Project root path (optional)" }
       },
       required: ["query"]
@@ -586,6 +670,184 @@ const tools = [
       },
       required: ["dataset"]
     }
+  },
+  // ── Security tools (require enableSecurity=true) ────────────────────────────
+  {
+    name: "kirograph_security",
+    description: "Security overview: vulnerability counts, affected/not_affected verdicts, stale data warnings. Requires enableSecurity=true and enableArchitecture=true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_vulns",
+    description: "List vulnerabilities with reachability verdicts, severity, and affected components. Supports on-demand refresh.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        severity: { type: "string", description: "Filter by severity level", enum: ["critical", "high", "medium", "low"] },
+        verdict: { type: "string", description: "Filter by reachability verdict", enum: ["affected", "not_affected", "under_investigation"] },
+        limit: { type: "number", description: "Max results (default: 20)", default: 20 },
+        refresh: { type: "boolean", description: "Trigger fresh vulnerability enrichment before listing (default: false)", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_vuln_add",
+    description: "Manually register a CVE against a dependency without querying external databases.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cveId: { type: "string", description: 'CVE identifier (e.g., "CVE-2023-12345")' },
+        package: { type: "string", description: "Package name to associate the CVE with" },
+        severity: { type: "number", description: "CVSS v3.1 base score (optional)" },
+        summary: { type: "string", description: "Vulnerability summary (optional)" },
+        fixedVersion: { type: "string", description: "Version that fixes the vulnerability (optional)" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["cveId", "package"]
+    }
+  },
+  {
+    name: "kirograph_vuln_suppress",
+    description: "Suppress a CVE so it no longer appears in vulnerability reports (mark as false positive or accepted risk). Suppressions are stored in .kirograph/security-suppressions.json.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cveId: { type: "string", description: 'CVE identifier to suppress (e.g., "CVE-2024-1234")' },
+        reason: { type: "string", description: "Reason for suppression (optional)" },
+        expires: { type: "string", description: 'Expiry date in ISO format after which the suppression is removed (e.g. "2026-12-31", optional)' },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["cveId"]
+    }
+  },
+  {
+    name: "kirograph_sbom",
+    description: "Generate and return CycloneDX 1.5 SBOM JSON for the project.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_vex",
+    description: "Generate and return CycloneDX 1.5 VEX JSON with reachability verdicts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_reachability",
+    description: "Check reachability for a specific dependency or vulnerability. Returns verdict, paths, and impact summary.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", description: "Dependency name or CVE ID to check reachability for" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["target"]
+    }
+  },
+  {
+    name: "kirograph_staleness",
+    description: "Check dependency freshness \u2014 identifies packages significantly behind their latest published version.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        threshold: { type: "number", description: "Only return packages with staleness_score >= threshold (default: 0.3)", default: 0.3 },
+        refresh: { type: "boolean", description: "Fetch latest version info from registries before listing (default: false)", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_licenses",
+    description: "Show dependency licenses and check against the configured license policy (deny/warn lists). Supports wildcard patterns (e.g. GPL-* matches GPL-2.0, GPL-3.0-only).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        policy: { type: "boolean", description: "Return only policy violations (default: false)", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_attack_surface",
+    description: "Map the attack surface: all HTTP routes and their paths to vulnerable dependencies, with hop count, authentication status, and risk score.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Max routes to return (default: 20)", default: 20 },
+        publicOnly: { type: "boolean", description: "Only return public/unauthenticated routes", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_secrets",
+    description: "Scan for hardcoded secrets and credentials, enriched with call-graph blast radius showing which entry points reach the secret.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        includeTests: { type: "boolean", description: "Include test files in scan", default: false },
+        severity: { type: "string", description: "Filter by severity: critical, high, medium, low", enum: ["critical", "high", "medium", "low"] },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_security_flows",
+    description: "SAST-lite: detect dangerous data flows (SQL injection, dangerous eval, unsafe deserialization, path traversal, weak crypto). Each finding tagged with OWASP Top 10 category.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", description: "Filter by type: sql, eval, deserialize, path, crypto, all", default: "all" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_supply_chain",
+    description: "Supply chain health: OpenSSF Scorecard scores, maintainer count, abandoned package detection for project dependencies.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        threshold: { type: "string", description: "Minimum risk level: critical, high, medium", enum: ["critical", "high", "medium"] },
+        refresh: { type: "boolean", description: "Re-fetch from APIs", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_dep_confusion",
+    description: "Detect dependency confusion vulnerabilities: internal package names that exist in public registries (typosquatting/supply chain attack vectors).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_remediation",
+    description: "Remediation SLA tracking: which vulnerabilities are overdue for fixing based on severity thresholds (critical=7d, high=30d, medium=90d).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        overdueOnly: { type: "boolean", description: "Show only overdue items", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
   }
 ];
 class ToolHandler {
@@ -639,6 +901,7 @@ class ToolHandler {
   async getConnection(projectPath) {
     if (!projectPath) return this.defaultCg;
     const resolved = path.resolve(projectPath);
+    if (!path.isAbsolute(resolved)) return null;
     if (this.connections.has(resolved)) return this.connections.get(resolved);
     try {
       const cg = await import__.default.open(resolved);
@@ -769,6 +1032,69 @@ class ToolHandler {
       }
       return lines.join("\n");
     }
+    if (toolName === "kirograph_read") {
+      const filePath = args.path;
+      if (!filePath) return "Error: path is required.";
+      const projectRoot = args.projectPath || process.cwd();
+      const resolvedPath = path.isAbsolute(filePath) ? filePath : path.join(projectRoot, filePath);
+      const mode = args.mode ?? "full";
+      const noCache = args.noCache ?? false;
+      if (!fs.existsSync(resolvedPath)) {
+        return `Error: File not found: ${resolvedPath}`;
+      }
+      const { getFileReadCache } = await Promise.resolve().then(() => require("./cache.js"));
+      const { executeReadMode } = await Promise.resolve().then(() => require("./read-modes.js"));
+      const cache = getFileReadCache();
+      if (mode !== "full") {
+        let cg2 = null;
+        try {
+          cg2 = await this.getConnection(args.projectPath);
+        } catch {
+        }
+        const result2 = executeReadMode({
+          mode,
+          filePath: resolvedPath,
+          start: args.start,
+          end: args.end,
+          cg: cg2
+        });
+        cache.read(resolvedPath, true);
+        return result2.content;
+      }
+      const result = cache.read(resolvedPath, noCache);
+      if (result.cached) {
+        return result.content;
+      }
+      if (result.changed) {
+        return `[file changed since last read]
+
+${result.content}`;
+      }
+      return result.content;
+    }
+    if (toolName === "kirograph_budget") {
+      const projectRoot = args.projectPath || process.cwd();
+      const reset = args.reset ?? false;
+      const { BudgetTracker } = await Promise.resolve().then(() => require("../compression/tracker.js"));
+      const budget = BudgetTracker.getInstance(projectRoot);
+      if (reset) {
+        budget.reset();
+        return "Context budget counters reset.";
+      }
+      const status = budget.getStatus();
+      const lines = [
+        "Context Budget:",
+        `  Tokens consumed: ${status.consumed.toLocaleString()}`,
+        `  Budget limit:    ${status.limit > 0 ? status.limit.toLocaleString() : "unlimited"}`,
+        `  Remaining:       ${status.limit > 0 ? status.remaining.toLocaleString() : "\u221E"}`,
+        `  Utilization:     ${status.utilization}%`
+      ];
+      if (status.warning) {
+        lines.push(`
+  \u26A0 ${status.warning}`);
+      }
+      return lines.join("\n");
+    }
     const cg = await this.getConnection(args.projectPath);
     if (!cg) return "KiroGraph not initialized. Run `kirograph init` in your project first.";
     writeSessionMarker(cg.getProjectRoot());
@@ -906,6 +1232,51 @@ class ToolHandler {
           }
         } catch {
         }
+        try {
+          const projectRootSec = cg.getProjectRoot();
+          const configSec = await (await Promise.resolve().then(() => require("../config.js"))).loadConfig(projectRootSec);
+          if (configSec.enableSecurity) {
+            const dbSec = cg.getDatabase();
+            dbSec.applySecuritySchema();
+            const rawDbSec = dbSec.getRawDb();
+            const contextNodeIds = [
+              ...ctx.entryPoints.map((n) => n.id),
+              ...ctx.relatedNodes.map((n) => n.id)
+            ].filter(Boolean);
+            if (contextNodeIds.length > 0) {
+              const { getSecurityWarningsForNodes, formatSecurityWarnings } = await Promise.resolve().then(() => require("../security/context-warnings.js"));
+              const warnings = getSecurityWarningsForNodes(rawDbSec, contextNodeIds);
+              if (warnings.length > 0) {
+                const nodeNames = /* @__PURE__ */ new Map();
+                for (const n of ctx.entryPoints) {
+                  nodeNames.set(n.id, n.name);
+                }
+                for (const n of ctx.relatedNodes) {
+                  nodeNames.set(n.id, n.name);
+                }
+                const secSection = formatSecurityWarnings(warnings, nodeNames);
+                if (secSection) {
+                  lines.push(secSection);
+                }
+              }
+            }
+          }
+        } catch {
+        }
+        const graphTokens = lines.join("\n").length / 4;
+        const uniqueFiles = /* @__PURE__ */ new Set([
+          ...ctx.entryPoints.map((n) => n.filePath),
+          ...ctx.relatedNodes.map((n) => n.filePath)
+        ]);
+        if (uniqueFiles.size > 0) {
+          const naiveTokens = estimateFileTokens(cg.getProjectRoot(), [...uniqueFiles]);
+          if (naiveTokens > 0) {
+            const savingsPct = Math.round((1 - graphTokens / naiveTokens) * 100);
+            if (savingsPct > 0) {
+              lines.push("", `---`, `Context savings: ~${Math.round(graphTokens)} tokens (graph) vs ~${naiveTokens} tokens (full files) \u2014 ${savingsPct}% reduction`);
+            }
+          }
+        }
         return lines.join("\n");
       }
       case "kirograph_callers": {
@@ -1035,6 +1406,23 @@ class ToolHandler {
           }
         } catch {
         }
+        let securityLine = "  Security: disabled";
+        try {
+          const { loadConfig: loadCfgSec } = await Promise.resolve().then(() => require("../config.js"));
+          const cfgSec = await loadCfgSec(cg.getProjectRoot());
+          if (cfgSec.enableSecurity) {
+            const db = cg.getDatabase();
+            db.applySecuritySchema();
+            const rawDb = db.getRawDb();
+            const depCount = rawDb.get("SELECT COUNT(*) as cnt FROM sec_dependencies")?.cnt ?? 0;
+            const vulnCount = rawDb.get("SELECT COUNT(*) as cnt FROM sec_vulnerabilities")?.cnt ?? 0;
+            const affectedCount = rawDb.get("SELECT COUNT(*) as cnt FROM sec_reachability WHERE verdict = 'affected'")?.cnt ?? 0;
+            const staleCount = rawDb.get("SELECT COUNT(*) as cnt FROM sec_dependencies WHERE vuln_data_stale = 1")?.cnt ?? 0;
+            const staleNote = staleCount > 0 ? ` \u26A0 ${staleCount} stale` : "";
+            securityLine = `  Security: enabled \u2014 ${depCount} deps, ${vulnCount} vulns (${affectedCount} affected)${staleNote}`;
+          }
+        } catch {
+        }
         const threshold = stats.syncWarningThreshold ?? 10;
         const pendingFiles = stats.pendingFiles ?? 0;
         const syncRunning = stats.syncRunning ?? false;
@@ -1065,6 +1453,7 @@ class ToolHandler {
           archLine,
           docsLine,
           dataLine,
+          securityLine,
           `  DB size: ${dbMb} MB`,
           ...semanticLines,
           ...syncLines,
@@ -1386,6 +1775,122 @@ class ToolHandler {
         }
         return lines.join("\n");
       }
+      case "kirograph_flows": {
+        const { getExecutionFlows, traceFlow, detectEntryPoints } = await Promise.resolve().then(() => require("../graph/flows.js"));
+        const db = cg.getDatabase();
+        if (args.entryPoint) {
+          const results = cg.searchNodes(args.entryPoint, void 0, 5);
+          if (results.length === 0) return `Symbol "${args.entryPoint}" not found in index.`;
+          const hops = traceFlow(db, results[0].node.id, args.maxDepth ?? 10);
+          if (hops.length < 2) return `No outgoing call chain found from "${args.entryPoint}".`;
+          const lines2 = [`## Execution flow from \`${args.entryPoint}\``, ""];
+          for (let i = 0; i < hops.length; i++) {
+            const hop = hops[i];
+            const indent = "  ".repeat(i);
+            const arrow = i === 0 ? "\u2192" : "\u21B3";
+            const conf = hop.confidence && hop.confidence !== "extracted" ? ` [${hop.confidence}]` : "";
+            lines2.push(`${indent}${arrow} ${hop.kind} \`${hop.symbol}\` \u2014 ${hop.filePath}:${hop.line}${conf}`);
+          }
+          return lines2.join("\n");
+        }
+        const flows = getExecutionFlows(db, {
+          maxFlows: args.maxFlows ?? 10,
+          maxDepth: args.maxDepth ?? 10
+        });
+        if (flows.length === 0) return "No execution flows detected. The graph may be too small or have no call edges.";
+        const lines = [`## Execution Flows (${flows.length} detected)`, ""];
+        for (const flow of flows) {
+          lines.push(`### \`${flow.entryPoint}\` (${flow.entryPointKind}) \u2014 criticality: ${flow.criticality.toFixed(2)}`);
+          lines.push(`File: ${flow.entryPointFile}`, "");
+          for (let i = 0; i < flow.hops.length; i++) {
+            const hop = flow.hops[i];
+            const indent = "  ".repeat(Math.min(i, 5));
+            const arrow = i === 0 ? "\u2192" : "\u21B3";
+            const conf = hop.confidence && hop.confidence !== "extracted" ? ` [${hop.confidence}]` : "";
+            lines.push(`${indent}${arrow} \`${hop.symbol}\` (${hop.kind}) \u2014 ${hop.filePath}:${hop.line}${conf}`);
+          }
+          lines.push("");
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_communities": {
+        const { detectCommunities } = await Promise.resolve().then(() => require("../graph/communities.js"));
+        const db = cg.getDatabase();
+        const result = detectCommunities(db, {
+          resolution: args.resolution ?? 1
+        });
+        if (result.communities.length === 0) return "No communities detected. The graph may be too small or have no edges.";
+        const limit = Math.min(args.limit ?? 15, result.communities.length);
+        const lines = [
+          `## Communities (${result.communities.length} detected, modularity: ${result.modularity.toFixed(3)})`,
+          `Graph: ${result.totalNodes} nodes, ${result.totalEdges} edges`,
+          ""
+        ];
+        for (const c of result.communities.slice(0, limit)) {
+          lines.push(`### ${c.label} (${c.memberCount} symbols)`);
+          lines.push(`- Directory: \`${c.dominantDirectory}\``);
+          lines.push(`- Language: ${c.dominantLanguage}`);
+          lines.push(`- Inter-community edges: ${c.interCommunityEdges}`);
+          lines.push(`- Top members:`);
+          for (const m of c.members.slice(0, 8)) {
+            lines.push(`  - ${m.kind} \`${m.name}\` \u2014 ${m.filePath}`);
+          }
+          if (c.memberCount > 8) lines.push(`  - \u2026and ${c.memberCount - 8} more`);
+          lines.push("");
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_refactor": {
+        const { renamePreview, suggestRefactorings } = await Promise.resolve().then(() => require("../graph/refactor.js"));
+        const db = cg.getDatabase();
+        const mode = args.mode;
+        if (mode === "rename") {
+          if (!args.symbol) return 'Error: "symbol" parameter is required for rename mode.';
+          const preview = renamePreview(db, args.symbol);
+          if (!preview) return `Symbol "${args.symbol}" not found in index.`;
+          const lines = [
+            `## Rename Preview: \`${preview.symbol}\``,
+            `Kind: ${preview.kind}`,
+            `Defined at: ${preview.filePath}:${preview.line}`,
+            `Total references: ${preview.totalReferences}`,
+            ""
+          ];
+          if (preview.references.length === 0) {
+            lines.push("No references found \u2014 this symbol can be safely renamed without affecting other code.");
+          } else {
+            const byFile = /* @__PURE__ */ new Map();
+            for (const ref of preview.references) {
+              if (!byFile.has(ref.filePath)) byFile.set(ref.filePath, []);
+              byFile.get(ref.filePath).push(ref);
+            }
+            for (const [file, refs] of byFile) {
+              lines.push(`### ${file} (${refs.length} references)`);
+              for (const ref of refs.slice(0, 10)) {
+                lines.push(`- Line ${ref.line}: \`${ref.context}\` (${ref.edgeKind})`);
+              }
+              if (refs.length > 10) lines.push(`  \u2026and ${refs.length - 10} more`);
+              lines.push("");
+            }
+          }
+          return lines.join("\n");
+        }
+        if (mode === "suggest") {
+          const suggestions = suggestRefactorings(db, args.limit ?? 10);
+          if (suggestions.length === 0) return "No refactoring suggestions \u2014 the codebase structure looks clean.";
+          const lines = [`## Refactoring Suggestions (${suggestions.length})`, ""];
+          for (const s of suggestions) {
+            const icon = s.priority === "high" ? "\u{1F534}" : s.priority === "medium" ? "\u{1F7E1}" : "\u{1F7E2}";
+            lines.push(`${icon} **${s.type}** [${s.priority}]: ${s.description}`);
+            lines.push(`   Rationale: ${s.rationale}`);
+            if (s.symbols.length > 0) {
+              lines.push(`   Symbols: ${s.symbols.slice(0, 3).join(", ")}`);
+            }
+            lines.push("");
+          }
+          return lines.join("\n");
+        }
+        return 'Unknown mode. Use "rename" or "suggest".';
+      }
       // ── Memory tools ────────────────────────────────────────────────────────
       case "kirograph_mem_search": {
         const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
@@ -1400,7 +1905,8 @@ class ToolHandler {
         const results = await mem.search(args.query, {
           limit: args.limit ?? 10,
           kind: args.kind,
-          sessionId: args.sessionId
+          sessionId: args.sessionId,
+          asOf: args.asOf
         });
         if (results.length === 0) return `No memory observations found for "${args.query}".`;
         return results.map((r, i) => {
@@ -1830,6 +2336,659 @@ ${lines.join("\n")}`;
 
 ${lines.join("\n")}`;
       }
+      // ── Security tools (require enableSecurity=true) ──────────────────────────
+      case "kirograph_security": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        if (!config.enableArchitecture) return "Security requires architecture analysis. Set enableArchitecture: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const rawDb = db.getRawDb();
+        const depCount = rawDb.get(
+          `SELECT COUNT(*) as count FROM sec_dependencies`
+        ) ?? { count: 0 };
+        const vulnCount = rawDb.get(
+          `SELECT COUNT(*) as count FROM sec_vulnerabilities`
+        ) ?? { count: 0 };
+        const verdictRows = rawDb.all(
+          `SELECT verdict, COUNT(*) as count FROM sec_reachability GROUP BY verdict`
+        );
+        const verdicts = {};
+        for (const row of verdictRows) {
+          verdicts[row.verdict] = row.count;
+        }
+        const staleCount = rawDb.get(
+          `SELECT COUNT(*) as count FROM sec_dependencies WHERE vuln_data_stale = 1`
+        ) ?? { count: 0 };
+        const { SuppressionManager: SecSuppressionManager } = await Promise.resolve().then(() => require("../security/suppressions.js"));
+        const secSuppressions = new SecSuppressionManager(projectRoot);
+        const allCveIds = rawDb.all(`SELECT cve_id FROM sec_vulnerabilities`);
+        const suppressedCveCount = allCveIds.filter((r) => secSuppressions.isSuppressed(r.cve_id)).length;
+        const visibleVulnCount = vulnCount.count - suppressedCveCount;
+        const lines = [
+          "# Security Overview",
+          "",
+          `Dependencies: ${depCount.count}`,
+          `Vulnerabilities: ${visibleVulnCount}${suppressedCveCount > 0 ? ` (${suppressedCveCount} suppressed)` : ""}`
+        ];
+        if (visibleVulnCount > 0) {
+          const affected = verdicts["affected"] ?? 0;
+          const notAffected = verdicts["not_affected"] ?? 0;
+          const underInvestigation = verdicts["under_investigation"] ?? 0;
+          const pending = visibleVulnCount - affected - notAffected - underInvestigation;
+          lines.push("", "## Reachability Verdicts", "");
+          if (affected > 0) lines.push(`\u25CF Affected: ${affected}`);
+          if (notAffected > 0) lines.push(`\u25CF Not affected: ${notAffected}`);
+          if (underInvestigation > 0) lines.push(`\u25CF Under investigation: ${underInvestigation}`);
+          if (pending > 0) lines.push(`\u25CF Pending analysis: ${pending}`);
+        }
+        if (staleCount.count > 0) {
+          lines.push("", `\u26A0 ${staleCount.count} dependenc${staleCount.count === 1 ? "y has" : "ies have"} stale vulnerability data. Use kirograph_vulns with refresh=true to update.`);
+        }
+        const lastVulnCheck = rawDb.get(
+          `SELECT MIN(last_vuln_check) as oldest FROM sec_dependencies WHERE last_vuln_check IS NOT NULL`
+        )?.oldest;
+        if (lastVulnCheck != null) {
+          const ageMs = Date.now() - lastVulnCheck;
+          const ageDays = ageMs / (1e3 * 60 * 60 * 24);
+          const maxAge = config.securityEnrichMaxAgeDays ?? 7;
+          if (ageDays > maxAge) {
+            lines.push("", `\u26A0 Vulnerability data is ${Math.floor(ageDays)} days old (max: ${maxAge}). Run kirograph vulns --refresh to update.`);
+          }
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_vulns": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const rawDb = db.getRawDb();
+        if (args.refresh === true) {
+          const { OsvAdapter } = await Promise.resolve().then(() => require("../security/vuln/osv-adapter.js"));
+          const { VulnerabilityDatabaseClient } = await Promise.resolve().then(() => require("../security/vuln/client.js"));
+          const adapters = config.securityDatabases.map((dbName) => {
+            if (dbName.toUpperCase() === "OSV") return new OsvAdapter();
+            return null;
+          }).filter(Boolean);
+          const client = new VulnerabilityDatabaseClient(adapters, db);
+          await client.enrichAll();
+        }
+        let query = `
+          SELECT
+            v.node_id, v.cve_id, v.severity_score, v.fixed_version, v.summary,
+            v.epss_score, v.epss_percentile, v.risk_score,
+            d.package_name, d.ecosystem, d.resolved_version, d.declared_constraint,
+            r.verdict
+          FROM sec_vulnerabilities v
+          LEFT JOIN edges e ON e.target = v.node_id AND e.kind = 'has_vulnerability'
+          LEFT JOIN sec_dependencies d ON d.node_id = e.source
+          LEFT JOIN sec_reachability r ON r.vulnerability_node_id = v.node_id
+          WHERE 1=1
+        `;
+        const params = [];
+        if (args.severity) {
+          const severityRanges = {
+            critical: [9, 10],
+            high: [7, 8.9],
+            medium: [4, 6.9],
+            low: [0.1, 3.9]
+          };
+          const range = severityRanges[args.severity.toLowerCase()];
+          if (!range) return `Invalid severity: ${args.severity}. Use: critical, high, medium, low`;
+          query += ` AND v.severity_score >= ? AND v.severity_score <= ?`;
+          params.push(range[0], range[1]);
+        }
+        if (args.verdict) {
+          const validVerdicts = ["affected", "not_affected", "under_investigation"];
+          if (!validVerdicts.includes(args.verdict)) {
+            return `Invalid verdict: ${args.verdict}. Use: affected, not_affected, under_investigation`;
+          }
+          query += ` AND r.verdict = ?`;
+          params.push(args.verdict);
+        }
+        const limit = clampLimit(args.limit, 20);
+        query += ` ORDER BY v.risk_score DESC NULLS LAST LIMIT ?`;
+        params.push(limit);
+        const rows = rawDb.all(query, params);
+        const verdictRankMcp = (v) => v === "affected" ? 3 : v === "under_investigation" ? 2 : v === "not_affected" ? 1 : 0;
+        const dedupMapMcp = /* @__PURE__ */ new Map();
+        for (const row of rows) {
+          const key = `${row.cve_id}::${row.package_name ?? ""}::${row.ecosystem ?? ""}`;
+          const ex = dedupMapMcp.get(key);
+          if (!ex || verdictRankMcp(row.verdict) > verdictRankMcp(ex.verdict)) dedupMapMcp.set(key, row);
+        }
+        const dedupedRowsMcp = [...dedupMapMcp.values()];
+        const { SuppressionManager } = await Promise.resolve().then(() => require("../security/suppressions.js"));
+        const suppressionMgr = new SuppressionManager(projectRoot);
+        const suppressedCount = dedupedRowsMcp.filter((row) => suppressionMgr.isSuppressed(row.cve_id)).length;
+        const filteredRows = dedupedRowsMcp.filter((row) => !suppressionMgr.isSuppressed(row.cve_id));
+        if (filteredRows.length === 0) {
+          const noMatch = "No vulnerabilities found" + (args.severity || args.verdict ? " matching filters." : ".");
+          return suppressedCount > 0 ? `${noMatch} (${suppressedCount} suppressed)` : noMatch;
+        }
+        const { formatFixSuggestion } = await Promise.resolve().then(() => require("../security/export/fix-suggestions.js"));
+        const lines = [`Vulnerabilities (${filteredRows.length}${suppressedCount > 0 ? `, ${suppressedCount} suppressed` : ""}):
+`];
+        for (const row of filteredRows) {
+          const score = row.severity_score;
+          let severityLabel;
+          if (score == null) severityLabel = "UNKNOWN";
+          else if (score >= 9) severityLabel = "CRITICAL";
+          else if (score >= 7) severityLabel = "HIGH";
+          else if (score >= 4) severityLabel = "MEDIUM";
+          else severityLabel = "LOW";
+          let verdictLabel;
+          if (!row.verdict) verdictLabel = "pending";
+          else if (row.verdict === "affected") verdictLabel = "affected";
+          else if (row.verdict === "not_affected") verdictLabel = "not affected";
+          else verdictLabel = "investigating";
+          const pkg = row.package_name ? `${row.package_name}@${row.resolved_version || row.declared_constraint || "?"}` : "unknown package";
+          const epssNote = row.epss_score != null ? ` [EPSS: ${row.epss_score.toFixed(2)}]` : "";
+          const riskNote = row.risk_score != null ? ` [Risk: ${row.risk_score.toFixed(1)}]` : "";
+          lines.push(`${severityLabel}  ${row.cve_id}  ${pkg}  [${verdictLabel}]${epssNote}${riskNote}`);
+          if (row.summary && row.summary !== "Manually registered") {
+            const truncSummary = row.summary.length > 120 ? row.summary.slice(0, 120) + "\u2026" : row.summary;
+            lines.push(`  ${truncSummary}`);
+          }
+          if (row.fixed_version && row.ecosystem && row.package_name) {
+            const fix = formatFixSuggestion(row.ecosystem, row.package_name, row.fixed_version);
+            if (fix) lines.push(`  ${fix}`);
+          }
+        }
+        return truncate(lines.join("\n"));
+      }
+      case "kirograph_vuln_add": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const cveId = args.cveId;
+        const pkgName = args.package;
+        if (!cveId) return "Error: cveId is required.";
+        if (!pkgName) return "Error: package is required.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const rawDb = db.getRawDb();
+        const depRow = rawDb.get(
+          `SELECT node_id, ecosystem FROM sec_dependencies WHERE package_name = ?`,
+          [pkgName]
+        );
+        if (!depRow) {
+          return `No dependency found matching "${pkgName}". Run kirograph index first to discover dependencies.`;
+        }
+        const vulnNodeId = `vuln:${cveId}`;
+        const now = Date.now();
+        const severity = args.severity;
+        const summary = args.summary ?? "Manually registered";
+        const fixedVersion = args.fixedVersion ?? null;
+        rawDb.run(
+          `INSERT OR REPLACE INTO nodes
+            (id, kind, name, qualified_name, file_path, language,
+             start_line, end_line, start_column, end_column,
+             is_exported, is_async, is_static, is_abstract, updated_at)
+           VALUES (?, 'vulnerability', ?, ?, '', 'unknown', 0, 0, 0, 0, 0, 0, 0, 0, ?)`,
+          [vulnNodeId, cveId, cveId, now]
+        );
+        rawDb.run(
+          `INSERT OR REPLACE INTO sec_vulnerabilities
+            (node_id, cve_id, severity_score, affected_ranges, fixed_version, summary, source_database)
+           VALUES (?, ?, ?, '[]', ?, ?, 'manual')`,
+          [vulnNodeId, cveId, severity ?? null, fixedVersion, summary]
+        );
+        rawDb.run(
+          `INSERT OR IGNORE INTO edges (source, target, kind, confidence, confidence_score)
+           VALUES (?, ?, 'has_vulnerability', 'extracted', 1.0)`,
+          [depRow.node_id, vulnNodeId]
+        );
+        return `Registered ${cveId} against ${pkgName}.`;
+      }
+      case "kirograph_vuln_suppress": {
+        const projectRoot = cg.getProjectRoot();
+        const cveId = args.cveId;
+        if (!cveId) return "Error: cveId is required.";
+        const { SuppressionManager } = await Promise.resolve().then(() => require("../security/suppressions.js"));
+        const manager = new SuppressionManager(projectRoot);
+        manager.add(cveId, args.reason, args.expires);
+        const reasonNote = args.reason ? ` Reason: ${args.reason}.` : "";
+        const expiresNote = args.expires ? ` Expires: ${args.expires}.` : "";
+        return `${cveId} suppressed.${reasonNote}${expiresNote}`;
+      }
+      case "kirograph_sbom": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const { SBOMExporter } = await Promise.resolve().then(() => require("../security/export/sbom.js"));
+        const exporter = new SBOMExporter(db, projectRoot);
+        const json = exporter.exportJSON();
+        return truncate(json);
+      }
+      case "kirograph_vex": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const { VEXExporter } = await Promise.resolve().then(() => require("../security/export/vex.js"));
+        const exporter = new VEXExporter(db, projectRoot);
+        const json = exporter.exportJSON();
+        return truncate(json);
+      }
+      case "kirograph_reachability": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const target = args.target;
+        if (!target) return "Error: target is required (dependency name or CVE ID).";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const rawDb = db.getRawDb();
+        let vulnerabilityNodeId = null;
+        let targetLabel = target;
+        const vulnRow = rawDb.get(
+          `SELECT node_id FROM sec_vulnerabilities WHERE cve_id = ?`,
+          [target]
+        );
+        if (vulnRow) {
+          vulnerabilityNodeId = vulnRow.node_id;
+        } else {
+          const depRow = rawDb.get(
+            `SELECT node_id, package_name FROM sec_dependencies WHERE package_name = ?`,
+            [target]
+          );
+          if (depRow) {
+            targetLabel = depRow.package_name;
+            const vulnEdge = rawDb.get(
+              `SELECT target FROM edges WHERE source = ? AND kind = 'has_vulnerability' LIMIT 1`,
+              [depRow.node_id]
+            );
+            if (vulnEdge) {
+              vulnerabilityNodeId = vulnEdge.target;
+            } else {
+              return `No vulnerabilities found for dependency "${target}". The dependency exists but has no known vulnerabilities.`;
+            }
+          } else {
+            return `Target "${target}" not found. Provide a valid CVE ID or dependency package name.`;
+          }
+        }
+        const { ReachabilityAnalyzer } = await Promise.resolve().then(() => require("../security/reachability.js"));
+        const analyzer = new ReachabilityAnalyzer(db, config);
+        const result = await analyzer.analyze(vulnerabilityNodeId);
+        const lines = [
+          `# Reachability: ${targetLabel}`,
+          "",
+          `Verdict: ${result.verdict}`,
+          `Reaching entry points: ${result.reachingEntryPointCount}`
+        ];
+        if (result.paths.length > 0) {
+          lines.push("", "## Paths");
+          for (const p of result.paths.slice(0, 5)) {
+            lines.push(`- From ${p.entryPoint}: ${p.path.join(" \u2192 ")}`);
+          }
+          if (result.paths.length > 5) {
+            lines.push(`  \u2026and ${result.paths.length - 5} more paths`);
+          }
+        }
+        if (result.unresolvedSymbols.length > 0) {
+          lines.push("", "## Unresolved Symbols");
+          for (const sym of result.unresolvedSymbols.slice(0, 10)) {
+            lines.push(`- ${sym}`);
+          }
+          if (result.unresolvedSymbols.length > 10) {
+            lines.push(`  \u2026and ${result.unresolvedSymbols.length - 10} more`);
+          }
+        }
+        if (result.verdict === "affected") {
+          const impact = await analyzer.getImpactSummary(vulnerabilityNodeId);
+          if (impact) {
+            lines.push("", "## Impact Summary");
+            if (impact.affectedLayers.length > 0) {
+              lines.push(`Affected layers: ${impact.affectedLayers.join(", ")}`);
+            }
+            lines.push(`Affected entry points: ${impact.affectedEntryPoints.length}`);
+            lines.push(`Distinct paths: ${impact.distinctPathCount}`);
+          }
+        }
+        return truncate(lines.join("\n"));
+      }
+      case "kirograph_staleness": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const rawDb = db.getRawDb();
+        const threshold = typeof args.threshold === "number" ? args.threshold : 0.3;
+        if (args.refresh === true) {
+          const { StalenessChecker } = await Promise.resolve().then(() => require("../security/staleness.js"));
+          const checker = new StalenessChecker(db);
+          await checker.checkAll();
+        }
+        const rows = rawDb.all(
+          `SELECT package_name, ecosystem, resolved_version, declared_constraint,
+                  latest_version, latest_published, staleness_score
+           FROM sec_dependencies
+           WHERE staleness_score >= ?
+           ORDER BY staleness_score DESC`,
+          [threshold]
+        );
+        if (rows.length === 0) {
+          return `No dependencies found with staleness_score >= ${threshold}.` + (args.refresh ? "" : " Use refresh=true to fetch latest version data from registries.");
+        }
+        const lines = [`Stale Dependencies (threshold: ${threshold}):
+`];
+        for (const row of rows) {
+          const resolved = row.resolved_version ?? row.declared_constraint ?? "?";
+          const latest = row.latest_version ?? "?";
+          const score = row.staleness_score ?? 0;
+          const months = row.latest_published ? Math.round((Date.now() - row.latest_published) / (1e3 * 60 * 60 * 24 * 30)) : null;
+          const bar = "\u2588".repeat(Math.round(score * 10)) + "\u2591".repeat(10 - Math.round(score * 10));
+          const monthsStr = months !== null ? `, ${months}mo since latest` : "";
+          lines.push(`${row.package_name} (${row.ecosystem}): ${resolved} \u2192 ${latest}${monthsStr}`);
+          lines.push(`  ${bar} ${score.toFixed(2)}`);
+        }
+        const totalCount = rawDb.get(`SELECT COUNT(*) as count FROM sec_dependencies`) ?? { count: 0 };
+        lines.push("", `${rows.length} of ${totalCount.count} dependencies are stale (score >= ${threshold})`);
+        return truncate(lines.join("\n"));
+      }
+      case "kirograph_licenses": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const rawDb = db.getRawDb();
+        const deps = rawDb.all(
+          `SELECT package_name, ecosystem, license FROM sec_dependencies ORDER BY ecosystem, package_name`
+        );
+        const { checkLicensePolicy } = await Promise.resolve().then(() => require("../security/license.js"));
+        const policy = config.securityLicensePolicy;
+        const violations = checkLicensePolicy(deps, policy);
+        if (args.policy === true) {
+          if (violations.length === 0) {
+            return "No license policy violations found.";
+          }
+          const lines2 = ["# License Policy Violations\n"];
+          for (const v of violations) {
+            lines2.push(`${v.severity.toUpperCase()}  ${v.packageName} [${v.ecosystem}]  ${v.license}`);
+          }
+          const denyCount2 = violations.filter((v) => v.severity === "deny").length;
+          const warnCount2 = violations.filter((v) => v.severity === "warn").length;
+          lines2.push("");
+          if (denyCount2 > 0) lines2.push(`${denyCount2} denied license${denyCount2 !== 1 ? "s" : ""}`);
+          if (warnCount2 > 0) lines2.push(`${warnCount2} license warning${warnCount2 !== 1 ? "s" : ""}`);
+          return truncate(lines2.join("\n"));
+        }
+        if (deps.length === 0) {
+          return "No dependencies found. Run kirograph index first.";
+        }
+        const violationMap = /* @__PURE__ */ new Map();
+        for (const v of violations) {
+          violationMap.set(`${v.ecosystem}:${v.packageName}`, v.severity);
+        }
+        const lines = [`# License Report (${deps.length} dependencies)
+`];
+        if (violations.length > 0) {
+          lines.push("## Policy Violations\n");
+          for (const v of violations) {
+            lines.push(`${v.severity.toUpperCase()}  ${v.packageName} [${v.ecosystem}]  ${v.license}`);
+          }
+          lines.push("");
+        }
+        lines.push("## All Dependencies\n");
+        lines.push("package | ecosystem | license | status");
+        lines.push("------- | --------- | ------- | ------");
+        for (const dep of deps) {
+          const key = `${dep.ecosystem}:${dep.package_name}`;
+          const violation = violationMap.get(key);
+          const license = dep.license ?? "(unknown)";
+          const status = violation ?? (dep.license ? "ok" : "unknown");
+          lines.push(`${dep.package_name} | ${dep.ecosystem} | ${license} | ${status}`);
+        }
+        const denyCount = violations.filter((v) => v.severity === "deny").length;
+        const warnCount = violations.filter((v) => v.severity === "warn").length;
+        const unknownCount = deps.filter((d) => !d.license).length;
+        lines.push("");
+        if (denyCount > 0) lines.push(`${denyCount} denied license${denyCount !== 1 ? "s" : ""}`);
+        if (warnCount > 0) lines.push(`${warnCount} license warning${warnCount !== 1 ? "s" : ""}`);
+        if (unknownCount > 0) lines.push(`${unknownCount} unknown license${unknownCount !== 1 ? "s" : ""}`);
+        if (denyCount === 0 && warnCount === 0) lines.push("No policy violations");
+        return truncate(lines.join("\n"));
+      }
+      case "kirograph_attack_surface": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const { AttackSurfaceAnalyzer } = await Promise.resolve().then(() => require("../security/attack-surface.js"));
+        const analyzer = new AttackSurfaceAnalyzer(db);
+        const result = await analyzer.analyze();
+        if (result.totalRoutes === 0) {
+          return "No route nodes found in the graph. Ensure the project has been indexed with architecture analysis enabled.";
+        }
+        const limit = clampLimit(args.limit, 20);
+        const routes = args.publicOnly === true ? result.criticalPaths.filter((r) => r.exposureLevel === "public") : result.criticalPaths;
+        const lines = [
+          "# Attack Surface",
+          "",
+          `Total routes: ${result.totalRoutes}  Public: ${result.publicRoutes}  Authenticated: ${result.authenticatedRoutes}  Routes with vulns: ${result.routesWithVulns}`,
+          ""
+        ];
+        const displayed = routes.slice(0, limit);
+        if (displayed.length === 0) {
+          lines.push(args.publicOnly === true ? "No public routes with vulnerable dependencies found." : "No routes with vulnerable dependencies found.");
+        } else {
+          for (const entry of displayed) {
+            const authTag = entry.isAuthenticated ? "[auth]" : "[public]";
+            const riskTag = entry.riskScore > 0 ? ` risk=${entry.riskScore.toFixed(1)}` : "";
+            lines.push(`${authTag} ${entry.route} (${entry.exposureLevel})${riskTag}  ${entry.filePath}`);
+            for (const dep of entry.vulnerableDeps.slice(0, 3)) {
+              lines.push(`  \u2514 ${dep.cveId} via ${dep.packageName} (${dep.hopCount} hop${dep.hopCount !== 1 ? "s" : ""}${dep.verdict ? `, ${dep.verdict}` : ""})`);
+            }
+            if (entry.vulnerableDeps.length > 3) {
+              lines.push(`  \u2514 \u2026and ${entry.vulnerableDeps.length - 3} more vulns`);
+            }
+          }
+          if (routes.length > limit) {
+            lines.push("", `\u2026and ${routes.length - limit} more routes (increase limit to see all)`);
+          }
+        }
+        return truncate(lines.join("\n"));
+      }
+      case "kirograph_secrets": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const { SecretsScanner } = await Promise.resolve().then(() => require("../security/secrets.js"));
+        const scanner = new SecretsScanner(db, projectRoot);
+        const result = await scanner.scan({ includeTests: args.includeTests === true });
+        if (result.totalFindings === 0) {
+          return `No secrets found. Scanned ${result.filesScanned} file${result.filesScanned !== 1 ? "s" : ""}.`;
+        }
+        let findings = result.findings;
+        if (args.severity) {
+          findings = findings.filter((f) => f.severity === args.severity);
+        }
+        if (findings.length === 0) {
+          return `No secrets found matching severity "${args.severity}". Total findings (all severities): ${result.totalFindings}.`;
+        }
+        const lines = [
+          `# Secrets Scan (${result.filesScanned} files scanned)`,
+          "",
+          `Found: ${result.totalFindings}  Critical: ${result.criticalCount}  High: ${result.highCount}`,
+          ""
+        ];
+        for (const f of findings) {
+          lines.push(`${f.severity.toUpperCase()}  ${f.type}`);
+          lines.push(`  ${f.filePath}:${f.line}:${f.column}  snippet: ${f.snippet}`);
+          if (f.nodeName) {
+            lines.push(`  in function: ${f.nodeName}`);
+          }
+          if (f.entryPointCount > 0) {
+            lines.push(`  reachable from ${f.entryPointCount} entry point${f.entryPointCount !== 1 ? "s" : ""}`);
+          }
+        }
+        return truncate(lines.join("\n"));
+      }
+      case "kirograph_security_flows": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const { DataFlowAnalyzer } = await Promise.resolve().then(() => require("../security/data-flows.js"));
+        const analyzer = new DataFlowAnalyzer(db);
+        let findings = await analyzer.analyze();
+        const typeFilter = args.type ?? "all";
+        const TYPE_MAP = {
+          sql: "sql-injection",
+          eval: "dangerous-eval",
+          deserialize: "unsafe-deserialize",
+          path: "path-traversal",
+          crypto: "hardcoded-crypto"
+        };
+        if (typeFilter !== "all") {
+          const mapped = TYPE_MAP[typeFilter];
+          if (!mapped) return `Invalid type filter "${typeFilter}". Use: sql, eval, deserialize, path, crypto, all`;
+          findings = findings.filter((f) => f.type === mapped);
+        }
+        if (findings.length === 0) {
+          return typeFilter === "all" ? "No dangerous data flows detected." : `No "${typeFilter}" findings detected.`;
+        }
+        const lines = [
+          `# Security Flows (${findings.length} finding${findings.length !== 1 ? "s" : ""})`,
+          ""
+        ];
+        for (const f of findings) {
+          lines.push(`${f.severity.toUpperCase()}  [${f.owaspCategory}]  ${f.type}`);
+          lines.push(`  ${f.filePath}:${f.line}  symbol: ${f.symbol}`);
+          lines.push(`  ${f.description}`);
+          lines.push(`  Fix: ${f.recommendation}`);
+          lines.push("");
+        }
+        return truncate(lines.join("\n"));
+      }
+      case "kirograph_supply_chain": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const { SupplyChainChecker } = await Promise.resolve().then(() => require("../security/supply-chain.js"));
+        const checker = new SupplyChainChecker(db);
+        const { results, errors } = await checker.checkAll();
+        const RISK_ORDER = { critical: 0, high: 1, medium: 2, low: 3, unknown: 4 };
+        const thresholdArg = args.threshold;
+        const thresholdOrder = thresholdArg ? RISK_ORDER[thresholdArg] ?? 4 : 2;
+        const filtered = results.filter((r) => (RISK_ORDER[r.riskLevel] ?? 4) <= thresholdOrder).sort((a, b) => (RISK_ORDER[a.riskLevel] ?? 4) - (RISK_ORDER[b.riskLevel] ?? 4));
+        if (filtered.length === 0) {
+          return `No supply chain risks found at threshold "${thresholdArg ?? "medium"}" or above. Checked ${results.length} dependencies.`;
+        }
+        const lines = [
+          `# Supply Chain Health (${filtered.length} risks, threshold: ${thresholdArg ?? "medium"})`,
+          ""
+        ];
+        for (const r of filtered) {
+          const scoreStr = r.scorecardScore !== null ? ` scorecard=${r.scorecardScore.toFixed(1)}/10` : "";
+          const maintainerStr = r.maintainerCount !== null ? ` maintainers=${r.maintainerCount}` : "";
+          lines.push(`${r.riskLevel.toUpperCase()}  ${r.packageName} (${r.ecosystem})${scoreStr}${maintainerStr}`);
+          for (const reason of r.riskReasons) {
+            lines.push(`  \u2022 ${reason}`);
+          }
+        }
+        if (errors.length > 0) {
+          lines.push("", `\u26A0 ${errors.length} package${errors.length !== 1 ? "s" : ""} could not be checked (network errors)`);
+        }
+        return truncate(lines.join("\n"));
+      }
+      case "kirograph_dep_confusion": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const { DepConfusionChecker } = await Promise.resolve().then(() => require("../security/dep-confusion.js"));
+        const checker = new DepConfusionChecker(db);
+        const findings = await checker.check();
+        if (findings.length === 0) {
+          return "No dependency confusion vulnerabilities detected.";
+        }
+        const RISK_ORDER = { critical: 0, high: 1, medium: 2 };
+        const sorted = [...findings].sort((a, b) => (RISK_ORDER[a.riskLevel] ?? 3) - (RISK_ORDER[b.riskLevel] ?? 3));
+        const lines = [
+          `# Dependency Confusion (${findings.length} finding${findings.length !== 1 ? "s" : ""})`,
+          ""
+        ];
+        for (const f of sorted) {
+          lines.push(`${f.riskLevel.toUpperCase()}  ${f.packageName} (${f.ecosystem})`);
+          lines.push(`  ${f.explanation}`);
+          if (f.publicExists && f.publicVersion) {
+            lines.push(`  Public version: ${f.publicVersion}${f.publicPublishedAt ? `  published: ${f.publicPublishedAt}` : ""}`);
+          }
+        }
+        return truncate(lines.join("\n"));
+      }
+      case "kirograph_remediation": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableSecurity) return "Security analysis is not enabled. Set enableSecurity: true in .kirograph/config.json and run kirograph index.";
+        const db = cg.getDatabase();
+        db.applySecuritySchema();
+        const { RemediationTracker } = await Promise.resolve().then(() => require("../security/remediation.js"));
+        const tracker = new RemediationTracker(db);
+        let statuses = tracker.getStatus();
+        if (args.overdueOnly === true) {
+          statuses = statuses.filter((s) => s.isOverdue);
+        }
+        if (statuses.length === 0) {
+          return args.overdueOnly === true ? "No overdue vulnerabilities found." : "No open vulnerabilities with SLA tracking data found.";
+        }
+        const SLA_ORDER = { overdue: 0, warning: 1, no_fix: 2, ok: 3 };
+        statuses.sort((a, b) => {
+          const slaA = SLA_ORDER[a.slaStatus] ?? 3;
+          const slaB = SLA_ORDER[b.slaStatus] ?? 3;
+          if (slaA !== slaB) return slaA - slaB;
+          return (b.severity ?? 0) - (a.severity ?? 0);
+        });
+        const overdueCount = statuses.filter((s) => s.isOverdue).length;
+        const warningCount = statuses.filter((s) => s.slaStatus === "warning").length;
+        const lines = [
+          `# Remediation SLA (${statuses.length} open${overdueCount > 0 ? `, ${overdueCount} overdue` : ""}${warningCount > 0 ? `, ${warningCount} warning` : ""})`,
+          ""
+        ];
+        for (const s of statuses) {
+          const severityLabel = s.severity == null ? "UNKNOWN" : s.severity >= 9 ? "CRITICAL" : s.severity >= 7 ? "HIGH" : s.severity >= 4 ? "MEDIUM" : "LOW";
+          const slaTag = s.slaStatus === "overdue" ? "[OVERDUE]" : s.slaStatus === "warning" ? "[WARNING]" : s.slaStatus === "no_fix" ? "[NO_FIX]" : "[OK]";
+          lines.push(`${slaTag}  ${severityLabel}  ${s.cveId}  ${s.packageName}`);
+          if (s.daysOpen !== null) lines.push(`  Open for ${s.daysOpen} day${s.daysOpen !== 1 ? "s" : ""}`);
+          if (s.daysWithFixAvailable !== null) lines.push(`  Fix available for ${s.daysWithFixAvailable} day${s.daysWithFixAvailable !== 1 ? "s" : ""}`);
+          if (s.slaDeadline !== null) {
+            const deadlineDate = new Date(s.slaDeadline).toISOString().slice(0, 10);
+            lines.push(`  SLA deadline: ${deadlineDate}`);
+          }
+        }
+        return truncate(lines.join("\n"));
+      }
       default:
         return `Unknown tool: ${toolName}`;
     }