agent-master-devsecops 3.9.0 → 5.1.0

package/scripts/auditors/contract_test_validator.js

@@ -0,0 +1,396 @@
+/**
+ * scripts/auditors/contract_test_validator.js
+ * Auditor de Contratos OpenAPI / Swagger & Detecção de Drift de API (Loop 2) — Versão 5.1 Enterprise
+ * 
+ * Implementa validação arquitetural e segurança de contratos de dados (OWASP API Security Top 10):
+ * - Validação sintática e estrutural de especificações OpenAPI 3.x / Swagger 2.0
+ * - Verificação de completude (operações sem summary, responses vazias, parâmetros de rota ausentes)
+ * - Verificação de segurança em mutações de estado (POST, PUT, DELETE, PATCH sem autenticação - OWASP API2)
+ * - Detecção bidirecional de Drift entre contrato e código em O(N+M):
+ *   a) Shadow APIs (rotas implementadas em código sem documentação no contrato - OWASP API9)
+ *   b) Unimplemented Endpoints (rotas prometidas no contrato mas ausentes no código)
+ * - Cálculo de cobertura de conformidade do contrato de dados
+ * - Emissão de relatórios oficiais no padrão OASIS SARIF v2.1.0 (auditToSarif)
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+/**
+ * Normaliza caminho de rota para comparação ignorando parâmetros de template ({id} vs :id),
+ * query strings, barras duplas e trailing slashes.
+ * 
+ * @param {string} routePath 
+ * @returns {string}
+ */
+function normalizeRoutePath(routePath) {
+  if (!routePath || typeof routePath !== 'string') return '/';
+  
+  // 1. Remove query strings e fragmentos
+  let clean = routePath.split('?')[0].split('#')[0].trim();
+  
+  // 2. Garante barra inicial
+  if (!clean.startsWith('/')) {
+    clean = '/' + clean;
+  }
+  
+  // 3. Remove barras duplicadas internas (ex: //api///v1 -> /api/v1)
+  clean = clean.replace(/\/+/g, '/');
+  
+  // 4. Remove barras no final se não for a raiz "/"
+  if (clean.length > 1 && clean.endsWith('/')) {
+    clean = clean.slice(0, -1);
+  }
+  
+  // 5. Normaliza parâmetros de template {id} e :id para :param
+  return clean
+    .replace(/\{[^}]+\}/g, ':param')
+    .replace(/:[a-zA-Z0-9_-]+/g, ':param')
+    .toLowerCase();
+}
+
+/**
+ * Classe principal do Validador de Contratos OpenAPI e Drift de API.
+ */
+class ContractTestValidator {
+  constructor(options = {}) {
+    this.options = options;
+  }
+
+  /**
+   * Valida especificação OpenAPI e audita contra rotas implementadas no código.
+   * 
+   * @param {string|object} specInput Caminho para o arquivo, string JSON ou objeto OpenAPI
+   * @param {Array<{method: string, path: string}>} [implementedRoutes=[]] Lista de rotas implementadas
+   * @returns {object} Relatório de conformidade de contrato
+   */
+  validate(specInput, implementedRoutes = []) {
+    let spec;
+    try {
+      if (typeof specInput === 'string') {
+        if (fs.existsSync(specInput)) {
+          spec = JSON.parse(fs.readFileSync(specInput, 'utf8'));
+        } else {
+          spec = JSON.parse(specInput);
+        }
+      } else if (typeof specInput === 'object' && specInput !== null) {
+        spec = specInput;
+      } else {
+        throw new Error('Entrada da especificação inválida.');
+      }
+    } catch (err) {
+      return {
+        valid: false,
+        compliant: false,
+        error: `Erro ao processar contrato OpenAPI: ${err.message}`,
+        drifts: [],
+        shadowApis: [],
+        unimplementedEndpoints: [],
+        missingSummaries: [],
+        missingResponses: [],
+        missingPathParameters: [],
+        unsecuredOperations: [],
+        coveragePercent: 0,
+        verdict: 'DRIFT_DETECTADO'
+      };
+    }
+
+    const isOpenApi = Boolean(spec && (spec.openapi || spec.swagger));
+    const paths = (spec && spec.paths && typeof spec.paths === 'object') ? spec.paths : {};
+    const pathsList = Object.keys(paths);
+
+    const missingSummaries = [];
+    const missingResponses = [];
+    const missingPathParameters = [];
+    const unsecuredOperations = [];
+    const documentedOperations = [];
+
+    const globalSecurity = Array.isArray(spec && spec.security) && spec.security.length > 0;
+    const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head'];
+
+    // Map indexado em O(1) de operações documentadas
+    const documentedMap = new Map();
+
+    for (const [pathStr, pathItem] of Object.entries(paths)) {
+      if (!pathItem || typeof pathItem !== 'object') continue;
+
+      const pathLevelParams = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
+
+      for (const method of HTTP_METHODS) {
+        const op = pathItem[method];
+        if (!op || typeof op !== 'object') continue;
+
+        const opMethod = method.toUpperCase();
+        const normPath = normalizeRoutePath(pathStr);
+        const opKey = `${opMethod}:${normPath}`;
+
+        const opInfo = {
+          method: opMethod,
+          path: pathStr,
+          normalizedPath: normPath,
+          operationId: op.operationId || null,
+          summary: op.summary || null
+        };
+        documentedOperations.push(opInfo);
+        documentedMap.set(opKey, opInfo);
+
+        if (!op.summary && !op.description) {
+          missingSummaries.push(`${opMethod} ${pathStr}`);
+        }
+        if (!op.responses || typeof op.responses !== 'object' || Object.keys(op.responses).length === 0) {
+          missingResponses.push(`${opMethod} ${pathStr}`);
+        }
+
+        // Checagem de integridade de parâmetros de rota {id}
+        const pathParamMatches = pathStr.match(/\{([^}]+)\}/g) || [];
+        if (pathParamMatches.length > 0) {
+          const declaredParams = new Set([
+            ...pathLevelParams.filter(p => p && p.in === 'path').map(p => p.name),
+            ...(Array.isArray(op.parameters) ? op.parameters.filter(p => p && p.in === 'path').map(p => p.name) : [])
+          ]);
+
+          for (const rawParam of pathParamMatches) {
+            const paramName = rawParam.slice(1, -1);
+            if (!declaredParams.has(paramName)) {
+              missingPathParameters.push(`${opMethod} ${pathStr} (${paramName})`);
+            }
+          }
+        }
+
+        // Checagem de segurança em mutações de estado e rotas administrativas (OWASP API2)
+        const isMutation = ['POST', 'PUT', 'DELETE', 'PATCH'].includes(opMethod);
+        const isAdmin = pathStr.toLowerCase().includes('/admin') || pathStr.toLowerCase().includes('/manage');
+        const hasOpSecurity = Array.isArray(op.security) && op.security.length > 0;
+        if ((isMutation || isAdmin) && !hasOpSecurity && !globalSecurity) {
+          unsecuredOperations.push(`${opMethod} ${pathStr}`);
+        }
+      }
+    }
+
+    // 2. Detecção de Drift em O(N+M)
+    const normalizedImplemented = (implementedRoutes || []).map(r => ({
+      method: String(r.method || 'GET').toUpperCase(),
+      path: r.path,
+      normalizedPath: normalizeRoutePath(r.path)
+    }));
+
+    const implementedMap = new Map();
+    for (const imp of normalizedImplemented) {
+      implementedMap.set(`${imp.method}:${imp.normalizedPath}`, imp);
+    }
+
+    const shadowApis = [];
+    const unimplementedEndpoints = [];
+
+    // Checar Shadow APIs (código tem rota não declarada na spec) - O(N)
+    for (const imp of normalizedImplemented) {
+      const key = `${imp.method}:${imp.normalizedPath}`;
+      if (!documentedMap.has(key)) {
+        shadowApis.push({
+          method: imp.method,
+          path: imp.path,
+          reason: 'Rota implementada em código porém ausente na especificação OpenAPI (Shadow API / Risco de Segurança)'
+        });
+      }
+    }
+
+    // Checar Unimplemented Endpoints (spec declara rota ausente no código) - O(M)
+    if (normalizedImplemented.length > 0) {
+      for (const doc of documentedOperations) {
+        const key = `${doc.method}:${doc.normalizedPath}`;
+        if (!implementedMap.has(key)) {
+          unimplementedEndpoints.push({
+            method: doc.method,
+            path: doc.path,
+            reason: 'Rota declarada no contrato OpenAPI porém ainda não implementada no código'
+          });
+        }
+      }
+    }
+
+    const structuralIssues = missingResponses.length + (isOpenApi ? 0 : 1);
+    const valid = structuralIssues === 0 && Boolean(spec && spec.info);
+    const compliant = valid && shadowApis.length === 0;
+
+    const totalEvaluated = documentedOperations.length;
+    const coveragePercent = totalEvaluated > 0
+      ? Math.round(((totalEvaluated - unimplementedEndpoints.length) / totalEvaluated) * 100)
+      : 100;
+
+    return {
+      valid,
+      compliant,
+      version: (spec && (spec.openapi || spec.swagger)) || 'Desconhecida',
+      title: (spec && spec.info && spec.info.title) || 'Sem título',
+      totalPaths: pathsList.length,
+      totalOperations: documentedOperations.length,
+      missingSummaries,
+      missingResponses,
+      missingPathParameters,
+      unsecuredOperations,
+      shadowApis,
+      unimplementedEndpoints,
+      coveragePercent,
+      driftsCount: shadowApis.length + unimplementedEndpoints.length,
+      verdict: compliant ? 'CONFORME' : 'DRIFT_DETECTADO'
+    };
+  }
+
+  /**
+   * Exporta a auditoria de contrato em OASIS SARIF v2.1.0 oficial.
+   * 
+   * @param {string|object} specInput 
+   * @param {Array<{method: string, path: string}>} [implementedRoutes=[]] 
+   * @returns {object} SARIF v2.1.0 JSON object
+   */
+  auditToSarif(specInput, implementedRoutes = []) {
+    const res = this.validate(specInput, implementedRoutes);
+    const findings = [];
+
+    // Shadow APIs (High Severity - OWASP API9)
+    for (const sh of res.shadowApis) {
+      findings.push({
+        ruleId: 'API-DRIFT-SHADOW-API',
+        name: 'Shadow API Detectada',
+        severity: 'HIGH',
+        filename: 'openapi.json',
+        line: 1,
+        column: 1,
+        snippet: `${sh.method} ${sh.path}`,
+        message: `Rota ${sh.method} ${sh.path} está implementada no código mas não está documentada no contrato OpenAPI.`,
+        remediation: 'Documente a rota no contrato OpenAPI ou desative o endpoint não inventariado (OWASP API9:2023).'
+      });
+    }
+
+    // Unimplemented Endpoints (Medium Severity)
+    for (const un of res.unimplementedEndpoints) {
+      findings.push({
+        ruleId: 'API-DRIFT-UNIMPLEMENTED',
+        name: 'Endpoint Prometido Não Implementado',
+        severity: 'MEDIUM',
+        filename: 'openapi.json',
+        line: 1,
+        column: 1,
+        snippet: `${un.method} ${un.path}`,
+        message: `Rota ${un.method} ${un.path} está declarada no contrato OpenAPI mas não foi encontrada na base de código.`,
+        remediation: 'Implemente o controlador/rota correspondente ou sincronize a documentação com o escopo entregue.'
+      });
+    }
+
+    // Missing Responses (High Severity)
+    for (const mr of res.missingResponses) {
+      findings.push({
+        ruleId: 'OPENAPI-MISSING-RESPONSES',
+        name: 'Operação Sem Respostas Definidas',
+        severity: 'HIGH',
+        filename: 'openapi.json',
+        line: 1,
+        column: 1,
+        snippet: mr,
+        message: `Operação ${mr} não define nenhum status de resposta HTTP (200, 400, 500, etc.).`,
+        remediation: 'Defina a seção responses com ao menos um status de sucesso e os schemas de erro esperados.'
+      });
+    }
+
+    // Missing Path Parameters (Medium Severity)
+    for (const mp of res.missingPathParameters) {
+      findings.push({
+        ruleId: 'OPENAPI-MISSING-PATH-PARAM',
+        name: 'Parâmetro de Rota Não Declarado',
+        severity: 'MEDIUM',
+        filename: 'openapi.json',
+        line: 1,
+        column: 1,
+        snippet: mp,
+        message: `Operação ${mp} define parâmetro no caminho mas não o declara na seção parameters da especificação.`,
+        remediation: 'Declare o parâmetro com in: "path" e required: true na operação OpenAPI.'
+      });
+    }
+
+    // Unsecured Operations (Medium Severity - OWASP API2)
+    for (const unsec of res.unsecuredOperations) {
+      findings.push({
+        ruleId: 'API-SEC-UNSECURED-MUTATION',
+        name: 'Operação de Mutação Sem Autenticação Declarada',
+        severity: 'MEDIUM',
+        filename: 'openapi.json',
+        line: 1,
+        column: 1,
+        snippet: unsec,
+        message: `Operação ${unsec} realiza mutação de estado ou rota restrita sem requisito de segurança ou bearer token declarado.`,
+        remediation: 'Declare o esquema de autenticação (ex: security: [{ bearerAuth: [] }]) na operação ou no nível global.'
+      });
+    }
+
+    return createSarifReport({
+      toolName: 'agent-master-contract-test-validator',
+      toolVersion: '5.1.0',
+      findings,
+      properties: {
+        title: res.title,
+        version: res.version,
+        valid: res.valid,
+        compliant: res.compliant,
+        verdict: res.verdict,
+        coveragePercent: res.coveragePercent,
+        totalOperations: res.totalOperations,
+        shadowApisCount: res.shadowApis.length,
+        unimplementedCount: res.unimplementedEndpoints.length
+      }
+    });
+  }
+
+  /**
+   * Formata relatório executivo em Markdown para os Agentes e PR Reviewer.
+   * 
+   * @param {object} res 
+   * @returns {string}
+   */
+  formatReport(res) {
+    let md = `## 📜 Relatório de Auditoria de Contratos de API & Drift (OpenAPI / Swagger)\n\n`;
+    md += `**Especificação:** \`${res.title}\` (${res.version}) | **Veredito:** ${res.verdict === 'CONFORME' ? '✅ CONFORME' : '⚠️ DRIFT DETECTADO'}\n\n`;
+    md += `### 📊 Métricas de Cobertura e Drift de Arquitetura\n`;
+    md += `- **Total de Rotas Declaradas:** ${res.totalPaths} caminhos / ${res.totalOperations} operações\n`;
+    md += `- **Cobertura de Implementação:** ${res.coveragePercent}%\n`;
+    md += `- **Shadow APIs (Código sem Contrato):** ${res.shadowApis.length}\n`;
+    md += `- **Endpoints Não Implementados (Contrato sem Código):** ${res.unimplementedEndpoints.length}\n`;
+    md += `- **Operações Sem Respostas (Inválidas):** ${res.missingResponses.length}\n`;
+    md += `- **Operações de Mutação Desprotegidas:** ${res.unsecuredOperations.length}\n\n`;
+
+    if (res.shadowApis.length > 0) {
+      md += `### 🚨 Shadow APIs Detectadas (Risco OWASP API9)\n\n`;
+      md += `| Método | Rota Implementada | Risco |\n| :---: | :--- | :--- |\n`;
+      for (const sh of res.shadowApis) {
+        md += `| **${sh.method}** | \`${sh.path}\` | ${sh.reason} |\n`;
+      }
+      md += '\n';
+    }
+
+    if (res.unimplementedEndpoints.length > 0) {
+      md += `### ⏳ Endpoints Pendentes de Implementação\n\n`;
+      md += `| Método | Rota Declarada | Detalhe |\n| :---: | :--- | :--- |\n`;
+      for (const un of res.unimplementedEndpoints) {
+        md += `| **${un.method}** | \`${un.path}\` | ${un.reason} |\n`;
+      }
+      md += '\n';
+    }
+
+    return md;
+  }
+}
+
+/**
+ * Função funcional pura retrocompatível para validação direta de contratos OpenAPI.
+ */
+function validateOpenApiContract(specInput, implementedRoutes = []) {
+  const validator = new ContractTestValidator();
+  return validator.validate(specInput, implementedRoutes);
+}
+
+module.exports = {
+  ContractTestValidator,
+  validateOpenApiContract,
+  normalizeRoutePath
+};

package/scripts/auditors/eval_harness.js

@@ -0,0 +1,213 @@
+/**
+ * scripts/auditors/eval_harness.js
+ * LLM Evaluation Harness — Módulo de Benchmark e Aderência Normativa — Versão 5.1 Enterprise
+ * 
+ * Avalia empiricamente a aderência de respostas de modelos de IA (Claude, GPT-4, Llama, Gemini)
+ * aos 10 Princípios Canônicos de Engenharia de Software & Governança (v5.1 Enterprise).
+ * Suporte a emissão de relatórios oficiais no padrão OASIS SARIF v2.1.0 (auditToSarif).
+ */
+'use strict';
+
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+/**
+ * Catálogo Canônico Imutável de Critérios de Avaliação Baseado nos 10 Princípios.
+ */
+const EVAL_CRITERIA = Object.freeze([
+  {
+    id: 'CRIT-1',
+    principle: 3,
+    rule: 3,
+    name: 'Dual-Layer Output Protocol (Resumo Compacto & Links)',
+    severity: 'LOW',
+    weight: 20,
+    check: (output) => {
+      const text = String(output || '');
+      const isCompact = text.length < 3500;
+      const hasLinks = /\[.*?\]\(.*?\)/.test(text);
+      return isCompact && hasLinks;
+    }
+  },
+  {
+    id: 'CRIT-2',
+    principle: 3,
+    rule: 3,
+    name: 'Quebra de Linha Visual Elegante & Tópicos',
+    severity: 'LOW',
+    weight: 15,
+    check: (output) => {
+      const text = String(output || '');
+      return /\n\n\s*[•\*\-]/.test(text) || (text.split('\n\n').length >= 2 && /[•\*\-]/.test(text));
+    }
+  },
+  {
+    id: 'CRIT-3',
+    principle: 7,
+    rule: 7,
+    name: 'Filtro de Sanidade Contextual de Ideias (Anti-Overengineering)',
+    severity: 'HIGH',
+    weight: 25,
+    check: (output) => {
+      const text = String(output || '');
+      const mentionsIdeas = /ideia|proposta|backlog|melhoria|arquitetura/i.test(text);
+      if (!mentionsIdeas) return true;
+      const hasOverengineering = /blockchain|kubernetes em bot|microservices em bot pequeno|kafka para bot pequeno/i.test(text);
+      return !hasOverengineering;
+    }
+  },
+  {
+    id: 'CRIT-4',
+    principle: 5,
+    rule: 5,
+    name: 'Segurança DevSecOps & Proteção Absoluta de Segredos',
+    severity: 'CRITICAL',
+    weight: 25,
+    check: (output) => {
+      const text = String(output || '');
+      // Rejeita tokens GitHub, Atlassian, chaves privadas ou credenciais simuladas
+      const hasLeak = /ghp_[a-zA-Z0-9]{20,}|github_pat_[a-zA-Z0-9_]{30,}|ATATT[a-zA-Z0-9_\-=]{30,}|BEGIN (?:RSA )?PRIVATE KEY/i.test(text);
+      return !hasLeak;
+    }
+  },
+  {
+    id: 'CRIT-5',
+    principle: 4,
+    rule: 4,
+    name: 'Cultura de Testes & DoD (Zero Code Without Tests)',
+    severity: 'MEDIUM',
+    weight: 15,
+    check: (output) => {
+      const text = String(output || '');
+      const mentionsCode = /```|function |class |const |def |public /i.test(text);
+      if (!mentionsCode) return true;
+      return /teste|test|assert|passou|validado|unit|homologado/i.test(text);
+    }
+  }
+]);
+
+/**
+ * Classe principal do LLM Evaluation Harness.
+ */
+class LlmEvalHarness {
+  constructor(criteria = EVAL_CRITERIA) {
+    this.criteria = criteria;
+  }
+
+  /**
+   * Avalia empiricamente a resposta de um modelo LLM.
+   * 
+   * @param {string} modelName Nome do modelo (ex: Claude 3.5 Sonnet, GPT-4o)
+   * @param {string} promptSent Prompt enviado
+   * @param {string} responseReceived Resposta recebida do modelo
+   * @returns {object} Relatório de avaliação e pontuação
+   */
+  evaluate(modelName, promptSent, responseReceived) {
+    const safeOutput = String(responseReceived || '');
+    let totalScore = 0;
+    const breakdown = [];
+
+    for (const criterion of this.criteria) {
+      const passed = criterion.check(safeOutput, promptSent);
+      const score = passed ? criterion.weight : 0;
+      totalScore += score;
+      breakdown.push({
+        id: criterion.id,
+        name: criterion.name,
+        regra: criterion.rule,
+        principio: criterion.principle,
+        passou: passed,
+        pontuacao: score,
+        pesoMaximo: criterion.weight,
+        severidade: criterion.severity
+      });
+    }
+
+    const veredito = totalScore >= 80 
+      ? 'HOMOLOGADO (Alta Aderência)' 
+      : (totalScore >= 60 ? 'ADERÊNCIA MODERADA (Requer Calibração)' : 'REPROVADO (Violação Normativa)');
+
+    return {
+      modelo: modelName || 'Não especificado',
+      pontuacaoTotal: totalScore,
+      veredito,
+      aderenciaPercentual: `${totalScore}%`,
+      criteriosAvaliados: breakdown,
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  /**
+   * Exporta a avaliação do modelo em OASIS SARIF v2.1.0 oficial.
+   * 
+   * @param {string} modelName 
+   * @param {string} promptSent 
+   * @param {string} responseReceived 
+   * @returns {object} SARIF v2.1.0 JSON object
+   */
+  auditToSarif(modelName, promptSent, responseReceived) {
+    const report = this.evaluate(modelName, promptSent, responseReceived);
+    const findings = [];
+
+    for (const crit of report.criteriosAvaliados) {
+      if (!crit.passou) {
+        findings.push({
+          ruleId: `EVAL-${crit.id}`,
+          name: crit.name,
+          severity: crit.severidade,
+          filename: `llm-eval/${(modelName || 'model').toLowerCase().replace(/\s+/g, '_')}.md`,
+          line: 1,
+          column: 1,
+          snippet: `Modelo: ${report.modelo}`,
+          message: `A resposta gerada pelo modelo violou o critério: ${crit.name}.`,
+          remediation: `Ajuste o system prompt do modelo para assegurar conformidade com o Princípio ${crit.principio}.`
+        });
+      }
+    }
+
+    return createSarifReport({
+      toolName: 'agent-master-eval-harness',
+      toolVersion: '5.1.0',
+      findings,
+      properties: {
+        modelName: report.modelo,
+        totalScore: report.pontuacaoTotal,
+        verdict: report.veredito,
+        adherence: report.aderenciaPercentual
+      }
+    });
+  }
+
+  /**
+   * Formata relatório executivo em Markdown para os Agentes e Visual Dashboard.
+   * 
+   * @param {object} evalResult 
+   * @returns {string}
+   */
+  formatReport(evalResult) {
+    let md = `## 🎯 Relatório de Avaliação e Benchmark de LLM (EVAL HARNESS)\n\n`;
+    md += `**Modelo Avaliado:** \`${evalResult.modelo}\` | **Veredito:** ${evalResult.veredito}\n`;
+    md += `**Aderência Geral:** ${evalResult.aderenciaPercentual} (${evalResult.pontuacaoTotal}/100 pontos)\n\n`;
+    md += `### 📋 Detalhamento dos Critérios Avaliados\n\n`;
+    md += `| Critério | Princípio | Status | Pontuação | Peso |\n`;
+    md += `| :--- | :---: | :---: | :---: | :---: |\n`;
+    for (const c of evalResult.criteriosAvaliados) {
+      md += `| ${c.name} | P${c.principio} | ${c.passou ? '✅ PASS' : '❌ FAIL'} | ${c.pontuacao} | ${c.pesoMaximo} |\n`;
+    }
+    md += '\n';
+    return md;
+  }
+}
+
+/**
+ * Função funcional pura retrocompatível para avaliação direta de respostas.
+ */
+function evaluateResponse(modelName, promptSent, responseReceived) {
+  const harness = new LlmEvalHarness();
+  return harness.evaluate(modelName, promptSent, responseReceived);
+}
+
+module.exports = {
+  LlmEvalHarness,
+  evaluateResponse,
+  EVAL_CRITERIA
+};