@saulwade/swl-ses 1.0.0

package/hooks/lib/skill-auditor.js

@@ -0,0 +1,588 @@
+'use strict';
+
+/**
+ * Skill Auditor — Analizadores de auditoría para skills SWL.
+ *
+ * Complementa prompt-injection-scanner.js (analizador "static") con 2 analizadores
+ * adicionales adoptados del patrón de skillshare (7 analizadores):
+ *
+ *   1. dataflow  — Detecta exfiltración de datos (curl/wget/fetch con variables sensibles)
+ *   2. structure — Valida estructura de SKILL.md (frontmatter, campos obligatorios, formato)
+ *
+ * Zero dependencias externas.
+ *
+ * Uso:
+ *   const { auditarSkill, auditarDirectorio } = require('./lib/skill-auditor');
+ *   const resultado = auditarSkill('/ruta/a/habilidades/mi-skill');
+ *   if (resultado.findings.length > 0) { ... }
+ *
+ * @module hooks/lib/skill-auditor
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const SEVERIDADES = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1, INFO: 0 };
+
+const CAMPOS_OBLIGATORIOS = ['name', 'description'];
+
+const CAMPOS_RECOMENDADOS = ['version'];
+
+// ---------------------------------------------------------------------------
+// Analizador: dataflow
+// ---------------------------------------------------------------------------
+
+/**
+ * Patrones de exfiltración de datos.
+ * Detecta intentos de enviar datos sensibles a URLs externas.
+ */
+const PATRONES_EXFILTRACION = [
+  // curl/wget con variables de entorno sensibles
+  { patron: /curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API_KEY)/i, ruleId: 'DF001', severity: 'CRITICAL', desc: 'curl con variable sensible' },
+  { patron: /wget\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API_KEY)/i, ruleId: 'DF002', severity: 'CRITICAL', desc: 'wget con variable sensible' },
+  // fetch/request a URLs con datos
+  { patron: /fetch\s*\(\s*['"`][^'"`]*\$\{/i, ruleId: 'DF003', severity: 'HIGH', desc: 'fetch con interpolación de variables en URL' },
+  // Redirección de archivos sensibles a red
+  { patron: /cat\s+[^\n]*(\.env|credentials|secrets)[^\n]*(curl|wget|nc\s)/i, ruleId: 'DF004', severity: 'CRITICAL', desc: 'lectura de archivo sensible + envío a red' },
+  // nc (netcat) con datos
+  { patron: /nc\s+-[^\n]*\d+\.\d+\.\d+\.\d+/i, ruleId: 'DF005', severity: 'HIGH', desc: 'netcat a IP externa' },
+  // Base64 encode + envío (ofuscación)
+  { patron: /base64\s*[^\n]*(curl|wget|fetch|nc)/i, ruleId: 'DF006', severity: 'HIGH', desc: 'base64 encoding antes de envío a red' },
+  // Lectura de SSH keys
+  { patron: /cat\s+[^\n]*\.ssh\/(id_rsa|id_ed25519|authorized_keys)/i, ruleId: 'DF007', severity: 'CRITICAL', desc: 'lectura de SSH keys' },
+  // Envío a webhook genérico
+  { patron: /https?:\/\/[^\s]*webhook[^\s]*/i, ruleId: 'DF008', severity: 'MEDIUM', desc: 'referencia a webhook URL' },
+];
+
+/**
+ * Ejecuta el analizador de flujo de datos (dataflow).
+ *
+ * @param {string} contenido - Contenido del SKILL.md
+ * @param {string} skillName - Nombre del skill
+ * @returns {Array<object>} Findings
+ */
+function analizarDataflow(contenido, skillName) {
+  const findings = [];
+  const lineas = contenido.split('\n');
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+    for (const { patron, ruleId, severity, desc } of PATRONES_EXFILTRACION) {
+      if (patron.test(linea)) {
+        findings.push({
+          analyzer: 'dataflow',
+          category: 'exfiltration',
+          ruleId,
+          severity,
+          skill: skillName,
+          line: i + 1,
+          snippet: linea.trim().substring(0, 120),
+          description: desc,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Analizador: structure
+// ---------------------------------------------------------------------------
+
+/**
+ * Ejecuta el analizador de estructura de SKILL.md.
+ *
+ * @param {string} contenido - Contenido del SKILL.md
+ * @param {string} skillName - Nombre del skill (del directorio)
+ * @returns {Array<object>} Findings
+ */
+function analizarStructure(contenido, skillName) {
+  const findings = [];
+
+  // Verificar que tiene frontmatter
+  if (!contenido.startsWith('---')) {
+    findings.push({
+      analyzer: 'structure',
+      category: 'structure',
+      ruleId: 'ST001',
+      severity: 'HIGH',
+      skill: skillName,
+      line: 1,
+      snippet: contenido.substring(0, 80),
+      description: 'SKILL.md no tiene frontmatter YAML (debe iniciar con ---)',
+    });
+    return findings; // Sin frontmatter no tiene sentido seguir
+  }
+
+  // Extraer frontmatter (soporta --- en primera línea y cierre ---)
+  const fmMatch = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) {
+    findings.push({
+      analyzer: 'structure',
+      category: 'structure',
+      ruleId: 'ST002',
+      severity: 'HIGH',
+      skill: skillName,
+      line: 1,
+      snippet: '---',
+      description: 'Frontmatter YAML no tiene cierre (falta segundo ---)',
+    });
+    return findings;
+  }
+
+  const frontmatter = fmMatch[1];
+
+  // Verificar campos obligatorios
+  for (const campo of CAMPOS_OBLIGATORIOS) {
+    const regex = new RegExp(`^${campo}:`, 'm');
+    if (!regex.test(frontmatter)) {
+      findings.push({
+        analyzer: 'structure',
+        category: 'structure',
+        ruleId: 'ST003',
+        severity: 'HIGH',
+        skill: skillName,
+        line: 1,
+        snippet: `Campo faltante: ${campo}`,
+        description: `Campo obligatorio "${campo}" no encontrado en frontmatter`,
+      });
+    }
+  }
+
+  // Verificar campos recomendados
+  for (const campo of CAMPOS_RECOMENDADOS) {
+    const regex = new RegExp(`^${campo}:`, 'm');
+    if (!regex.test(frontmatter)) {
+      findings.push({
+        analyzer: 'structure',
+        category: 'structure',
+        ruleId: 'ST004',
+        severity: 'LOW',
+        skill: skillName,
+        line: 1,
+        snippet: `Campo faltante: ${campo}`,
+        description: `Campo recomendado "${campo}" no encontrado en frontmatter`,
+      });
+    }
+  }
+
+  // Verificar que name coincide con directorio
+  const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+  if (nameMatch) {
+    const declaredName = nameMatch[1].trim().replace(/['"]/g, '');
+    if (declaredName !== skillName) {
+      findings.push({
+        analyzer: 'structure',
+        category: 'structure',
+        ruleId: 'ST005',
+        severity: 'MEDIUM',
+        skill: skillName,
+        line: 1,
+        snippet: `name: ${declaredName} vs directorio: ${skillName}`,
+        description: `El campo "name" (${declaredName}) no coincide con el directorio (${skillName})`,
+      });
+    }
+  }
+
+  // Verificar que description no está vacía
+  const descMatch = frontmatter.match(/^description:\s*>?\s*\n?\s*(.+)/m);
+  if (descMatch) {
+    const desc = descMatch[1].trim();
+    if (desc.length < 20) {
+      findings.push({
+        analyzer: 'structure',
+        category: 'structure',
+        ruleId: 'ST006',
+        severity: 'MEDIUM',
+        skill: skillName,
+        line: 1,
+        snippet: `description: ${desc.substring(0, 60)}`,
+        description: `Descripción demasiado corta (${desc.length} chars, mínimo 20)`,
+      });
+    }
+  }
+
+  // Verificar que el body no está vacío
+  const bodyStart = contenido.indexOf('---', 4);
+  if (bodyStart > 0) {
+    const body = contenido.substring(bodyStart + 3).trim();
+    if (body.length < 50) {
+      findings.push({
+        analyzer: 'structure',
+        category: 'structure',
+        ruleId: 'ST007',
+        severity: 'MEDIUM',
+        skill: skillName,
+        line: bodyStart + 1,
+        snippet: body.substring(0, 60),
+        description: `Body del skill demasiado corto (${body.length} chars). Un skill útil necesita más contenido`,
+      });
+    }
+  }
+
+  // Verificar tamaño máximo (skills > 300 líneas violan convención)
+  const lineCount = contenido.split('\n').length;
+  if (lineCount > 300) {
+    findings.push({
+      analyzer: 'structure',
+      category: 'structure',
+      ruleId: 'ST008',
+      severity: 'LOW',
+      skill: skillName,
+      line: 300,
+      snippet: `${lineCount} líneas`,
+      description: `Skill excede 300 líneas (${lineCount}). Considerar dividir en sub-recursos`,
+    });
+  }
+
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Analizador: integrity
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica integridad del contenido: links rotos, referencias a archivos inexistentes.
+ *
+ * @param {string} contenido - Contenido del SKILL.md
+ * @param {string} skillName - Nombre del skill
+ * @param {string} skillDir  - Ruta al directorio del skill
+ * @returns {Array<object>} Findings
+ */
+function analizarIntegrity(contenido, skillName, skillDir) {
+  const findings = [];
+  const lineas = contenido.split('\n');
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+
+    // Detectar referencias a archivos locales que no existen
+    const fileRefs = linea.matchAll(/(?:assets|recursos)\/([a-zA-Z0-9_.-]+)/g);
+    for (const match of fileRefs) {
+      const refPath = path.join(skillDir, match[0]);
+      if (!fs.existsSync(refPath)) {
+        findings.push({
+          analyzer: 'integrity',
+          category: 'integrity',
+          ruleId: 'IN001',
+          severity: 'MEDIUM',
+          skill: skillName,
+          line: i + 1,
+          snippet: match[0],
+          description: `Referencia a archivo local inexistente: ${match[0]}`,
+        });
+      }
+    }
+
+    // Detectar placeholders no reemplazados
+    const placeholders = linea.matchAll(/\[TODO\]|\[PENDIENTE\]|\[FIXME\]|<PLACEHOLDER>|\{\{[^}]+\}\}/gi);
+    for (const match of placeholders) {
+      findings.push({
+        analyzer: 'integrity',
+        category: 'integrity',
+        ruleId: 'IN002',
+        severity: 'LOW',
+        skill: skillName,
+        line: i + 1,
+        snippet: match[0],
+        description: `Placeholder no reemplazado: ${match[0]}`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Analizador: metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * Valida metadata del frontmatter contra el schema.
+ *
+ * @param {string} contenido - Contenido del SKILL.md
+ * @param {string} skillName - Nombre del skill
+ * @returns {Array<object>} Findings
+ */
+function analizarMetadata(contenido, skillName) {
+  const findings = [];
+
+  const fmMatch = contenido.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return findings;
+
+  const frontmatter = fmMatch[1];
+
+  // Verificar que version sigue semver si existe
+  const versionMatch = frontmatter.match(/^version:\s*["']?([0-9][0-9a-zA-Z._-]*)["']?/m);
+  if (versionMatch) {
+    const v = versionMatch[1];
+    if (!/^\d+\.\d+\.\d+$/.test(v)) {
+      findings.push({
+        analyzer: 'metadata',
+        category: 'metadata',
+        ruleId: 'MD001',
+        severity: 'LOW',
+        skill: skillName,
+        line: 1,
+        snippet: `version: ${v}`,
+        description: `Versión "${v}" no sigue formato semver (X.Y.Z)`,
+      });
+    }
+  }
+
+  // Verificar que targets contiene valores válidos si existe
+  const targetsMatch = frontmatter.match(/^targets:\s*\[([^\]]+)\]/m);
+  if (targetsMatch) {
+    const VALID_TARGETS = ['claude', 'openclaude', 'copilot', 'opencode', 'codex', 'gemini'];
+    const targets = targetsMatch[1].split(',').map(t => t.trim().replace(/['"]/g, ''));
+    for (const t of targets) {
+      if (!VALID_TARGETS.includes(t)) {
+        findings.push({
+          analyzer: 'metadata',
+          category: 'metadata',
+          ruleId: 'MD002',
+          severity: 'MEDIUM',
+          skill: skillName,
+          line: 1,
+          snippet: `targets: [${targets.join(', ')}]`,
+          description: `Target "${t}" no es un runtime válido de swl-ses`,
+        });
+      }
+    }
+  }
+
+  // Verificar description multilinea con > tiene contenido
+  const descMulti = frontmatter.match(/^description:\s*>\s*$/m);
+  if (descMulti) {
+    const afterDesc = frontmatter.split(/^description:\s*>\s*$/m)[1];
+    if (afterDesc) {
+      const firstLine = afterDesc.split('\n').find(l => l.trim().length > 0);
+      if (!firstLine || firstLine.trim().length < 10) {
+        findings.push({
+          analyzer: 'metadata',
+          category: 'metadata',
+          ruleId: 'MD003',
+          severity: 'MEDIUM',
+          skill: skillName,
+          line: 1,
+          snippet: 'description: >',
+          description: 'Descripción multilinea vacía o demasiado corta',
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Analizador: cross-skill
+// ---------------------------------------------------------------------------
+
+/**
+ * Detecta dependencias entre skills y posibles problemas de acoplamiento.
+ *
+ * @param {string} contenido - Contenido del SKILL.md
+ * @param {string} skillName - Nombre del skill
+ * @param {Set<string>} allSkills - Set con todos los nombres de skills existentes
+ * @returns {Array<object>} Findings
+ */
+function analizarCrossSkill(contenido, skillName, allSkills) {
+  const findings = [];
+
+  // Detectar referencias a otros skills con Skill("nombre")
+  const skillRefs = contenido.matchAll(/Skill\(["']([^"']+)["']\)/g);
+  const referenced = new Set();
+
+  for (const match of skillRefs) {
+    const refName = match[1];
+    referenced.add(refName);
+
+    // Verificar que el skill referenciado existe
+    if (allSkills && !allSkills.has(refName)) {
+      findings.push({
+        analyzer: 'cross-skill',
+        category: 'cross-skill',
+        ruleId: 'CS001',
+        severity: 'MEDIUM',
+        skill: skillName,
+        line: 0,
+        snippet: `Skill("${refName}")`,
+        description: `Referencia a skill inexistente: "${refName}"`,
+      });
+    }
+  }
+
+  // Auto-referencia es normal (documentación de cómo cargar el skill) — no es finding
+
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Analizador: tier
+// ---------------------------------------------------------------------------
+
+/**
+ * Evalúa complejidad y nivel de confianza del skill.
+ *
+ * @param {string} contenido - Contenido del SKILL.md
+ * @param {string} skillName - Nombre del skill
+ * @returns {Array<object>} Findings
+ */
+function analizarTier(contenido, skillName) {
+  const findings = [];
+
+  // Detectar skills que incluyen ejecución de código
+  const codeExecPatterns = [
+    /```(?:bash|sh|shell|python|node|ruby)\n[^`]*(?:rm\s+-rf|chmod\s+777|sudo\s+)/i,
+    /(?:exec|eval|spawn|system)\s*\(/i,
+  ];
+
+  for (const pattern of codeExecPatterns) {
+    if (pattern.test(contenido)) {
+      findings.push({
+        analyzer: 'tier',
+        category: 'risk',
+        ruleId: 'TR001',
+        severity: 'MEDIUM',
+        skill: skillName,
+        line: 0,
+        snippet: 'Skill contiene patrones de ejecución de código potencialmente peligrosos',
+        description: 'Skill incluye ejemplos de ejecución de código con privilegios elevados. Revisar manualmente',
+      });
+      break;
+    }
+  }
+
+  // Detectar skills con instrucciones de modificar archivos del sistema
+  if (/\/etc\/|\/usr\/|C:\\Windows|HKEY_/i.test(contenido)) {
+    findings.push({
+      analyzer: 'tier',
+      category: 'risk',
+      ruleId: 'TR002',
+      severity: 'HIGH',
+      skill: skillName,
+      line: 0,
+      snippet: 'Referencia a rutas del sistema operativo',
+      description: 'Skill referencia rutas del sistema (/etc/, /usr/, Windows registry). Verificar que son ejemplos, no instrucciones',
+    });
+  }
+
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Audita un skill individual ejecutando los 7 analizadores.
+ *
+ * @param {string} skillDir - Ruta al directorio del skill
+ * @param {object} [opciones]
+ * @param {Set<string>} [opciones.allSkills] - Set de todos los skills existentes (para cross-skill)
+ * @returns {{ skill: string, findings: Array, riskScore: number, riskLabel: string }}
+ */
+function auditarSkill(skillDir, opciones) {
+  const skillName = path.basename(skillDir);
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+
+  if (!fs.existsSync(skillMdPath)) {
+    return {
+      skill: skillName,
+      findings: [{
+        analyzer: 'structure',
+        category: 'structure',
+        ruleId: 'ST000',
+        severity: 'CRITICAL',
+        skill: skillName,
+        line: 0,
+        snippet: 'SKILL.md no encontrado',
+        description: `El directorio ${skillName} no contiene SKILL.md`,
+      }],
+      riskScore: 100,
+      riskLabel: 'critical',
+    };
+  }
+
+  const contenido = fs.readFileSync(skillMdPath, 'utf8');
+
+  // Ejecutar los 7 analizadores (patrón skillshare)
+  // 1. static → cubierto por prompt-injection-scanner.js (externo)
+  // 2-7 → ejecutados aquí
+  const findings = [
+    ...analizarDataflow(contenido, skillName),       // 2. dataflow
+    ...analizarStructure(contenido, skillName),       // 3. structure
+    ...analizarIntegrity(contenido, skillName, skillDir), // 4. integrity
+    ...analizarMetadata(contenido, skillName),        // 5. metadata
+    ...analizarCrossSkill(contenido, skillName, opciones && opciones.allSkills), // 6. cross-skill
+    ...analizarTier(contenido, skillName),            // 7. tier
+  ];
+
+  // Calcular risk score (0-100)
+  let score = 0;
+  for (const f of findings) {
+    score += (SEVERIDADES[f.severity] || 0) * 10;
+  }
+  score = Math.min(score, 100);
+
+  const riskLabel = score >= 70 ? 'critical'
+    : score >= 40 ? 'high'
+    : score >= 20 ? 'medium'
+    : score > 0 ? 'low'
+    : 'clean';
+
+  return { skill: skillName, findings, riskScore: score, riskLabel };
+}
+
+/**
+ * Audita todos los skills en un directorio.
+ *
+ * @param {string} habsDir - Ruta al directorio de habilidades
+ * @returns {{ total: number, clean: number, withFindings: number, results: Array }}
+ */
+function auditarDirectorio(habsDir) {
+  const results = [];
+  let clean = 0;
+  let withFindings = 0;
+
+  const entries = fs.readdirSync(habsDir, { withFileTypes: true });
+  const allSkills = new Set(entries.filter(e => e.isDirectory()).map(e => e.name));
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const resultado = auditarSkill(path.join(habsDir, entry.name), { allSkills });
+    results.push(resultado);
+    if (resultado.findings.length === 0) clean++;
+    else withFindings++;
+  }
+
+  return {
+    total: results.length,
+    clean,
+    withFindings,
+    results,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  auditarSkill,
+  auditarDirectorio,
+  analizarDataflow,
+  analizarStructure,
+  analizarIntegrity,
+  analizarMetadata,
+  analizarCrossSkill,
+  analizarTier,
+  SEVERIDADES,
+};