system-docs/02_COMPONENTES/internos/auditoria.md

Auditoría

Nombre: Sentinel
Estado: Planificado

---

Descripción

Sistema de auditoría automatizada con estrategia dual: LIGHT (rápido, exhaustivo) y DEEP (selectivo, profundo).

┌─────────────────────────────────────────────────────────────────┐
│                    PRINCIPIO SENTINEL                           │
│                                                                 │
│  "Confía, pero verifica. Verifica todo, siempre, sin excepción" │
└─────────────────────────────────────────────────────────────────┘

---

Filosofía Dual

Aspecto	SENTINEL-LIGHT	SENTINEL-DEEP
Analogía	Guardia de seguridad	Detective investigador
Enfoque	Exhaustivo, superficial	Selectivo, profundo
Motor	Reglas + ML ligero	LLM pesado
Frecuencia	Cada 5 min	Cada hora
Costo	Mínimo	Variable

---

SENTINEL-LIGHT

Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                      SENTINEL-LIGHT                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│  │   RULES     │    │    STATS    │    │   ALERTS    │         │
│  │   ENGINE    │───▶│  COLLECTOR  │───▶│  DISPATCHER │         │
│  └─────────────┘    └─────────────┘    └─────────────┘         │
│         │                  │                  │                 │
│         ▼                  ▼                  ▼                 │
│  ┌─────────────────────────────────────────────────────────────┤
│  │                    SYS_LOG (Source)                         │
│  └─────────────────────────────────────────────────────────────┤
│                            │                                    │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────────────┤
│  │                 AUDIT_RESULTS (Sink)                        │
│  └─────────────────────────────────────────────────────────────┤
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Ciclo de Ejecución (cada 5 min)

1. QUERY
   SELECT * FROM SYS_LOG
   WHERE audit_status = 'PENDING'
   AND timestamp_created > NOW() - INTERVAL '10 minutes'
   LIMIT 1000

2. APPLY RULES
   Para cada registro:
   - Ejecutar reglas de integridad
   - Ejecutar reglas de conformidad
   - Ejecutar reglas de rendimiento

3. CLASSIFY
   - PASS: Todas las reglas OK
   - WARN: Reglas MEDIUM fallaron
   - FAIL: Reglas HIGH/CRITICAL fallaron

4. UPDATE & ESCALATE
   - UPDATE SYS_LOG SET audit_status
   - INSERT AUDIT_RESULTS
   - Si FAIL → marcar para DEEP
   - Si CRITICAL → alerta inmediata

---

Reglas de Integridad (I-*)

Regla	Nombre	Severidad	Condición
I-001	Hash entrada coincide	CRITICAL	input_hash == SHA256(archivo)
I-002	Hash salida coincide	CRITICAL	output_hash == SHA256(archivo)
I-003	Cadena trazas válida	HIGH	parent_trace_id existe o es null
I-004	Referencias no huérfanas	HIGH	input_ref y output_ref existen
I-005	Idempotency key única	MEDIUM	No duplicados con distinto resultado

---

Reglas de Conformidad (C-*)

Regla	Nombre	Severidad	Condición
C-001	Campos obligatorios	HIGH	Todos los campos requeridos presentes
C-002	Status code válido	HIGH	status_code en lista permitida
C-003	Step type válido	HIGH	step_type en lista permitida
C-004	Confidence en rango	MEDIUM	0 <= confidence <= 1
C-005	Timestamps coherentes	MEDIUM	completed >= started >= created

---

Reglas de Rendimiento (P-*)

Regla	Nombre	Severidad	Condición
P-001	Latencia aceptable	MEDIUM	duration_ms <= expected * 2
P-002	Costo razonable	MEDIUM	cost_units <= max_expected
P-003	Sin reintentos excesivos	LOW	retries <= 3

---

SENTINEL-DEEP

Cuándo se Activa

• Regla CRITICAL falló en LIGHT
• Muestreo aleatorio (5% de registros PASS)
• Petición manual de auditoría

Qué Hace

┌─────────────────────────────────────────────────────────────────┐
│                      SENTINEL-DEEP                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Obtener contexto completo del registro                     │
│  2. Recuperar archivos de input_ref y output_ref               │
│  3. Analizar con LLM:                                          │
│     - ¿El output es coherente con el input?                    │
│     - ¿Hay anomalías semánticas?                               │
│     - ¿La confianza reportada es realista?                     │
│  4. Generar informe detallado                                  │
│  5. Si anomalía → alerta + bloqueo                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Niveles de Severidad

Nivel	Acción	Alerta
CRITICAL	Escalado inmediato + DEEP	Inmediata
HIGH	Log error + revisar	Batch (cada hora)
MEDIUM	Log warning	Batch (diario)
LOW	Log info	Ninguna

---

Schema SQL

CREATE TABLE audit_results (
    id BIGSERIAL PRIMARY KEY,
    batch_id UUID NOT NULL,
    audit_type VARCHAR(10) NOT NULL,  -- 'LIGHT' o 'DEEP'
    records_checked INTEGER NOT NULL,
    records_pass INTEGER NOT NULL,
    records_warn INTEGER NOT NULL,
    records_fail INTEGER NOT NULL,
    rules_triggered JSONB,
    started_at TIMESTAMPTZ NOT NULL,
    completed_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Índice para búsqueda por fecha
CREATE INDEX idx_audit_results_created ON audit_results(created_at);

---

Métricas

Métrica	Descripción	Umbral
pass_rate	% registros que pasan	> 99%
avg_latency_ms	Latencia promedio	< 100ms
escalation_rate	% escalados a DEEP	< 1%
alert_rate	Alertas por hora	< 5

---

Pendiente

• Implementación scheduler LIGHT (cada 5 min)
• Implementación scheduler DEEP (cada hora)
• Dashboard de estado
• Sistema de alertas (ntfy)
• Integración con Feldman para verificar cadena de bloques