agentshield-sdk 10.0.0 → 12.0.0

package/src/incident-response.js

@@ -0,0 +1,265 @@
+'use strict';
+
+/**
+ * Agent Shield — Automated Incident Response (v12)
+ *
+ * When an attack is detected, don't just alert — automatically:
+ * isolate the compromised agent, preserve forensic evidence,
+ * notify the SOC, generate an incident report, and suggest remediation.
+ *
+ * Closes the loop from detection to response.
+ *
+ * All processing runs locally — no data ever leaves your environment.
+ *
+ * @module incident-response
+ */
+
+const crypto = require('crypto');
+
+// =========================================================================
+// RESPONSE STRATEGIES
+// =========================================================================
+
+const RESPONSE_STRATEGIES = {
+  /** Block the action and continue monitoring. */
+  block: { name: 'block', description: 'Block the malicious action. Agent continues operating.' },
+  /** Isolate the agent — kill its active sessions. */
+  isolate: { name: 'isolate', description: 'Isolate the compromised agent. Terminate all sessions.' },
+  /** Alert only — log the incident but take no action. */
+  alert: { name: 'alert', description: 'Alert security team. No automated action.' },
+  /** Quarantine — block and preserve state for forensics. */
+  quarantine: { name: 'quarantine', description: 'Quarantine agent and preserve full state for investigation.' },
+  /** Rollback — revert to last known-good state. */
+  rollback: { name: 'rollback', description: 'Revert agent to last known-good configuration.' }
+};
+
+const SEVERITY_TO_STRATEGY = {
+  critical: 'quarantine',
+  high: 'block',
+  medium: 'alert',
+  low: 'alert'
+};
+
+// =========================================================================
+// IncidentResponse
+// =========================================================================
+
+/**
+ * Automated incident response engine for AI agent security events.
+ */
+class IncidentResponse {
+  /**
+   * @param {object} [options]
+   * @param {object} [options.strategyOverrides] - Override default severity→strategy mapping.
+   * @param {Function} [options.onIncident] - Callback when incident is created.
+   * @param {Function} [options.onAction] - Callback when response action is taken.
+   * @param {boolean} [options.autoRespond=true] - Automatically execute response strategy.
+   */
+  constructor(options = {}) {
+    this.strategies = { ...SEVERITY_TO_STRATEGY, ...(options.strategyOverrides || {}) };
+    this.onIncident = options.onIncident || null;
+    this.onAction = options.onAction || null;
+    this.autoRespond = options.autoRespond !== false;
+
+    /** @type {Array<object>} */
+    this.incidents = [];
+    /** @type {Array<object>} */
+    this.actions = [];
+    this.stats = { incidentsCreated: 0, actionsExecuted: 0, agentsIsolated: 0, actionsBlocked: 0 };
+  }
+
+  /**
+   * Handle a security event — create incident, determine strategy, execute response.
+   *
+   * @param {object} event
+   * @param {string} event.type - Threat type (e.g., 'prompt_injection', 'ssrf', 'tool_poisoning').
+   * @param {string} event.severity - 'critical', 'high', 'medium', 'low'.
+   * @param {string} [event.agentId] - Affected agent ID.
+   * @param {string} [event.serverId] - Affected MCP server ID.
+   * @param {string} [event.description] - Human-readable description.
+   * @param {*} [event.evidence] - Raw evidence (tool call, input text, etc.).
+   * @returns {object} Incident record with response actions.
+   */
+  handleEvent(event) {
+    const incidentId = crypto.randomBytes(8).toString('hex');
+    const strategy = this.strategies[event.severity] || 'alert';
+    const strategyInfo = RESPONSE_STRATEGIES[strategy] || RESPONSE_STRATEGIES.alert;
+
+    const incident = {
+      incidentId,
+      timestamp: Date.now(),
+      type: event.type,
+      severity: event.severity,
+      agentId: event.agentId || 'unknown',
+      serverId: event.serverId || null,
+      description: event.description || `${event.type} detected (${event.severity})`,
+      evidence: event.evidence ? JSON.stringify(event.evidence).substring(0, 2000) : null,
+      strategy: strategyInfo.name,
+      strategyDescription: strategyInfo.description,
+      status: 'open',
+      actions: [],
+      forensics: null
+    };
+
+    // Preserve forensic evidence
+    incident.forensics = {
+      capturedAt: Date.now(),
+      eventSnapshot: { ...event, evidence: incident.evidence },
+      contextHash: crypto.createHash('sha256').update(JSON.stringify(event)).digest('hex')
+    };
+
+    this.incidents.push(incident);
+    this.stats.incidentsCreated++;
+
+    // Bound incidents
+    if (this.incidents.length > 1000) this.incidents = this.incidents.slice(-1000);
+
+    // Notify
+    if (this.onIncident) {
+      try { this.onIncident(incident); } catch { /* ignore */ }
+    }
+
+    // Auto-respond
+    if (this.autoRespond) {
+      this._executeStrategy(incident);
+    }
+
+    return incident;
+  }
+
+  /**
+   * Get all open incidents.
+   * @returns {Array<object>}
+   */
+  getOpenIncidents() {
+    return this.incidents.filter(i => i.status === 'open');
+  }
+
+  /**
+   * Close an incident.
+   * @param {string} incidentId
+   * @param {string} [resolution] - How it was resolved.
+   * @returns {boolean}
+   */
+  closeIncident(incidentId, resolution) {
+    const incident = this.incidents.find(i => i.incidentId === incidentId);
+    if (!incident) return false;
+    incident.status = 'closed';
+    incident.closedAt = Date.now();
+    incident.resolution = resolution || 'Manually closed.';
+    return true;
+  }
+
+  /**
+   * Generate an incident report.
+   * @param {string} [incidentId] - Specific incident, or null for summary.
+   * @returns {object}
+   */
+  generateReport(incidentId) {
+    if (incidentId) {
+      const incident = this.incidents.find(i => i.incidentId === incidentId);
+      if (!incident) return null;
+      return {
+        title: `Incident Report: ${incident.incidentId}`,
+        incident,
+        timeline: incident.actions,
+        forensics: incident.forensics,
+        recommendation: this._getRemediation(incident)
+      };
+    }
+
+    // Summary report
+    const open = this.incidents.filter(i => i.status === 'open');
+    const closed = this.incidents.filter(i => i.status === 'closed');
+    const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const i of this.incidents) bySeverity[i.severity] = (bySeverity[i.severity] || 0) + 1;
+
+    return {
+      title: 'Incident Summary Report',
+      totalIncidents: this.incidents.length,
+      open: open.length,
+      closed: closed.length,
+      bySeverity,
+      recentIncidents: this.incidents.slice(-10),
+      stats: { ...this.stats },
+      generatedAt: Date.now()
+    };
+  }
+
+  /**
+   * Get stats.
+   * @returns {object}
+   */
+  getStats() {
+    return { ...this.stats, totalIncidents: this.incidents.length, openIncidents: this.incidents.filter(i => i.status === 'open').length };
+  }
+
+  // -----------------------------------------------------------------------
+  // Private
+  // -----------------------------------------------------------------------
+
+  /** @private */
+  _executeStrategy(incident) {
+    const actions = [];
+
+    switch (incident.strategy) {
+      case 'quarantine':
+        actions.push({ action: 'isolate_agent', target: incident.agentId, timestamp: Date.now() });
+        actions.push({ action: 'preserve_forensics', evidenceHash: incident.forensics.contextHash, timestamp: Date.now() });
+        actions.push({ action: 'notify_soc', severity: incident.severity, timestamp: Date.now() });
+        this.stats.agentsIsolated++;
+        this.stats.actionsBlocked++;
+        break;
+      case 'block':
+        actions.push({ action: 'block_action', target: incident.agentId, timestamp: Date.now() });
+        actions.push({ action: 'notify_soc', severity: incident.severity, timestamp: Date.now() });
+        this.stats.actionsBlocked++;
+        break;
+      case 'isolate':
+        actions.push({ action: 'isolate_agent', target: incident.agentId, timestamp: Date.now() });
+        this.stats.agentsIsolated++;
+        break;
+      case 'alert':
+        actions.push({ action: 'log_alert', severity: incident.severity, timestamp: Date.now() });
+        break;
+      case 'rollback':
+        actions.push({ action: 'rollback_config', target: incident.agentId, timestamp: Date.now() });
+        break;
+    }
+
+    incident.actions = actions;
+    this.stats.actionsExecuted += actions.length;
+
+    for (const action of actions) {
+      this.actions.push({ ...action, incidentId: incident.incidentId });
+      if (this.onAction) {
+        try { this.onAction(action, incident); } catch { /* ignore */ }
+      }
+    }
+  }
+
+  /** @private */
+  _getRemediation(incident) {
+    const remediations = {
+      prompt_injection: 'Review and harden system prompt. Add input validation. Enable semantic isolation.',
+      ssrf: 'Block private IP ranges. Validate all URLs against allowlist. Apply CVE-2026-26118 patches.',
+      tool_poisoning: 'Re-attest tool definitions. Pin tool versions. Enable full-schema scanning.',
+      data_exfiltration: 'Enable DLP scanning on outbound calls. Review tool permissions. Add URL allowlists.',
+      config_poisoning: 'Audit .claude/ and .cursor/ config files. Block ANTHROPIC_BASE_URL overrides.',
+      role_hijack: 'Strengthen system prompt. Enable prompt hardening. Add role boundary monitoring.',
+      memory_poisoning: 'Clear agent memory. Enable memory write validation. Add persistence monitoring.',
+      cross_agent_injection: 'Enable cross-server isolation. Add message signing between agents.',
+    };
+    return remediations[incident.type] || 'Review security configuration and enable additional detection layers.';
+  }
+}
+
+// =========================================================================
+// EXPORTS
+// =========================================================================
+
+module.exports = {
+  IncidentResponse,
+  RESPONSE_STRATEGIES,
+  SEVERITY_TO_STRATEGY
+};

package/src/intent-binding.js

@@ -0,0 +1,314 @@
+'use strict';
+
+/**
+ * Agent Shield — Cryptographic Intent Binding (L5)
+ *
+ * When a user makes a request, the intent is hashed. Every subsequent
+ * agent action must include a cryptographic proof that it derives from
+ * that intent. If an injected instruction causes an action that can't
+ * be linked back to the original intent, it's blocked at the crypto
+ * level — not the pattern level. Unbypassable by any prompt technique.
+ *
+ * All processing runs locally — no data ever leaves your environment.
+ *
+ * @module intent-binding
+ */
+
+const crypto = require('crypto');
+
+// =========================================================================
+// IntentToken
+// =========================================================================
+
+/**
+ * Cryptographic token binding an action to a user intent.
+ */
+class IntentToken {
+  /**
+   * @param {string} intentHash - SHA-256 hash of the original user intent.
+   * @param {string} action - The action being authorized.
+   * @param {string} scope - Scope of the authorization.
+   * @param {string} signature - HMAC signature binding action to intent.
+   * @param {number} expiresAt - Expiration timestamp in ms.
+   */
+  constructor(intentHash, action, scope, signature, expiresAt) {
+    this.intentHash = intentHash;
+    this.action = action;
+    this.scope = scope;
+    this.signature = signature;
+    this.createdAt = Date.now();
+    this.expiresAt = expiresAt;
+    this.used = false;
+  }
+
+  /**
+   * Check if this token has expired.
+   * @returns {boolean}
+   */
+  isExpired() {
+    return Date.now() > this.expiresAt;
+  }
+}
+
+// =========================================================================
+// IntentBinder
+// =========================================================================
+
+/**
+ * Cryptographic intent binding engine. Creates tamper-proof links between
+ * user intents and agent actions.
+ */
+class IntentBinder {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.signingKey] - HMAC signing key (auto-generated if not provided).
+   * @param {number} [options.tokenTtlMs=300000] - Token TTL in ms (default: 5 minutes).
+   * @param {number} [options.maxActionsPerIntent=50] - Max actions per intent.
+   * @param {boolean} [options.singleUseTokens=false] - Whether tokens can only be used once.
+   */
+  constructor(options = {}) {
+    this.signingKey = options.signingKey || crypto.randomBytes(32).toString('hex');
+    this.tokenTtlMs = options.tokenTtlMs || 300000;
+    this.maxActions = options.maxActionsPerIntent || 50;
+    this.singleUse = options.singleUseTokens || false;
+
+    /** @type {Map<string, { intent: string, hash: string, actions: string[], createdAt: number }>} */
+    this.activeIntents = new Map();
+
+    /** @type {Array<object>} */
+    this.auditLog = [];
+    this.stats = { intentsBound: 0, tokensIssued: 0, verified: 0, rejected: 0 };
+  }
+
+  /**
+   * Bind a user intent. Returns an intent hash that must be included
+   * with every subsequent action.
+   *
+   * @param {string} intentText - The user's original request.
+   * @param {object} [metadata] - Additional context (userId, sessionId, etc.).
+   * @returns {{ intentHash: string, allowedActions: string[] }}
+   */
+  bindIntent(intentText, metadata = {}) {
+    const intentHash = this._hash(intentText);
+    const allowedActions = this._deriveAllowedActions(intentText);
+
+    this.activeIntents.set(intentHash, {
+      intent: intentText,
+      hash: intentHash,
+      actions: allowedActions,
+      metadata,
+      createdAt: Date.now(),
+      actionCount: 0
+    });
+
+    this.stats.intentsBound++;
+    this._log('intent_bound', { intentHash, allowedActions, metadata });
+
+    // Auto-purge if map grows too large
+    if (this.activeIntents.size > 10000) {
+      this.purgeExpired();
+    }
+
+    return { intentHash, allowedActions };
+  }
+
+  /**
+   * Issue a cryptographic token authorizing a specific action
+   * linked to an intent.
+   *
+   * @param {string} intentHash - The intent hash from bindIntent().
+   * @param {string} action - The action to authorize (e.g., 'tool:readFile').
+   * @param {string} [scope] - Optional scope restriction.
+   * @returns {{ token: IntentToken|null, error: string|null }}
+   */
+  issueToken(intentHash, action, scope) {
+    const intent = this.activeIntents.get(intentHash);
+    if (!intent) {
+      this.stats.rejected++;
+      return { token: null, error: 'Intent not found or expired.' };
+    }
+
+    // Check action limit
+    if (intent.actionCount >= this.maxActions) {
+      this.stats.rejected++;
+      return { token: null, error: `Action limit (${this.maxActions}) exceeded for this intent.` };
+    }
+
+    // Verify the action is derivable from the intent
+    if (!this._isActionAllowed(intent, action)) {
+      this.stats.rejected++;
+      this._log('token_rejected', { intentHash, action, reason: 'Action not derivable from intent.' });
+      return { token: null, error: `Action "${action}" is not derivable from the bound intent.` };
+    }
+
+    // Create signed token
+    const scopeStr = scope || 'default';
+    const payload = `${intentHash}:${action}:${scopeStr}`;
+    const signature = this._sign(payload);
+    const expiresAt = Date.now() + this.tokenTtlMs;
+
+    const token = new IntentToken(intentHash, action, scopeStr, signature, expiresAt);
+    intent.actionCount++;
+    this.stats.tokensIssued++;
+    this._log('token_issued', { intentHash, action, scope: scopeStr });
+
+    return { token, error: null };
+  }
+
+  /**
+   * Verify that a token is valid and the action is still bound to the intent.
+   *
+   * @param {IntentToken} token - The token to verify.
+   * @returns {{ valid: boolean, reason: string|null }}
+   */
+  verify(token) {
+    if (!token) {
+      this.stats.rejected++;
+      return { valid: false, reason: 'No token provided.' };
+    }
+
+    if (token.isExpired()) {
+      this.stats.rejected++;
+      return { valid: false, reason: 'Token has expired.' };
+    }
+
+    if (this.singleUse && token.used) {
+      this.stats.rejected++;
+      return { valid: false, reason: 'Token has already been used (single-use mode).' };
+    }
+
+    // Verify HMAC signature
+    const payload = `${token.intentHash}:${token.action}:${token.scope}`;
+    const expectedSig = this._sign(payload);
+    if (token.signature !== expectedSig) {
+      this.stats.rejected++;
+      this._log('token_tampered', { intentHash: token.intentHash, action: token.action });
+      return { valid: false, reason: 'Token signature is invalid. Possible tampering.' };
+    }
+
+    // Verify intent still active
+    if (!this.activeIntents.has(token.intentHash)) {
+      this.stats.rejected++;
+      return { valid: false, reason: 'Bound intent no longer active.' };
+    }
+
+    token.used = true;
+    this.stats.verified++;
+    return { valid: true, reason: null };
+  }
+
+  /**
+   * Revoke an intent and all its tokens.
+   * @param {string} intentHash
+   * @returns {boolean}
+   */
+  revokeIntent(intentHash) {
+    const deleted = this.activeIntents.delete(intentHash);
+    if (deleted) this._log('intent_revoked', { intentHash });
+    return deleted;
+  }
+
+  /**
+   * Get statistics.
+   * @returns {object}
+   */
+  getStats() {
+    return { ...this.stats, activeIntents: this.activeIntents.size };
+  }
+
+  /**
+   * Get audit log.
+   * @returns {Array<object>}
+   */
+  getAuditLog() {
+    return [...this.auditLog];
+  }
+
+  /**
+   * Purge expired intents.
+   */
+  purgeExpired() {
+    const now = Date.now();
+    for (const [hash, intent] of this.activeIntents) {
+      if (now - intent.createdAt > this.tokenTtlMs * 2) {
+        this.activeIntents.delete(hash);
+      }
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Private
+  // -----------------------------------------------------------------------
+
+  /**
+   * Derive allowed actions from intent text using keyword analysis.
+   * @private
+   */
+  _deriveAllowedActions(intentText) {
+    const lower = intentText.toLowerCase();
+    const actions = [];
+
+    if (/\b(?:read|get|fetch|show|display|find|search|query|list|look\s*up)\b/.test(lower)) actions.push('data:read');
+    if (/\b(?:write|create|update|edit|modify|save|add|insert|set)\b/.test(lower)) actions.push('data:write');
+    if (/\b(?:delete|remove|drop|clear|purge|destroy)\b/.test(lower)) actions.push('data:delete');
+    if (/\b(?:send|email|message|notify|post|share|communicate|slack)\b/.test(lower)) actions.push('comm:send');
+    if (/\b(?:run|execute|bash|shell|script|compile|build|test)\b/.test(lower)) actions.push('exec:run');
+    if (/\b(?:file|open|download|upload|path|directory|folder)\b/.test(lower)) actions.push('fs:access');
+    if (/\b(?:http|api|request|fetch|curl|endpoint|url|webhook)\b/.test(lower)) actions.push('net:request');
+    if (/\b(?:analyze|calculate|compute|summarize|compare|evaluate)\b/.test(lower)) actions.push('compute:analyze');
+
+    if (actions.length === 0) actions.push('compute:analyze'); // Default: analysis only
+
+    return actions;
+  }
+
+  /**
+   * Check if an action is allowed by the bound intent.
+   * @private
+   */
+  _isActionAllowed(intent, action) {
+    // Exact match
+    if (intent.actions.includes(action)) return true;
+
+    // Category match (e.g., 'data:read' allows 'tool:readFile')
+    const actionCategory = action.split(':')[0];
+    return intent.actions.some(a => a.split(':')[0] === actionCategory);
+  }
+
+  /**
+   * SHA-256 hash.
+   * @private
+   */
+  _hash(text) {
+    return crypto.createHash('sha256').update(text).digest('hex');
+  }
+
+  /**
+   * HMAC-SHA256 sign.
+   * @private
+   */
+  _sign(payload) {
+    return crypto.createHmac('sha256', this.signingKey).update(payload).digest('hex');
+  }
+
+  /**
+   * Log an event.
+   * @private
+   */
+  _log(action, details) {
+    this.auditLog.push({ timestamp: Date.now(), action, ...details });
+    if (this.auditLog.length > 5000) {
+      this.auditLog = this.auditLog.slice(-5000);
+    }
+  }
+}
+
+// =========================================================================
+// EXPORTS
+// =========================================================================
+
+module.exports = {
+  IntentBinder,
+  IntentToken,
+  PROVENANCE: require('./semantic-isolation').PROVENANCE
+};