@weave_protocol/mund 0.2.3 → 0.3.1

package/src/cli/scan.ts

@@ -0,0 +1,260 @@
+/**
+ * Mund - The Guardian Protocol
+ * `mund-mcp scan` - scan files on disk and report as text, JSON or SARIF
+ *
+ *   mund-mcp scan [paths...] [--format=text|json|sarif] [--output=FILE]
+ *                 [--fail-on=critical|high|medium|low|none]
+ *                 [--no-osv] [--offline]
+ */
+
+import { readFile, writeFile, readdir, stat } from 'fs/promises';
+import { basename, join, relative, resolve, sep } from 'path';
+import type { SecurityIssue, Severity } from '../types.js';
+import { DEFAULT_RULES } from '../constants.js';
+import { AnalyzerEngine } from '../analyzers/index.js';
+import { computeRiskScore, type RiskScore } from '../scoring.js';
+import { toSarif, type SarifTarget } from '../sarif.js';
+import { OsvClient, parseNpmLockfile, advisoriesToIssues, type OsvSource } from '../osv.js';
+import { getVersion } from '../version.js';
+import { canaries, loadCanariesFromEnv } from '../canary.js';
+
+export type OutputFormat = 'text' | 'json' | 'sarif';
+type FailOn = Severity | 'none';
+
+export interface ScanCliOptions {
+  paths: string[];
+  format: OutputFormat;
+  output?: string;
+  failOn: FailOn;
+  osv: boolean;
+  offline: boolean;
+  canaries: string[];
+}
+
+export interface FileReport extends SarifTarget {
+  risk: RiskScore;
+}
+
+export interface ScanReport {
+  tool: { name: 'mund'; version: string };
+  risk: RiskScore;
+  files_scanned: number;
+  osv?: { source: OsvSource; lockfiles: number; unchecked: number; error?: string };
+  files: FileReport[];
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.turbo', 'vendor', '__pycache__', '.venv']);
+const LOCKFILES = new Set(['package-lock.json', 'npm-shrinkwrap.json']);
+const MAX_FILE_BYTES = 1024 * 1024;
+const SEVERITY_RANK: Record<Severity, number> = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+
+export const SCAN_USAGE = `Usage: mund-mcp scan [paths...] [options]
+
+Scan files for secrets, PII, injection, exfiltration and dangerous code,
+plus known-vulnerable npm dependencies (via OSV.dev) in package-lock.json.
+
+Options:
+  --format=FORMAT    text (default), json, or sarif
+  --output=FILE      Write the report to FILE instead of stdout
+  --fail-on=LEVEL    Exit 1 if any finding is at or above LEVEL
+                     (critical, high [default], medium, low, none)
+  --no-osv           Skip dependency vulnerability lookups
+  --offline          Use only the local OSV cache (also: MUND_OFFLINE=1)
+  --canary=TOKEN     Flag any file containing this canary token (repeatable;
+                     also MUND_CANARIES / MUND_CANARY_FILE)
+
+Examples:
+  mund-mcp scan .
+  mund-mcp scan src --format=sarif --output=mund.sarif
+`;
+
+export function parseScanArgs(args: string[]): ScanCliOptions {
+  const opts: ScanCliOptions = { paths: [], format: 'text', failOn: 'high', osv: true, offline: false, canaries: [] };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const [flag, inline] = arg.startsWith('--') && arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, undefined];
+    const value = () => {
+      const v = inline ?? args[++i];
+      if (v === undefined) throw new Error(`${flag} needs a value`);
+      return v;
+    };
+
+    switch (flag) {
+      case '--format': {
+        const v = value();
+        if (v !== 'text' && v !== 'json' && v !== 'sarif') throw new Error(`Unknown format "${v}" (expected text, json or sarif)`);
+        opts.format = v;
+        break;
+      }
+      case '--output':
+      case '-o':
+        opts.output = value();
+        break;
+      case '--fail-on': {
+        const v = value();
+        if (v !== 'none' && !(v in SEVERITY_RANK)) throw new Error(`Unknown --fail-on level "${v}"`);
+        opts.failOn = v as FailOn;
+        break;
+      }
+      case '--no-osv':
+        opts.osv = false;
+        break;
+      case '--offline':
+        opts.offline = true;
+        break;
+      case '--canary':
+        opts.canaries.push(value());
+        break;
+      default:
+        if (flag.startsWith('-')) throw new Error(`Unknown option ${flag}`);
+        opts.paths.push(arg);
+    }
+  }
+
+  if (opts.paths.length === 0) opts.paths.push('.');
+  return opts;
+}
+
+export async function runScan(opts: ScanCliOptions, osvClient?: OsvClient): Promise<ScanReport> {
+  const cwd = process.cwd();
+  loadCanariesFromEnv();
+  for (const token of opts.canaries) canaries.register(token, 'cli');
+  const engine = new AnalyzerEngine();
+  const files: FileReport[] = [];
+  const lockfiles: string[] = [];
+  let scanned = 0;
+
+  for (const file of await collectFiles(opts.paths.map(p => resolve(cwd, p)))) {
+    if (LOCKFILES.has(basename(file))) {
+      lockfiles.push(file);
+      continue;
+    }
+    const content = await readText(file);
+    if (content === null) continue;
+    scanned++;
+    const issues = await engine.analyzeAll(content, DEFAULT_RULES);
+    if (issues.length > 0) files.push({ uri: toUri(cwd, file), issues, risk: computeRiskScore(issues) });
+  }
+
+  let osv: ScanReport['osv'];
+  if (opts.osv && lockfiles.length > 0) {
+    const client = osvClient ?? new OsvClient({ offline: opts.offline });
+    let source: OsvSource = 'live';
+    let unchecked = 0;
+    let error: string | undefined;
+
+    for (const lockfile of lockfiles) {
+      const content = await readFile(lockfile, 'utf8');
+      let packages;
+      try {
+        packages = parseNpmLockfile(content);
+      } catch {
+        continue; // malformed lockfile; nothing to look up
+      }
+      const result = await client.lookup(packages);
+      // Report the weakest source across lockfiles.
+      if (result.source === 'unavailable' || (result.source === 'cache' && source === 'live')) source = result.source;
+      unchecked += result.unchecked.length;
+      error ??= result.error;
+
+      const issues = advisoriesToIssues(packages, result, content);
+      if (issues.length > 0) files.push({ uri: toUri(cwd, lockfile), issues, risk: computeRiskScore(issues) });
+    }
+    osv = { source, lockfiles: lockfiles.length, unchecked, ...(error ? { error } : {}) };
+  }
+
+  return {
+    tool: { name: 'mund', version: getVersion() },
+    risk: computeRiskScore(files.flatMap(f => f.issues)),
+    files_scanned: scanned,
+    ...(osv ? { osv } : {}),
+    files,
+  };
+}
+
+export function formatReport(report: ScanReport, format: OutputFormat): string {
+  if (format === 'json') return JSON.stringify(report, null, 2);
+  if (format === 'sarif') return JSON.stringify(toSarif(report.files, { toolVersion: report.tool.version }), null, 2);
+
+  const lines: string[] = [];
+  for (const file of report.files) {
+    lines.push(`${file.uri}  (risk ${file.risk.score}/100, ${file.risk.label})`);
+    for (const issue of file.issues) {
+      const where = issue.location?.line ? `${issue.location.line}:${issue.location.column ?? 1}` : '-';
+      lines.push(`  ${where.padEnd(8)} ${issue.severity.padEnd(8)} ${issue.rule_name}`);
+    }
+    lines.push('');
+  }
+
+  const total = report.files.reduce((n, f) => n + f.issues.length, 0);
+  const { counts } = report.risk;
+  lines.push(`Scanned ${report.files_scanned} file(s): ${total} finding(s) ` +
+    `(${counts.critical} critical, ${counts.high} high, ${counts.medium} medium, ${counts.low} low)`);
+  lines.push(`Risk score: ${report.risk.score}/100 (${report.risk.label})`);
+  if (report.osv) {
+    const note = report.osv.source === 'live' ? 'live' : `${report.osv.source} - ${report.osv.error ?? ''}`.trim();
+    lines.push(`Dependencies: OSV.dev (${note})` + (report.osv.unchecked ? `, ${report.osv.unchecked} package(s) unchecked` : ''));
+  }
+  return lines.join('\n');
+}
+
+export function shouldFail(report: ScanReport, failOn: FailOn): boolean {
+  if (failOn === 'none') return false;
+  const threshold = SEVERITY_RANK[failOn];
+  return report.files.some(f => f.issues.some((i: SecurityIssue) => SEVERITY_RANK[i.severity] <= threshold));
+}
+
+/** Entry point for `mund-mcp scan`. Returns the process exit code. */
+export async function runScanCli(args: string[]): Promise<number> {
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(SCAN_USAGE);
+    return 0;
+  }
+
+  let opts: ScanCliOptions;
+  try {
+    opts = parseScanArgs(args);
+  } catch (error) {
+    process.stderr.write(`mund scan: ${(error as Error).message}\n\n${SCAN_USAGE}`);
+    return 2;
+  }
+
+  const report = await runScan(opts);
+  const out = formatReport(report, opts.format) + '\n';
+  if (opts.output) await writeFile(opts.output, out);
+  else process.stdout.write(out);
+
+  return shouldFail(report, opts.failOn) ? 1 : 0;
+}
+
+async function collectFiles(roots: string[]): Promise<string[]> {
+  const out: string[] = [];
+  const walk = async (path: string) => {
+    const info = await stat(path).catch(() => null);
+    if (!info) return;
+    if (info.isFile()) {
+      out.push(path);
+    } else if (info.isDirectory()) {
+      for (const entry of await readdir(path, { withFileTypes: true })) {
+        if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+        if (entry.isDirectory() || entry.isFile()) await walk(join(path, entry.name));
+      }
+    }
+  };
+  for (const root of roots) await walk(root);
+  return out.sort();
+}
+
+/** Read a file as UTF-8 text, or null if it's too big or looks binary. */
+async function readText(file: string): Promise<string | null> {
+  const info = await stat(file);
+  if (info.size > MAX_FILE_BYTES) return null;
+  const buf = await readFile(file);
+  if (buf.subarray(0, 8000).includes(0)) return null;
+  return buf.toString('utf8');
+}
+
+function toUri(cwd: string, file: string): string {
+  return relative(cwd, file).split(sep).join('/');
+}

package/src/index.ts

@@ -15,6 +15,9 @@ import { createStorage } from './storage/index.js';
 import { AnalyzerEngine } from './analyzers/index.js';
 import { NotificationHub } from './notifications/index.js';
 import { registerAllTools } from './tools/index.js';
+import { runScanCli } from './cli/scan.js';
+import { getVersion } from './version.js';
+import { loadCanariesFromEnv } from './canary.js';
 
 // Threat Intelligence imports
 import { threatIntel } from './threat-intel-manager.js';
@@ -154,7 +157,7 @@ async function createMundServer(config: MundConfig): Promise<McpServer> {
   // Create MCP server
   const server = new McpServer({
     name: 'mund-mcp-server',
-    version: '0.2.0'
+    version: getVersion()
   });
 
   // Initialize storage
@@ -178,6 +181,7 @@ async function createMundServer(config: MundConfig): Promise<McpServer> {
   }
 
   // Register all core tools
+  loadCanariesFromEnv();
   registerAllTools(server, storage, rules, analyzer, notificationHub, config.block_mode);
 
   // Register threat intelligence tools
@@ -218,7 +222,7 @@ async function runHTTP(config: MundConfig): Promise<void> {
 
   // Health check endpoint
   app.get('/health', (_req, res) => {
-    res.json({ status: 'ok', version: '0.2.0' });
+    res.json({ status: 'ok', version: getVersion() });
   });
 
   // Threat intel status endpoint
@@ -254,7 +258,8 @@ function printHelp(): void {
 Mund - The Guardian Protocol
 MCP-based security monitoring for agentic AI systems
 
-Usage: mund-mcp [options]
+Usage: mund-mcp [options]          Run the MCP server
+       mund-mcp scan [paths...]    Scan files (see: mund-mcp scan --help)
 
 Options:
   --help, -h          Show this help message
@@ -314,6 +319,10 @@ For more information, visit: https://github.com/Tyox-all/Weave_Protocol
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
 
+  if (args[0] === 'scan') {
+    process.exit(await runScanCli(args.slice(1)));
+  }
+
   // Parse CLI arguments
   if (args.includes('--help') || args.includes('-h')) {
     printHelp();
@@ -321,7 +330,7 @@ async function main(): Promise<void> {
   }
 
   if (args.includes('--version') || args.includes('-v')) {
-    console.log('0.2.0');
+    console.log(getVersion());
     process.exit(0);
   }
 

package/src/notifications/email.ts

@@ -1,210 +1,54 @@
 /**
  * Mund - The Guardian Protocol
- * Email Notifier - Send alerts via email
+ * Email Notifier - NOT IMPLEMENTED in v0.2.x.
+ *
+ * The nodemailer dependency was removed because it carried a
+ * high-severity CVE and was never actually wired up (the previous
+ * revision had only comments like "In a real implementation, use
+ * nodemailer here"). Carrying a prod dep for a feature nobody uses
+ * meant inheriting its CVE for no benefit.
+ *
+ * This stub keeps the INotifier contract so NotificationManager can
+ * still wire it up when `notificationConfig.email.smtp_host` is set,
+ * but every send() call returns false and logs a one-time warning,
+ * so operators see email alerts aren't actually being delivered.
+ *
+ * When/if email notifications become a real feature:
+ *   1. npm install nodemailer@^10 @types/nodemailer
+ *   2. Replace this stub with a real implementation
+ *   3. Add test fixtures under test/notifications/
+ *   4. Remove the console.warn in the constructor
  */
 
-import type { INotifier, NotificationPayload, EmailConfig, Severity } from '../types.js';
-
-// Note: In production, use nodemailer
-// For now, we'll implement a basic interface that can be extended
+import type { INotifier, NotificationPayload, EmailConfig } from '../types.js';
 
 export class EmailNotifier implements INotifier {
   name = 'EmailNotifier';
-  private config: EmailConfig;
+  // Config is retained so a future real implementation can see what
+  // shape to expect. Public (not private) because noUnusedLocals flags
+  // unread private members even with an underscore prefix.
+  readonly config: EmailConfig;
+  private warned = false;
 
   constructor(config: EmailConfig) {
     this.config = config;
+    console.warn(
+      '[mund] EmailNotifier configured but NOT IMPLEMENTED in this version. ' +
+        'Email alerts will be dropped. Use a webhook, Slack, or Teams notifier ' +
+        'for actual delivery. Track at ' +
+        'https://github.com/Tyox-all/Weave_Protocol/issues',
+    );
   }
 
-  async send(payload: NotificationPayload): Promise<boolean> {
-    const { event } = payload;
-
-    // Check minimum severity
-    if (this.config.min_severity && !this.meetsMinSeverity(event.severity, this.config.min_severity)) {
-      return true; // Successfully skipped
-    }
-
-    const emailContent = this.formatEmail(payload);
-
-    try {
-      // In a real implementation, use nodemailer here
-      // For now, we'll log the email content
-      console.log('Email notification would be sent:');
-      console.log('To:', this.config.to_addresses.join(', '));
-      console.log('Subject:', emailContent.subject);
-      console.log('Body:', emailContent.html.substring(0, 500) + '...');
-      
-      // Uncomment when nodemailer is configured:
-      // const transporter = nodemailer.createTransport({
-      //   host: this.config.smtp_host,
-      //   port: this.config.smtp_port,
-      //   secure: this.config.smtp_secure,
-      //   auth: this.config.smtp_user ? {
-      //     user: this.config.smtp_user,
-      //     pass: this.config.smtp_pass
-      //   } : undefined
-      // });
-      //
-      // await transporter.sendMail({
-      //   from: this.config.from_address,
-      //   to: this.config.to_addresses.join(', '),
-      //   subject: emailContent.subject,
-      //   html: emailContent.html,
-      //   text: emailContent.text
-      // });
-
-      return true;
-    } catch (error) {
-      console.error('Failed to send email notification:', error);
-      return false;
+  async send(_payload: NotificationPayload): Promise<boolean> {
+    if (!this.warned) {
+      console.error(
+        '[mund] EmailNotifier.send() called but email delivery is not ' +
+          'implemented. Alert dropped. (This warning fires once per process.)',
+      );
+      this.warned = true;
     }
-  }
-
-  private formatEmail(payload: NotificationPayload): { subject: string; html: string; text: string } {
-    const { event } = payload;
-    const severityEmoji = this.getSeverityEmoji(event.severity);
-    const severityColor = this.getSeverityColor(event.severity);
-
-    const subject = `${severityEmoji} [Mund ${event.severity.toUpperCase()}] ${event.rule_name}`;
-
-    const html = `
-<!DOCTYPE html>
-<html>
-<head>
-  <style>
-    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.6; color: #333; }
-    .container { max-width: 600px; margin: 0 auto; padding: 20px; }
-    .header { background: ${severityColor}; color: white; padding: 20px; border-radius: 8px 8px 0 0; }
-    .content { background: #f8f9fa; padding: 20px; border: 1px solid #dee2e6; border-top: none; border-radius: 0 0 8px 8px; }
-    .snippet { background: #1e1e1e; color: #d4d4d4; padding: 15px; border-radius: 4px; font-family: monospace; overflow-x: auto; }
-    .details { margin-top: 20px; }
-    .detail-row { display: flex; border-bottom: 1px solid #dee2e6; padding: 8px 0; }
-    .detail-label { font-weight: bold; width: 120px; flex-shrink: 0; }
-    .detail-value { color: #495057; }
-    .footer { margin-top: 20px; padding-top: 20px; border-top: 1px solid #dee2e6; font-size: 12px; color: #6c757d; }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <div class="header">
-      <h1 style="margin: 0;">${severityEmoji} Mund Security Alert</h1>
-      <p style="margin: 10px 0 0 0; opacity: 0.9;">${event.rule_name}</p>
-    </div>
-    <div class="content">
-      <h3>Detected Content</h3>
-      <div class="snippet">${this.escapeHtml(event.content_snippet)}</div>
-      
-      <div class="details">
-        <h3>Event Details</h3>
-        <div class="detail-row">
-          <span class="detail-label">Severity:</span>
-          <span class="detail-value">${event.severity.toUpperCase()}</span>
-        </div>
-        <div class="detail-row">
-          <span class="detail-label">Type:</span>
-          <span class="detail-value">${event.type}</span>
-        </div>
-        <div class="detail-row">
-          <span class="detail-label">Action:</span>
-          <span class="detail-value">${event.action_taken}</span>
-        </div>
-        <div class="detail-row">
-          <span class="detail-label">Rule ID:</span>
-          <span class="detail-value">${event.rule_id}</span>
-        </div>
-        <div class="detail-row">
-          <span class="detail-label">Event ID:</span>
-          <span class="detail-value">${event.id}</span>
-        </div>
-        <div class="detail-row">
-          <span class="detail-label">Timestamp:</span>
-          <span class="detail-value">${event.timestamp.toISOString()}</span>
-        </div>
-        ${event.context.tool_name ? `
-        <div class="detail-row">
-          <span class="detail-label">Tool:</span>
-          <span class="detail-value">${event.context.tool_name}</span>
-        </div>
-        ` : ''}
-        ${event.context.agent_id ? `
-        <div class="detail-row">
-          <span class="detail-label">Agent:</span>
-          <span class="detail-value">${event.context.agent_id}</span>
-        </div>
-        ` : ''}
-      </div>
-      
-      <div class="footer">
-        This alert was generated by Mund - The Guardian Protocol.<br>
-        Review and acknowledge this alert in your security dashboard.
-      </div>
-    </div>
-  </div>
-</body>
-</html>`;
-
-    const text = `
-MUND SECURITY ALERT
-====================
-
-${event.severity.toUpperCase()}: ${event.rule_name}
-
-Detected Content:
-${event.content_snippet}
-
-Event Details:
-- Severity: ${event.severity.toUpperCase()}
-- Type: ${event.type}
-- Action: ${event.action_taken}
-- Rule ID: ${event.rule_id}
-- Event ID: ${event.id}
-- Timestamp: ${event.timestamp.toISOString()}
-${event.context.tool_name ? `- Tool: ${event.context.tool_name}` : ''}
-${event.context.agent_id ? `- Agent: ${event.context.agent_id}` : ''}
-
----
-This alert was generated by Mund - The Guardian Protocol.
-`;
-
-    return { subject, html, text };
-  }
-
-  private escapeHtml(text: string): string {
-    return text
-      .replace(/&/g, '&amp;')
-      .replace(/</g, '&lt;')
-      .replace(/>/g, '&gt;')
-      .replace(/"/g, '&quot;')
-      .replace(/'/g, '&#039;');
-  }
-
-  private getSeverityColor(severity: Severity): string {
-    const colors: Record<Severity, string> = {
-      critical: '#dc3545',
-      high: '#fd7e14',
-      medium: '#ffc107',
-      low: '#17a2b8',
-      info: '#6c757d'
-    };
-    return colors[severity] || colors.info;
-  }
-
-  private getSeverityEmoji(severity: Severity): string {
-    const emojis: Record<Severity, string> = {
-      critical: '🚨',
-      high: '⚠️',
-      medium: '⚡',
-      low: 'ℹ️',
-      info: '📝'
-    };
-    return emojis[severity] || '📝';
-  }
-
-  private meetsMinSeverity(eventSeverity: Severity, minSeverity: Severity): boolean {
-    const order: Severity[] = ['critical', 'high', 'medium', 'low', 'info'];
-    const eventIndex = order.indexOf(eventSeverity);
-    const minIndex = order.indexOf(minSeverity);
-    return eventIndex <= minIndex;
+    return false;
   }
 }