@mcp-shark/mcp-shark 1.5.13 → 1.7.2

package/core/cli/DoctorCommand.js

@@ -0,0 +1,218 @@
+/**
+ * Doctor Command
+ * Quick environment health check covering IDE configs,
+ * environment, security posture, and MCP SDK status
+ */
+import { existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import kleur from 'kleur';
+import { scanIdeConfigs } from './ConfigScanner.js';
+import { S } from './symbols.js';
+
+const LOCKFILE_NAME = '.mcp-shark.lock';
+
+/**
+ * Execute the doctor command
+ */
+export function executeDoctor() {
+  console.log('');
+  console.log(kleur.bold('  mcp-shark doctor'));
+  console.log('');
+
+  const checks = {
+    passed: 0,
+    warnings: 0,
+    failures: 0,
+  };
+
+  runIdeChecks(checks);
+  runEnvironmentChecks(checks);
+  runSecurityChecks(checks);
+
+  console.log('');
+  const summary = [
+    kleur.green(`${checks.passed} passed`),
+    kleur.yellow(`${checks.warnings} warnings`),
+    kleur.red(`${checks.failures} failures`),
+  ].join(kleur.dim(` ${S.dot} `));
+
+  console.log(`  ${summary}`);
+  console.log('');
+
+  return checks.failures > 0 ? 1 : 0;
+}
+
+/**
+ * Check IDE installations and configurations
+ */
+function runIdeChecks(checks) {
+  console.log(kleur.bold('  IDE Installations'));
+
+  const ideResults = scanIdeConfigs();
+
+  for (const ide of ideResults) {
+    if (ide.found) {
+      const details = `${ide.displayPath}, ${ide.serverCount} servers`;
+      printPass(ide.name, details);
+      checks.passed += 1;
+    } else {
+      printInfo(ide.name, 'not found');
+    }
+  }
+
+  console.log('');
+}
+
+/**
+ * Check Node.js environment
+ */
+function runEnvironmentChecks(checks) {
+  console.log(kleur.bold('  Environment'));
+
+  const nodeVersion = process.version;
+  const nodeMajor = Number.parseInt(nodeVersion.slice(1).split('.')[0], 10);
+
+  if (nodeMajor >= 20) {
+    printPass(`Node.js ${nodeVersion}`, 'supported');
+    checks.passed += 1;
+  } else {
+    printFail(`Node.js ${nodeVersion}`, 'requires >= 20.0.0');
+    checks.failures += 1;
+  }
+
+  printPass(`Platform: ${process.platform} ${process.arch}`, '');
+  checks.passed += 1;
+
+  console.log('');
+}
+
+/**
+ * Check security-related configurations
+ */
+function runSecurityChecks(checks) {
+  console.log(kleur.bold('  Security'));
+
+  const ideResults = scanIdeConfigs();
+  const foundIdes = ideResults.filter((ide) => ide.found);
+
+  for (const ide of foundIdes) {
+    checkFilePermissions(ide, checks);
+  }
+
+  checkLockfile(checks);
+  checkDuplicateToolNames(foundIdes, checks);
+
+  console.log('');
+}
+
+/**
+ * Check if config files have overly permissive permissions
+ */
+function checkFilePermissions(ide, checks) {
+  if (process.platform === 'win32') {
+    return;
+  }
+  if (!ide.permissions) {
+    return;
+  }
+
+  const perms = Number.parseInt(ide.permissions, 8);
+  const worldReadable = (perms & 0o004) !== 0;
+  const groupReadable = (perms & 0o040) !== 0;
+
+  if (worldReadable || groupReadable) {
+    const reason = worldReadable ? 'world-readable' : 'group-readable';
+    printWarn(`${ide.displayPath} permissions: ${ide.permissions}`, reason);
+    checks.warnings += 1;
+  } else {
+    printPass(`${ide.displayPath} permissions: ${ide.permissions}`, 'restricted');
+    checks.passed += 1;
+  }
+}
+
+/**
+ * Check for lockfile presence
+ */
+function checkLockfile(checks) {
+  const lockfilePath = join(process.cwd(), LOCKFILE_NAME);
+  const homeLockfile = join(homedir(), LOCKFILE_NAME);
+
+  if (existsSync(lockfilePath) || existsSync(homeLockfile)) {
+    const path = existsSync(lockfilePath) ? lockfilePath : homeLockfile;
+    try {
+      const stats = statSync(path);
+      const ageMs = Date.now() - stats.mtimeMs;
+      const ageDays = Math.floor(ageMs / (1000 * 60 * 60 * 24));
+
+      if (ageDays > 30) {
+        printWarn(`${LOCKFILE_NAME} is ${ageDays} days old`, 'consider refreshing');
+        checks.warnings += 1;
+      } else {
+        printPass(`${LOCKFILE_NAME} found`, `${ageDays} days old`);
+        checks.passed += 1;
+      }
+    } catch (_err) {
+      printPass(`${LOCKFILE_NAME} found`, '');
+      checks.passed += 1;
+    }
+  } else {
+    printWarn(`No ${LOCKFILE_NAME} found`, 'run: npx mcp-shark lock');
+    checks.warnings += 1;
+  }
+}
+
+/**
+ * Check for duplicate tool names across servers
+ */
+function checkDuplicateToolNames(foundIdes, checks) {
+  const toolServers = new Map();
+
+  for (const ide of foundIdes) {
+    for (const [serverName, serverConfig] of Object.entries(ide.servers)) {
+      const tools = serverConfig.tools || [];
+      const toolNames = Array.isArray(tools)
+        ? tools.map((t) => (typeof t === 'string' ? t : t.name))
+        : Object.keys(tools);
+
+      for (const toolName of toolNames) {
+        if (!toolServers.has(toolName)) {
+          toolServers.set(toolName, []);
+        }
+        toolServers.get(toolName).push(serverName);
+      }
+    }
+  }
+
+  const duplicates = [...toolServers.entries()].filter(([_name, servers]) => servers.length > 1);
+
+  if (duplicates.length > 0) {
+    for (const [name, servers] of duplicates) {
+      printWarn(`Duplicate tool "${name}"`, `in ${servers.join(', ')}`);
+      checks.warnings += 1;
+    }
+  } else {
+    printPass('No duplicate tool names across servers', '');
+    checks.passed += 1;
+  }
+}
+
+function printPass(label, detail) {
+  const detailText = detail ? kleur.dim(` ${detail}`) : '';
+  console.log(`    ${kleur.green(S.pass)} ${label}${detailText}`);
+}
+
+function printWarn(label, detail) {
+  const detailText = detail ? kleur.dim(` (${detail})`) : '';
+  console.log(`    ${kleur.yellow(S.warn)} ${label}${detailText}`);
+}
+
+function printFail(label, detail) {
+  const detailText = detail ? kleur.dim(` (${detail})`) : '';
+  console.log(`    ${kleur.red(S.fail)} ${label}${detailText}`);
+}
+
+function printInfo(label, detail) {
+  const detailText = detail ? kleur.dim(` ${detail}`) : '';
+  console.log(`    ${kleur.gray(S.info)} ${label}${detailText}`);
+}

package/core/cli/FixHandlers.js

@@ -0,0 +1,222 @@
+/**
+ * Fix handler implementations
+ * Each handler applies a specific type of auto-fix with backup support
+ */
+import { chmodSync, copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const BACKUP_SUFFIX = '.shark-backup';
+
+/**
+ * Apply a single fix based on fix type
+ */
+export function applyFix(finding, envVarsCollected) {
+  if (finding.fix_type === 'env_var_replacement') {
+    return fixEnvVarReplacement(finding, envVarsCollected);
+  }
+  if (finding.fix_type === 'chmod') {
+    return fixPermissions(finding);
+  }
+  if (finding.fix_type === 'strip_ansi') {
+    return fixStripAnsi(finding);
+  }
+  return { success: false, finding, reason: 'Unknown fix type' };
+}
+
+/**
+ * Replace hardcoded secret with environment variable reference
+ */
+function fixEnvVarReplacement(finding, envVarsCollected) {
+  const configPath = finding.config_path;
+  if (!configPath || !existsSync(configPath)) {
+    return { success: false, finding, error: 'Config file not found' };
+  }
+
+  try {
+    const envVarName = deriveEnvVarName(finding.fix_data.key);
+    backupFile(configPath);
+
+    const content = readFileSync(configPath, 'utf-8');
+    const original = finding.fix_data.original;
+    const replacement = `\${${envVarName}}`;
+    const updated = content.replace(original, replacement);
+
+    if (updated === content) {
+      return { success: false, finding, reason: 'Value not found in config' };
+    }
+
+    writeFileSync(configPath, updated, 'utf-8');
+    envVarsCollected.push({ name: envVarName, original: maskValue(original) });
+
+    return {
+      success: true,
+      finding,
+      message: `Replaced ${maskValue(original)} → \${${envVarName}}`,
+      backupPath: `${configPath}${BACKUP_SUFFIX}`,
+    };
+  } catch (err) {
+    return { success: false, finding, error: err.message };
+  }
+}
+
+/**
+ * Fix file permissions (chmod 600)
+ */
+function fixPermissions(finding) {
+  const configPath = finding.config_path;
+  if (!configPath || !existsSync(configPath)) {
+    return { success: false, finding, error: 'Config file not found' };
+  }
+
+  if (process.platform === 'win32') {
+    return { success: false, finding, reason: 'chmod not supported on Windows' };
+  }
+
+  try {
+    backupFile(configPath);
+    const oldPerms = finding.fix_data?.oldPerms || '644';
+    chmodSync(configPath, 0o600);
+    return {
+      success: true,
+      finding,
+      message: `Set permissions: ${configPath} ${oldPerms} → 600`,
+      backupPath: `${configPath}${BACKUP_SUFFIX}`,
+    };
+  } catch (err) {
+    return { success: false, finding, error: err.message };
+  }
+}
+
+/**
+ * Strip ANSI escape sequences from tool description
+ */
+function fixStripAnsi(finding) {
+  const configPath = finding.config_path;
+  if (!configPath || !existsSync(configPath)) {
+    return { success: false, finding, error: 'Config file not found' };
+  }
+
+  try {
+    backupFile(configPath);
+    const content = readFileSync(configPath, 'utf-8');
+    const escChar = String.fromCharCode(0x1b);
+    const ansiPattern = new RegExp(`${escChar}\\[[0-9;]*m`, 'g');
+    const stripped = content.replace(ansiPattern, '');
+
+    if (stripped === content) {
+      return { success: false, finding, reason: 'No ANSI sequences found' };
+    }
+
+    writeFileSync(configPath, stripped, 'utf-8');
+    return {
+      success: true,
+      finding,
+      message: 'Stripped ANSI escape sequences from config',
+      backupPath: `${configPath}${BACKUP_SUFFIX}`,
+    };
+  } catch (err) {
+    return { success: false, finding, error: err.message };
+  }
+}
+
+/**
+ * Create .env.example with required environment variable names
+ */
+export function createEnvExample(envVars, result) {
+  const envExamplePath = join(process.cwd(), '.env.example');
+  const existingContent = existsSync(envExamplePath) ? readFileSync(envExamplePath, 'utf-8') : '';
+
+  const newVars = envVars.filter((v) => !existingContent.includes(v.name));
+
+  if (newVars.length === 0) {
+    return;
+  }
+
+  const lines = newVars.map((v) => `${v.name}=`);
+  const content = existingContent
+    ? `${existingContent.trimEnd()}\n${lines.join('\n')}\n`
+    : `${lines.join('\n')}\n`;
+
+  try {
+    writeFileSync(envExamplePath, content, 'utf-8');
+    result.fixed.push({
+      success: true,
+      finding: { title: 'Created .env.example' },
+      message: `Created .env.example with ${newVars.map((v) => v.name).join(', ')}`,
+    });
+  } catch (err) {
+    result.errors.push({
+      success: false,
+      finding: { title: 'Create .env.example' },
+      error: err.message,
+    });
+  }
+}
+
+/**
+ * Undo previous fixes by restoring backups
+ */
+export function undoFixes(findings) {
+  const result = { fixed: [], skipped: [], errors: [] };
+
+  const configPaths = new Set(findings.filter((f) => f.config_path).map((f) => f.config_path));
+
+  for (const configPath of configPaths) {
+    const backupPath = `${configPath}${BACKUP_SUFFIX}`;
+    if (!existsSync(backupPath)) {
+      result.skipped.push({
+        success: false,
+        reason: 'No backup found',
+        finding: { config_path: configPath },
+      });
+      continue;
+    }
+
+    try {
+      copyFileSync(backupPath, configPath);
+      result.fixed.push({
+        success: true,
+        message: `Restored ${configPath} from backup`,
+        finding: { config_path: configPath },
+      });
+    } catch (err) {
+      result.errors.push({
+        success: false,
+        error: err.message,
+        finding: { config_path: configPath },
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Create a backup of a file before modifying it
+ */
+function backupFile(filePath) {
+  const backupPath = `${filePath}${BACKUP_SUFFIX}`;
+  if (!existsSync(backupPath)) {
+    copyFileSync(filePath, backupPath);
+  }
+}
+
+/**
+ * Derive environment variable name from a config key
+ */
+function deriveEnvVarName(key) {
+  return key
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .replace(/[^a-zA-Z0-9]/g, '_')
+    .toUpperCase();
+}
+
+/**
+ * Mask a secret value for display
+ */
+function maskValue(value) {
+  if (!value || value.length <= 8) {
+    return '****';
+  }
+  return `${value.slice(0, 4)}****`;
+}

package/core/cli/HtmlReportGenerator.js

@@ -0,0 +1,203 @@
+/**
+ * HTML Report Generator
+ * Produces a self-contained, offline HTML security report.
+ * No external CSS/JS dependencies — everything is inlined.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import kleur from 'kleur';
+import { S } from './symbols.js';
+
+/**
+ * Generate an HTML report from scan results
+ * @param {object} scanResult - Full scan result from ScanService
+ * @param {string} [outputPath] - Output file path (defaults to cwd/mcp-shark-report.html)
+ * @returns {string} Path to generated report
+ */
+export function generateHtmlReport(scanResult, outputPath) {
+  const reportPath = outputPath || join(process.cwd(), 'mcp-shark-report.html');
+  const html = buildHtml(scanResult);
+  writeFileSync(reportPath, html, 'utf-8');
+  console.log(`  ${kleur.green(S.pass)} Report saved: ${reportPath}`);
+  return reportPath;
+}
+
+/**
+ * Build the complete HTML document
+ */
+function buildHtml(scanResult) {
+  const score = scanResult.scoreResult;
+  const timestamp = new Date().toISOString();
+  const gradeColor = getGradeColor(score.grade);
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>MCP Shark Security Report</title>
+<style>
+${getStyles()}
+</style>
+</head>
+<body>
+<div class="container">
+  <header>
+    <h1>MCP Shark Security Report</h1>
+    <p class="timestamp">Generated: ${timestamp}</p>
+  </header>
+
+  <div class="score-card">
+    <div class="score-circle" style="border-color: ${gradeColor}">
+      <span class="score-number">${score.score}</span>
+      <span class="score-grade" style="color: ${gradeColor}">${score.grade}</span>
+    </div>
+    <div class="score-details">
+      <h2>Shark Score</h2>
+      <p>${score.score}/100 — Grade ${score.grade}</p>
+      <p class="score-summary">${scanResult.findings.length} findings across ${scanResult.serverCount} servers</p>
+    </div>
+  </div>
+
+  <div class="summary-bar">
+    ${renderSummaryBadges(scanResult.severityCounts)}
+    <span class="badge badge-flow">${scanResult.toxicFlows.length} toxic flows</span>
+  </div>
+
+  <section class="findings">
+    <h2>Findings</h2>
+    ${renderFindingsHtml(scanResult.findings)}
+  </section>
+
+  ${renderToxicFlowsHtml(scanResult.toxicFlows)}
+
+  <section class="servers">
+    <h2>Servers Scanned</h2>
+    <table>
+      <thead><tr><th>Server</th><th>IDE</th><th>Findings</th></tr></thead>
+      <tbody>
+        ${renderServersTable(scanResult)}
+      </tbody>
+    </table>
+  </section>
+
+  <footer>
+    <p>mcp-shark v${getVersion()} — ${scanResult.ruleCount} rules · ${scanResult.elapsedMs}ms scan time · 100% local</p>
+  </footer>
+</div>
+</body>
+</html>`;
+}
+
+function getStyles() {
+  return `
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#0d1117;color:#c9d1d9;line-height:1.6}
+.container{max-width:900px;margin:0 auto;padding:2rem}
+header{text-align:center;margin-bottom:2rem}
+header h1{font-size:2rem;color:#58a6ff}
+.timestamp{color:#8b949e;font-size:.85rem}
+.score-card{display:flex;align-items:center;gap:2rem;background:#161b22;border:1px solid #30363d;border-radius:12px;padding:2rem;margin-bottom:1.5rem}
+.score-circle{width:100px;height:100px;border-radius:50%;border:4px solid;display:flex;flex-direction:column;align-items:center;justify-content:center}
+.score-number{font-size:2rem;font-weight:bold;color:#fff}
+.score-grade{font-size:1rem;font-weight:bold}
+.score-details h2{color:#f0f6fc}
+.score-summary{color:#8b949e}
+.summary-bar{display:flex;gap:.5rem;flex-wrap:wrap;margin-bottom:2rem}
+.badge{padding:.25rem .75rem;border-radius:20px;font-size:.8rem;font-weight:600}
+.badge-critical{background:#da3633;color:#fff}
+.badge-high{background:#d29922;color:#fff}
+.badge-medium{background:#1f6feb;color:#fff}
+.badge-low{background:#30363d;color:#8b949e}
+.badge-flow{background:#8957e5;color:#fff}
+h2{color:#f0f6fc;margin:1.5rem 0 1rem;font-size:1.3rem}
+.finding{background:#161b22;border:1px solid #30363d;border-radius:8px;padding:1rem;margin-bottom:.75rem}
+.finding-header{display:flex;justify-content:space-between;align-items:center}
+.finding-title{font-weight:600;color:#f0f6fc}
+.sev{padding:.15rem .5rem;border-radius:4px;font-size:.75rem;font-weight:600;text-transform:uppercase}
+.sev-critical{background:#da3633;color:#fff}
+.sev-high{background:#d29922;color:#fff}
+.sev-medium{background:#1f6feb;color:#fff}
+.sev-low{background:#30363d;color:#8b949e}
+.finding-desc{color:#8b949e;margin-top:.5rem;font-size:.9rem}
+.finding-meta{color:#484f58;font-size:.8rem;margin-top:.25rem}
+.toxic-flow{background:#1c1229;border:1px solid #8957e5;border-radius:8px;padding:1rem;margin-bottom:.75rem}
+.flow-chain{color:#d2a8ff;font-weight:600}
+table{width:100%;border-collapse:collapse;background:#161b22;border-radius:8px;overflow:hidden}
+th{background:#21262d;color:#f0f6fc;text-align:left;padding:.75rem 1rem;font-size:.85rem}
+td{padding:.75rem 1rem;border-top:1px solid #30363d;font-size:.9rem}
+footer{text-align:center;margin-top:3rem;color:#484f58;font-size:.8rem}`;
+}
+
+function getGradeColor(grade) {
+  const colors = { A: '#3fb950', B: '#56d364', C: '#d29922', D: '#db6d28', F: '#da3633' };
+  return colors[grade] || '#8b949e';
+}
+
+function renderSummaryBadges(counts) {
+  return ['critical', 'high', 'medium', 'low']
+    .filter((s) => (counts[s] || 0) > 0)
+    .map((s) => `<span class="badge badge-${s}">${counts[s]} ${s}</span>`)
+    .join('\n    ');
+}
+
+function renderFindingsHtml(findings) {
+  if (findings.length === 0) {
+    return '<p style="color:#3fb950">No security issues found.</p>';
+  }
+  return findings
+    .map((f) => {
+      const sev = (f.severity || 'medium').toLowerCase();
+      return `<div class="finding">
+      <div class="finding-header">
+        <span class="finding-title">${escapeHtml(f.title)}</span>
+        <span class="sev sev-${sev}">${sev}</span>
+      </div>
+      <div class="finding-desc">${escapeHtml(f.description || '')}</div>
+      <div class="finding-meta">${f.rule_id || ''} · ${f.server_name || ''} · ${f.ide || ''}</div>
+    </div>`;
+    })
+    .join('\n  ');
+}
+
+function renderToxicFlowsHtml(flows) {
+  if (flows.length === 0) {
+    return '';
+  }
+  const items = flows
+    .map(
+      (f) => `<div class="toxic-flow">
+      <div class="flow-chain">${escapeHtml(f.chain || `${f.source} → ${f.sink}`)}</div>
+      <div class="finding-desc">${escapeHtml(f.scenario || f.description || '')}</div>
+    </div>`
+    )
+    .join('\n  ');
+  return `<section><h2>Toxic Flows</h2>${items}</section>`;
+}
+
+function renderServersTable(scanResult) {
+  return scanResult.servers
+    .map((s) => {
+      const count = scanResult.findings.filter((f) => f.server_name === s.name).length;
+      return `<tr><td>${escapeHtml(s.name)}</td><td>${escapeHtml(s.ide)}</td><td>${count}</td></tr>`;
+    })
+    .join('\n        ');
+}
+
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function getVersion() {
+  try {
+    const pkgPath = join(import.meta.dirname, '..', '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return pkg.version;
+  } catch (_err) {
+    return '1.x';
+  }
+}