# RF-AUDIT-003: Eventos de Seguridad

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | RF-AUDIT-003 |
| **Modulo** | MGN-007 Audit |
| **Titulo** | Eventos de Seguridad |
| **Prioridad** | P0 - Critica |
| **Estado** | Draft |
| **Fecha** | 2025-12-05 |

---

## Descripcion

El sistema debe detectar, registrar y alertar sobre eventos de seguridad como intentos de acceso fallidos, cambios en permisos, accesos desde ubicaciones inusuales, y otros patrones sospechosos.

---

## Requisitos Funcionales

### RF-AUDIT-003.1: Estructura del Evento de Seguridad

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador unico |
| tenant_id | UUID | Tenant (si aplica) |
| user_id | UUID | Usuario afectado |
| event_type | VARCHAR(50) | Tipo de evento |
| severity | ENUM | low, medium, high, critical |
| title | VARCHAR(255) | Titulo descriptivo |
| description | TEXT | Descripcion detallada |
| metadata | JSONB | Datos adicionales |
| ip_address | INET | IP origen |
| country_code | VARCHAR(2) | Pais |
| is_resolved | BOOLEAN | Evento resuelto |
| resolved_by | UUID | Usuario que resolvio |
| resolved_at | TIMESTAMPTZ | Fecha resolucion |
| created_at | TIMESTAMPTZ | Timestamp |

### RF-AUDIT-003.2: Tipos de Eventos de Seguridad

```typescript
enum SecurityEventType {
  // Autenticacion
  LOGIN_FAILED = 'login_failed',
  LOGIN_BLOCKED = 'login_blocked',
  BRUTE_FORCE_DETECTED = 'brute_force_detected',
  PASSWORD_CHANGED = 'password_changed',
  PASSWORD_RESET_REQUESTED = 'password_reset_requested',

  // Sesiones
  SESSION_HIJACK_ATTEMPT = 'session_hijack_attempt',
  CONCURRENT_SESSION = 'concurrent_session',
  SESSION_FROM_NEW_LOCATION = 'session_from_new_location',
  SESSION_FROM_NEW_DEVICE = 'session_from_new_device',

  // Permisos
  PERMISSION_ESCALATION = 'permission_escalation',
  ROLE_CHANGED = 'role_changed',
  ADMIN_CREATED = 'admin_created',

  // Datos
  MASS_DELETE_ATTEMPT = 'mass_delete_attempt',
  DATA_EXPORT = 'data_export',
  SENSITIVE_DATA_ACCESS = 'sensitive_data_access',

  // Sistema
  API_KEY_CREATED = 'api_key_created',
  WEBHOOK_MODIFIED = 'webhook_modified',
  SETTINGS_CHANGED = 'settings_changed'
}
```

### RF-AUDIT-003.3: Severidad de Eventos

| Severidad | Descripcion | Accion |
|-----------|-------------|--------|
| `low` | Informativo, sin accion requerida | Log only |
| `medium` | Requiere revision | Notificar admin |
| `high` | Accion requerida pronto | Notificar + alertar |
| `critical` | Accion inmediata requerida | Bloquear + notificar |

### RF-AUDIT-003.4: Deteccion de Patrones

El sistema detecta automaticamente:

```typescript
interface SecurityPattern {
  // Brute force
  maxLoginAttempts: 5;
  windowMinutes: 15;
  lockoutMinutes: 30;

  // Ubicacion
  flagNewCountry: true;
  flagNewCity: true;

  // Comportamiento
  flagMassDelete: { threshold: 10, windowMinutes: 5 };
  flagMassExport: { threshold: 1000, windowMinutes: 60 };

  // Horario
  flagOutOfHours: { start: '22:00', end: '06:00' };
}
```

### RF-AUDIT-003.5: Alertas Automaticas

Cuando se detecta un evento critico:

1. Registrar en base de datos
2. Enviar notificacion a admins
3. Opcionalmente bloquear accion
4. Crear tarea de seguimiento

```typescript
interface SecurityAlert {
  eventId: UUID;
  sentTo: UUID[];  // Admins
  channels: ('email' | 'push' | 'slack')[];
  sentAt: TIMESTAMPTZ;
  acknowledged: boolean;
  acknowledgedBy?: UUID;
}
```

### RF-AUDIT-003.6: Resolucion de Eventos

Un admin puede marcar un evento como resuelto:

```typescript
POST /api/v1/audit/security/:eventId/resolve
{
  "resolution": "verified_legitimate",  // o "blocked_user", "reset_password", etc.
  "notes": "Usuario verificado por telefono"
}
```

---

## Operaciones

### Listar Eventos de Seguridad

```typescript
GET /api/v1/audit/security?severity=high&isResolved=false

Response:
{
  "data": [
    {
      "id": "uuid",
      "eventType": "brute_force_detected",
      "severity": "high",
      "title": "Multiples intentos de login fallidos",
      "user": { "id": "...", "email": "user@example.com" },
      "ipAddress": "192.168.1.100",
      "countryCode": "MX",
      "isResolved": false,
      "createdAt": "2025-12-05T10:00:00Z"
    }
  ]
}
```

### Obtener Detalle de Evento

```typescript
GET /api/v1/audit/security/:eventId

Response:
{
  "id": "uuid",
  "eventType": "brute_force_detected",
  "severity": "high",
  "title": "Multiples intentos de login fallidos",
  "description": "Se detectaron 5 intentos fallidos en 10 minutos",
  "metadata": {
    "attempts": 5,
    "windowMinutes": 10,
    "lastAttemptAt": "2025-12-05T09:55:00Z"
  },
  "relatedEvents": [...]
}
```

### Dashboard de Seguridad

```typescript
GET /api/v1/audit/security/dashboard

Response:
{
  "summary": {
    "critical": 0,
    "high": 2,
    "medium": 5,
    "low": 20,
    "unresolvedCount": 7
  },
  "recentEvents": [...],
  "topAffectedUsers": [...],
  "topSourceIPs": [...]
}
```

---

## Reglas de Negocio

| ID | Regla | Severidad |
|----|-------|-----------|
| BR-001 | Eventos criticos notifican inmediatamente | Critical |
| BR-002 | Brute force bloquea cuenta temporalmente | Security |
| BR-003 | Login desde nuevo pais requiere verificacion | Security |
| BR-004 | Solo admins ven eventos de seguridad | Security |
| BR-005 | Eventos no se pueden eliminar | Compliance |

---

## Criterios de Aceptacion

- [ ] Deteccion automatica de patrones sospechosos
- [ ] Clasificacion por severidad
- [ ] Alertas en tiempo real
- [ ] Dashboard de seguridad
- [ ] Flujo de resolucion de eventos
- [ ] Historial de eventos por usuario
- [ ] Integracion con bloqueo de cuentas

---

## Historial

| Version | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0 | 2025-12-05 | Requirements-Analyst | Creacion inicial |