@mcp-shark/mcp-shark 1.5.13 → 1.7.2

package/core/cli/output/Formatter.js

@@ -0,0 +1,183 @@
+/**
+ * Terminal output formatter for scan results
+ * Renders findings, toxic flows, and summaries with colors
+ */
+import kleur from 'kleur';
+import { S } from '../symbols.js';
+
+const SEVERITY_COLORS = {
+  critical: (text) => kleur.bgRed().white().bold(` ${text} `),
+  high: (text) => kleur.red().bold(text),
+  medium: (text) => kleur.yellow(text),
+  low: (text) => kleur.blue(text),
+};
+
+const SEVERITY_LABELS = {
+  critical: 'CRIT',
+  high: 'HIGH',
+  medium: 'MED ',
+  low: 'LOW ',
+};
+
+/**
+ * Format a single finding for terminal output
+ */
+export function formatFinding(finding) {
+  const severity = (finding.severity || finding.risk_level || 'medium').toLowerCase();
+  const label = SEVERITY_LABELS[severity] || 'INFO';
+  const colorFn = SEVERITY_COLORS[severity] || kleur.gray;
+  const confidence = finding.confidence === 'possible' ? 'advisory' : 'confirmed';
+  const confidenceColor = confidence === 'confirmed' ? kleur.white : kleur.gray;
+
+  const ruleId = finding.rule_id || finding.category || '';
+  const ruleDisplay = ruleId.toUpperCase().replace(/-/g, '').slice(0, 5);
+
+  const message = finding.title || finding.description || finding.message || '';
+
+  return `    ${colorFn(label)}  ${kleur.dim(ruleDisplay)}  ${message}  ${confidenceColor(confidence)}`;
+}
+
+/**
+ * Format findings grouped by server
+ */
+export function formatServerFindings(serverName, ideName, findings) {
+  const lines = [];
+  const header = kleur.bold(`  ${serverName}`) + kleur.dim(` (${ideName})`);
+  lines.push(header);
+
+  for (const finding of findings) {
+    lines.push(formatFinding(finding));
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Format clean servers summary
+ */
+export function formatCleanServers(cleanServerNames) {
+  if (cleanServerNames.length === 0) {
+    return '';
+  }
+  const names = cleanServerNames.join(', ');
+  return `  ${names} ${kleur.green(`${S.bar} clean ${S.pass}`)}\n`;
+}
+
+/**
+ * Format toxic flow section
+ */
+export function formatToxicFlows(flows) {
+  if (flows.length === 0) {
+    return '';
+  }
+
+  const lines = [];
+  lines.push(`  ${kleur.dim(S.bar.repeat(65))}`);
+  lines.push(`  ${kleur.bold('Toxic Flows')}`);
+  lines.push(`  ${kleur.dim(S.bar.repeat(65))}`);
+  lines.push('');
+
+  for (const flow of flows) {
+    const riskColor = flow.risk === 'HIGH' ? kleur.red : kleur.yellow;
+    lines.push(
+      `  ${riskColor(`${S.warn} ${flow.risk}`)}  ${kleur.bold(flow.source)} ${kleur.dim(S.arrow)} ${kleur.bold(flow.target)}`
+    );
+    lines.push(`    ${flow.scenario}`);
+    lines.push(`    ${kleur.dim(`(Catalog ${flow.catalog})`)}`);
+    lines.push('');
+  }
+
+  lines.push(`  ${kleur.dim(S.bar.repeat(65))}`);
+  return lines.join('\n');
+}
+
+/**
+ * Format the Shark Score display
+ */
+export function formatSharkScore(scoreResult) {
+  const { score, grade } = scoreResult;
+
+  const gradeColors = {
+    A: kleur.green,
+    B: kleur.green,
+    C: kleur.yellow,
+    D: kleur.red,
+    F: kleur.bgRed().white,
+  };
+
+  const colorFn = gradeColors[grade] || kleur.white;
+  return `  Shark Score: ${colorFn(`${score}/100 (${grade})`)}`;
+}
+
+/**
+ * Format the summary counts line
+ */
+export function formatSummaryCounts(counts, flowCount) {
+  const parts = [];
+  if (counts.critical > 0) {
+    parts.push(kleur.red(`${counts.critical} critical`));
+  }
+  if (counts.high > 0) {
+    parts.push(kleur.red(`${counts.high} high`));
+  }
+  if (counts.medium > 0) {
+    parts.push(kleur.yellow(`${counts.medium} medium`));
+  }
+  if (counts.low > 0) {
+    parts.push(kleur.blue(`${counts.low} low`));
+  }
+  if (flowCount > 0) {
+    parts.push(kleur.red(`${flowCount} toxic flows`));
+  }
+
+  if (parts.length === 0) {
+    return `  ${kleur.green(`${S.pass} No issues found`)}`;
+  }
+
+  return `  ${parts.join(kleur.dim(` ${S.dot} `))}`;
+}
+
+/**
+ * Format completion timing
+ */
+export function formatTiming(elapsedMs, serverCount, ruleCount, toolCount) {
+  const seconds = (elapsedMs / 1000).toFixed(1);
+  return kleur.dim(
+    `  Completed in ${seconds}s ${S.dot} ${serverCount} servers ${S.dot} ${ruleCount} rules ${S.dot} ${toolCount} tools checked`
+  );
+}
+
+/**
+ * Format next steps suggestions
+ */
+export function formatNextSteps(hasFixable, hasFlows) {
+  const lines = [];
+  lines.push('');
+  lines.push(kleur.dim('  Next steps:'));
+
+  if (hasFixable) {
+    lines.push(`    ${kleur.cyan('npx mcp-shark scan --fix')}          Auto-fix fixable issues`);
+  }
+  if (hasFlows) {
+    lines.push(`    ${kleur.cyan('npx mcp-shark scan --walkthrough')}  See full attack chains`);
+  }
+  lines.push(`    ${kleur.cyan('npx mcp-shark lock')}                Pin tool definitions`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Format IDE discovery line
+ */
+export function formatIdeDiscovery(ideResults) {
+  const found = ideResults.filter((ide) => ide.found);
+  const names = found.map((ide) => ide.name);
+  const serverCount = found.reduce((sum, ide) => sum + ide.serverCount, 0);
+
+  if (names.length === 0) {
+    return `  ${kleur.yellow(`${S.warn} No MCP configurations found`)}`;
+  }
+
+  return kleur.dim(`  Scanning ${serverCount} servers across ${names.join(', ')}...`);
+}

package/core/cli/output/JsonFormatter.js

@@ -0,0 +1,106 @@
+/**
+ * JSON and SARIF output formatters for scan results
+ */
+
+/**
+ * Format scan results as JSON
+ */
+export function formatAsJson(scanResult) {
+  return JSON.stringify(scanResult, null, 2);
+}
+
+/**
+ * Format scan results as SARIF v2.1.0
+ * Static Analysis Results Interchange Format for CI/CD integration
+ */
+export function formatAsSarif(scanResult) {
+  const sarifRules = buildSarifRules(scanResult.findings);
+  const sarifResults = buildSarifResults(scanResult.findings);
+
+  const sarif = {
+    $schema:
+      'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json',
+    version: '2.1.0',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'mcp-shark',
+            version: scanResult.version || '1.0.0',
+            informationUri: 'https://mcpshark.sh',
+            rules: sarifRules,
+          },
+        },
+        results: sarifResults,
+      },
+    ],
+  };
+
+  return JSON.stringify(sarif, null, 2);
+}
+
+/**
+ * Build SARIF rule descriptors from findings
+ */
+function buildSarifRules(findings) {
+  const ruleMap = new Map();
+
+  for (const finding of findings) {
+    const ruleId = finding.rule_id || finding.category || 'unknown';
+    if (ruleMap.has(ruleId)) {
+      continue;
+    }
+
+    ruleMap.set(ruleId, {
+      id: ruleId,
+      name: finding.title || ruleId,
+      shortDescription: {
+        text: finding.title || finding.description || ruleId,
+      },
+      defaultConfiguration: {
+        level: mapSeverityToSarif(finding.severity || finding.risk_level),
+      },
+    });
+  }
+
+  return [...ruleMap.values()];
+}
+
+/**
+ * Build SARIF result entries from findings
+ */
+function buildSarifResults(findings) {
+  return findings.map((finding) => ({
+    ruleId: finding.rule_id || finding.category || 'unknown',
+    level: mapSeverityToSarif(finding.severity || finding.risk_level),
+    message: {
+      text: finding.description || finding.title || finding.message || '',
+    },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: {
+            uri: finding.config_path || finding.server_name || 'unknown',
+          },
+        },
+      },
+    ],
+    properties: {
+      confidence: finding.confidence || 'probable',
+      serverName: finding.server_name || null,
+    },
+  }));
+}
+
+/**
+ * Map internal severity to SARIF level
+ */
+function mapSeverityToSarif(severity) {
+  const map = {
+    critical: 'error',
+    high: 'error',
+    medium: 'warning',
+    low: 'note',
+  };
+  return map[(severity || '').toLowerCase()] || 'warning';
+}

package/core/cli/output/index.js

@@ -0,0 +1,16 @@
+/**
+ * CLI output module barrel file
+ */
+export { displayScanBanner, displayServeBanner } from './Banner.js';
+export {
+  formatFinding,
+  formatServerFindings,
+  formatCleanServers,
+  formatToxicFlows,
+  formatSharkScore,
+  formatSummaryCounts,
+  formatTiming,
+  formatNextSteps,
+  formatIdeDiscovery,
+} from './Formatter.js';
+export { formatAsJson, formatAsSarif } from './JsonFormatter.js';

package/core/cli/secureRegistryFetch.js

@@ -0,0 +1,157 @@
+/**
+ * Hardened HTTP fetch for rule registry and pack downloads.
+ * - HTTPS only by default (HTTP only with MCP_SHARK_INSECURE_HTTP_REGISTRY=1)
+ * - No userinfo in URLs (prevents credential injection)
+ * - Manual redirect handling with re-validation each hop (mitigates redirect-to-internal SSRF)
+ * - Response size cap (mitigates memory exhaustion)
+ */
+import { createHash } from 'node:crypto';
+
+const MAX_REDIRECTS = 5;
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+
+/**
+ * @param {string} urlString
+ * @returns {string} normalized href
+ */
+export function assertAllowedRegistryUrl(urlString) {
+  let parsed;
+  try {
+    parsed = new URL(urlString);
+  } catch {
+    throw new Error('Invalid URL');
+  }
+
+  const allowHttp = process.env.MCP_SHARK_INSECURE_HTTP_REGISTRY === '1';
+
+  if (parsed.protocol === 'https:') {
+    // ok
+  } else if (parsed.protocol === 'http:' && allowHttp) {
+    // lab / air-gapped mirrors only — explicit env required
+  } else {
+    throw new Error(
+      'Registry URLs must use HTTPS. For trusted internal HTTP mirrors only, set MCP_SHARK_INSECURE_HTTP_REGISTRY=1.'
+    );
+  }
+
+  if (!parsed.hostname) {
+    throw new Error('Registry URL must have a hostname');
+  }
+
+  if (parsed.username !== '' || parsed.password !== '') {
+    throw new Error('Registry URL must not embed credentials');
+  }
+
+  return parsed.href;
+}
+
+/**
+ * Fetch JSON with size limit and safe redirects.
+ * @param {string} initialUrl
+ * @param {number} [maxBytes]
+ * @returns {Promise<object>}
+ */
+export async function fetchUtf8Secure(initialUrl, maxBytes = DEFAULT_MAX_BYTES) {
+  let url = assertAllowedRegistryUrl(initialUrl);
+
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const response = await fetch(url, {
+      redirect: 'manual',
+      headers: {
+        Accept: 'application/json, text/plain;q=0.9, */*;q=0.8',
+        'User-Agent': 'mcp-shark-rule-update',
+      },
+    });
+
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get('location');
+      if (!location || hop === MAX_REDIRECTS) {
+        throw new Error('Too many HTTP redirects or missing Location header');
+      }
+      url = assertAllowedRegistryUrl(new URL(location, url).href);
+      continue;
+    }
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return readBodyWithLimit(response, maxBytes);
+  }
+
+  throw new Error('Redirect loop');
+}
+
+/**
+ * @param {string} initialUrl
+ * @param {number} [maxBytes]
+ * @returns {Promise<object>}
+ */
+export async function fetchJsonSecure(initialUrl, maxBytes = DEFAULT_MAX_BYTES) {
+  const text = await fetchUtf8Secure(initialUrl, maxBytes);
+  return JSON.parse(text);
+}
+
+/**
+ * @param {Response} response
+ * @param {number} maxBytes
+ * @returns {Promise<string>}
+ */
+async function readBodyWithLimit(response, maxBytes) {
+  if (!response.body) {
+    const text = await response.text();
+    if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+      throw new Error('Response body exceeds size limit');
+    }
+    return text;
+  }
+
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    total += value.length;
+    if (total > maxBytes) {
+      throw new Error('Response body exceeds size limit');
+    }
+    chunks.push(value);
+  }
+
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+const SAFE_PACK_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+
+/**
+ * @param {string} id
+ */
+export function assertSafePackId(id) {
+  if (typeof id !== 'string' || !SAFE_PACK_ID.test(id)) {
+    throw new Error(
+      'Pack id must be 1–128 chars: letters, digits, dot, underscore, hyphen; no path segments.'
+    );
+  }
+}
+
+/**
+ * @param {string} expectedHex
+ * @param {string} utf8Body
+ */
+export function assertSha256(expectedHex, utf8Body) {
+  if (!expectedHex || typeof expectedHex !== 'string') {
+    return;
+  }
+  const normalized = expectedHex.trim().toLowerCase();
+  if (!/^[a-f0-9]{64}$/.test(normalized)) {
+    throw new Error('Invalid sha256 format in manifest');
+  }
+  const actual = createHash('sha256').update(utf8Body, 'utf8').digest('hex');
+  if (actual !== normalized) {
+    throw new Error('Downloaded pack failed SHA-256 verification');
+  }
+}

package/core/cli/symbols.js

@@ -0,0 +1,16 @@
+/**
+ * CLI Symbol Vocabulary
+ * Geometric symbols — consistent across all output.
+ * Inspired by Biome/Astro/@clack aesthetic.
+ */
+
+export const S = {
+  pass: '◇',
+  fail: '◆',
+  warn: '▲',
+  info: '│',
+  dot: '·',
+  bar: '─',
+  arrow: '→',
+  pointer: '▸',
+};

package/core/configs/environment.js

@@ -12,10 +12,12 @@ export const Environment = {
   },
   /**
    * Get UI server port
+   * Honours UI_PORT first, then the documented MCP_SHARK_PORT alias.
    * @returns {number} UI server port (default: 9853)
    */
   getUiPort() {
-    const port = Number.parseInt(process.env.UI_PORT, 10);
+    const raw = process.env.UI_PORT ?? process.env.MCP_SHARK_PORT;
+    const port = Number.parseInt(raw, 10);
     return Number.isNaN(port) ? Server.DEFAULT_UI_PORT : port;
   },
 

package/core/configs/index.js

@@ -1,17 +1,15 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { Environment } from './environment.js';
 
 export { Environment } from './environment.js';
 
-const WORKING_DIRECTORY_NAME = '.mcp-shark';
 const MCP_CONFIG_NAME = 'mcps.json';
 const APP_DB_DIR_NAME = 'db';
 const APP_DB_FILE_NAME = 'mcp-shark.sqlite';
-const HELP_STATE_NAME = 'help-state.json';
 
 export function getWorkingDirectory() {
-  return join(homedir(), WORKING_DIRECTORY_NAME);
+  return Environment.getMcpSharkHome();
 }
 
 export function getDatabasePath() {
@@ -61,62 +59,3 @@ export function ensureDirectoryExists(filePath) {
     mkdirSync(dir, { recursive: true });
   }
 }
-
-export function getHelpStatePath() {
-  return join(getWorkingDirectory(), HELP_STATE_NAME);
-}
-
-export function readHelpState() {
-  try {
-    const helpStatePath = getHelpStatePath();
-    if (existsSync(helpStatePath)) {
-      const content = readFileSync(helpStatePath, 'utf8');
-      const state = JSON.parse(content);
-      // Ensure we have the expected structure
-      return {
-        dismissed: state.dismissed || false,
-        tourCompleted: state.tourCompleted || false,
-        dismissedAt: state.dismissedAt || null,
-        version: state.version || '1.0.0',
-      };
-    }
-    return {
-      dismissed: false,
-      tourCompleted: false,
-      dismissedAt: null,
-      version: '1.0.0',
-    };
-  } catch (_error) {
-    // Error reading help state - return defaults
-    return {
-      dismissed: false,
-      tourCompleted: false,
-      dismissedAt: null,
-      version: '1.0.0',
-    };
-  }
-}
-
-export function writeHelpState(state) {
-  try {
-    const helpStatePath = getHelpStatePath();
-    prepareAppDataSpaces(); // Ensure directory exists
-
-    // Merge with existing state to preserve other fields
-    const existingState = readHelpState();
-    const newState = {
-      ...existingState,
-      ...state,
-      dismissedAt:
-        state.dismissed || state.tourCompleted
-          ? new Date().toISOString()
-          : existingState.dismissedAt,
-      version: '1.0.0',
-    };
-
-    writeFileSync(helpStatePath, JSON.stringify(newState, null, 2));
-    return true;
-  } catch (_error) {
-    return false;
-  }
-}

package/core/container/DependencyContainer.js

@@ -33,6 +33,7 @@ import {
   StatisticsService,
   TokenService,
   TrafficAnalysisService,
+  TrafficToxicFlowService,
   YaraEngineService,
 } from '#core/services/index.js';
 import { ConfigParserFactory } from '#core/services/parsers/ConfigParserFactory.js';
@@ -160,10 +161,12 @@ export class DependencyContainer {
         this._services.yaraEngine,
         libs.logger
       );
+      this._services.trafficToxicFlow = new TrafficToxicFlowService(repos.packet, libs.logger);
       this._services.trafficAnalysis = new TrafficAnalysisService(
         this._services.staticRules,
         repos.securityFindings,
-        libs.logger
+        libs.logger,
+        this._services.trafficToxicFlow
       );
       this._services.rulesManager = new RulesManagerService(
         repos.securityRules,

package/core/mcp-server/index.js

@@ -142,7 +142,10 @@ export async function startMcpSharkServer(options = {}) {
       throw new Error('auditLogger is required. Call initAuditLogger() and pass it in options.');
     }
     const auditLogger = providedAuditLogger;
-    const externalServersResult = await runAllExternalServers(serverLogger, configPath);
+    const externalServersResult = await runAllExternalServers(serverLogger, configPath, {
+      selfPort: port,
+      allowEmpty: true,
+    });
 
     if (isError(externalServersResult)) {
       serverLogger.error(

package/core/mcp-server/server/external/all.js

@@ -1,4 +1,4 @@
-import { CompositeError, getErrors } from '#core/libraries/ErrorLibrary.js';
+import { CompositeError, getErrors, isError } from '#core/libraries/ErrorLibrary.js';
 import { normalizeConfig } from './config.js';
 import { buildKv } from './kv.js';
 import { runExternalServer } from './single/run.js';
@@ -10,8 +10,15 @@ export class RunAllExternalServersError extends CompositeError {
   }
 }
 
-export async function runAllExternalServers(logger, parsedConfig) {
-  const configs = normalizeConfig(parsedConfig);
+export async function runAllExternalServers(logger, parsedConfig, options = {}) {
+  const configs = normalizeConfig(parsedConfig, { ...options, logger });
+  if (isError(configs)) {
+    return new RunAllExternalServersError(
+      `Failed to normalize upstream config: ${configs.message}`,
+      configs,
+      [configs]
+    );
+  }
   const results = await Promise.all(
     Object.entries(configs).map(([name, config]) => runExternalServer({ logger, name, config }))
   );