sinapse-ai 1.1.0 → 5.0.3

package/docs/es/guides/security-hardening.md

@@ -0,0 +1,1359 @@
+# Guía de Hardening de Seguridad de SINAPSE
+
+> [EN](../../guides/security-hardening.md) | [PT](../../pt/guides/security-hardening.md) | **ES**
+
+---
+
+> Guía completa para fortalecer la seguridad en despliegues de SINAPSE - desde desarrollo hasta producción.
+
+**Versión:** 2.1.0
+**Última Actualización:** 2026-01-29
+
+---
+
+## Tabla de Contenidos
+
+1. [Visión General de Seguridad](#visión-general-de-seguridad)
+2. [Gestión de Claves API](#gestión-de-claves-api)
+3. [Variables de Entorno y Secretos](#variables-de-entorno-y-secretos)
+4. [Permisos de Archivos y Directorios](#permisos-de-archivos-y-directorios)
+5. [Sandboxing y Aislamiento](#sandboxing-y-aislamiento)
+6. [Validación de Entrada](#validación-de-entrada)
+7. [Protección contra Inyección](#protección-contra-inyección)
+8. [Logging y Auditoría](#logging-y-auditoría)
+9. [Configuración de Producción vs Desarrollo](#configuración-de-producción-vs-desarrollo)
+10. [Lista de Verificación de Seguridad](#lista-de-verificación-de-seguridad)
+11. [Reporte de Vulnerabilidades](#reporte-de-vulnerabilidades)
+
+---
+
+## Visión General de Seguridad
+
+SINAPSE opera en una capa privilegiada entre los modelos de IA y tu sistema. Esta guía cubre estrategias de hardening específicas para entornos de desarrollo orquestados por IA.
+
+### Arquitectura de Seguridad
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        CAPA EXTERNA                              │
+│    Network Firewall | WAF | TLS Termination | Rate Limiting     │
+├─────────────────────────────────────────────────────────────────┤
+│                      CAPA DE APLICACIÓN                          │
+│   Permission Modes | Input Validation | Command Sanitization    │
+├─────────────────────────────────────────────────────────────────┤
+│                       CAPA DE EJECUCIÓN                          │
+│    Sandboxing | Process Isolation | Resource Limits | Hooks     │
+├─────────────────────────────────────────────────────────────────┤
+│                         CAPA DE DATOS                            │
+│   Encryption at Rest | Secure Storage | Audit Logging           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Preocupaciones de Seguridad Específicas de SINAPSE
+
+| Preocupación                   | Nivel de Riesgo | Mitigación                        |
+| ------------------------------ | --------------- | --------------------------------- |
+| Ejecución de código de agentes | CRÍTICO         | Permission Modes, Sandboxing      |
+| Exposición de claves API       | CRÍTICO         | Aislamiento de entorno, cifrado   |
+| Inyección de comandos vía IA   | ALTO            | Sanitización de entrada, hooks    |
+| Acceso no autorizado a archivos| ALTO            | Restricciones de directorio       |
+| Secuestro de sesión            | MEDIO           | Rotación de tokens, almacenamiento seguro |
+| Divulgación de información     | MEDIO           | Audit logging, controles de acceso|
+
+### Defensa en Profundidad
+
+SINAPSE implementa múltiples capas de protección:
+
+1. **Permission Modes** - Controlan la autonomía del agente (Explore/Ask/Auto)
+2. **Claude Hooks** - Validación previa a la ejecución (read-protection, sql-governance)
+3. **Sanitización de Entrada** - Toda entrada de usuario/IA es validada
+4. **Aislamiento de Procesos** - Los servidores MCP se ejecutan en contenedores
+5. **Audit Logging** - Todas las operaciones son registradas
+
+---
+
+## Gestión de Claves API
+
+Las claves API son los secretos más críticos en SINAPSE. Las claves comprometidas pueden llevar a uso no autorizado, brechas de datos e impacto financiero significativo.
+
+### Jerarquía de Almacenamiento
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│  NUNCA                                                          │
+│  ❌ Código fuente                                               │
+│  ❌ Repositorios Git                                            │
+│  ❌ Archivos de configuración (commiteados)                     │
+│  ❌ Archivos de log                                             │
+│  ❌ Mensajes de error                                           │
+├────────────────────────────────────────────────────────────────┤
+│  ACEPTABLE (Desarrollo)                                         │
+│  ⚠️  Archivos .env (gitignored)                                 │
+│  ⚠️  Variables de entorno locales                               │
+├────────────────────────────────────────────────────────────────┤
+│  RECOMENDADO (Producción)                                       │
+│  ✅ Secret managers (Vault, AWS Secrets, etc.)                  │
+│  ✅ Inyección de secretos en CI/CD                              │
+│  ✅ Kubernetes secrets                                          │
+│  ✅ Almacenes de credenciales cifrados                          │
+└────────────────────────────────────────────────────────────────┘
+```
+
+### Configuración Segura de Claves API
+
+**Desarrollo (archivo .env - nunca commitear)**
+
+```bash
+# .env - Agregar a .gitignore INMEDIATAMENTE
+# Claves de Proveedores de API
+ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Claves de Servidores MCP
+EXA_API_KEY=exa-xxxxxxxxxxxxxxxxxxxxxxxx
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+APIFY_TOKEN=apify_api_xxxxxxxxxxxxxxxxxxxxx
+
+# Nunca usar valores predeterminados o débiles
+JWT_SECRET=your-256-bit-cryptographically-secure-random-key
+```
+
+**Producción (usando secret manager)**
+
+```javascript
+// Cargar secretos desde vault seguro
+const secrets = await SecretManager.loadSecrets({
+  provider: 'aws-secrets-manager', // o 'hashicorp-vault', 'gcp-secrets'
+  secretName: 'sinapse/production/api-keys',
+  region: process.env.AWS_REGION,
+});
+
+process.env.ANTHROPIC_API_KEY = secrets.ANTHROPIC_API_KEY;
+process.env.OPENAI_API_KEY = secrets.OPENAI_API_KEY;
+```
+
+### Política de Rotación de Claves
+
+| Tipo de Clave      | Frecuencia de Rotación | En Caso de Compromiso |
+| ------------------ | ---------------------- | --------------------- |
+| Claves de Proveedores AI | 90 días           | Inmediato             |
+| JWT Secrets        | 30 días                | Inmediato             |
+| Claves de Servidores MCP | 90 días           | Inmediato             |
+| Tokens de Servicio | 7 días                 | Inmediato             |
+| Claves de Desarrollo | Nunca reutilizar     | Revocar inmediatamente|
+
+### Validación de Claves al Iniciar
+
+```javascript
+// .sinapse-ai/core/security/key-validator.js
+const requiredKeys = [
+  { name: 'ANTHROPIC_API_KEY', pattern: /^sk-ant-[a-zA-Z0-9_-]+$/ },
+  { name: 'JWT_SECRET', minLength: 32 },
+];
+
+function validateApiKeys() {
+  const errors = [];
+
+  for (const key of requiredKeys) {
+    const value = process.env[key.name];
+
+    if (!value) {
+      errors.push(`Clave requerida faltante: ${key.name}`);
+      continue;
+    }
+
+    if (key.pattern && !key.pattern.test(value)) {
+      errors.push(`Formato inválido para ${key.name}`);
+    }
+
+    if (key.minLength && value.length < key.minLength) {
+      errors.push(`${key.name} debe tener al menos ${key.minLength} caracteres`);
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Validación de Clave API Fallida:\n${errors.join('\n')}`);
+  }
+}
+```
+
+---
+
+## Variables de Entorno y Secretos
+
+### Plantilla de Archivo .env Seguro
+
+```bash
+# ============================================================
+# CONFIGURACIÓN DE ENTORNO SINAPSE
+# ============================================================
+# SEGURIDAD: Este archivo NUNCA debe ser commiteado a control de versiones
+# Agregar a .gitignore: .env, .env.local, .env.*.local
+# ============================================================
+
+# ------------------------------------------------------------
+# ENTORNO
+# ------------------------------------------------------------
+NODE_ENV=development
+SINAPSE_DEBUG=false
+LOG_LEVEL=info
+
+# ------------------------------------------------------------
+# CONFIGURACIÓN DE PROVEEDOR AI
+# ------------------------------------------------------------
+# Proveedor principal
+AI_PROVIDER=anthropic
+ANTHROPIC_API_KEY=
+
+# Proveedor de respaldo (opcional)
+OPENAI_API_KEY=
+
+# ------------------------------------------------------------
+# AUTENTICACIÓN Y SESIÓN
+# ------------------------------------------------------------
+# Generar con: openssl rand -hex 32
+JWT_SECRET=
+JWT_EXPIRY=1h
+REFRESH_TOKEN_EXPIRY=7d
+
+# Configuración de sesión
+SESSION_SECRET=
+SESSION_TIMEOUT=3600000
+
+# ------------------------------------------------------------
+# CIFRADO
+# ------------------------------------------------------------
+# Generar con: openssl rand -hex 32
+DATABASE_ENCRYPTION_KEY=
+FILE_ENCRYPTION_KEY=
+
+# ------------------------------------------------------------
+# SERVIDORES MCP
+# ------------------------------------------------------------
+# EXA Web Search
+EXA_API_KEY=
+
+# Integración GitHub
+GITHUB_TOKEN=
+
+# Apify Web Scraping
+APIFY_TOKEN=
+
+# ------------------------------------------------------------
+# CONFIGURACIÓN DE SEGURIDAD
+# ------------------------------------------------------------
+# Rate limiting
+RATE_LIMIT_WINDOW=900000
+RATE_LIMIT_MAX_REQUESTS=1000
+
+# CORS (solo producción)
+CORS_ORIGIN=https://your-domain.com
+
+# Content Security Policy
+CSP_ENABLED=true
+
+# ------------------------------------------------------------
+# AUDITORÍA Y LOGGING
+# ------------------------------------------------------------
+AUDIT_LOG_ENABLED=true
+AUDIT_LOG_PATH=/var/log/sinapse/audit.log
+AUDIT_LOG_RETENTION_DAYS=90
+```
+
+### Protección de Archivos de Secretos
+
+```bash
+# Crear directorio seguro para secretos
+mkdir -p ~/.sinapse/secrets
+chmod 700 ~/.sinapse/secrets
+
+# Crear archivo de secretos cifrado
+# Nunca almacenar secretos en texto plano
+openssl enc -aes-256-cbc -salt -pbkdf2 \
+  -in secrets.txt \
+  -out ~/.sinapse/secrets/encrypted.dat
+
+# Establecer permisos apropiados
+chmod 600 ~/.sinapse/secrets/*
+
+# Verificar que no hay secretos en el historial de git
+git log -p --all -S "API_KEY" -- .
+```
+
+### Aislamiento de Entorno
+
+```javascript
+// Validar aislamiento de entorno
+function validateEnvironment() {
+  // Asegurar que los secretos de producción no se usen en desarrollo
+  if (process.env.NODE_ENV === 'development') {
+    if (process.env.ANTHROPIC_API_KEY?.includes('prod')) {
+      throw new Error('Clave API de producción detectada en entorno de desarrollo');
+    }
+  }
+
+  // Asegurar que el modo debug esté desactivado en producción
+  if (process.env.NODE_ENV === 'production') {
+    if (process.env.SINAPSE_DEBUG === 'true') {
+      console.warn('ADVERTENCIA: Modo debug habilitado en producción');
+    }
+  }
+}
+```
+
+---
+
+## Permisos de Archivos y Directorios
+
+### Permisos de Estructura de Directorios SINAPSE
+
+```bash
+# ============================================================
+# PERMISOS RECOMENDADOS
+# ============================================================
+
+# Raíz del proyecto (estándar)
+chmod 755 /path/to/project
+
+# Directorios de configuración SINAPSE
+chmod 700 .sinapse/              # Solo el propietario puede acceder
+chmod 700 .sinapse-ai/         # Fuente del framework
+chmod 700 .claude/            # Configuración de Claude
+
+# Archivos de configuración sensibles
+chmod 600 .env                # Variables de entorno
+chmod 600 .sinapse/config.yaml   # Configuración principal
+chmod 600 .sinapse/users.json    # Base de datos de usuarios
+chmod 600 .sinapse/sessions.json # Sesiones activas
+
+# Directorio de secretos
+chmod 700 ~/.sinapse/secrets/
+chmod 600 ~/.sinapse/secrets/*
+
+# Archivos de log
+chmod 640 logs/*.log          # Propietario lectura/escritura, grupo lectura
+chmod 750 logs/               # Propietario completo, grupo lectura/ejecución
+
+# Archivos temporales
+chmod 700 .sinapse/temp/
+chmod 600 .sinapse/temp/*
+```
+
+### Control de Acceso a Directorios
+
+```yaml
+# .sinapse/config.yaml - Configuración de directorios permitidos
+security:
+  allowedDirectories:
+    read:
+      - '${PROJECT_ROOT}'
+      - '${HOME}/.sinapse'
+    write:
+      - '${PROJECT_ROOT}/src'
+      - '${PROJECT_ROOT}/docs'
+      - '${PROJECT_ROOT}/tests'
+    execute:
+      - '${PROJECT_ROOT}/scripts'
+      - '${PROJECT_ROOT}/node_modules/.bin'
+
+  blockedPaths:
+    - '/etc'
+    - '/var'
+    - '/usr'
+    - '${HOME}/.ssh'
+    - '${HOME}/.gnupg'
+    - '${HOME}/.aws'
+```
+
+### Script de Validación de Permisos
+
+```bash
+#!/bin/bash
+# scripts/check-permissions.sh
+
+echo "Verificación de Permisos de Seguridad SINAPSE"
+echo "==========================================="
+
+# Verificar archivos críticos
+check_permission() {
+  local file=$1
+  local expected=$2
+  local actual=$(stat -f "%Lp" "$file" 2>/dev/null || stat -c "%a" "$file" 2>/dev/null)
+
+  if [ "$actual" != "$expected" ]; then
+    echo "ADVERTENCIA: $file tiene permisos $actual, se esperaba $expected"
+    return 1
+  else
+    echo "OK: $file ($actual)"
+    return 0
+  fi
+}
+
+# Verificar archivos críticos
+check_permission ".env" "600"
+check_permission ".sinapse" "700"
+check_permission ".sinapse/config.yaml" "600"
+
+# Verificar archivos sensibles legibles por todos
+find . -name "*.key" -o -name "*.pem" -o -name "*.env*" | while read f; do
+  perms=$(stat -f "%Lp" "$f" 2>/dev/null || stat -c "%a" "$f" 2>/dev/null)
+  if [ "${perms: -1}" != "0" ]; then
+    echo "CRÍTICO: ¡$f es legible por todos!"
+  fi
+done
+
+echo ""
+echo "Verificación de permisos completada."
+```
+
+---
+
+## Sandboxing y Aislamiento
+
+### Aislamiento de MCP con Docker
+
+SINAPSE usa contenedores Docker para aislar los servidores MCP del sistema host:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      SISTEMA HOST                            │
+│                                                              │
+│  ┌────────────────┐    ┌────────────────────────────────┐  │
+│  │  Claude Code   │    │      Contenedor Docker         │  │
+│  │                │    │  ┌──────────────────────────┐  │  │
+│  │  ┌──────────┐  │    │  │  docker-gateway          │  │  │
+│  │  │ Native   │  │◄──►│  │  ┌─────┐ ┌─────────┐    │  │  │
+│  │  │ Tools    │  │    │  │  │ EXA │ │Context7 │    │  │  │
+│  │  └──────────┘  │    │  │  └─────┘ └─────────┘    │  │  │
+│  │                │    │  │  ┌─────────┐            │  │  │
+│  │  ┌──────────┐  │    │  │  │  Apify  │            │  │  │
+│  │  │Playwright│  │    │  │  └─────────┘            │  │  │
+│  │  └──────────┘  │    │  └──────────────────────────┘  │  │
+│  └────────────────┘    └────────────────────────────────┘  │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Configuración de Seguridad de Contenedores
+
+```yaml
+# docker-compose.security.yml
+version: '3.8'
+
+services:
+  mcp-gateway:
+    image: docker-mcp-gateway:latest
+    security_opt:
+      - no-new-privileges:true
+      - seccomp:./seccomp-profile.json
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_BIND_SERVICE
+    read_only: true
+    tmpfs:
+      - /tmp:noexec,nosuid,nodev
+    networks:
+      - mcp-isolated
+    deploy:
+      resources:
+        limits:
+          cpus: '1.0'
+          memory: 512M
+        reservations:
+          cpus: '0.25'
+          memory: 128M
+
+networks:
+  mcp-isolated:
+    driver: bridge
+    internal: true # Sin acceso externo
+```
+
+### Aislamiento de Procesos con Permission Modes
+
+```javascript
+// Aplicación de Permission Mode
+const { OperationGuard } = require('./.sinapse-ai/core/permissions');
+
+async function executeWithIsolation(operation, context) {
+  const guard = new OperationGuard();
+
+  // Verificar si la operación está permitida en el modo actual
+  const permission = await guard.guard(operation.tool, {
+    command: operation.command,
+    args: operation.args,
+  });
+
+  if (!permission.proceed) {
+    if (permission.needsConfirmation) {
+      // Solicitar confirmación del usuario
+      const confirmed = await requestUserConfirmation(operation);
+      if (!confirmed) {
+        throw new Error('Operación denegada por el usuario');
+      }
+    } else {
+      throw new Error(`Operación bloqueada: ${permission.reason}`);
+    }
+  }
+
+  // Ejecutar en contexto aislado
+  return await isolatedExecutor.run(operation, {
+    timeout: 30000,
+    maxMemory: '256M',
+    networkAccess: false,
+  });
+}
+```
+
+### Límites de Recursos
+
+```javascript
+// Configuración de límites de recursos
+const resourceLimits = {
+  cpu: {
+    maxPercent: 50,
+    throttleAt: 80,
+  },
+  memory: {
+    maxMB: 512,
+    warnAt: 400,
+  },
+  disk: {
+    maxWriteMB: 100,
+    tempDirMaxMB: 50,
+  },
+  network: {
+    maxRequestsPerMinute: 100,
+    maxBandwidthMBps: 10,
+  },
+  process: {
+    maxConcurrent: 5,
+    maxRuntime: 300000, // 5 minutos
+  },
+};
+```
+
+---
+
+## Validación de Entrada
+
+### Reglas de Validación por Tipo de Entrada
+
+| Tipo de Entrada     | Reglas de Validación                    | Ejemplo                   |
+| ------------------- | --------------------------------------- | ------------------------- |
+| **Rutas de archivo**| Sin traversal, whitelist dirs, normalizar | `/project/src/file.ts`    |
+| **Comandos**        | Whitelist comandos, sanitizar args      | `npm run build`           |
+| **Nombres de proyecto** | Alfanumérico, guiones, guiones bajos| `my-project-01`           |
+| **URLs**            | Whitelist de protocolos, validación de dominio | `https://api.example.com` |
+| **Entrada de usuario** | Límites de longitud, filtrado de caracteres | `Comentario del usuario`  |
+| **Configuración**   | Verificación de tipos, validación de enums | `{ mode: "ask" }`        |
+
+### Implementación de Sanitizador de Entrada
+
+```javascript
+// .sinapse-ai/core/security/input-sanitizer.js
+
+class InputSanitizer {
+  /**
+   * Sanitizar ruta de archivo para prevenir directory traversal
+   */
+  static sanitizePath(inputPath, basePath) {
+    // Remover null bytes
+    let sanitized = inputPath.replace(/\0/g, '');
+
+    // Normalizar separadores de ruta
+    sanitized = sanitized.replace(/\\/g, '/');
+
+    // Remover intentos de directory traversal
+    sanitized = sanitized.replace(/\.\.+\//g, '');
+    sanitized = sanitized.replace(/\/\.\.+/g, '');
+
+    // Resolver a ruta absoluta
+    const resolved = path.resolve(basePath, sanitized);
+
+    // Verificar que la ruta está dentro del directorio permitido
+    if (!resolved.startsWith(path.resolve(basePath))) {
+      throw new SecurityError('Intento de directory traversal detectado');
+    }
+
+    return resolved;
+  }
+
+  /**
+   * Sanitizar comando para ejecución segura
+   */
+  static sanitizeCommand(command) {
+    // Bloquear patrones peligrosos
+    const dangerousPatterns = [
+      /;/g, // Encadenamiento de comandos
+      /\|/g, // Pipes
+      /&/g, // Background/AND
+      /`/g, // Sustitución de comandos
+      /\$\(/g, // Sustitución de comandos
+      />/g, // Redirección
+      /</g, // Redirección
+      /\n/g, // Nuevas líneas
+      /\r/g, // Retornos de carro
+    ];
+
+    let sanitized = command;
+    for (const pattern of dangerousPatterns) {
+      sanitized = sanitized.replace(pattern, '');
+    }
+
+    // Limitar longitud
+    if (sanitized.length > 1000) {
+      throw new SecurityError('Comando demasiado largo');
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Validar y sanitizar nombre de proyecto
+   */
+  static sanitizeProjectName(name) {
+    // Solo permitir alfanumérico, guiones y guiones bajos
+    const sanitized = name.replace(/[^a-zA-Z0-9-_]/g, '');
+
+    if (sanitized.length === 0) {
+      throw new SecurityError('Nombre de proyecto inválido');
+    }
+
+    if (sanitized.length > 64) {
+      throw new SecurityError('Nombre de proyecto demasiado largo');
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Validar URL
+   */
+  static validateUrl(url) {
+    const allowedProtocols = ['https:', 'http:'];
+
+    try {
+      const parsed = new URL(url);
+
+      if (!allowedProtocols.includes(parsed.protocol)) {
+        throw new SecurityError('Protocolo de URL inválido');
+      }
+
+      // Bloquear localhost en producción
+      if (process.env.NODE_ENV === 'production') {
+        if (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1') {
+          throw new SecurityError('URLs de localhost no permitidas en producción');
+        }
+      }
+
+      return parsed.toString();
+    } catch (error) {
+      throw new SecurityError(`URL inválida: ${error.message}`);
+    }
+  }
+}
+```
+
+### Validación de Esquema
+
+```javascript
+// Usar JSON Schema para validación de configuración
+const Ajv = require('ajv');
+const ajv = new Ajv({ allErrors: true });
+
+const configSchema = {
+  type: 'object',
+  required: ['version', 'permissions'],
+  properties: {
+    version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
+    permissions: {
+      type: 'object',
+      properties: {
+        mode: { type: 'string', enum: ['explore', 'ask', 'auto'] },
+      },
+      required: ['mode'],
+    },
+    security: {
+      type: 'object',
+      properties: {
+        allowedDirectories: {
+          type: 'array',
+          items: { type: 'string' },
+        },
+      },
+    },
+  },
+  additionalProperties: false,
+};
+
+function validateConfig(config) {
+  const validate = ajv.compile(configSchema);
+  const valid = validate(config);
+
+  if (!valid) {
+    throw new SecurityError(`Validación de configuración fallida: ${JSON.stringify(validate.errors)}`);
+  }
+
+  return config;
+}
+```
+
+---
+
+## Protección contra Inyección
+
+### Prevención de Inyección de Comandos
+
+```javascript
+// PELIGROSO - Nunca hacer esto
+const userInput = req.query.file;
+exec(`cat ${userInput}`); // ¡Vulnerabilidad de inyección de comandos!
+
+// SEGURO - Usar ejecución parametrizada
+const { execFile } = require('child_process');
+const userInput = sanitizePath(req.query.file, PROJECT_ROOT);
+execFile('cat', [userInput], (error, stdout) => {
+  // Ejecución segura
+});
+
+// MÁS SEGURO - Usar operaciones de archivo integradas
+const fs = require('fs').promises;
+const safePath = sanitizePath(req.query.file, PROJECT_ROOT);
+const content = await fs.readFile(safePath, 'utf8');
+```
+
+### Prevención de Inyección SQL (Hook de SQL Governance)
+
+```python
+# .claude/hooks/sql-governance.py
+# Este hook se aplica automáticamente
+
+BLOCKED_PATTERNS = [
+    r'CREATE\s+TABLE',
+    r'DROP\s+TABLE',
+    r'ALTER\s+TABLE',
+    r'TRUNCATE',
+    r'DELETE\s+FROM',
+    r'UPDATE\s+.*\s+SET',
+    r'INSERT\s+INTO',
+]
+
+def validate_sql(query: str) -> bool:
+    """Bloquear operaciones SQL peligrosas sin aprobación explícita"""
+    for pattern in BLOCKED_PATTERNS:
+        if re.search(pattern, query, re.IGNORECASE):
+            raise SecurityError(f"Patrón SQL bloqueado detectado: {pattern}")
+    return True
+```
+
+### Prevención de Inyección de Plantillas
+
+```javascript
+// PELIGROSO - Interpolación directa de plantillas
+const template = `Hello ${userInput}!`; // ¡Vulnerabilidad XSS!
+
+// SEGURO - Codificación HTML
+const { escape } = require('html-escaper');
+const template = `Hello ${escape(userInput)}!`;
+
+// Para plantillas Markdown
+function safeMarkdownInterpolation(template, data) {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    const value = data[key];
+    if (value === undefined) return match;
+
+    // Escapar caracteres especiales de Markdown
+    return String(value).replace(/[\\`*_{}[\]()#+\-.!]/g, '\\$&');
+  });
+}
+```
+
+### Prevención de Path Traversal
+
+```javascript
+// Aplicación de hook para archivos protegidos
+// .claude/hooks/read-protection.py
+
+PROTECTED_FILES = [
+    '.claude/CLAUDE.md',
+    '.claude/rules/*.md',
+    '.sinapse-ai/development/agents/*.md',
+    'package.json',
+    'tsconfig.json'
+]
+
+def validate_read(file_path: str, params: dict) -> bool:
+    """Bloquear lecturas parciales en archivos protegidos"""
+    for pattern in PROTECTED_FILES:
+        if fnmatch.fnmatch(file_path, pattern):
+            if params.get('limit') or params.get('offset'):
+                raise SecurityError(
+                    f"Lectura parcial bloqueada en archivo protegido: {file_path}\n"
+                    "Debe leer el archivo completo."
+                )
+    return True
+```
+
+### Prevención de Prototype Pollution
+
+```javascript
+// Prevenir ataques de prototype pollution
+function safeObjectMerge(target, source) {
+  const blockedKeys = ['__proto__', 'constructor', 'prototype'];
+
+  function merge(t, s, depth = 0) {
+    if (depth > 10) {
+      throw new SecurityError('Profundidad de merge de objeto excedida');
+    }
+
+    for (const key of Object.keys(s)) {
+      if (blockedKeys.includes(key)) {
+        throw new SecurityError(`Propiedad bloqueada: ${key}`);
+      }
+
+      if (typeof s[key] === 'object' && s[key] !== null) {
+        t[key] = t[key] || {};
+        merge(t[key], s[key], depth + 1);
+      } else {
+        t[key] = s[key];
+      }
+    }
+
+    return t;
+  }
+
+  return merge(target, source);
+}
+```
+
+---
+
+## Logging y Auditoría
+
+### Configuración de Audit Log
+
+```yaml
+# .sinapse/config.yaml - Configuración de auditoría
+audit:
+  enabled: true
+  level: info # debug, info, warn, error
+
+  # Qué registrar
+  events:
+    - authentication
+    - authorization
+    - fileAccess
+    - commandExecution
+    - configChange
+    - agentActivation
+    - modeChange
+    - error
+
+  # Configuración de salida
+  output:
+    file:
+      enabled: true
+      path: .sinapse/logs/audit.log
+      maxSize: 10M
+      maxFiles: 10
+      compress: true
+    console:
+      enabled: false
+    remote:
+      enabled: false
+      endpoint: https://logs.example.com/audit
+
+  # Retención
+  retention:
+    days: 90
+    archivePath: .sinapse/logs/archive
+```
+
+### Formato de Audit Log
+
+```json
+{
+  "timestamp": "2026-01-29T14:30:00.000Z",
+  "level": "info",
+  "event": "commandExecution",
+  "actor": {
+    "type": "agent",
+    "id": "dev",
+    "name": "Dex"
+  },
+  "action": {
+    "type": "execute",
+    "tool": "Bash",
+    "command": "npm run build"
+  },
+  "context": {
+    "mode": "ask",
+    "project": "my-project",
+    "story": "1.1"
+  },
+  "result": {
+    "status": "success",
+    "duration": 12500
+  },
+  "security": {
+    "approved": true,
+    "approvedBy": "user",
+    "riskLevel": "low"
+  }
+}
+```
+
+### Implementación de Audit Logger
+
+```javascript
+// .sinapse-ai/core/security/audit-logger.js
+
+const winston = require('winston');
+const { format } = winston;
+
+class AuditLogger {
+  constructor(config) {
+    this.config = config;
+    this.logger = this.createLogger();
+  }
+
+  createLogger() {
+    const transports = [];
+
+    if (this.config.output.file.enabled) {
+      transports.push(
+        new winston.transports.File({
+          filename: this.config.output.file.path,
+          maxsize: this.parseSize(this.config.output.file.maxSize),
+          maxFiles: this.config.output.file.maxFiles,
+          tailable: true,
+        })
+      );
+    }
+
+    return winston.createLogger({
+      level: this.config.level,
+      format: format.combine(format.timestamp(), format.json()),
+      transports,
+    });
+  }
+
+  log(event, data) {
+    if (!this.config.events.includes(event)) {
+      return;
+    }
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      event,
+      ...this.sanitizeData(data),
+    };
+
+    this.logger.info(entry);
+  }
+
+  sanitizeData(data) {
+    // Remover información sensible antes de registrar
+    const sensitivePatterns = [/api[_-]?key/i, /password/i, /secret/i, /token/i, /auth/i];
+
+    const sanitized = JSON.parse(JSON.stringify(data));
+
+    function redact(obj) {
+      for (const key of Object.keys(obj)) {
+        if (sensitivePatterns.some((p) => p.test(key))) {
+          obj[key] = '[REDACTADO]';
+        } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+          redact(obj[key]);
+        }
+      }
+    }
+
+    redact(sanitized);
+    return sanitized;
+  }
+
+  // Métodos de logging específicos
+  logAuthentication(result, context) {
+    this.log('authentication', {
+      action: { type: 'authenticate', result: result.success ? 'success' : 'failure' },
+      context,
+      security: { failureReason: result.reason },
+    });
+  }
+
+  logCommandExecution(command, result, context) {
+    this.log('commandExecution', {
+      action: { type: 'execute', command },
+      result: { status: result.success ? 'success' : 'failure', duration: result.duration },
+      context,
+    });
+  }
+
+  logFileAccess(path, operation, context) {
+    this.log('fileAccess', {
+      action: { type: operation, path },
+      context,
+    });
+  }
+
+  logSecurityEvent(event, severity, details) {
+    this.log('security', {
+      action: { type: event },
+      security: { severity, ...details },
+    });
+  }
+}
+
+module.exports = AuditLogger;
+```
+
+### Consultas de Análisis de Logs
+
+```bash
+# Encontrar todas las autenticaciones fallidas
+jq 'select(.event == "authentication" and .result.status == "failure")' audit.log
+
+# Encontrar todas las ejecuciones de comandos por agente
+jq 'select(.event == "commandExecution" and .actor.type == "agent")' audit.log
+
+# Encontrar todos los eventos de seguridad en las últimas 24 horas
+jq 'select(.event == "security" and (.timestamp | fromdateiso8601) > (now - 86400))' audit.log
+
+# Contar eventos por tipo
+jq -s 'group_by(.event) | map({event: .[0].event, count: length})' audit.log
+```
+
+---
+
+## Configuración de Producción vs Desarrollo
+
+### Detección de Entorno
+
+```javascript
+// Carga de configuración consciente del entorno
+function loadSecurityConfig() {
+  const env = process.env.NODE_ENV || 'development';
+
+  const baseConfig = require('./security-config.base.json');
+  const envConfig = require(`./security-config.${env}.json`);
+
+  return deepMerge(baseConfig, envConfig);
+}
+```
+
+### Comparación de Configuración
+
+| Configuración          | Desarrollo        | Producción       |
+| ---------------------- | ----------------- | ---------------- |
+| **SINAPSE_DEBUG**         | `true`            | `false`          |
+| **LOG_LEVEL**          | `debug`           | `info`           |
+| **Permission Mode**    | `auto`            | `ask`            |
+| **Rate Limiting**      | Relajado          | Estricto         |
+| **CORS**               | `*`               | Orígenes específicos |
+| **Detalles de Error**  | Stack traces completos | Mensajes genéricos |
+| **Validación de API Key** | Solo advertencia | Bloquear si inválida |
+| **SSL/TLS**            | Opcional          | Requerido        |
+| **Audit Logging**      | Opcional          | Requerido        |
+| **Timeout de Sesión**  | 24 horas          | 1 hora           |
+
+### Configuración de Desarrollo
+
+```yaml
+# .sinapse/config.development.yaml
+security:
+  debug: true
+
+  validation:
+    strict: false
+    warnOnly: true
+
+  rateLimiting:
+    enabled: false
+
+  cors:
+    origin: '*'
+    credentials: true
+
+  session:
+    timeout: 86400000 # 24 horas
+    secure: false
+
+  audit:
+    enabled: true
+    level: debug
+    console: true
+
+  permissions:
+    mode: auto
+```
+
+### Configuración de Producción
+
+```yaml
+# .sinapse/config.production.yaml
+security:
+  debug: false
+
+  validation:
+    strict: true
+    warnOnly: false
+
+  rateLimiting:
+    enabled: true
+    windowMs: 900000 # 15 minutos
+    maxRequests: 1000
+
+  cors:
+    origin:
+      - https://app.example.com
+      - https://admin.example.com
+    credentials: true
+
+  session:
+    timeout: 3600000 # 1 hora
+    secure: true
+    sameSite: strict
+
+  tls:
+    enabled: true
+    minVersion: TLSv1.2
+    ciphers: ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384
+
+  headers:
+    hsts: true
+    hstsMaxAge: 31536000
+    xssProtection: true
+    noSniff: true
+    frameOptions: DENY
+
+  audit:
+    enabled: true
+    level: info
+    console: false
+    remote:
+      enabled: true
+      endpoint: https://logs.example.com/audit
+
+  permissions:
+    mode: ask
+    requireApprovalFor:
+      - delete
+      - execute
+```
+
+### Script de Validación de Entorno
+
+```javascript
+// Validar requisitos de seguridad de producción
+function validateProductionSecurity() {
+  const errors = [];
+
+  // Variables de entorno requeridas
+  const required = ['JWT_SECRET', 'DATABASE_ENCRYPTION_KEY', 'SESSION_SECRET'];
+  for (const key of required) {
+    if (!process.env[key]) {
+      errors.push(`Variable de entorno requerida faltante: ${key}`);
+    }
+  }
+
+  // Debug debe estar desactivado
+  if (process.env.SINAPSE_DEBUG === 'true') {
+    errors.push('SINAPSE_DEBUG debe ser false en producción');
+  }
+
+  // TLS debe estar habilitado (verificar archivos de certificado)
+  if (!fs.existsSync(process.env.TLS_CERT_PATH)) {
+    errors.push('Certificado TLS no encontrado');
+  }
+
+  // Fortaleza de secretos
+  if (process.env.JWT_SECRET?.length < 32) {
+    errors.push('JWT_SECRET debe tener al menos 32 caracteres');
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Validación de seguridad de producción fallida:\n${errors.join('\n')}`);
+  }
+
+  console.log('Validación de seguridad de producción aprobada');
+}
+```
+
+---
+
+## Lista de Verificación de Seguridad
+
+### Lista de Verificación Pre-Despliegue
+
+```markdown
+## Lista de Verificación de Seguridad Pre-Despliegue
+
+### Gestión de Secretos
+
+- [ ] Todas las claves API almacenadas en variables de entorno o secret manager
+- [ ] Sin secretos en código fuente o historial de git
+- [ ] Archivo .env agregado a .gitignore
+- [ ] Secretos de producción usan claves separadas de desarrollo
+- [ ] Cronograma de rotación de secretos establecido
+
+### Configuración
+
+- [ ] NODE_ENV establecido a 'production'
+- [ ] Modo debug deshabilitado
+- [ ] Mensajes de error no exponen detalles internos
+- [ ] Rate limiting configurado y probado
+- [ ] CORS configurado correctamente para dominios de producción
+
+### Autenticación y Autorización
+
+- [ ] Política de contraseñas fuertes aplicada
+- [ ] JWT secrets son criptográficamente fuertes (32+ caracteres)
+- [ ] Expiración de tokens configurada apropiadamente
+- [ ] Gestión de sesiones implementada
+- [ ] Permission modes configurados (predeterminado: ask)
+
+### Validación de Entrada
+
+- [ ] Toda entrada de usuario sanitizada
+- [ ] Validación de rutas de archivo habilitada
+- [ ] Protección contra inyección de comandos activa
+- [ ] Hooks de SQL governance instalados
+- [ ] Validación de esquema para configuración
+
+### Seguridad de Red
+
+- [ ] TLS 1.2+ requerido
+- [ ] Headers de seguridad configurados (HSTS, CSP, etc.)
+- [ ] Puertos innecesarios cerrados
+- [ ] Reglas de firewall implementadas
+
+### Logging y Monitoreo
+
+- [ ] Audit logging habilitado
+- [ ] Archivos de log asegurados (permisos 640)
+- [ ] Datos sensibles redactados de los logs
+- [ ] Alertas configuradas para eventos de seguridad
+- [ ] Política de retención de logs establecida
+
+### Seguridad de Dependencias
+
+- [ ] npm audit no muestra vulnerabilidades críticas
+- [ ] Dependabot o similar habilitado
+- [ ] Lockfile commiteado y verificado
+```
+
+### Lista de Verificación de Seguridad Continua
+
+```markdown
+## Mantenimiento de Seguridad Continuo
+
+### Semanal
+
+- [ ] Revisar alertas de seguridad del monitoreo
+- [ ] Verificar nuevas vulnerabilidades de dependencias
+- [ ] Revisar logs de acceso en busca de anomalías
+
+### Mensual
+
+- [ ] Ejecutar escaneo de seguridad completo (npm audit, snyk)
+- [ ] Actualizar dependencias con parches de seguridad
+- [ ] Revisar y rotar tokens de servicio
+- [ ] Auditar acceso y permisos de usuarios
+
+### Trimestral
+
+- [ ] Pruebas de penetración completas
+- [ ] Revisar y actualizar políticas de seguridad
+- [ ] Rotar secretos de larga duración (claves API, JWT secrets)
+- [ ] Actualización de capacitación en seguridad
+
+### Anual
+
+- [ ] Auditoría de seguridad por terceros
+- [ ] Pruebas de recuperación ante desastres
+- [ ] Rotación completa de secretos
+- [ ] Revisión de arquitectura de seguridad
+```
+
+---
+
+## Reporte de Vulnerabilidades
+
+### Política de Divulgación Responsable
+
+Si descubres una vulnerabilidad de seguridad en SINAPSE, por favor sigue las prácticas de divulgación responsable:
+
+### Proceso de Reporte
+
+1. **NO** crees un issue público en GitHub para vulnerabilidades de seguridad
+2. Reporta preocupaciones de seguridad via [GitHub Security Advisories](https://github.com/SynkraAI/sinapse-ai/security/advisories)
+3. Incluye lo siguiente en tu reporte:
+   - Descripción de la vulnerabilidad
+   - Pasos para reproducir
+   - Evaluación del impacto potencial
+   - Cualquier corrección sugerida (opcional)
+
+### Qué Incluir
+
+```markdown
+## Plantilla de Reporte de Vulnerabilidad
+
+**Tipo de Vulnerabilidad:** [ej., Command Injection, XSS, Auth Bypass]
+
+**Severidad:** [Crítica / Alta / Media / Baja]
+
+**Componente Afectado:** [ej., InputSanitizer, AuthSystem, MCP Gateway]
+
+**Versión de SINAPSE:** [ej., 2.1.0]
+
+**Descripción:**
+[Descripción detallada de la vulnerabilidad]
+
+**Pasos para Reproducir:**
+
+1. [Paso 1]
+2. [Paso 2]
+3. [Paso 3]
+
+**Prueba de Concepto:**
+[Código o comandos para demostrar la vulnerabilidad]
+
+**Impacto:**
+[Qué podría lograr un atacante con esta vulnerabilidad]
+
+**Corrección Sugerida:**
+[Opcional: Tu recomendación para corregir el problema]
+```
+
+### Cronograma de Respuesta
+
+| Etapa                    | Plazo                  |
+| ------------------------ | ---------------------- |
+| Acuse de recibo inicial  | 24 horas               |
+| Evaluación preliminar    | 72 horas               |
+| Desarrollo de corrección | 7-14 días              |
+| Lanzamiento del parche   | 14-30 días             |
+| Divulgación pública      | 90 días (o después del fix) |
+
+### Salón de la Fama de Seguridad
+
+Los contribuyentes que divulguen vulnerabilidades de manera responsable son reconocidos en nuestro Salón de la Fama de Seguridad (con permiso).
+
+### Programa de Bug Bounty
+
+Actualmente, SINAPSE no tiene un programa formal de bug bounty. Sin embargo, las contribuciones significativas de seguridad son reconocidas y pueden recibir licencias de SINAPSE Pro u otro reconocimiento.
+
+---
+
+## Documentación Relacionada
+
+- [Mejores Prácticas de Seguridad](../security-best-practices.md) - Directrices generales de seguridad
+- [Guía de Permission Modes](./permission-modes.md) - Control de autonomía de agentes
+- [Configuración Global de MCP](./mcp-global-setup.md) - Configuración segura de MCP
+- [Quality Gates](./quality-gates.md) - Verificaciones de seguridad en CI/CD
+
+---
+
+_Guía de Hardening de Seguridad de SINAPSE v4.0_