# 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

```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