@mcp-shark/mcp-shark 1.5.13 → 1.7.2

package/core/cli/LockDiffEngine.js

@@ -0,0 +1,152 @@
+/**
+ * Lock Diff Engine
+ * Computes and renders differences between lockfile and current MCP state.
+ * Used by both `lock --verify` and `diff` commands.
+ */
+import { createHash } from 'node:crypto';
+import kleur from 'kleur';
+import { S } from './symbols.js';
+
+/**
+ * Hash a tool definition using SHA-256
+ */
+export function hashToolDefinition(tool) {
+  const canonical = JSON.stringify({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema || tool.parameters,
+  });
+  return createHash('sha256').update(canonical).digest('hex');
+}
+
+/**
+ * Count parameters in a tool definition
+ */
+export function countParameters(tool) {
+  const schema = tool.inputSchema || tool.parameters || {};
+  const properties = schema.properties || {};
+  return Object.keys(properties).length;
+}
+
+/**
+ * Normalize server.tools (array or name→definition map) to an array of tool objects
+ */
+export function normalizeToolsList(tools) {
+  if (!tools) {
+    return [];
+  }
+  if (Array.isArray(tools)) {
+    return tools;
+  }
+  if (typeof tools === 'object') {
+    return Object.entries(tools).map(([name, def]) => {
+      if (def && typeof def === 'object' && !Array.isArray(def)) {
+        return { ...def, name: def.name || name };
+      }
+      return typeof def === 'string' ? { name, description: def } : { name };
+    });
+  }
+  return [];
+}
+
+/**
+ * Compute diff between lockfile and current state
+ * @param {object} lockData - Parsed lockfile data
+ * @param {Array} currentServers - Current servers from ConfigScanner
+ * @returns {Array} List of change objects
+ */
+export function computeDiff(lockData, currentServers) {
+  const changes = [];
+
+  for (const server of currentServers) {
+    const locked = lockData.servers[server.name];
+    if (!locked) {
+      changes.push({ type: 'added_server', server: server.name, ide: server.ide });
+      continue;
+    }
+
+    const tools = normalizeToolsList(server.tools);
+    for (const tool of tools) {
+      const toolObj = typeof tool === 'string' ? { name: tool } : tool;
+      const toolName = toolObj.name || 'unknown';
+      const lockedTool = locked.tools[toolName];
+
+      if (!lockedTool) {
+        changes.push({ type: 'added_tool', server: server.name, tool: toolName });
+        continue;
+      }
+
+      const currentHash = `sha256:${hashToolDefinition(toolObj)}`;
+      if (currentHash !== lockedTool.hash) {
+        changes.push({ type: 'changed_tool', server: server.name, tool: toolName });
+      }
+    }
+
+    checkRemovedTools(locked, tools, server.name, changes);
+  }
+
+  checkRemovedServers(lockData, currentServers, changes);
+
+  return changes;
+}
+
+/**
+ * Check for tools that were in lockfile but removed from current state
+ */
+function checkRemovedTools(locked, tools, serverName, changes) {
+  for (const lockedToolName of Object.keys(locked.tools)) {
+    const stillExists = tools.some((t) => {
+      const name = typeof t === 'string' ? t : t.name;
+      return name === lockedToolName;
+    });
+    if (!stillExists) {
+      changes.push({ type: 'removed_tool', server: serverName, tool: lockedToolName });
+    }
+  }
+}
+
+/**
+ * Check for servers that were in lockfile but removed
+ */
+function checkRemovedServers(lockData, currentServers, changes) {
+  for (const lockedServerName of Object.keys(lockData.servers)) {
+    const stillExists = currentServers.some((s) => s.name === lockedServerName);
+    if (!stillExists) {
+      changes.push({ type: 'removed_server', server: lockedServerName });
+    }
+  }
+}
+
+/**
+ * Render diff changes to terminal
+ */
+export function renderDiff(changes) {
+  if (changes.length === 0) {
+    console.log(`  ${kleur.green(S.pass)} No changes detected`);
+    return;
+  }
+
+  console.log('');
+  for (const change of changes) {
+    if (change.type === 'added_server') {
+      console.log(
+        `  ${kleur.green('+')} Server added: ${kleur.bold(change.server)} (${change.ide})`
+      );
+    }
+    if (change.type === 'removed_server') {
+      console.log(`  ${kleur.red('-')} Server removed: ${kleur.bold(change.server)}`);
+    }
+    if (change.type === 'added_tool') {
+      console.log(`  ${kleur.green('+')} Tool added: ${change.server}/${kleur.bold(change.tool)}`);
+    }
+    if (change.type === 'removed_tool') {
+      console.log(`  ${kleur.red('-')} Tool removed: ${change.server}/${kleur.bold(change.tool)}`);
+    }
+    if (change.type === 'changed_tool') {
+      console.log(
+        `  ${kleur.yellow('~')} Tool changed: ${change.server}/${kleur.bold(change.tool)} ${kleur.yellow(S.warn)}`
+      );
+    }
+  }
+  console.log('');
+}

package/core/cli/RuleRegistryConfig.js

@@ -0,0 +1,131 @@
+/**
+ * Resolves rule registry URL and update policy without hardcoding beyond bootstrap defaults.
+ *
+ * Precedence (highest first):
+ *   1. CLI --source (passed in as overrideUrl)
+ *   2. MCP_SHARK_RULE_REGISTRY
+ *   3. .mcp-shark/rule-registry.json (project cwd)
+ *   4. ~/.config/mcp-shark/rule-registry.json (XDG-style)
+ *   5. Built-in rule-sources.json
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadBuiltinJson } from './DataLoader.js';
+
+const BUILTIN = loadBuiltinJson('rule-sources.json');
+
+function projectRegistryPath() {
+  return join(process.cwd(), '.mcp-shark', 'rule-registry.json');
+}
+
+function userRegistryPath() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'mcp-shark', 'rule-registry.json');
+}
+
+/**
+ * @param {object} raw
+ * @returns {object|null}
+ */
+function parseRegistryFile(rawPath) {
+  if (!existsSync(rawPath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(rawPath, 'utf-8'));
+    return typeof parsed === 'object' && parsed !== null ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reject cache_dir path traversal and absolute paths.
+ * @param {string} rel
+ */
+function assertSafeRelativeCacheDir(rel) {
+  if (typeof rel !== 'string' || rel.length === 0) {
+    return;
+  }
+  if (rel.includes('..') || rel.startsWith('/') || /^[A-Za-z]:[\\/]/.test(rel)) {
+    throw new Error('rule-registry.json cache_dir must be a relative path without ..');
+  }
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.overrideUrl] - from CLI --source
+ * @returns {{
+ *   registryUrl: string,
+ *   cacheDir: string,
+ *   autoUpdate: boolean,
+ *   autoUpdateMaxAgeHours: number
+ * }}
+ */
+export function resolveRuleRegistryConfig(opts = {}) {
+  const projectFile = parseRegistryFile(projectRegistryPath());
+  const userFile = parseRegistryFile(userRegistryPath());
+
+  const merged = {
+    ...BUILTIN,
+    ...(userFile || {}),
+    ...(projectFile || {}),
+  };
+
+  if (merged.cache_dir) {
+    assertSafeRelativeCacheDir(merged.cache_dir);
+  }
+
+  const cliUrl = opts.overrideUrl && String(opts.overrideUrl).trim();
+  const envUrl = process.env.MCP_SHARK_RULE_REGISTRY?.trim();
+  const registryUrl = cliUrl || envUrl || merged.registry_url || BUILTIN.registry_url;
+
+  const cacheDirRel = merged.cache_dir || BUILTIN.cache_dir;
+  assertSafeRelativeCacheDir(cacheDirRel);
+  const cacheDir = join(process.cwd(), cacheDirRel);
+
+  const autoUpdate = merged.auto_update === true;
+  const autoUpdateMaxAgeHours = Number(merged.auto_update_max_age_hours);
+  const builtinMax = Number(BUILTIN.default_auto_update_max_age_hours);
+  const maxAge =
+    Number.isFinite(autoUpdateMaxAgeHours) && autoUpdateMaxAgeHours > 0
+      ? autoUpdateMaxAgeHours
+      : Number.isFinite(builtinMax) && builtinMax > 0
+        ? builtinMax
+        : 168;
+
+  return {
+    registryUrl,
+    cacheDir,
+    autoUpdate,
+    autoUpdateMaxAgeHours: maxAge,
+  };
+}
+
+/**
+ * True when cache has no packs or newest pack file is older than maxAgeHours.
+ * @param {string} cacheDir
+ * @param {number} maxAgeHours
+ */
+export function isRuleCacheStale(cacheDir, maxAgeHours) {
+  if (!existsSync(cacheDir)) {
+    return true;
+  }
+
+  const files = readdirSync(cacheDir).filter((f) => f.endsWith('.json') && f !== '.meta.json');
+  if (files.length === 0) {
+    return true;
+  }
+
+  let newest = 0;
+  for (const f of files) {
+    const m = statSync(join(cacheDir, f)).mtimeMs;
+    if (m > newest) {
+      newest = m;
+    }
+  }
+
+  const maxAgeMs = maxAgeHours * 60 * 60 * 1000;
+  return Date.now() - newest > maxAgeMs;
+}

package/core/cli/ScanCommand.js

@@ -0,0 +1,244 @@
+/**
+ * Scan Command
+ * Wires ScanService results to CLI output with flag support
+ */
+import { confirm } from '@clack/prompts';
+import { applyFixes, renderFixResults } from './AutoFixEngine.js';
+import { generateHtmlReport } from './HtmlReportGenerator.js';
+import { isRuleCacheStale, resolveRuleRegistryConfig } from './RuleRegistryConfig.js';
+import { runScan } from './ScanService.js';
+import { calculateSharkScore } from './SharkScoreCalculator.js';
+import { executeUpdateRules } from './UpdateCommand.js';
+import { formatWalkthrough, generateWalkthroughs } from './WalkthroughGenerator.js';
+import {
+  displayScanBanner,
+  formatAsJson,
+  formatAsSarif,
+  formatCleanServers,
+  formatIdeDiscovery,
+  formatNextSteps,
+  formatServerFindings,
+  formatSharkScore,
+  formatSummaryCounts,
+  formatTiming,
+  formatToxicFlows,
+} from './output/index.js';
+
+/**
+ * Execute the scan command
+ * @param {object} options - CLI options from commander
+ * @param {boolean} [options.fix] - Auto-fix fixable issues
+ * @param {boolean} [options.walkthrough] - Show attack chain narratives
+ * @param {boolean} [options.ci] - CI mode (exit code 1 on critical/high)
+ * @param {string} [options.format] - Output format: 'json' | 'sarif' | 'terminal'
+ * @param {boolean} [options.strict] - Count advisory findings in score
+ * @param {string} [options.ide] - Filter to specific IDE
+ * @param {boolean} [options.yes] - Skip confirmation for --fix
+ * @param {string} [options.output] - Output file path (for html format)
+ * @param {string} [options.rules] - Path to custom YAML rules directory
+ * @param {boolean} [options.refreshRules] - Fetch registry packs before scan
+ */
+export async function executeScan(options = {}) {
+  const refreshExit = await maybeRefreshRulesBeforeScan(options);
+  if (refreshExit !== 0) {
+    return refreshExit;
+  }
+
+  const format = (options.format || 'terminal').toLowerCase();
+
+  const scanResult = runScan({
+    ide: options.ide,
+    strict: options.strict,
+    rulesPath: options.rules,
+  });
+
+  if (format === 'json') {
+    console.log(formatAsJson(buildJsonOutput(scanResult)));
+    return exitWithCode(scanResult, options.ci);
+  }
+
+  if (format === 'sarif') {
+    console.log(formatAsSarif(buildJsonOutput(scanResult)));
+    return exitWithCode(scanResult, options.ci);
+  }
+
+  if (format === 'html') {
+    generateHtmlReport(scanResult, options.output);
+    return exitWithCode(scanResult, options.ci);
+  }
+
+  renderTerminalOutput(scanResult, options);
+
+  if (options.fix) {
+    await executeAutoFix(scanResult, {
+      undo: options.undo,
+      skipConfirm: options.yes || options.ci,
+    });
+  }
+
+  return exitWithCode(scanResult, options.ci);
+}
+
+/**
+ * Optional network: only when --refresh-rules or auto_update + stale cache.
+ * --refresh-rules: failure exits non-zero. Background auto-update: fail-open (scan continues).
+ */
+async function maybeRefreshRulesBeforeScan(options) {
+  const config = resolveRuleRegistryConfig({});
+  if (options.refreshRules) {
+    return executeUpdateRules({ quiet: true });
+  }
+  if (config.autoUpdate && isRuleCacheStale(config.cacheDir, config.autoUpdateMaxAgeHours)) {
+    await executeUpdateRules({ quiet: true });
+  }
+  return 0;
+}
+
+/**
+ * Render the full terminal output
+ */
+function renderTerminalOutput(scanResult, options) {
+  displayScanBanner();
+  console.log(formatIdeDiscovery(scanResult.ideResults));
+  console.log('');
+
+  renderFindings(scanResult);
+  renderToxicFlows(scanResult);
+  renderScore(scanResult);
+
+  if (options.walkthrough && scanResult.toxicFlows.length > 0) {
+    renderWalkthroughs(scanResult.toxicFlows);
+  }
+
+  const hasFixable = scanResult.findings.some((f) => f.fixable);
+  const hasFlows = scanResult.toxicFlows.length > 0;
+  console.log(formatNextSteps(hasFixable, hasFlows));
+  console.log('');
+}
+
+/**
+ * Render findings grouped by server
+ */
+function renderFindings(scanResult) {
+  for (const [serverName, findings] of Object.entries(scanResult.findingsByServer)) {
+    const server = scanResult.servers.find((s) => s.name === serverName);
+    const ideName = server ? server.ide : 'unknown';
+    console.log(formatServerFindings(serverName, ideName, findings));
+  }
+
+  if (scanResult.cleanServers.length > 0) {
+    console.log(formatCleanServers(scanResult.cleanServers));
+  }
+}
+
+/**
+ * Render toxic flows section
+ */
+function renderToxicFlows(scanResult) {
+  if (scanResult.toxicFlows.length > 0) {
+    console.log(formatToxicFlows(scanResult.toxicFlows));
+  }
+}
+
+/**
+ * Render score and summary
+ */
+function renderScore(scanResult) {
+  console.log('');
+  console.log(formatSharkScore(scanResult.scoreResult));
+  console.log(formatSummaryCounts(scanResult.severityCounts, scanResult.toxicFlows.length));
+  console.log(
+    formatTiming(
+      scanResult.elapsedMs,
+      scanResult.serverCount,
+      scanResult.ruleCount,
+      scanResult.totalToolCount
+    )
+  );
+}
+
+/**
+ * Render attack walkthroughs
+ */
+function renderWalkthroughs(toxicFlows) {
+  const walkthroughs = generateWalkthroughs(toxicFlows);
+  for (const walkthrough of walkthroughs) {
+    console.log(formatWalkthrough(walkthrough));
+  }
+}
+
+/**
+ * Execute auto-fix (or undo) with optional interactive confirmation
+ */
+async function executeAutoFix(scanResult, fixOptions = {}) {
+  const fixable = scanResult.findings.filter((f) => f.fixable);
+
+  if (fixable.length === 0 && !fixOptions.undo) {
+    return;
+  }
+
+  if (!fixOptions.skipConfirm && !fixOptions.undo) {
+    const shouldProceed = await confirm({
+      message: `Apply ${fixable.length} auto-fixes? (backups will be created)`,
+    });
+    if (!shouldProceed || typeof shouldProceed === 'symbol') {
+      console.log('  Fix cancelled.');
+      return;
+    }
+  }
+
+  const scoreBefore = scanResult.scoreResult.score;
+  const fixResult = applyFixes(scanResult.findings, { undo: fixOptions.undo });
+
+  const remainingFindings = scanResult.findings.filter(
+    (f) => !fixResult.fixed.some((fx) => fx.finding === f)
+  );
+  const scoreAfterResult = calculateSharkScore(remainingFindings, scanResult.toxicFlows);
+  const scoreAfter = scoreAfterResult.score;
+
+  renderFixResults(fixResult, scoreBefore, scoreAfter);
+}
+
+/**
+ * Build structured JSON output
+ */
+function buildJsonOutput(scanResult) {
+  return {
+    version: '1.0.0',
+    timestamp: new Date().toISOString(),
+    score: scanResult.scoreResult,
+    findings: scanResult.findings,
+    toxicFlows: scanResult.toxicFlows,
+    servers: scanResult.servers.map((s) => ({
+      name: s.name,
+      ide: s.ide,
+      configPath: s.configPath,
+    })),
+    summary: {
+      serverCount: scanResult.serverCount,
+      ruleCount: scanResult.ruleCount,
+      toolCount: scanResult.totalToolCount,
+      elapsedMs: scanResult.elapsedMs,
+      severityCounts: scanResult.severityCounts,
+    },
+  };
+}
+
+/**
+ * Exit with appropriate code for CI mode
+ */
+function exitWithCode(scanResult, ciMode) {
+  if (!ciMode) {
+    return 0;
+  }
+
+  const hasCriticalOrHigh = scanResult.findings.some((f) => {
+    const severity = (f.severity || f.risk_level || '').toLowerCase();
+    return severity === 'critical' || severity === 'high';
+  });
+
+  if (hasCriticalOrHigh) {
+    return 1;
+  }
+  return 0;
+}