agentshield-sdk 7.0.0

package/src/audit-streaming.js

@@ -0,0 +1,469 @@
+'use strict';
+
+/**
+ * Agent Shield — Audit Log Streaming (v2.1)
+ *
+ * Stream security audit events to external logging/SIEM systems.
+ * Supports Splunk HEC, Elasticsearch, file-based logging, and custom transports.
+ *
+ * Zero dependencies — uses Node.js built-in http/https/fs modules.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const https = require('https');
+
+// =========================================================================
+// TRANSPORT INTERFACE
+// =========================================================================
+
+/**
+ * Base transport class. Extend for custom destinations.
+ */
+class AuditTransport {
+  /**
+   * Send an event to the transport.
+   * @param {object} event - Audit event.
+   * @returns {Promise<void>}
+   */
+  async send(event) { throw new Error('Not implemented'); }
+
+  /**
+   * Send multiple events in a batch.
+   * @param {Array<object>} events
+   * @returns {Promise<void>}
+   */
+  async sendBatch(events) {
+    for (const event of events) {
+      await this.send(event);
+    }
+  }
+
+  /**
+   * Flush any buffered events.
+   * @returns {Promise<void>}
+   */
+  async flush() {}
+
+  /**
+   * Close the transport.
+   * @returns {Promise<void>}
+   */
+  async close() {}
+}
+
+// =========================================================================
+// FILE TRANSPORT
+// =========================================================================
+
+/**
+ * Writes audit events to a local file (JSONL format).
+ */
+class FileTransport extends AuditTransport {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.filePath='./agent-shield-audit.log'] - Log file path.
+   * @param {number} [options.maxSizeMB=100] - Max file size before rotation.
+   * @param {number} [options.maxFiles=5] - Number of rotated files to keep.
+   */
+  constructor(options = {}) {
+    super();
+    this.filePath = options.filePath || './agent-shield-audit.log';
+    this.maxSizeBytes = (options.maxSizeMB || 100) * 1024 * 1024;
+    this.maxFiles = options.maxFiles || 5;
+    this._buffer = [];
+    this._bufferSize = 0;
+    this._flushInterval = setInterval(() => this.flush(), 5000);
+  }
+
+  async send(event) {
+    const line = JSON.stringify(event) + '\n';
+    this._buffer.push(line);
+    this._bufferSize += line.length;
+
+    if (this._bufferSize >= 64 * 1024) {
+      await this.flush();
+    }
+  }
+
+  async flush() {
+    if (this._buffer.length === 0) return;
+
+    const data = this._buffer.join('');
+    this._buffer = [];
+    this._bufferSize = 0;
+
+    try {
+      // Check rotation
+      if (fs.existsSync(this.filePath)) {
+        const stat = fs.statSync(this.filePath);
+        if (stat.size + data.length > this.maxSizeBytes) {
+          this._rotate();
+        }
+      }
+
+      fs.appendFileSync(this.filePath, data);
+    } catch (e) {
+      console.warn('[Agent Shield] FileTransport write error:', e.message);
+    }
+  }
+
+  async close() {
+    clearInterval(this._flushInterval);
+    await this.flush();
+  }
+
+  /** @private */
+  _rotate() {
+    for (let i = this.maxFiles - 1; i >= 1; i--) {
+      const from = `${this.filePath}.${i}`;
+      const to = `${this.filePath}.${i + 1}`;
+      if (fs.existsSync(from)) {
+        if (i + 1 > this.maxFiles) fs.unlinkSync(from);
+        else fs.renameSync(from, to);
+      }
+    }
+    if (fs.existsSync(this.filePath)) {
+      fs.renameSync(this.filePath, `${this.filePath}.1`);
+    }
+  }
+}
+
+// =========================================================================
+// SPLUNK HEC TRANSPORT
+// =========================================================================
+
+/**
+ * Sends audit events to Splunk via HTTP Event Collector (HEC).
+ */
+class SplunkTransport extends AuditTransport {
+  /**
+   * @param {object} options
+   * @param {string} options.url - Splunk HEC URL (e.g., https://splunk:8088/services/collector/event).
+   * @param {string} options.token - HEC token.
+   * @param {string} [options.index='main'] - Splunk index.
+   * @param {string} [options.source='agent-shield'] - Event source.
+   * @param {string} [options.sourcetype='_json'] - Source type.
+   * @param {number} [options.batchSize=50] - Events per batch.
+   * @param {number} [options.flushIntervalMs=5000] - Auto-flush interval.
+   */
+  constructor(options = {}) {
+    super();
+    this.url = options.url;
+    this.token = options.token;
+    this.index = options.index || 'main';
+    this.source = options.source || 'agent-shield';
+    this.sourcetype = options.sourcetype || '_json';
+    this.batchSize = options.batchSize || 50;
+    this._buffer = [];
+    this._flushInterval = setInterval(() => this.flush(), options.flushIntervalMs || 5000);
+    this._stats = { sent: 0, errors: 0 };
+
+    if (!this.url || !this.token) {
+      console.warn('[Agent Shield] SplunkTransport: url and token are required.');
+    }
+  }
+
+  async send(event) {
+    this._buffer.push({
+      time: event.timestamp ? event.timestamp / 1000 : Date.now() / 1000,
+      source: this.source,
+      sourcetype: this.sourcetype,
+      index: this.index,
+      event
+    });
+
+    if (this._buffer.length >= this.batchSize) {
+      await this.flush();
+    }
+  }
+
+  async flush() {
+    if (this._buffer.length === 0 || !this.url || !this.token) return;
+
+    const events = this._buffer.splice(0, this.batchSize);
+    const payload = events.map(e => JSON.stringify(e)).join('\n');
+
+    try {
+      await this._post(this.url, payload, {
+        'Authorization': `Splunk ${this.token}`,
+        'Content-Type': 'application/json'
+      });
+      this._stats.sent += events.length;
+    } catch (e) {
+      this._stats.errors += events.length;
+      console.warn('[Agent Shield] SplunkTransport error:', e.message);
+      // Re-queue failed events
+      this._buffer.unshift(...events);
+    }
+  }
+
+  async close() {
+    clearInterval(this._flushInterval);
+    await this.flush();
+  }
+
+  getStats() { return { ...this._stats, buffered: this._buffer.length }; }
+
+  /** @private */
+  _post(url, body, headers) {
+    return new Promise((resolve, reject) => {
+      const parsed = new URL(url);
+      const lib = parsed.protocol === 'https:' ? https : http;
+      const req = lib.request({
+        hostname: parsed.hostname, port: parsed.port,
+        path: parsed.pathname, method: 'POST',
+        headers: { ...headers, 'Content-Length': Buffer.byteLength(body) },
+        rejectUnauthorized: false, timeout: 10000
+      }, (res) => {
+        let data = '';
+        res.on('data', c => data += c);
+        res.on('end', () => resolve(data));
+      });
+      req.on('error', reject);
+      req.on('timeout', () => { req.destroy(); reject(new Error('Timeout')); });
+      req.write(body);
+      req.end();
+    });
+  }
+}
+
+// =========================================================================
+// ELASTICSEARCH TRANSPORT
+// =========================================================================
+
+/**
+ * Sends audit events to Elasticsearch.
+ */
+class ElasticsearchTransport extends AuditTransport {
+  /**
+   * @param {object} options
+   * @param {string} options.url - Elasticsearch URL (e.g., http://localhost:9200).
+   * @param {string} [options.index='agent-shield-audit'] - Index name.
+   * @param {string} [options.apiKey] - API key for authentication.
+   * @param {number} [options.batchSize=100] - Events per bulk request.
+   * @param {number} [options.flushIntervalMs=5000]
+   */
+  constructor(options = {}) {
+    super();
+    this.url = options.url;
+    this.index = options.index || 'agent-shield-audit';
+    this.apiKey = options.apiKey || null;
+    this.batchSize = options.batchSize || 100;
+    this._buffer = [];
+    this._flushInterval = setInterval(() => this.flush(), options.flushIntervalMs || 5000);
+    this._stats = { sent: 0, errors: 0 };
+
+    if (!this.url) {
+      console.warn('[Agent Shield] ElasticsearchTransport: url is required.');
+    }
+  }
+
+  async send(event) {
+    this._buffer.push(event);
+    if (this._buffer.length >= this.batchSize) {
+      await this.flush();
+    }
+  }
+
+  async flush() {
+    if (this._buffer.length === 0 || !this.url) return;
+
+    const events = this._buffer.splice(0, this.batchSize);
+    const dateStr = new Date().toISOString().split('T')[0].replace(/-/g, '.');
+    const indexName = `${this.index}-${dateStr}`;
+
+    // Build NDJSON bulk payload
+    const lines = [];
+    for (const event of events) {
+      lines.push(JSON.stringify({ index: { _index: indexName } }));
+      lines.push(JSON.stringify({ ...event, '@timestamp': event.timestamp || Date.now() }));
+    }
+    const payload = lines.join('\n') + '\n';
+
+    const headers = { 'Content-Type': 'application/x-ndjson' };
+    if (this.apiKey) headers['Authorization'] = `ApiKey ${this.apiKey}`;
+
+    try {
+      await this._post(`${this.url}/_bulk`, payload, headers);
+      this._stats.sent += events.length;
+    } catch (e) {
+      this._stats.errors += events.length;
+      console.warn('[Agent Shield] ElasticsearchTransport error:', e.message);
+      this._buffer.unshift(...events);
+    }
+  }
+
+  async close() {
+    clearInterval(this._flushInterval);
+    await this.flush();
+  }
+
+  getStats() { return { ...this._stats, buffered: this._buffer.length }; }
+
+  /** @private */
+  _post(url, body, headers) {
+    return new Promise((resolve, reject) => {
+      const parsed = new URL(url);
+      const lib = parsed.protocol === 'https:' ? https : http;
+      const req = lib.request({
+        hostname: parsed.hostname, port: parsed.port,
+        path: parsed.pathname, method: 'POST',
+        headers: { ...headers, 'Content-Length': Buffer.byteLength(body) },
+        timeout: 10000
+      }, (res) => {
+        let data = '';
+        res.on('data', c => data += c);
+        res.on('end', () => resolve(data));
+      });
+      req.on('error', reject);
+      req.on('timeout', () => { req.destroy(); reject(new Error('Timeout')); });
+      req.write(body);
+      req.end();
+    });
+  }
+}
+
+// =========================================================================
+// AUDIT STREAM MANAGER
+// =========================================================================
+
+/**
+ * Manages multiple audit transports and routes events to all of them.
+ */
+class AuditStreamManager {
+  /**
+   * @param {object} [options]
+   * @param {Array<AuditTransport>} [options.transports] - Initial transports.
+   * @param {boolean} [options.includeMetadata=true] - Add instance metadata to events.
+   * @param {string} [options.environment='production'] - Environment label.
+   */
+  constructor(options = {}) {
+    this._transports = options.transports || [];
+    this.includeMetadata = options.includeMetadata !== false;
+    this.environment = options.environment || 'production';
+    this._eventCount = 0;
+
+    console.log('[Agent Shield] AuditStreamManager initialized (%d transports)', this._transports.length);
+  }
+
+  /**
+   * Add a transport.
+   * @param {AuditTransport} transport
+   */
+  addTransport(transport) {
+    this._transports.push(transport);
+  }
+
+  /**
+   * Emit an audit event to all transports.
+   * @param {string} type - Event type (e.g., 'scan', 'threat', 'block', 'config_change').
+   * @param {object} data - Event data.
+   * @returns {Promise<void>}
+   */
+  async emit(type, data = {}) {
+    this._eventCount++;
+
+    const event = {
+      type,
+      ...data,
+      timestamp: Date.now(),
+      eventId: `evt_${this._eventCount}_${Date.now()}`
+    };
+
+    if (this.includeMetadata) {
+      event.environment = this.environment;
+      event.agentShieldVersion = '2.1.0';
+    }
+
+    const promises = this._transports.map(t =>
+      t.send(event).catch(e => console.warn('[Agent Shield] Transport error:', e.message))
+    );
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * Emit a scan event.
+   * @param {object} scanResult - Result from scanText/AgentShield.
+   * @param {object} [context] - Additional context.
+   */
+  async emitScan(scanResult, context = {}) {
+    await this.emit('scan', {
+      status: scanResult.status,
+      threatCount: scanResult.threats ? scanResult.threats.length : 0,
+      categories: scanResult.threats ? [...new Set(scanResult.threats.map(t => t.category))] : [],
+      scanTimeMs: scanResult.stats ? scanResult.stats.scanTimeMs : 0,
+      ...context
+    });
+  }
+
+  /**
+   * Emit a threat event.
+   * @param {object} threat - Individual threat object.
+   * @param {object} [context]
+   */
+  async emitThreat(threat, context = {}) {
+    await this.emit('threat', {
+      severity: threat.severity,
+      category: threat.category,
+      description: threat.description,
+      confidence: threat.confidence,
+      ...context
+    });
+  }
+
+  /**
+   * Emit a block event.
+   * @param {string} reason
+   * @param {object} [context]
+   */
+  async emitBlock(reason, context = {}) {
+    await this.emit('block', { reason, ...context });
+  }
+
+  /**
+   * Flush all transports.
+   * @returns {Promise<void>}
+   */
+  async flush() {
+    await Promise.all(this._transports.map(t => t.flush()));
+  }
+
+  /**
+   * Close all transports.
+   * @returns {Promise<void>}
+   */
+  async close() {
+    await Promise.all(this._transports.map(t => t.close()));
+  }
+
+  /**
+   * Get streaming statistics.
+   * @returns {object}
+   */
+  getStats() {
+    return {
+      eventCount: this._eventCount,
+      transports: this._transports.length,
+      transportStats: this._transports.map((t, i) => ({
+        index: i,
+        type: t.constructor.name,
+        stats: typeof t.getStats === 'function' ? t.getStats() : null
+      }))
+    };
+  }
+}
+
+// =========================================================================
+// EXPORTS
+// =========================================================================
+
+module.exports = {
+  AuditStreamManager,
+  AuditTransport,
+  FileTransport,
+  SplunkTransport,
+  ElasticsearchTransport
+};

package/src/badges.js

@@ -0,0 +1,196 @@
+'use strict';
+
+/**
+ * Agent Shield — Integration Badges & GitHub Action Support
+ *
+ * Generate SVG badges for READMEs and CI/CD pipelines.
+ */
+
+// =========================================================================
+// Badge Generator
+// =========================================================================
+
+class BadgeGenerator {
+  /**
+   * Generate a Shield Score badge in SVG.
+   */
+  static shieldScore(score) {
+    const color = score >= 90 ? '22c55e' : score >= 70 ? 'eab308' : score >= 50 ? 'f97316' : 'ef4444';
+    const grade = score >= 95 ? 'A+' : score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : score >= 50 ? 'D' : 'F';
+    return BadgeGenerator.generateSVG('shield score', `${score} (${grade})`, color);
+  }
+
+  /**
+   * Generate a protection status badge.
+   */
+  static protectionStatus(enabled = true) {
+    return BadgeGenerator.generateSVG(
+      'agent shield',
+      enabled ? 'protected' : 'unprotected',
+      enabled ? '3b82f6' : 'ef4444'
+    );
+  }
+
+  /**
+   * Generate a detection rate badge.
+   */
+  static detectionRate(rate) {
+    const num = parseFloat(rate);
+    const color = num >= 90 ? '22c55e' : num >= 70 ? 'eab308' : 'ef4444';
+    return BadgeGenerator.generateSVG('detection rate', `${num}%`, color);
+  }
+
+  /**
+   * Generate a scan count badge.
+   */
+  static scanCount(count) {
+    return BadgeGenerator.generateSVG('scans', count.toLocaleString(), '06b6d4');
+  }
+
+  /**
+   * Generate a compliance badge.
+   */
+  static compliance(framework, rate) {
+    const num = parseFloat(rate);
+    const color = num >= 80 ? '22c55e' : num >= 50 ? 'eab308' : 'ef4444';
+    return BadgeGenerator.generateSVG(framework, `${num}%`, color);
+  }
+
+  /**
+   * Generate a custom badge.
+   */
+  static custom(label, value, color = '3b82f6') {
+    return BadgeGenerator.generateSVG(label, value, color);
+  }
+
+  /**
+   * Generate Markdown badge links for README.
+   */
+  static markdownBadges(options = {}) {
+    const lines = [];
+
+    if (options.score !== undefined) {
+      const color = options.score >= 90 ? 'brightgreen' : options.score >= 70 ? 'yellow' : options.score >= 50 ? 'orange' : 'red';
+      lines.push(`![Shield Score](https://img.shields.io/badge/shield_score-${options.score}-${color}?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyMnM4LTQgOC0xMFY1bC04LTMtOCAzdjdjMCA2IDggMTAgOCAxMHoiLz48L3N2Zz4=)`);
+    }
+
+    lines.push(`![Agent Shield](https://img.shields.io/badge/protected_by-agent_shield-blue?style=flat-square)`);
+
+    if (options.detectionRate) {
+      const color = parseFloat(options.detectionRate) >= 90 ? 'brightgreen' : 'yellow';
+      lines.push(`![Detection Rate](https://img.shields.io/badge/detection_rate-${options.detectionRate}%25-${color}?style=flat-square)`);
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Core SVG badge generator.
+   */
+  static generateSVG(label, value, color) {
+    const labelWidth = label.length * 7 + 12;
+    const valueWidth = String(value).length * 7 + 12;
+    const totalWidth = labelWidth + valueWidth;
+
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="20" role="img">
+  <title>${label}: ${value}</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r"><rect width="${totalWidth}" height="20" rx="3" fill="#fff"/></clipPath>
+  <g clip-path="url(#r)">
+    <rect width="${labelWidth}" height="20" fill="#555"/>
+    <rect x="${labelWidth}" width="${valueWidth}" height="20" fill="#${color}"/>
+    <rect width="${totalWidth}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="11">
+    <text x="${labelWidth / 2}" y="14" fill="#010101" fill-opacity=".3">${label}</text>
+    <text x="${labelWidth / 2}" y="13">${label}</text>
+    <text x="${labelWidth + valueWidth / 2}" y="14" fill="#010101" fill-opacity=".3">${value}</text>
+    <text x="${labelWidth + valueWidth / 2}" y="13">${value}</text>
+  </g>
+</svg>`;
+  }
+}
+
+// =========================================================================
+// GitHub Action Output
+// =========================================================================
+
+class GitHubActionReporter {
+  constructor() {
+    this.annotations = [];
+  }
+
+  /**
+   * Report scan results as GitHub Action annotations.
+   */
+  reportScan(result, file = '', line = 0) {
+    if (!result.threats || result.threats.length === 0) return;
+
+    for (const threat of result.threats) {
+      const level = threat.severity === 'critical' || threat.severity === 'high' ? 'error' : 'warning';
+      const msg = `[Agent Shield] ${threat.description} (${threat.severity})`;
+
+      // GitHub Actions annotation format
+      if (file) {
+        console.log(`::${level} file=${file},line=${line}::${msg}`);
+      } else {
+        console.log(`::${level}::${msg}`);
+      }
+
+      this.annotations.push({ level, file, line, message: msg });
+    }
+  }
+
+  /**
+   * Set GitHub Action output variables.
+   */
+  setOutputs(results) {
+    const total = results.threats ? results.threats.length : 0;
+    const blocked = results.blocked || false;
+    const status = results.status || 'unknown';
+
+    // Use GITHUB_OUTPUT env file (modern) with fallback to deprecated ::set-output
+    const githubOutput = process.env.GITHUB_OUTPUT;
+    if (githubOutput) {
+      const fs = require('fs');
+      fs.appendFileSync(githubOutput, `threat_count=${total}\n`);
+      fs.appendFileSync(githubOutput, `status=${status}\n`);
+      fs.appendFileSync(githubOutput, `blocked=${blocked}\n`);
+    } else {
+      console.log(`::set-output name=threat_count::${total}`);
+      console.log(`::set-output name=status::${status}`);
+      console.log(`::set-output name=blocked::${blocked}`);
+    }
+  }
+
+  /**
+   * Create a summary for GitHub Actions.
+   */
+  createSummary(shieldScore, scanResults) {
+    const lines = [];
+    lines.push('## Agent Shield Scan Results\n');
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+
+    if (shieldScore) {
+      lines.push(`| Shield Score | ${shieldScore.score}/100 (${shieldScore.grade}) |`);
+    }
+
+    if (scanResults) {
+      lines.push(`| Status | ${scanResults.status} |`);
+      lines.push(`| Threats | ${scanResults.threats ? scanResults.threats.length : 0} |`);
+      lines.push(`| Blocked | ${scanResults.blocked ? 'Yes' : 'No'} |`);
+    }
+
+    lines.push('');
+    return lines.join('\n');
+  }
+}
+
+module.exports = {
+  BadgeGenerator,
+  GitHubActionReporter
+};