agentshield-sdk 7.0.0

package/src/multi-agent.js

@@ -0,0 +1,404 @@
+'use strict';
+
+/**
+ * Multi-Agent Protection: Agent-to-Agent Firewall (#39),
+ * Delegation Chain Tracking (#40), Consensus Verification (#41),
+ * and Shared Threat State (#42)
+ */
+
+const { scanText } = require('./detector-core');
+
+// =========================================================================
+// AGENT-TO-AGENT FIREWALL
+// =========================================================================
+
+class AgentFirewall {
+  /**
+   * Scans all inter-agent messages. Enforces trust boundaries.
+   *
+   * @param {object} [options]
+   * @param {object} [options.trustPolicy={}] - Trust levels between agents.
+   * @param {string} [options.defaultTrust='scan'] - Default trust: 'trust', 'scan', or 'block'.
+   * @param {Function} [options.onViolation] - Callback on firewall violation.
+   */
+  constructor(options = {}) {
+    this.trustPolicy = options.trustPolicy || {};
+    this.defaultTrust = options.defaultTrust || 'scan';
+    this.onViolation = options.onViolation || null;
+    this.messageLog = [];
+  }
+
+  /**
+   * Sets trust level between two agents.
+   *
+   * @param {string} fromAgent - Sending agent ID.
+   * @param {string} toAgent - Receiving agent ID.
+   * @param {string} level - Trust level: 'trust', 'scan', or 'block'.
+   * @returns {AgentFirewall} this
+   */
+  setTrust(fromAgent, toAgent, level) {
+    const key = `${fromAgent}->${toAgent}`;
+    this.trustPolicy[key] = level;
+    return this;
+  }
+
+  /**
+   * Checks an inter-agent message through the firewall.
+   *
+   * @param {string} fromAgent - Sending agent ID.
+   * @param {string} toAgent - Receiving agent ID.
+   * @param {string} message - The message content.
+   * @returns {object} { allowed: boolean, scanned: boolean, threats: Array, reason?: string }
+   */
+  check(fromAgent, toAgent, message) {
+    const key = `${fromAgent}->${toAgent}`;
+    const trustLevel = this.trustPolicy[key] || this.defaultTrust;
+
+    const logEntry = {
+      from: fromAgent,
+      to: toAgent,
+      trustLevel,
+      timestamp: Date.now(),
+      messagePreview: message.substring(0, 100)
+    };
+
+    // Block immediately
+    if (trustLevel === 'block') {
+      logEntry.result = 'blocked';
+      this.messageLog.push(logEntry);
+      if (this.messageLog.length > 500) this.messageLog.shift();
+
+      const result = {
+        allowed: false,
+        scanned: false,
+        threats: [],
+        reason: `Messages from "${fromAgent}" to "${toAgent}" are blocked by firewall policy.`
+      };
+      if (this.onViolation) { try { this.onViolation(result); } catch (e) { console.error('[Agent Shield] onViolation callback error:', e.message); } }
+      return result;
+    }
+
+    // Trust — pass through without scanning
+    if (trustLevel === 'trust') {
+      logEntry.result = 'trusted';
+      this.messageLog.push(logEntry);
+      if (this.messageLog.length > 500) this.messageLog.shift();
+
+      return { allowed: true, scanned: false, threats: [] };
+    }
+
+    // Scan — check for threats
+    const scanResult = scanText(message, {
+      source: `agent_message:${fromAgent}->${toAgent}`,
+      sensitivity: 'high'
+    });
+
+    const allowed = scanResult.threats.length === 0;
+    logEntry.result = allowed ? 'passed' : 'blocked';
+    logEntry.threatCount = scanResult.threats.length;
+    this.messageLog.push(logEntry);
+    if (this.messageLog.length > 500) this.messageLog.shift();
+
+    if (!allowed && this.onViolation) {
+      try {
+        this.onViolation({
+          allowed: false,
+          from: fromAgent,
+          to: toAgent,
+          threats: scanResult.threats,
+          reason: `Inter-agent message from "${fromAgent}" contains threats.`
+        });
+      } catch (e) { console.error('[Agent Shield] onViolation callback error:', e.message); }
+    }
+
+    return {
+      allowed,
+      scanned: true,
+      threats: scanResult.threats,
+      reason: allowed ? undefined : `Message from "${fromAgent}" blocked: ${scanResult.threats.length} threat(s) detected.`
+    };
+  }
+
+  getLog() {
+    return [...this.messageLog];
+  }
+
+  reset() {
+    this.messageLog = [];
+  }
+}
+
+// =========================================================================
+// DELEGATION CHAIN TRACKER
+// =========================================================================
+
+class DelegationChain {
+  /**
+   * Tracks the full chain of who requested what when agents delegate tasks.
+   *
+   * @param {object} [options]
+   * @param {number} [options.maxDepth=10] - Maximum delegation depth.
+   * @param {Function} [options.onMaxDepth] - Callback when max depth reached.
+   */
+  constructor(options = {}) {
+    this.maxDepth = options.maxDepth || 10;
+    this.onMaxDepth = options.onMaxDepth || null;
+    this.chains = new Map(); // requestId -> chain
+    this.activeChains = new Map(); // agentId -> requestId
+    this.maxChains = options.maxChains || 1000;
+  }
+
+  /**
+   * Starts a new delegation chain.
+   *
+   * @param {string} requestId - Unique request ID.
+   * @param {string} originAgent - The agent that received the original request.
+   * @param {string} [originalInput] - The original user input.
+   * @returns {object} Chain entry.
+   */
+  start(requestId, originAgent, originalInput) {
+    const chain = {
+      requestId,
+      originAgent,
+      originalInput: originalInput ? originalInput.substring(0, 500) : null,
+      steps: [{
+        agent: originAgent,
+        action: 'received_request',
+        timestamp: Date.now(),
+        depth: 0
+      }],
+      status: 'active',
+      createdAt: Date.now()
+    };
+
+    // Prune completed chains if over limit
+    if (this.chains.size >= this.maxChains) {
+      for (const [id, c] of this.chains) {
+        if (c.status === 'completed') { this.chains.delete(id); }
+        if (this.chains.size < this.maxChains) break;
+      }
+    }
+
+    this.chains.set(requestId, chain);
+    this.activeChains.set(originAgent, requestId);
+    return chain;
+  }
+
+  /**
+   * Records a delegation from one agent to another.
+   *
+   * @param {string} requestId - The request chain ID.
+   * @param {string} fromAgent - Delegating agent.
+   * @param {string} toAgent - Receiving agent.
+   * @param {string} action - What was delegated (e.g., 'call_tool:bash').
+   * @param {string} [permissions] - What permissions the delegatee has.
+   * @returns {object} { allowed: boolean, depth: number, chain: object }
+   */
+  delegate(requestId, fromAgent, toAgent, action, permissions) {
+    const chain = this.chains.get(requestId);
+    if (!chain) {
+      return { allowed: false, depth: 0, chain: null, reason: 'Unknown request chain.' };
+    }
+
+    const depth = chain.steps.length;
+
+    if (depth >= this.maxDepth) {
+      if (this.onMaxDepth) {
+        try { this.onMaxDepth({ requestId, depth, fromAgent, toAgent }); } catch (e) { console.error('[Agent Shield] onMaxDepth callback error:', e.message); }
+      }
+      return {
+        allowed: false,
+        depth,
+        chain,
+        reason: `Maximum delegation depth (${this.maxDepth}) reached. Possible delegation loop.`
+      };
+    }
+
+    // Check for circular delegation
+    const visited = new Set(chain.steps.map(s => s.agent));
+    if (visited.has(toAgent)) {
+      return {
+        allowed: false,
+        depth,
+        chain,
+        reason: `Circular delegation detected: "${toAgent}" is already in the delegation chain.`
+      };
+    }
+
+    chain.steps.push({
+      agent: fromAgent,
+      delegatedTo: toAgent,
+      action,
+      permissions: permissions || 'inherited',
+      timestamp: Date.now(),
+      depth
+    });
+
+    this.activeChains.set(toAgent, requestId);
+
+    return { allowed: true, depth, chain };
+  }
+
+  /**
+   * Completes a delegation chain.
+   * @param {string} requestId
+   */
+  complete(requestId) {
+    const chain = this.chains.get(requestId);
+    if (chain) {
+      chain.status = 'completed';
+      chain.completedAt = Date.now();
+    }
+  }
+
+  /**
+   * Gets the full chain for a request.
+   * @param {string} requestId
+   * @returns {object|null}
+   */
+  getChain(requestId) {
+    return this.chains.get(requestId) || null;
+  }
+
+  /**
+   * Gets the active chain for an agent.
+   * @param {string} agentId
+   * @returns {object|null}
+   */
+  getActiveChain(agentId) {
+    const requestId = this.activeChains.get(agentId);
+    return requestId ? this.chains.get(requestId) : null;
+  }
+
+  /**
+   * Returns all chains.
+   * @returns {Array}
+   */
+  getAllChains() {
+    return Array.from(this.chains.values());
+  }
+
+  reset() {
+    this.chains.clear();
+    this.activeChains.clear();
+  }
+}
+
+// =========================================================================
+// SHARED THREAT STATE
+// =========================================================================
+
+class SharedThreatState {
+  /**
+   * When one agent detects an attack, broadcast the signature to all others.
+   *
+   * @param {object} [options]
+   * @param {number} [options.ttlMs=3600000] - How long threats stay active (default: 1 hour).
+   * @param {Function} [options.onBroadcast] - Callback when threat is broadcast.
+   */
+  constructor(options = {}) {
+    this.ttlMs = options.ttlMs || 3600000;
+    this.onBroadcast = options.onBroadcast || null;
+    this.threats = new Map(); // signature -> threat data
+    this.subscribers = new Map(); // agentId -> callback
+  }
+
+  /**
+   * Registers an agent to receive threat broadcasts.
+   *
+   * @param {string} agentId
+   * @param {Function} callback - Called with threat data when broadcast received.
+   */
+  subscribe(agentId, callback) {
+    this.subscribers.set(agentId, callback);
+  }
+
+  /**
+   * Unregisters an agent.
+   * @param {string} agentId
+   */
+  unsubscribe(agentId) {
+    this.subscribers.delete(agentId);
+  }
+
+  /**
+   * Broadcasts a threat to all subscribed agents.
+   *
+   * @param {string} reportingAgent - Agent that detected the threat.
+   * @param {object} threat - Threat data.
+   * @param {string} threat.signature - Unique signature (e.g., hash of the attack text).
+   * @param {string} threat.category - Threat category.
+   * @param {string} threat.severity - Threat severity.
+   * @param {string} [threat.description] - Description.
+   */
+  broadcast(reportingAgent, threat) {
+    const entry = {
+      ...threat,
+      reportedBy: reportingAgent,
+      reportedAt: Date.now(),
+      expiresAt: Date.now() + this.ttlMs
+    };
+
+    this.threats.set(threat.signature, entry);
+
+    // Notify all subscribers except the reporter
+    for (const [agentId, callback] of this.subscribers) {
+      if (agentId !== reportingAgent) {
+        try { callback(entry); } catch (e) { console.error(`[Agent Shield] subscriber ${agentId} callback error:`, e.message); }
+      }
+    }
+
+    if (this.onBroadcast) {
+      try { this.onBroadcast(entry); } catch (e) { console.error('[Agent Shield] onBroadcast callback error:', e.message); }
+    }
+  }
+
+  /**
+   * Checks if a threat signature is already known.
+   *
+   * @param {string} signature
+   * @returns {object|null} Known threat data, or null.
+   */
+  isKnown(signature) {
+    const entry = this.threats.get(signature);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.threats.delete(signature);
+      return null;
+    }
+    return entry;
+  }
+
+  /**
+   * Returns all active threats.
+   * @returns {Array}
+   */
+  getActiveThreats() {
+    const now = Date.now();
+    const active = [];
+    for (const [sig, entry] of this.threats) {
+      if (now <= entry.expiresAt) {
+        active.push(entry);
+      } else {
+        this.threats.delete(sig);
+      }
+    }
+    return active;
+  }
+
+  /**
+   * Generates a simple signature from text.
+   * @param {string} text
+   * @returns {string}
+   */
+  static generateSignature(text) {
+    const crypto = require('crypto');
+    return crypto.createHash('sha256').update(text.substring(0, 500)).digest('hex').substring(0, 16);
+  }
+
+  reset() {
+    this.threats.clear();
+  }
+}
+
+module.exports = { AgentFirewall, DelegationChain, SharedThreatState };

package/src/multimodal.js

@@ -0,0 +1,296 @@
+'use strict';
+
+/**
+ * Agent Shield — Multi-Modal Scanning (v3.0)
+ *
+ * Scans non-text modalities for injection attacks:
+ * - Image alt text and metadata
+ * - Audio/video transcripts
+ * - PDF extracted text
+ * - Structured tool outputs (JSON, XML)
+ * - Base64-encoded payloads in any field
+ *
+ * All processing runs locally — no data ever leaves your environment.
+ */
+
+const { scanText } = require('./detector-core');
+
+// =========================================================================
+// MODALITY EXTRACTORS
+// =========================================================================
+
+/**
+ * Extract scannable text from various data formats.
+ */
+class ModalityExtractor {
+  /**
+   * Extract text from an image-like object (metadata, alt text, EXIF).
+   * @param {object} imageData - { altText, title, caption, metadata, ocrText }
+   * @returns {Array<{text: string, source: string}>}
+   */
+  extractFromImage(imageData) {
+    const texts = [];
+
+    if (imageData.altText) texts.push({ text: imageData.altText, source: 'image:alt_text' });
+    if (imageData.title) texts.push({ text: imageData.title, source: 'image:title' });
+    if (imageData.caption) texts.push({ text: imageData.caption, source: 'image:caption' });
+    if (imageData.ocrText) texts.push({ text: imageData.ocrText, source: 'image:ocr' });
+
+    // Check EXIF/metadata fields for hidden payloads
+    if (imageData.metadata && typeof imageData.metadata === 'object') {
+      for (const [key, value] of Object.entries(imageData.metadata)) {
+        if (typeof value === 'string' && value.length > 10) {
+          texts.push({ text: value, source: `image:metadata:${key}` });
+        }
+      }
+    }
+
+    // Check for base64 encoded content in any field
+    if (imageData.base64) {
+      try {
+        const decoded = Buffer.from(imageData.base64.substring(0, 10000), 'base64').toString('utf-8');
+        const printable = decoded.split('').filter(c => c.charCodeAt(0) >= 32 && c.charCodeAt(0) <= 126).length;
+        if (printable / decoded.length > 0.7) {
+          texts.push({ text: decoded, source: 'image:base64_decoded' });
+        }
+      } catch (e) {
+        // Not valid base64
+      }
+    }
+
+    return texts;
+  }
+
+  /**
+   * Extract text from an audio/video transcript.
+   * @param {object} audioData - { transcript, segments, metadata, speakers }
+   * @returns {Array<{text: string, source: string}>}
+   */
+  extractFromAudio(audioData) {
+    const texts = [];
+
+    if (audioData.transcript) {
+      texts.push({ text: audioData.transcript, source: 'audio:transcript' });
+    }
+
+    if (audioData.segments && Array.isArray(audioData.segments)) {
+      for (let i = 0; i < audioData.segments.length; i++) {
+        const seg = audioData.segments[i];
+        if (seg.text && seg.text.length > 10) {
+          texts.push({ text: seg.text, source: `audio:segment:${i}` });
+        }
+      }
+    }
+
+    if (audioData.speakers && typeof audioData.speakers === 'object') {
+      for (const [speaker, content] of Object.entries(audioData.speakers)) {
+        if (typeof content === 'string' && content.length > 10) {
+          texts.push({ text: content, source: `audio:speaker:${speaker}` });
+        }
+      }
+    }
+
+    if (audioData.metadata && typeof audioData.metadata === 'object') {
+      for (const [key, value] of Object.entries(audioData.metadata)) {
+        if (typeof value === 'string' && value.length > 10) {
+          texts.push({ text: value, source: `audio:metadata:${key}` });
+        }
+      }
+    }
+
+    return texts;
+  }
+
+  /**
+   * Extract text from a PDF-like object.
+   * @param {object} pdfData - { text, pages, metadata, annotations }
+   * @returns {Array<{text: string, source: string}>}
+   */
+  extractFromPDF(pdfData) {
+    const texts = [];
+
+    if (pdfData.text) {
+      texts.push({ text: pdfData.text, source: 'pdf:full_text' });
+    }
+
+    if (pdfData.pages && Array.isArray(pdfData.pages)) {
+      for (let i = 0; i < pdfData.pages.length; i++) {
+        const page = pdfData.pages[i];
+        const pageText = typeof page === 'string' ? page : page.text;
+        if (pageText && pageText.length > 10) {
+          texts.push({ text: pageText, source: `pdf:page:${i + 1}` });
+        }
+      }
+    }
+
+    if (pdfData.annotations && Array.isArray(pdfData.annotations)) {
+      for (let i = 0; i < pdfData.annotations.length; i++) {
+        const ann = pdfData.annotations[i];
+        const annText = typeof ann === 'string' ? ann : ann.text || ann.content;
+        if (annText && annText.length > 10) {
+          texts.push({ text: annText, source: `pdf:annotation:${i}` });
+        }
+      }
+    }
+
+    if (pdfData.metadata && typeof pdfData.metadata === 'object') {
+      for (const [key, value] of Object.entries(pdfData.metadata)) {
+        if (typeof value === 'string' && value.length > 10) {
+          texts.push({ text: value, source: `pdf:metadata:${key}` });
+        }
+      }
+    }
+
+    return texts;
+  }
+
+  /**
+   * Extract text from a tool call response.
+   * @param {object} toolOutput - Any structured object from a tool call.
+   * @param {string} [toolName='unknown'] - Name of the tool.
+   * @returns {Array<{text: string, source: string}>}
+   */
+  extractFromToolOutput(toolOutput, toolName = 'unknown') {
+    const texts = [];
+    this._extractStrings(toolOutput, `tool:${toolName}`, texts, 0);
+    return texts;
+  }
+
+  /** @private */
+  _extractStrings(obj, prefix, results, depth) {
+    if (depth > 8) return;
+
+    if (typeof obj === 'string' && obj.length > 10) {
+      results.push({ text: obj, source: prefix });
+    } else if (Array.isArray(obj)) {
+      for (let i = 0; i < Math.min(obj.length, 100); i++) {
+        this._extractStrings(obj[i], `${prefix}[${i}]`, results, depth + 1);
+      }
+    } else if (obj && typeof obj === 'object') {
+      for (const [key, value] of Object.entries(obj)) {
+        this._extractStrings(value, `${prefix}.${key}`, results, depth + 1);
+      }
+    }
+  }
+}
+
+// =========================================================================
+// MULTI-MODAL SCANNER
+// =========================================================================
+
+/**
+ * Scans multi-modal inputs for injection attacks.
+ */
+class MultiModalScanner {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.sensitivity='high'] - Scan sensitivity.
+   * @param {Function} [options.onThreat] - Callback on threat detection.
+   */
+  constructor(options = {}) {
+    this.sensitivity = options.sensitivity || 'high';
+    this.onThreat = options.onThreat || null;
+
+    this._extractor = new ModalityExtractor();
+    this._stats = { scans: 0, threats: 0, modalities: {} };
+
+    console.log('[Agent Shield] MultiModalScanner initialized (sensitivity: %s)', this.sensitivity);
+  }
+
+  /**
+   * Scan an image for hidden injections.
+   * @param {object} imageData - Image data with text fields.
+   * @returns {object} { clean: boolean, threats: Array, modality: 'image' }
+   */
+  scanImage(imageData) {
+    return this._scanModality('image', this._extractor.extractFromImage(imageData));
+  }
+
+  /**
+   * Scan audio/video transcript for injections.
+   * @param {object} audioData - Audio data with transcript/segments.
+   * @returns {object}
+   */
+  scanAudio(audioData) {
+    return this._scanModality('audio', this._extractor.extractFromAudio(audioData));
+  }
+
+  /**
+   * Scan PDF content for injections.
+   * @param {object} pdfData - PDF data with text/pages.
+   * @returns {object}
+   */
+  scanPDF(pdfData) {
+    return this._scanModality('pdf', this._extractor.extractFromPDF(pdfData));
+  }
+
+  /**
+   * Scan a tool's output for injections.
+   * @param {object} toolOutput - Tool output data.
+   * @param {string} [toolName] - Tool name.
+   * @returns {object}
+   */
+  scanToolOutput(toolOutput, toolName) {
+    return this._scanModality('tool_output', this._extractor.extractFromToolOutput(toolOutput, toolName));
+  }
+
+  /**
+   * Scan any modality by providing extracted texts directly.
+   * @param {string} modality - Modality label.
+   * @param {Array<{text: string, source: string}>} texts - Extracted text items.
+   * @returns {object}
+   */
+  scanRaw(modality, texts) {
+    return this._scanModality(modality, texts);
+  }
+
+  /**
+   * Get scanning statistics.
+   * @returns {object}
+   */
+  getStats() {
+    return { ...this._stats };
+  }
+
+  /** @private */
+  _scanModality(modality, texts) {
+    this._stats.scans++;
+    this._stats.modalities[modality] = (this._stats.modalities[modality] || 0) + 1;
+
+    const allThreats = [];
+
+    for (const { text, source } of texts) {
+      const result = scanText(text, { source, sensitivity: this.sensitivity });
+      if (result.threats.length > 0) {
+        for (const threat of result.threats) {
+          allThreats.push({
+            ...threat,
+            modality,
+            source,
+            description: `[${modality.toUpperCase()}] ${threat.description}`
+          });
+        }
+      }
+    }
+
+    if (allThreats.length > 0) {
+      this._stats.threats += allThreats.length;
+      if (this.onThreat) {
+        this.onThreat({ modality, threats: allThreats });
+      }
+    }
+
+    return {
+      clean: allThreats.length === 0,
+      threats: allThreats,
+      modality,
+      textsScanned: texts.length
+    };
+  }
+}
+
+// =========================================================================
+// EXPORTS
+// =========================================================================
+
+module.exports = { MultiModalScanner, ModalityExtractor };