@weave_protocol/mund 0.1.0

package/src/index.ts

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/**
+ * Mund - The Guardian Protocol
+ * Main Entry Point
+ * 
+ * An MCP-based security monitoring protocol for agentic AI systems.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express from 'express';
+
+import type { MundConfig, DetectionRule } from './types.js';
+import { DEFAULT_CONFIG, DEFAULT_RULES } from './constants.js';
+import { createStorage } from './storage/index.js';
+import { AnalyzerEngine } from './analyzers/index.js';
+import { NotificationHub } from './notifications/index.js';
+import { registerAllTools } from './tools/index.js';
+
+// ============================================================================
+// Configuration Loading
+// ============================================================================
+
+function loadConfig(): MundConfig {
+  const config: MundConfig = {
+    ...DEFAULT_CONFIG,
+    
+    // Server settings from environment
+    port: parseInt(process.env.MUND_PORT || '3000'),
+    host: process.env.MUND_HOST || '127.0.0.1',
+    transport: (process.env.MUND_TRANSPORT as 'stdio' | 'http') || 'stdio',
+    
+    // Logging
+    log_level: (process.env.MUND_LOG_LEVEL as MundConfig['log_level']) || 'info',
+    
+    // Storage
+    storage_type: (process.env.MUND_STORAGE as MundConfig['storage_type']) || 'memory',
+    database_url: process.env.MUND_DATABASE_URL,
+    
+    // Security
+    block_mode: process.env.MUND_BLOCK_MODE === 'block',
+    api_key: process.env.MUND_API_KEY,
+    
+    // Notifications
+    notifications: {
+      slack: process.env.MUND_SLACK_WEBHOOK ? {
+        webhook_url: process.env.MUND_SLACK_WEBHOOK,
+        channel: process.env.MUND_SLACK_CHANNEL,
+        username: process.env.MUND_SLACK_USERNAME || 'Mund Guardian',
+        icon_emoji: process.env.MUND_SLACK_EMOJI || ':eye:',
+        min_severity: (process.env.MUND_SLACK_MIN_SEVERITY as any) || 'high'
+      } : undefined,
+      
+      teams: process.env.MUND_TEAMS_WEBHOOK ? {
+        webhook_url: process.env.MUND_TEAMS_WEBHOOK,
+        min_severity: (process.env.MUND_TEAMS_MIN_SEVERITY as any) || 'high'
+      } : undefined,
+      
+      email: process.env.MUND_EMAIL_SMTP_HOST ? {
+        smtp_host: process.env.MUND_EMAIL_SMTP_HOST,
+        smtp_port: parseInt(process.env.MUND_EMAIL_SMTP_PORT || '587'),
+        smtp_secure: process.env.MUND_EMAIL_SMTP_SECURE === 'true',
+        smtp_user: process.env.MUND_EMAIL_SMTP_USER,
+        smtp_pass: process.env.MUND_EMAIL_SMTP_PASS,
+        from_address: process.env.MUND_EMAIL_FROM || 'mund@localhost',
+        to_addresses: (process.env.MUND_EMAIL_TO || '').split(',').filter(Boolean),
+        min_severity: (process.env.MUND_EMAIL_MIN_SEVERITY as any) || 'high'
+      } : undefined,
+      
+      webhooks: process.env.MUND_WEBHOOK_URL ? [{
+        url: process.env.MUND_WEBHOOK_URL,
+        method: 'POST' as const,
+        headers: process.env.MUND_WEBHOOK_HEADERS ? JSON.parse(process.env.MUND_WEBHOOK_HEADERS) : undefined,
+        min_severity: (process.env.MUND_WEBHOOK_MIN_SEVERITY as 'critical' | 'high' | 'medium' | 'low' | 'info') || 'high'
+      }] : undefined
+    }
+  };
+
+  return config;
+}
+
+// ============================================================================
+// Server Initialization
+// ============================================================================
+
+async function createMundServer(config: MundConfig): Promise<McpServer> {
+  // Create MCP server
+  const server = new McpServer({
+    name: 'mund-mcp-server',
+    version: '0.1.0'
+  });
+
+  // Initialize storage
+  const storage = createStorage(config);
+
+  // Initialize analyzer engine
+  const analyzer = new AnalyzerEngine();
+
+  // Initialize notification hub
+  const notificationHub = new NotificationHub(config);
+
+  // Load rules (start with defaults, could be extended from file)
+  const rules: DetectionRule[] = [...DEFAULT_RULES];
+
+  // Load any saved custom rules from storage
+  const savedRules = await storage.getRules();
+  for (const rule of savedRules) {
+    if (!rules.find(r => r.id === rule.id)) {
+      rules.push(rule);
+    }
+  }
+
+  // Register all tools
+  registerAllTools(server, storage, rules, analyzer, notificationHub, config.block_mode);
+
+  // Log startup info
+  console.error(`Mund Guardian Protocol v0.1.0`);
+  console.error(`- Transport: ${config.transport}`);
+  console.error(`- Storage: ${config.storage_type}`);
+  console.error(`- Block Mode: ${config.block_mode ? 'enabled' : 'disabled'}`);
+  console.error(`- Rules Loaded: ${rules.filter(r => r.enabled).length}`);
+  console.error(`- Notifiers: ${notificationHub.getNotifierNames().join(', ') || 'none'}`);
+
+  return server;
+}
+
+// ============================================================================
+// Transport Handlers
+// ============================================================================
+
+async function runStdio(config: MundConfig): Promise<void> {
+  const server = await createMundServer(config);
+  const transport = new StdioServerTransport();
+  
+  await server.connect(transport);
+  console.error('Mund MCP server running on stdio');
+}
+
+async function runHTTP(config: MundConfig): Promise<void> {
+  const server = await createMundServer(config);
+  const app = express();
+  
+  app.use(express.json({ limit: '10mb' }));
+
+  // Health check endpoint
+  app.get('/health', (_req, res) => {
+    res.json({ status: 'ok', version: '0.1.0' });
+  });
+
+  // MCP endpoint
+  app.post('/mcp', async (req, res) => {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true
+    });
+
+    res.on('close', () => transport.close());
+
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  // Start server
+  app.listen(config.port, config.host, () => {
+    console.error(`Mund MCP server running on http://${config.host}:${config.port}/mcp`);
+  });
+}
+
+// ============================================================================
+// CLI and Main
+// ============================================================================
+
+function printHelp(): void {
+  console.log(`
+Mund - The Guardian Protocol
+MCP-based security monitoring for agentic AI systems
+
+Usage: mund-mcp [options]
+
+Options:
+  --help, -h          Show this help message
+  --version, -v       Show version number
+  --transport <type>  Transport type: stdio (default) or http
+  --port <port>       HTTP port (default: 3000)
+  --host <host>       HTTP host (default: 127.0.0.1)
+  --block             Enable block mode (block dangerous content)
+
+Environment Variables:
+  MUND_PORT                   HTTP server port
+  MUND_HOST                   HTTP server host
+  MUND_TRANSPORT              Transport type (stdio or http)
+  MUND_LOG_LEVEL              Log level (debug, info, warn, error)
+  MUND_STORAGE                Storage type (memory, sqlite, postgres)
+  MUND_DATABASE_URL           Database connection URL
+  MUND_BLOCK_MODE             Set to 'block' to enable blocking
+  MUND_API_KEY                API key for authentication
+  
+  MUND_SLACK_WEBHOOK          Slack webhook URL
+  MUND_SLACK_CHANNEL          Slack channel override
+  MUND_SLACK_MIN_SEVERITY     Minimum severity for Slack alerts
+  
+  MUND_TEAMS_WEBHOOK          Microsoft Teams webhook URL
+  MUND_TEAMS_MIN_SEVERITY     Minimum severity for Teams alerts
+  
+  MUND_EMAIL_SMTP_HOST        SMTP server host
+  MUND_EMAIL_SMTP_PORT        SMTP server port
+  MUND_EMAIL_FROM             From address for emails
+  MUND_EMAIL_TO               Comma-separated recipient addresses
+  
+  MUND_WEBHOOK_URL            Generic webhook URL
+  MUND_WEBHOOK_HEADERS        JSON string of webhook headers
+
+Examples:
+  # Run as stdio server (for MCP clients)
+  mund-mcp
+  
+  # Run as HTTP server
+  mund-mcp --transport http --port 3000
+  
+  # Run with Slack notifications
+  MUND_SLACK_WEBHOOK=https://hooks.slack.com/... mund-mcp
+  
+  # Run in block mode
+  mund-mcp --block
+
+For more information, visit: https://github.com/your-org/mund-mcp
+`);
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  // Parse CLI arguments
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (args.includes('--version') || args.includes('-v')) {
+    console.log('0.1.0');
+    process.exit(0);
+  }
+
+  // Load config
+  const config = loadConfig();
+
+  // Override from CLI
+  const transportIndex = args.indexOf('--transport');
+  if (transportIndex !== -1 && args[transportIndex + 1]) {
+    config.transport = args[transportIndex + 1] as 'stdio' | 'http';
+  }
+
+  const portIndex = args.indexOf('--port');
+  if (portIndex !== -1 && args[portIndex + 1]) {
+    config.port = parseInt(args[portIndex + 1]);
+  }
+
+  const hostIndex = args.indexOf('--host');
+  if (hostIndex !== -1 && args[hostIndex + 1]) {
+    config.host = args[hostIndex + 1];
+  }
+
+  if (args.includes('--block')) {
+    config.block_mode = true;
+  }
+
+  // Run appropriate transport
+  try {
+    if (config.transport === 'http') {
+      await runHTTP(config);
+    } else {
+      await runStdio(config);
+    }
+  } catch (error) {
+    console.error('Failed to start Mund server:', error);
+    process.exit(1);
+  }
+}
+
+// Run
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/src/notifications/email.ts

@@ -0,0 +1,211 @@
+/**
+ * Mund - The Guardian Protocol
+ * Email Notifier - Send alerts via email
+ */
+
+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
+
+export class EmailNotifier implements INotifier {
+  name = 'EmailNotifier';
+  private config: EmailConfig;
+
+  constructor(config: EmailConfig) {
+    this.config = config;
+  }
+
+  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;
+    }
+  }
+
+  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;
+  }
+}
+
+export default EmailNotifier;

package/src/notifications/index.ts

@@ -0,0 +1,136 @@
+/**
+ * Mund - The Guardian Protocol
+ * Notifications Index - Notification hub and exports
+ */
+
+export { SlackNotifier } from './slack.js';
+export { TeamsNotifier } from './teams.js';
+export { EmailNotifier } from './email.js';
+export { WebhookNotifier } from './webhook.js';
+
+import { SlackNotifier } from './slack.js';
+import { TeamsNotifier } from './teams.js';
+import { EmailNotifier } from './email.js';
+import { WebhookNotifier } from './webhook.js';
+import type { 
+  INotifier, 
+  NotificationConfig, 
+  NotificationPayload, 
+  SecurityEvent,
+  MundConfig 
+} from '../types.js';
+
+/**
+ * Notification Hub - Manages and dispatches notifications to all configured channels
+ */
+export class NotificationHub {
+  private notifiers: INotifier[] = [];
+  private config: MundConfig;
+
+  constructor(config: MundConfig) {
+    this.config = config;
+    this.initializeNotifiers(config.notifications);
+  }
+
+  private initializeNotifiers(notificationConfig: NotificationConfig): void {
+    // Slack
+    if (notificationConfig.slack?.webhook_url) {
+      this.notifiers.push(new SlackNotifier(notificationConfig.slack));
+    }
+
+    // Teams
+    if (notificationConfig.teams?.webhook_url) {
+      this.notifiers.push(new TeamsNotifier(notificationConfig.teams));
+    }
+
+    // Email
+    if (notificationConfig.email?.smtp_host) {
+      this.notifiers.push(new EmailNotifier(notificationConfig.email));
+    }
+
+    // Webhooks
+    if (notificationConfig.webhooks) {
+      for (const webhookConfig of notificationConfig.webhooks) {
+        this.notifiers.push(new WebhookNotifier(webhookConfig));
+      }
+    }
+  }
+
+  /**
+   * Send notification to all configured channels
+   */
+  async notify(event: SecurityEvent): Promise<{ success: boolean; results: NotificationResult[] }> {
+    if (this.notifiers.length === 0) {
+      return { success: true, results: [] };
+    }
+
+    const payload: NotificationPayload = {
+      event,
+      config: this.config,
+      formatted_message: this.formatMessage(event)
+    };
+
+    const results: NotificationResult[] = [];
+
+    for (const notifier of this.notifiers) {
+      try {
+        const success = await notifier.send(payload);
+        results.push({
+          notifier: notifier.name,
+          success,
+          error: success ? undefined : 'Failed to send notification'
+        });
+      } catch (error) {
+        results.push({
+          notifier: notifier.name,
+          success: false,
+          error: error instanceof Error ? error.message : 'Unknown error'
+        });
+      }
+    }
+
+    const allSuccessful = results.every(r => r.success);
+    return { success: allSuccessful, results };
+  }
+
+  /**
+   * Format a human-readable message
+   */
+  private formatMessage(event: SecurityEvent): string {
+    return `[${event.severity.toUpperCase()}] ${event.rule_name}: ${event.content_snippet}`;
+  }
+
+  /**
+   * Add a notifier at runtime
+   */
+  addNotifier(notifier: INotifier): void {
+    this.notifiers.push(notifier);
+  }
+
+  /**
+   * Remove a notifier by name
+   */
+  removeNotifier(name: string): void {
+    this.notifiers = this.notifiers.filter(n => n.name !== name);
+  }
+
+  /**
+   * Get list of configured notifiers
+   */
+  getNotifierNames(): string[] {
+    return this.notifiers.map(n => n.name);
+  }
+
+  /**
+   * Check if any notifiers are configured
+   */
+  hasNotifiers(): boolean {
+    return this.notifiers.length > 0;
+  }
+}
+
+interface NotificationResult {
+  notifier: string;
+  success: boolean;
+  error?: string;
+}