agent-master-devsecops 0.0.0-stage → 5.1.0

package/scripts/integrations/credentials_guard.js

@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+/**
+ * scripts/integrations/credentials_guard.js
+ * 
+ * Guardião Canônico Unificado de Credenciais, Healthcheck e Imutabilidade de Requisitos (Regras 15 e 17).
+ * Consolida o Healthcheck interativo de credenciais Atlassian/GitHub e a validação inviolável da Regra 15.
+ * Garante obtenção ativa, pré-validação compulsória, mascaramento de segredos e zero falhas silenciosas em todos os vetores.
+ * 
+ * Versão: 5.1.0 Enterprise
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  getAtlassianCredentials,
+  checkGithubAuth,
+  getGitRepositoryUrl,
+  getGitMetadata,
+  AtlassianClient,
+  auditToSarif: auditAtlassianToSarifBase
+} = require('./atlassian_client.js');
+
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+class InviolableRuleError extends Error {
+  constructor(message, missingRequirements = [], remediationSteps = []) {
+    super(message);
+    this.name = 'InviolableRuleError';
+    this.rule = 'Regra 15 - Imutabilidade de Requisitos & Validação Compulsória de Segredos';
+    this.missingRequirements = missingRequirements;
+    this.remediationSteps = remediationSteps;
+  }
+}
+
+/**
+ * Utilitário puro de mascaramento defensivo de segredos (evita CWE-798 / CWE-200 em logs e relatórios).
+ * @param {string} secret
+ * @param {number} [visibleChars=4]
+ * @returns {string}
+ */
+function maskSecret(secret, visibleChars = 4) {
+  if (!secret || typeof secret !== 'string') return '';
+  if (secret.length <= visibleChars) return '****';
+  const visible = secret.slice(-visibleChars);
+  return `${'*'.repeat(Math.min(12, secret.length - visibleChars))}${visible}`;
+}
+
+/**
+ * Helpers funcionais puros para merge seguro de .env
+ */
+function parseEnvLines(content) {
+  if (!content || typeof content !== 'string') return [];
+  return content.split(/\r?\n/);
+}
+
+function mergeEnvUpdates(existingContent, updates = {}) {
+  const lines = parseEnvLines(existingContent);
+  const updatedKeys = new Set();
+  const validUpdates = Object.entries(updates).filter(([_, val]) => val !== undefined && val !== null && val !== '');
+
+  const newLines = lines.map(line => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return line;
+    for (const [key, val] of validUpdates) {
+      if (trimmed.startsWith(`${key}=`)) {
+        updatedKeys.add(key);
+        return `${key}=${val}`;
+      }
+    }
+    return line;
+  });
+
+  for (const [key, val] of validUpdates) {
+    if (!updatedKeys.has(key)) {
+      newLines.push(`${key}=${val}`);
+    }
+  }
+
+  return newLines.filter(line => line !== undefined && line !== null).join('\n').trim() + '\n';
+}
+
+function ensureGitignoreProtected(existingContent, entries = ['.env', '.env.local']) {
+  const content = typeof existingContent === 'string' ? existingContent : '';
+  const lines = content.split(/\r?\n/).map(l => l.trim());
+  const missingEntries = entries.filter(entry => !lines.includes(entry));
+
+  if (missingEntries.length === 0) {
+    return { modified: false, content };
+  }
+
+  let updatedContent = content.trimEnd();
+  if (updatedContent.length > 0) updatedContent += '\n';
+  updatedContent += '\n# Segurança - Credenciais e Segredos (Regra 15)\n';
+  updatedContent += missingEntries.join('\n') + '\n';
+
+  return { modified: true, content: updatedContent };
+}
+
+/**
+ * Validação rigorosa da Regra 15 com suporte a Fail-Fast.
+ */
+function validateRule15({ failFast = true, requireGitHub = true, requireAtlassian = true } = {}) {
+  const missing = [];
+  const remediation = [];
+
+  const atlassian = getAtlassianCredentials();
+  if (requireAtlassian && !atlassian.isConfigured) {
+    if (!atlassian.token) missing.push('ATLASSIAN_API_TOKEN');
+    if (!atlassian.email) missing.push('ATLASSIAN_EMAIL');
+    if (!atlassian.domain) missing.push('ATLASSIAN_DOMAIN');
+
+    remediation.push(
+      'Configurar variáveis de ambiente ou secrets no GitHub Actions: gh secret set ATLASSIAN_API_TOKEN / ATLASSIAN_EMAIL / ATLASSIAN_DOMAIN'
+    );
+  }
+
+  const github = checkGithubAuth();
+  if (requireGitHub && !github.isAuthenticated) {
+    missing.push('GITHUB_AUTH (gh CLI ou GITHUB_TOKEN)');
+    remediation.push('Autenticar GitHub CLI via "gh auth login" ou exportar GITHUB_TOKEN');
+  }
+
+  const isValid = missing.length === 0;
+
+  if (!isValid && failFast) {
+    const msg = `[REGRA 15 INVIOLÁVEL: PRÉ-REQUISITOS NÃO ATENDIDOS]\n` +
+      `Faltam credenciais/ferramentas obrigatórias: ${missing.join(', ')}\n` +
+      `Remediação: ${remediation.join(' | ')}`;
+    throw new InviolableRuleError(msg, missing, remediation);
+  }
+
+  return {
+    valid: isValid,
+    missing,
+    remediation,
+    atlassian,
+    github
+  };
+}
+
+/**
+ * Verifica credenciais Atlassian a partir do diretório alvo.
+ */
+function checkAtlassianAuth(targetDir = process.cwd()) {
+  const creds = getAtlassianCredentials(targetDir);
+  const missingFields = [];
+  if (!creds.token) missingFields.push('token');
+  if (!creds.email) missingFields.push('email');
+  if (!creds.domain) missingFields.push('domain');
+
+  return {
+    configured: creds.isConfigured,
+    email: creds.email,
+    domain: creds.domain,
+    tokenPresent: Boolean(creds.token),
+    maskedToken: maskSecret(creds.token),
+    source: creds.source,
+    missingFields
+  };
+}
+
+/**
+ * Configura credenciais no arquivo .env e garante proteção no .gitignore.
+ */
+function configureCredentials(targetDir = process.cwd(), credentials = {}) {
+  const dir = typeof targetDir === 'string' && targetDir ? targetDir : process.cwd();
+  const safeCreds = credentials && typeof credentials === 'object' ? credentials : {};
+
+  const updates = {
+    ATLASSIAN_DOMAIN: safeCreds.domain,
+    ATLASSIAN_EMAIL: safeCreds.email,
+    ATLASSIAN_API_TOKEN: safeCreds.token,
+    JIRA_PROJECT_KEY: safeCreds.jiraKey,
+    CONFLUENCE_SPACE_KEY: safeCreds.confluenceSpace,
+    GITHUB_TOKEN: safeCreds.githubToken
+  };
+
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const envPath = path.join(dir, '.env');
+    const existingEnv = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8') : '';
+    const updatedEnv = mergeEnvUpdates(existingEnv, updates);
+    fs.writeFileSync(envPath, updatedEnv, 'utf8');
+
+    const gitignorePath = path.join(dir, '.gitignore');
+    const existingGitignore = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+    const { modified, content: updatedGitignore } = ensureGitignoreProtected(existingGitignore);
+    if (modified || !fs.existsSync(gitignorePath)) {
+      fs.writeFileSync(gitignorePath, updatedGitignore, 'utf8');
+    }
+
+    return {
+      status: 'SUCCESS',
+      success: true,
+      envPath,
+      configuredKeys: Object.keys(updates).filter(k => updates[k])
+    };
+  } catch (err) {
+    return {
+      status: 'ERROR',
+      success: false,
+      error: err.message,
+      configuredKeys: []
+    };
+  }
+}
+
+/**
+ * Executa o diagnóstico completo de saúde das credenciais Atlassian e GitHub.
+ */
+function runCredentialHealthcheck(targetDir = process.cwd()) {
+  const safeDir = typeof targetDir === 'string' && targetDir ? targetDir : process.cwd();
+  const gh = checkGithubAuth();
+  const atlassian = checkAtlassianAuth(safeDir);
+
+  const gitignorePath = path.join(safeDir, '.gitignore');
+  let envIgnored = false;
+  if (fs.existsSync(gitignorePath)) {
+    const gitignoreContent = fs.readFileSync(gitignorePath, 'utf8');
+    envIgnored = gitignoreContent.includes('.env');
+  }
+
+  const missing = [];
+  const remediation = [];
+
+  if (!gh.authenticated) {
+    missing.push('GitHub CLI');
+    remediation.push({
+      tool: 'GitHub CLI',
+      command: 'gh auth login',
+      instruction: 'Execute "gh auth login" no terminal para autenticar sua conta GitHub no CLI.'
+    });
+  }
+
+  if (!atlassian.configured) {
+    const missingItems = (atlassian.missingFields || []).join(', ');
+    missing.push(`Credenciais Atlassian (${missingItems})`);
+    remediation.push({
+      tool: 'Atlassian Cloud (Jira & Confluence)',
+      instruction: 'Cadastre suas credenciais no arquivo .env ou execute "npx agent-master-init":',
+      requiredVariables: {
+        ATLASSIAN_DOMAIN: 'seu-subdominio.atlassian.net',
+        ATLASSIAN_EMAIL: '<seu_email_corporativo>',
+        ATLASSIAN_API_TOKEN: 'https://id.atlassian.com/manage-profile/security/api-tokens'
+      }
+    });
+  }
+
+  if (!envIgnored && fs.existsSync(path.join(safeDir, '.env'))) {
+    remediation.push({
+      tool: 'Git Security Guard',
+      instruction: 'Adicione ".env" ao seu arquivo .gitignore para evitar o commit acidental de credenciais.'
+    });
+  }
+
+  const allReady = gh.authenticated && atlassian.configured;
+
+  let promptGuidance = '';
+  if (!allReady) {
+    promptGuidance = `⚠️ [ALERTA DE CONFIGURAÇÃO DE AMBIENTE - REGRA 15]\n` +
+      `Faltam credenciais essenciais para o funcionamento autônomo da suíte:\n` +
+      remediation.map(r => `- ${r.tool}: ${r.instruction || r.command}`).join('\n') +
+      `\nSolicite as credenciais ao usuário ou instrua a execução de "gh auth login" antes de prosseguir com tarefas que exijam Jira/Confluence/Git.`;
+  } else {
+    promptGuidance = '✅ Todas as integrações (GitHub, Jira e Confluence) estão configuradas e prontas para operação autônoma.';
+  }
+
+  return {
+    allReady,
+    github: gh,
+    atlassian,
+    envProtected: envIgnored,
+    missing,
+    remediation,
+    promptGuidance
+  };
+}
+
+/**
+ * Formata relatório executivo em Markdown sobre o status das credenciais e conformidade com a Regra 15.
+ * @param {object} [health={}]
+ * @returns {string}
+ */
+function formatReport(health = {}) {
+  const safeHealth = health && typeof health === 'object' ? health : {};
+  let md = '# 🛡️ Credentials Guard — Status Report de Credenciais & Regra 15\n\n';
+
+  const allReady = Boolean(safeHealth.allReady);
+  const statusBadge = allReady ? '🟢 **HOMOLOGADO**' : '🔴 **PENDENTE DE CONFIGURAÇÃO**';
+
+  md += `**Status Global:** ${statusBadge}\n\n`;
+  md += '| Componente / Integração | Status | Detalhes | Ação Recomendada |\n';
+  md += '| :--- | :---: | :--- | :--- |\n';
+
+  const gh = safeHealth.github || {};
+  const ghStatus = gh.authenticated ? '✅ Conectado' : '❌ Não autenticado';
+  const ghDetails = gh.user ? `Usuário: \`${gh.user}\`` : 'Token/CLI ausente';
+  const ghAction = gh.authenticated ? 'Nenhuma' : 'Executar `gh auth login`';
+  md += `| **GitHub CLI / Token** | ${ghStatus} | ${ghDetails} | ${ghAction} |\n`;
+
+  const atl = safeHealth.atlassian || {};
+  const atlStatus = atl.configured ? '✅ Configurado' : '❌ Incompleto';
+  const atlDetails = atl.configured
+    ? `Domínio: \`${atl.domain || 'N/A'}\` | Email: \`${atl.email || 'N/A'}\``
+    : `Campos faltantes: \`${(atl.missingFields || []).join(', ') || 'todos'}\``;
+  const atlAction = atl.configured ? 'Nenhuma' : 'Configurar variáveis no `.env`';
+  md += `| **Atlassian Cloud (Jira & Confluence)** | ${atlStatus} | ${atlDetails} | ${atlAction} |\n`;
+
+  if (safeHealth.envProtected !== undefined) {
+    const envStatus = safeHealth.envProtected ? '✅ Protegido' : '⚠️ Desprotegido';
+    const envDetails = safeHealth.envProtected ? '`.env` consta no `.gitignore`' : '`.env` ausente do `.gitignore`';
+    const envAction = safeHealth.envProtected ? 'Nenhuma' : 'Adicionar `.env` ao `.gitignore`';
+    md += `| **Proteção de Segredos (.gitignore)** | ${envStatus} | ${envDetails} | ${envAction} |\n`;
+  }
+
+  md += '\n';
+
+  if (!allReady && Array.isArray(safeHealth.remediation) && safeHealth.remediation.length > 0) {
+    md += '### 🛠️ Ações de Remediação Imediata\n\n';
+    for (const r of safeHealth.remediation) {
+      md += `- **${r.tool}:** ${r.instruction || r.command}\n`;
+    }
+  }
+
+  return md;
+}
+
+/**
+ * Audita a prontidão de credenciais e integridade emitindo relatório oficial no formato OASIS SARIF v2.1.0.
+ * @param {object} [result={}]
+ * @returns {object} SARIF v2.1.0 JSON object
+ */
+function auditToSarif(result = {}) {
+  const safeResult = result && typeof result === 'object' ? result : {};
+  const rules = [
+    {
+      id: 'RULE-SEC-015',
+      name: 'MissingRequiredCredentials',
+      severity: 'HIGH',
+      message: 'Credenciais essenciais da Regra 15 ausentes (Jira, Confluence ou GitHub).'
+    },
+    {
+      id: 'RULE-SEC-016',
+      name: 'GitignoreEnvUnprotected',
+      severity: 'CRITICAL',
+      message: 'Arquivo de ambiente .env desprotegido no .gitignore (Risco de vazamento de segredos).'
+    },
+    {
+      id: 'RULE-SEC-017',
+      name: 'GitHubCliUnauthenticated',
+      severity: 'MEDIUM',
+      message: 'CLI do GitHub (gh) não está autenticado.'
+    }
+  ];
+
+  const findings = [];
+
+  // Avaliação baseada em validateRule15
+  if (safeResult.valid === false && Array.isArray(safeResult.missing)) {
+    findings.push({
+      ruleId: 'RULE-SEC-015',
+      message: `Regra 15 violada: Faltam pré-requisitos obrigatórios (${safeResult.missing.join(', ')}).`,
+      filePath: '.env',
+      line: 1,
+      column: 1
+    });
+  }
+
+  // Avaliação baseada em runCredentialHealthcheck
+  if (safeResult.allReady === false) {
+    if (safeResult.atlassian && !safeResult.atlassian.configured) {
+      findings.push({
+        ruleId: 'RULE-SEC-015',
+        message: `Credenciais Atlassian não configuradas (${(safeResult.atlassian.missingFields || []).join(', ')}).`,
+        filePath: '.env',
+        line: 1,
+        column: 1
+      });
+    }
+
+    if (safeResult.github && !safeResult.github.authenticated) {
+      findings.push({
+        ruleId: 'RULE-SEC-017',
+        message: 'GitHub CLI não autenticado no ambiente local.',
+        filePath: '.git/config',
+        line: 1,
+        column: 1
+      });
+    }
+  }
+
+  if (safeResult.envProtected === false) {
+    findings.push({
+      ruleId: 'RULE-SEC-016',
+      message: 'Arquivo .env detectado sem proteção de entrada correspondente no .gitignore (CWE-798).',
+      filePath: '.gitignore',
+      line: 1,
+      column: 1
+    });
+  }
+
+  return createSarifReport({
+    toolName: 'agent-credentials-guard',
+    toolVersion: '5.1.0',
+    rules,
+    findings,
+    properties: {
+      category: 'Security & Secret Management',
+      rule: 'Regra 15 - Imutabilidade de Requisitos & Validação Compulsória de Segredos'
+    }
+  });
+}
+
+/**
+ * Classe Canônica CredentialsGuard
+ */
+class CredentialsGuard {
+  constructor(options = {}) {
+    this.targetDir = typeof options.targetDir === 'string' && options.targetDir ? options.targetDir : process.cwd();
+    this.logger = options.logger || console;
+    this.dryRun = Boolean(options.dryRun);
+  }
+
+  validateRule15(opts = {}) {
+    return CredentialsGuard.validateRule15(opts);
+  }
+
+  checkAtlassianAuth(targetDir = this.targetDir) {
+    return CredentialsGuard.checkAtlassianAuth(targetDir);
+  }
+
+  checkGithubAuth() {
+    return CredentialsGuard.checkGithubAuth();
+  }
+
+  configureCredentials(targetDir = this.targetDir, credentials = {}) {
+    return CredentialsGuard.configureCredentials(targetDir, credentials);
+  }
+
+  runCredentialHealthcheck(targetDir = this.targetDir) {
+    return CredentialsGuard.runCredentialHealthcheck(targetDir);
+  }
+
+  formatReport(health) {
+    return CredentialsGuard.formatReport(health);
+  }
+
+  auditToSarif(result) {
+    return CredentialsGuard.auditToSarif(result);
+  }
+
+  // Métodos estáticos canônicos
+  static get InviolableRuleError() { return InviolableRuleError; }
+  static validateRule15(opts) { return validateRule15(opts); }
+  static checkAtlassianAuth(dir) { return checkAtlassianAuth(dir); }
+  static checkGithubAuth() { return checkGithubAuth(); }
+  static configureCredentials(dir, creds) { return configureCredentials(dir, creds); }
+  static runCredentialHealthcheck(dir) { return runCredentialHealthcheck(dir); }
+  static formatReport(health) { return formatReport(health); }
+  static auditToSarif(result) { return auditToSarif(result); }
+  static maskSecret(str, chars) { return maskSecret(str, chars); }
+  static parseEnvLines(str) { return parseEnvLines(str); }
+  static mergeEnvUpdates(existing, updates) { return mergeEnvUpdates(existing, updates); }
+  static ensureGitignoreProtected(existing, entries) { return ensureGitignoreProtected(existing, entries); }
+}
+
+if (require.main === module) {
+  const outcome = runCredentialHealthcheck();
+  console.log(formatReport(outcome));
+  if (!outcome.allReady) {
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  CredentialsGuard,
+  InviolableRuleError,
+  validateRule15,
+  getAtlassianConfig: getAtlassianCredentials,
+  getGitHubConfig: checkGithubAuth,
+  checkGitHubAuth: checkGithubAuth,
+  checkGithubAuth,
+  getGitRepositoryUrl,
+  getGitMetadata,
+  checkAtlassianAuth,
+  configureCredentials,
+  runCredentialHealthcheck,
+  formatReport,
+  auditToSarif,
+  auditCredentialsToSarif: auditToSarif,
+  auditAtlassianToSarif: auditAtlassianToSarifBase,
+  maskSecret,
+  AtlassianClient
+};