@mcp-shark/mcp-shark 1.5.13 → 1.6.0

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

package/core/cli/ScanService.js

@@ -0,0 +1,200 @@
+import { StaticRulesService } from '#core/services/security/StaticRulesService.js';
+/**
+ * Scan Service
+ * Orchestrates: config detection → rule analysis → toxic flows → shark score
+ * Pure business logic, no HTTP knowledge, no CLI formatting.
+ *
+ * Server-level checks are registry-driven — add a new check by
+ * appending to SERVER_CONFIG_CHECKS, no other edits needed.
+ */
+import { analyzeConfigPermissions } from '#core/services/security/rules/scans/configPermissions.js';
+import { analyzeAllServerToolNames } from '#core/services/security/rules/scans/duplicateToolNames.js';
+import { analyzeServerTransport } from '#core/services/security/rules/scans/insecureTransport.js';
+import { analyzeServerContainment } from '#core/services/security/rules/scans/missingContainment.js';
+import { analyzeServerShellRisk } from '#core/services/security/rules/scans/shellEnvInjection.js';
+import { analyzeServerDefaults } from '#core/services/security/rules/scans/unsafeDefaults.js';
+import { getAllServers, scanIdeConfigs } from './ConfigScanner.js';
+import { detectHardcodedSecrets } from './SecretDetector.js';
+import { calculateSharkScore, countBySeverity } from './SharkScoreCalculator.js';
+import { analyzeToxicFlows } from './ToxicFlowAnalyzer.js';
+import { applyYamlRules, loadYamlRules } from './YamlRuleEngine.js';
+
+/**
+ * Registry of server-level config checks.
+ * Each entry takes (serverName, config) and returns Finding[].
+ * To add a new check: import it and append here.
+ */
+const SERVER_CONFIG_CHECKS = [
+  analyzeServerContainment,
+  analyzeServerShellRisk,
+  analyzeServerTransport,
+  analyzeServerDefaults,
+];
+
+/**
+ * Run a full security scan on all detected MCP configurations
+ * @param {object} options
+ * @param {string} [options.ide] - Filter to specific IDE
+ * @param {boolean} [options.strict] - Count advisory findings in score
+ * @param {string} [options.rulesPath] - Path to custom YAML rules
+ * @returns {object} Complete scan result
+ */
+export function runScan(options = {}) {
+  const startTime = Date.now();
+
+  const ideResults = scanIdeConfigs({ ide: options.ide });
+  const servers = getAllServers(ideResults);
+
+  const rulesService = new StaticRulesService(null);
+  const ruleMetadata = rulesService.getRuleMetadata();
+
+  const allFindings = analyzeAllServers(servers, rulesService, ideResults);
+
+  const yamlRules = loadYamlRules(options.rulesPath);
+  if (yamlRules.length > 0) {
+    const yamlFindings = applyYamlRules(yamlRules, servers);
+    allFindings.push(...yamlFindings);
+  }
+
+  const toxicFlows = analyzeToxicFlows(servers);
+
+  const scorableFindings = options.strict
+    ? allFindings
+    : allFindings.filter((f) => f.confidence !== 'possible');
+
+  const scoreResult = calculateSharkScore(scorableFindings, toxicFlows);
+  const severityCounts = countBySeverity(allFindings);
+  const elapsedMs = Date.now() - startTime;
+
+  const totalToolCount = servers.reduce(
+    (sum, s) => sum + (Array.isArray(s.tools) ? s.tools.length : 0),
+    0
+  );
+
+  return {
+    ideResults,
+    servers,
+    findings: allFindings,
+    findingsByServer: groupFindingsByServer(allFindings),
+    toxicFlows,
+    scoreResult,
+    severityCounts,
+    ruleCount: ruleMetadata.length,
+    totalToolCount,
+    serverCount: servers.length,
+    elapsedMs,
+    cleanServers: getCleanServers(servers, allFindings),
+  };
+}
+
+/**
+ * Analyze all servers with the static rules engine + config-level checks
+ */
+function analyzeAllServers(servers, rulesService, ideResults) {
+  const findings = [];
+
+  for (const server of servers) {
+    const serverFindings = analyzeServer(server, rulesService);
+    findings.push(...serverFindings);
+  }
+
+  const dupFindings = analyzeAllServerToolNames(servers);
+  findings.push(...dupFindings);
+
+  const permFindings = analyzeIdePermissions(ideResults);
+  findings.push(...permFindings);
+
+  return findings;
+}
+
+/**
+ * Check permissions on all found IDE config files
+ */
+function analyzeIdePermissions(ideResults) {
+  const findings = [];
+  for (const ide of ideResults) {
+    if (!ide.found || !ide.permissions) {
+      continue;
+    }
+    const permFindings = analyzeConfigPermissions(ide.configPath, ide.permissions);
+    findings.push(...permFindings);
+  }
+  return findings;
+}
+
+/**
+ * Analyze a single server's tools with the rules engine
+ */
+function analyzeServer(server, rulesService) {
+  const findings = [];
+
+  const configFindings = runServerConfigChecks(server);
+  findings.push(...configFindings);
+
+  if (Array.isArray(server.tools)) {
+    for (const tool of server.tools) {
+      const toolObj = typeof tool === 'string' ? { name: tool } : tool;
+      const toolFindings = rulesService.analyzeTool(toolObj, server.name);
+      for (const f of toolFindings) {
+        findings.push({
+          ...f,
+          ide: server.ide,
+          config_path: server.configPath,
+        });
+      }
+    }
+  }
+
+  const serverConfig = server.config || {};
+  if (serverConfig.env) {
+    const secretFindings = detectHardcodedSecrets(serverConfig.env, server);
+    findings.push(...secretFindings);
+  }
+
+  return findings;
+}
+
+/**
+ * Run all registered server-level config checks against a single server.
+ * Iterates SERVER_CONFIG_CHECKS registry — no manual calls needed.
+ */
+function runServerConfigChecks(server) {
+  const config = server.config || {};
+  const findings = [];
+
+  for (const check of SERVER_CONFIG_CHECKS) {
+    const checkFindings = check(server.name, config);
+    for (const f of checkFindings) {
+      findings.push({
+        ...f,
+        ide: server.ide,
+        config_path: server.configPath,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Group findings by server name
+ */
+function groupFindingsByServer(findings) {
+  const grouped = {};
+  for (const finding of findings) {
+    const key = finding.server_name || 'unknown';
+    if (!grouped[key]) {
+      grouped[key] = [];
+    }
+    grouped[key].push(finding);
+  }
+  return grouped;
+}
+
+/**
+ * Get list of servers with no findings
+ */
+function getCleanServers(servers, findings) {
+  const serversWithFindings = new Set(findings.map((f) => f.server_name));
+  return servers.filter((s) => !serversWithFindings.has(s.name)).map((s) => s.name);
+}

package/core/cli/SecretDetector.js

@@ -0,0 +1,92 @@
+/**
+ * Hardcoded Secret Detection
+ * Detects API keys, tokens, and credentials hardcoded in MCP server env vars.
+ *
+ * Patterns are loaded from data/secret-patterns.json (built-in)
+ * and merged with user overrides from .mcp-shark/secrets.yaml.
+ */
+import { loadBuiltinJson, loadUserYamlList } from './DataLoader.js';
+
+const BUILTIN_PATTERNS = loadBuiltinJson('secret-patterns.json');
+const USER_PATTERNS = loadUserYamlList('secrets.yaml');
+
+const SECRET_PATTERNS = compilePatterns([...BUILTIN_PATTERNS, ...USER_PATTERNS]);
+
+/**
+ * Compile raw pattern definitions into regex objects
+ * @param {Array<{pattern: string, name: string, severity: string}>} rawPatterns
+ * @returns {Array<{pattern: RegExp, name: string, severity: string}>}
+ */
+function compilePatterns(rawPatterns) {
+  const compiled = [];
+  for (const entry of rawPatterns) {
+    try {
+      compiled.push({
+        pattern: new RegExp(entry.pattern),
+        name: entry.name,
+        severity: entry.severity,
+      });
+    } catch (_err) {
+      // skip malformed patterns from user overrides
+    }
+  }
+  return compiled;
+}
+
+/**
+ * Detect hardcoded secrets in server environment variables
+ * @param {object} envVars - Environment variables from server config
+ * @param {object} server - Server context (name, ide, configPath)
+ * @returns {Array} Findings
+ */
+export function detectHardcodedSecrets(envVars, server) {
+  const findings = [];
+  if (!envVars || typeof envVars !== 'object') {
+    return findings;
+  }
+
+  for (const [key, value] of Object.entries(envVars)) {
+    if (typeof value !== 'string') {
+      continue;
+    }
+    if (value.startsWith('${')) {
+      continue;
+    }
+    if (/^\$[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+      continue;
+    }
+
+    for (const { pattern, name, severity } of SECRET_PATTERNS) {
+      if (pattern.test(value)) {
+        const masked = maskSecret(value);
+        findings.push({
+          rule_id: 'hardcoded-secret',
+          category: 'MCP01',
+          severity,
+          confidence: 'definite',
+          title: `${name} hardcoded in config`,
+          description: `${key}=${masked} — use environment variable reference instead`,
+          server_name: server.name,
+          ide: server.ide,
+          config_path: server.configPath,
+          fixable: true,
+          fix_type: 'env_var_replacement',
+          fix_data: { key, original: value },
+        });
+        break;
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Mask a secret value for display
+ */
+function maskSecret(value) {
+  if (value.length <= 8) {
+    return '****';
+  }
+  return `${value.slice(0, 4)}****`;
+}