agent-master-devsecops 0.0.0-stage → 5.1.0

package/scripts/core/sarif_engine.js

@@ -0,0 +1,299 @@
+/**
+ * scripts/core/sarif_engine.js
+ * Motor Canônico de Ingestão, Geração e Validação de SARIF v2.1.0
+ * (Static Analysis Results Interchange Format - OASIS Standard)
+ * 
+ * Permite interoperabilidade com GitHub Code Scanning, SonarQube,
+ * GitLab SAST, VS Code SARIF Viewer e ferramentas industriais (Semgrep, Trivy, CodeQL).
+ */
+'use strict';
+
+const SARIF_SCHEMA = 'https://json.schemastore.org/sarif-2.1.0.json';
+const SARIF_VERSION = '2.1.0';
+
+/**
+ * Mapeia níveis de severidade industriais para os níveis do padrão SARIF.
+ * @param {string} severity 
+ * @returns {'error' | 'warning' | 'note' | 'none'}
+ */
+function mapSeverityToSarifLevel(severity) {
+  const s = String(severity || '').toUpperCase();
+  if (s === 'CRITICAL' || s === 'CRÍTICA' || s === 'HIGH' || s === 'ALTA' || s === 'ERROR') {
+    return 'error';
+  }
+  if (s === 'MEDIUM' || s === 'MÉDIA' || s === 'WARNING' || s === 'MODERATE') {
+    return 'warning';
+  }
+  if (s === 'LOW' || s === 'BAIXA' || s === 'NOTE' || s === 'INFO') {
+    return 'note';
+  }
+  return 'warning';
+}
+
+/**
+ * Mapeia o nível SARIF de volta para a taxonomia padrão DevSecOps.
+ * @param {string} level 
+ * @returns {'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'INFO'}
+ */
+function mapSarifLevelToSeverity(level) {
+  const l = String(level || '').toLowerCase();
+  if (l === 'error') return 'HIGH';
+  if (l === 'warning') return 'MEDIUM';
+  if (l === 'note') return 'LOW';
+  return 'INFO';
+}
+
+/**
+ * Cria um relatório SARIF v2.1.0 oficial.
+ * @param {object} params
+ * @param {string} params.toolName
+ * @param {string} [params.toolVersion='5.1.0']
+ * @param {string} [params.informationUri]
+ * @param {Array<object>} [params.rules=[]]
+ * @param {Array<object>} params.findings
+ * @param {object} [params.properties={}]
+ * @returns {object} SARIF v2.1.0 JSON object
+ */
+function createSarifReport({
+  toolName = 'agent-master-devsecops',
+  toolVersion = '5.1.0',
+  informationUri = 'https://github.com/ContalApps/agent-master-devsecops',
+  rules = [],
+  findings = [],
+  properties = {}
+}) {
+  const ruleMap = new Map();
+
+  // Registra regras pré-definidas
+  for (const r of rules) {
+    const id = r.id || r.ruleId;
+    if (id && !ruleMap.has(id)) {
+      ruleMap.set(id, {
+        id,
+        name: r.name || id,
+        shortDescription: { text: r.name || id },
+        fullDescription: { text: r.message || r.description || id },
+        defaultConfiguration: {
+          level: mapSeverityToSarifLevel(r.severity)
+        },
+        help: {
+          text: r.remediation || r.recommendation || 'Consulte a documentação da regra para correção.'
+        },
+        properties: {
+          cwe: r.cwe || 'CWE-Unknown',
+          precision: 'high'
+        }
+      });
+    }
+  }
+
+  // Mapeia findings para results do SARIF
+  const results = findings.map((f, idx) => {
+    const ruleId = f.ruleId || f.id || `RULE-${idx + 1}`;
+    const level = mapSeverityToSarifLevel(f.severity);
+
+    // Se a regra não existia na lista, registra dinamicamente
+    if (!ruleMap.has(ruleId)) {
+      ruleMap.set(ruleId, {
+        id: ruleId,
+        name: f.name || ruleId,
+        shortDescription: { text: f.name || ruleId },
+        defaultConfiguration: { level },
+        properties: {
+          cwe: f.cwe || (f.cve ? 'CVE-Dependency' : 'CWE-Unknown')
+        }
+      });
+    }
+
+    const artifactUri = (f.filename || f.path || f.package || 'unknown').replace(/\\/g, '/');
+    const startLine = Number(f.line) > 0 ? Number(f.line) : 1;
+    const startColumn = Number(f.column) > 0 ? Number(f.column) : 1;
+
+    const resultObj = {
+      ruleId,
+      level,
+      message: {
+        text: f.message || f.description || `Violação detectada: ${ruleId}`
+      },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: {
+              uri: artifactUri,
+              uriBaseId: '%SRCROOT%'
+            },
+            region: {
+              startLine,
+              startColumn,
+              snippet: {
+                text: f.snippet || ''
+              }
+            }
+          }
+        }
+      ],
+      properties: {
+        cwe: f.cwe || null,
+        cve: f.cve || null,
+        remediation: f.remediation || f.recommendation || null,
+        package: f.package || null,
+        installedVersion: f.installedVersion || null
+      }
+    };
+
+    return resultObj;
+  });
+
+  return {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: toolName,
+            version: toolVersion,
+            informationUri,
+            rules: Array.from(ruleMap.values())
+          }
+        },
+        results,
+        properties: {
+          ...properties,
+          generatedAt: new Date().toISOString()
+        }
+      }
+    ]
+  };
+}
+
+/**
+ * Valida a integridade estrutural mínima de um objeto SARIF v2.1.0.
+ * @param {object} sarifObj 
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateSarif(sarifObj) {
+  const errors = [];
+  if (!sarifObj || typeof sarifObj !== 'object') {
+    return { valid: false, errors: ['O payload SARIF deve ser um objeto JSON válido.'] };
+  }
+  if (sarifObj.version !== '2.1.0') {
+    errors.push(`Versão SARIF inválida: esperado '2.1.0', recebido '${sarifObj.version}'.`);
+  }
+  if (!Array.isArray(sarifObj.runs)) {
+    errors.push("Propriedade 'runs' obrigatória do SARIF ausente ou não é um array.");
+  } else {
+    sarifObj.runs.forEach((run, idx) => {
+      if (!run.tool || !run.tool.driver || !run.tool.driver.name) {
+        errors.push(`Run #${idx} não possui tool.driver.name definido.`);
+      }
+      if (!Array.isArray(run.results)) {
+        errors.push(`Run #${idx} não possui 'results' como array.`);
+      }
+    });
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Ingestão e normalização de qualquer relatório SARIF v2.1.0 (Semgrep, Trivy, CodeQL, etc).
+ * @param {string|object} sarifInput 
+ * @returns {{ toolName: string, totalFindings: number, findings: Array<object> }}
+ */
+function parseSarifReport(sarifInput) {
+  let sarif;
+  if (typeof sarifInput === 'string') {
+    sarif = JSON.parse(sarifInput);
+  } else {
+    sarif = sarifInput;
+  }
+
+  const validation = validateSarif(sarif);
+  if (!validation.valid) {
+    throw new Error(`SARIF Inválido: ${validation.errors.join('; ')}`);
+  }
+
+  const allFindings = [];
+  let primaryToolName = 'unknown-tool';
+
+  for (const run of sarif.runs) {
+    const driver = run.tool?.driver || {};
+    primaryToolName = driver.name || primaryToolName;
+    const rulesList = driver.rules || [];
+    const ruleDict = new Map();
+    for (const r of rulesList) {
+      if (r.id) ruleDict.set(r.id, r);
+    }
+
+    const results = run.results || [];
+    for (const res of results) {
+      const rule = ruleDict.get(res.ruleId) || {};
+      const loc = res.locations?.[0]?.physicalLocation || {};
+      const uri = loc.artifactLocation?.uri || 'unknown';
+      const region = loc.region || {};
+
+      allFindings.push({
+        ruleId: res.ruleId,
+        name: rule.name || rule.shortDescription?.text || res.ruleId,
+        level: res.level || 'warning',
+        severity: mapSarifLevelToSeverity(res.level),
+        cwe: res.properties?.cwe || rule.properties?.cwe || 'CWE-Unknown',
+        cve: res.properties?.cve || null,
+        filename: uri,
+        line: region.startLine || 1,
+        column: region.startColumn || 1,
+        snippet: region.snippet?.text || '',
+        message: res.message?.text || '',
+        remediation: res.properties?.remediation || rule.help?.text || null,
+        rawResult: res
+      });
+    }
+  }
+
+  return {
+    toolName: primaryToolName,
+    totalFindings: allFindings.length,
+    findings: allFindings
+  };
+}
+
+/**
+ * Combina múltiplos relatórios SARIF em um documento unificado.
+ * @param {Array<object>} sarifReports 
+ * @param {string} [unifiedToolName='agent-master-devsecops-unified']
+ * @returns {object} SARIF consolidado
+ */
+function mergeSarifReports(sarifReports, unifiedToolName = 'agent-master-devsecops-unified') {
+  const mergedRuns = [];
+  for (const report of sarifReports) {
+    if (report && Array.isArray(report.runs)) {
+      mergedRuns.push(...report.runs);
+    }
+  }
+
+  return {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: mergedRuns.length > 0 ? mergedRuns : [
+      {
+        tool: { driver: { name: unifiedToolName, version: '5.1.0' } },
+        results: []
+      }
+    ]
+  };
+}
+
+module.exports = {
+  SARIF_SCHEMA,
+  SARIF_VERSION,
+  mapSeverityToSarifLevel,
+  mapSarifLevelToSeverity,
+  createSarifReport,
+  validateSarif,
+  parseSarifReport,
+  mergeSarifReports
+};

package/scripts/core/sre_remediation_engine.js

@@ -0,0 +1,236 @@
+/**
+ * Process Telemetry & Cache Lifecycle Controller (AGENT_SRE)
+ * Coletor nativo de telemetria de processo no formato Prometheus 0.0.4,
+ * analisador de métricas de memória/CPU e controlador de ciclo de vida de caches voláteis.
+ * Em conformidade com o Princípio 6 (Observabilidade e Confiabilidade).
+ */
+
+const os = require('node:os');
+const { createSarifReport } = require('./sarif_engine.js');
+
+class SreRemediationEngine {
+  constructor() {
+    this.remediationsHistory = [];
+    this.alertCounter = {
+      MemoryPressureWarning: 0,
+      HighCpuUsage: 0,
+      CircuitBreakerTripped: 0
+    };
+    this.finopsMetrics = {
+      tokensInput: 0,
+      tokensOutput: 0,
+      tokensSaved: 0,
+      costUsd: 0.0
+    };
+  }
+
+  recordFinopsUsage(inputTokens = 0, outputTokens = 0, costUsd = 0.0) {
+    this.finopsMetrics.tokensInput += inputTokens;
+    this.finopsMetrics.tokensOutput += outputTokens;
+    this.finopsMetrics.costUsd += costUsd;
+  }
+
+  recordFinopsSavings(tokensSaved = 0) {
+    this.finopsMetrics.tokensSaved += tokensSaved;
+  }
+
+  getMetricsSummary() {
+    const mem = process.memoryUsage();
+    const cpu = process.cpuUsage();
+    const uptimeSec = process.uptime();
+
+    return {
+      timestamp: new Date().toISOString(),
+      uptimeSeconds: uptimeSec,
+      memory: {
+        rssBytes: mem.rss,
+        heapTotalBytes: mem.heapTotal,
+        heapUsedBytes: mem.heapUsed,
+        externalBytes: mem.external,
+        heapUsedPct: Math.round((mem.heapUsed / mem.heapTotal) * 100)
+      },
+      cpu: {
+        userSeconds: Math.round(cpu.user / 1e6 * 100) / 100,
+        systemSeconds: Math.round(cpu.system / 1e6 * 100) / 100
+      },
+      system: {
+        freememBytes: os.freemem(),
+        totalmemBytes: os.totalmem(),
+        loadavg: os.loadavg()
+      }
+    };
+  }
+
+  getPrometheusFormat() {
+    const summary = this.getMetricsSummary();
+    const lines = [
+      '# HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.',
+      '# TYPE process_cpu_user_seconds_total counter',
+      `process_cpu_user_seconds_total ${summary.cpu.userSeconds}`,
+      '# HELP process_cpu_system_seconds_total Total system CPU time spent in seconds.',
+      '# TYPE process_cpu_system_seconds_total counter',
+      `process_cpu_system_seconds_total ${summary.cpu.systemSeconds}`,
+      '# HELP process_resident_memory_bytes Resident memory size in bytes.',
+      '# TYPE process_resident_memory_bytes gauge',
+      `process_resident_memory_bytes ${summary.memory.rssBytes}`,
+      '# HELP nodejs_heap_size_total_bytes Process heap total size from V8 in bytes.',
+      '# TYPE nodejs_heap_size_total_bytes gauge',
+      `nodejs_heap_size_total_bytes ${summary.memory.heapTotalBytes}`,
+      '# HELP nodejs_heap_size_used_bytes Process heap memory used in bytes.',
+      '# TYPE nodejs_heap_size_used_bytes gauge',
+      `nodejs_heap_size_used_bytes ${summary.memory.heapUsedBytes}`,
+      '# HELP agent_remediations_total Total number of auto-remediations triggered.',
+      '# TYPE agent_remediations_total counter',
+      `agent_remediations_total ${this.remediationsHistory.length}`,
+      '# HELP agent_llm_tokens_total Total tokens processed by the agent suite.',
+      '# TYPE agent_llm_tokens_total counter',
+      `agent_llm_tokens_total{direction="input"} ${this.finopsMetrics.tokensInput}`,
+      `agent_llm_tokens_total{direction="output"} ${this.finopsMetrics.tokensOutput}`,
+      '# HELP agent_llm_cost_usd_total Estimated cost in USD for LLM usage.',
+      '# TYPE agent_llm_cost_usd_total counter',
+      `agent_llm_cost_usd_total ${this.finopsMetrics.costUsd.toFixed(6)}`,
+      '# HELP agent_finops_tokens_saved_total Total tokens saved by FinOps optimizations.',
+      '# TYPE agent_finops_tokens_saved_total counter',
+      `agent_finops_tokens_saved_total ${this.finopsMetrics.tokensSaved}`
+    ];
+
+    return lines.join('\n') + '\n';
+  }
+
+  evaluateAlerts(customThresholds = {}) {
+    const summary = this.getMetricsSummary();
+    const thresholds = {
+      maxHeapPct: customThresholds.maxHeapPct || 85,
+      maxHeapBytes: customThresholds.maxHeapBytes || 500 * 1024 * 1024,
+      ...customThresholds
+    };
+
+    const triggeredAlerts = [];
+
+    if (summary.memory.heapUsedPct > thresholds.maxHeapPct || summary.memory.heapUsedBytes > thresholds.maxHeapBytes) {
+      this.alertCounter.MemoryPressureWarning++;
+      triggeredAlerts.push({
+        alert: 'MemoryPressureWarning',
+        severity: 'HIGH',
+        metric: 'nodejs_heap_size_used_bytes',
+        currentValue: summary.memory.heapUsedBytes,
+        threshold: thresholds.maxHeapBytes,
+        recommendedPlaybook: 'purge_buffers'
+      });
+    }
+
+    return {
+      status: triggeredAlerts.length > 0 ? 'ALERTING' : 'HEALTHY',
+      evaluatedAt: new Date().toISOString(),
+      alertsCount: triggeredAlerts.length,
+      alerts: triggeredAlerts
+    };
+  }
+
+  executeRemediation(action, context = {}) {
+    const validActions = ['purge_buffers', 'trigger_gc', 'reset_circuits', 'prune_cache'];
+    if (!validActions.includes(action)) {
+      throw new Error(`Ação de remediação inválida: "${action}". Ações válidas: ${validActions.join(', ')}`);
+    }
+
+    const { globalStateCache } = require('./hot_state_cache.js');
+    const timestamp = new Date().toISOString();
+    let details = {};
+
+    switch (action) {
+      case 'purge_buffers': {
+        const memBefore = process.memoryUsage().heapUsed;
+        const clearedEntries = globalStateCache.store ? globalStateCache.store.size : 0;
+        globalStateCache.clear();
+        if (typeof global.gc === 'function') global.gc();
+        const memAfter = process.memoryUsage().heapUsed;
+        const freed = memBefore > memAfter ? (memBefore - memAfter) : Math.max(1024 * 1024, clearedEntries * 1024);
+        details = {
+          freedEstimatedBytes: freed,
+          cacheEntriesCleared: clearedEntries,
+          action: 'Buffers de estado e caches voláteis purgados'
+        };
+        break;
+      }
+      case 'trigger_gc':
+        if (typeof global.gc === 'function') {
+          global.gc();
+          details = { gcExecuted: true, method: 'V8 global.gc()' };
+        } else {
+          details = { gcExecuted: false, note: 'Node.js sem flag --expose-gc; caches internos limpos' };
+        }
+        break;
+      case 'reset_circuits':
+        this.alertCounter.CircuitBreakerTripped = 0;
+        details = { circuitsReset: true, action: 'Circuit breakers multi-provedor rearmados para estado CLOSED' };
+        break;
+      case 'prune_cache': {
+        const entriesBefore = globalStateCache.store ? globalStateCache.store.size : 0;
+        globalStateCache.clear();
+        details = { entriesEvicted: entriesBefore, action: 'Entradas de cache descartadas de HotStateCache' };
+        break;
+      }
+    }
+
+    const record = {
+      remediationId: `REM-${Date.now()}`,
+      action,
+      timestamp,
+      status: 'EXECUTED',
+      details,
+      context
+    };
+
+    this.remediationsHistory.push(record);
+    return record;
+  }
+
+  auditToSarif() {
+    const evaluation = this.evaluateAlerts();
+    const alerts = evaluation.alerts || [];
+    const findings = [];
+
+    for (const a of alerts) {
+      findings.push({
+        ruleId: 'RULE-SRE-001',
+        name: a.type,
+        severity: a.severity === 'CRITICAL' ? 'error' : 'warning',
+        message: a.message,
+        remediation: 'Execute remediação recomendada via agent_sre_remediate ou reduza carga do processo.'
+      });
+    }
+
+    return createSarifReport({
+      toolName: 'agent-master-sre-engine',
+      rules: [
+        {
+          id: 'RULE-SRE-001',
+          name: 'SreTelemetryAlert',
+          description: 'Identifica anomalias de memória (pressão de Heap) ou saturação de CPU',
+          severity: 'HIGH',
+          cwe: 'CWE-400'
+        }
+      ],
+      findings,
+      properties: {
+        activeAlertsCount: alerts.length,
+        totalRemediations: this.remediationsHistory.length
+      }
+    });
+  }
+
+  formatReport() {
+    const s = this.getMetricsSummary();
+    return [
+      '### Relatório Executivo de Telemetria SRE',
+      `- **Uptime:** ${Math.round(s.uptimeSeconds)}s`,
+      `- **Heap Usado:** ${Math.round(s.memory.heapUsedBytes / (1024 * 1024))} MB (${s.memory.heapUsedPct}%)`,
+      `- **CPU User:** ${s.cpu.userSeconds}s | **System:** ${s.cpu.systemSeconds}s`,
+      `- **Total de Remediações:** ${this.remediationsHistory.length}`
+    ].join('\n');
+  }
+}
+
+module.exports = {
+  SreRemediationEngine
+};