# US-MGN007-003: Gestionar Eventos de Seguridad

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN007-003 |
| **Modulo** | MGN-007 Audit |
| **Sprint** | Sprint 5 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 8 |
| **Estado** | Ready |
| **RF Relacionado** | RF-AUDIT-003 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** administrador del sistema
**Quiero** detectar y gestionar eventos de seguridad automaticamente
**Para** proteger el sistema y responder rapidamente a amenazas

---

## Descripcion

El sistema detecta automaticamente eventos de seguridad como intentos de login fallidos, accesos desde ubicaciones inusuales y cambios en permisos. Clasifica por severidad y permite flujo de resolucion.

### Contexto

- Deteccion automatica de patrones sospechosos
- Clasificacion por severidad
- Alertas en tiempo real
- Flujo de resolucion de incidentes

---

## Criterios de Aceptacion

### Escenario 1: Detectar brute force

```gherkin
Given configuracion: max 5 intentos en 15 minutos
When un usuario tiene 5 intentos de login fallidos
Then el sistema crea evento de seguridad:
  | event_type | "brute_force_detected" |
  | severity | "high" |
  | title | "Multiples intentos de login fallidos" |
  And notifica a los administradores
  And bloquea la cuenta temporalmente
```

### Escenario 2: Detectar login desde nueva ubicacion

```gherkin
Given usuario que siempre accede desde Mexico
When inicia sesion desde un pais diferente por primera vez
Then el sistema crea evento de seguridad:
  | event_type | "session_from_new_location" |
  | severity | "medium" |
  And incluye los detalles de ubicacion en metadata
```

### Escenario 3: Listar eventos de seguridad

```gherkin
Given un administrador con permiso "audit.security.read"
When accede a GET /api/v1/audit/security?severity=high&isResolved=false
Then retorna eventos sin resolver de severidad alta
  And ordenados por fecha descendente
```

### Escenario 4: Ver dashboard de seguridad

```gherkin
Given eventos de seguridad en el sistema
When accede a GET /api/v1/audit/security/dashboard
Then retorna:
  | summary | { critical: 0, high: 2, medium: 5, low: 20 } |
  | unresolvedCount | 7 |
  | recentEvents | [...] |
  | topAffectedUsers | [...] |
```

### Escenario 5: Resolver evento de seguridad

```gherkin
Given un evento de seguridad no resuelto
  And administrador con permiso "audit.security.resolve"
When envia POST /api/v1/audit/security/{eventId}/resolve
  | resolution | "verified_legitimate" |
  | notes | "Usuario verificado por telefono" |
Then el evento se marca como resuelto
  And se registra quien y cuando lo resolvio
```

### Escenario 6: Detectar cambio de permisos

```gherkin
Given un usuario regular
When se le asigna rol de administrador
Then el sistema crea evento de seguridad:
  | event_type | "permission_escalation" |
  | severity | "medium" |
  | metadata | { old_role: "user", new_role: "admin" } |
```

### Escenario 7: Detectar eliminacion masiva

```gherkin
Given configuracion: alertar si mas de 10 deletes en 5 minutos
When un usuario elimina 15 registros en 3 minutos
Then el sistema crea evento de seguridad:
  | event_type | "mass_delete_attempt" |
  | severity | "high" |
  | metadata | { count: 15, windowMinutes: 3 } |
```

### Escenario 8: Alertas automaticas

```gherkin
Given evento critico detectado
When el evento se registra
Then se envia notificacion a todos los admins
  And se marca el canal utilizado (email, push)
  And se registra a quienes se notifico
```

### Escenario 9: Detalle de evento

```gherkin
Given un evento de seguridad existente
When consulta GET /api/v1/audit/security/{eventId}
Then retorna toda la informacion del evento
  And incluye eventos relacionados (si aplica)
  And muestra timeline de acciones
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  EVENTOS DE SEGURIDAD                                  [Dashboard]|
+------------------------------------------------------------------+
| [Severidad: Todas v] [Resueltos: No v] [Tipo: Todos v] [Buscar...] |
+------------------------------------------------------------------+

RESUMEN
+------------------------------------------------------------------+
| ⚫ Critical: 0 | 🔴 High: 2 | 🟠 Medium: 5 | 🟢 Low: 20 | ⏳ 7 pendientes |
+------------------------------------------------------------------+

| FECHA              | SEVERIDAD | TIPO                  | USUARIO   | ESTADO |
+------------------------------------------------------------------+
| 2025-12-05 10:30   | 🔴 High    | Brute force detected  | john@...  | ⏳     |
|   5 intentos fallidos en 10 minutos desde IP 192.168.1.100       |
|                                               [Ver] [=== Resolver ===]|
+------------------------------------------------------------------+
| 2025-12-05 09:15   | 🟠 Medium  | Nueva ubicacion       | mary@...  | ⏳     |
|   Login desde Estados Unidos (usualmente Mexico)                  |
|                                               [Ver] [=== Resolver ===]|
+------------------------------------------------------------------+
| 2025-12-04 16:00   | 🟠 Medium  | Rol modificado        | new@...   | ✓      |
|   Usuario promovido a admin                                       |
|   Resuelto por: Admin - "Promocion autorizada por HR"            |
+------------------------------------------------------------------+

Modal: Resolver Evento
+------------------------------------------------------------------+
| RESOLVER EVENTO                                             [X]  |
+------------------------------------------------------------------+
| Evento: Multiples intentos de login fallidos                      |
| Usuario afectado: john@company.com                                |
| Fecha: 2025-12-05 10:30:00                                       |
|                                                                   |
| Resolucion*                                                       |
| [v] Verificado como legitimo                                      |
| [ ] Bloquear usuario                                              |
| [ ] Resetear password                                             |
| [ ] Falso positivo                                                |
|                                                                   |
| Notas                                                             |
| [Usuario verificado por telefono. Olvido password.           ]   |
|                                                                   |
|                               [Cancelar]  [=== Resolver ===]     |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /audit/security | Listar eventos |
| GET | /audit/security/:id | Detalle de evento |
| GET | /audit/security/dashboard | Dashboard |
| POST | /audit/security/:id/resolve | Resolver evento |

### Tipos de Eventos

| Categoria | Eventos |
|-----------|---------|
| Autenticacion | login_failed, brute_force_detected, login_blocked |
| Sesiones | session_from_new_location, concurrent_session |
| Permisos | permission_escalation, admin_created |
| Datos | mass_delete_attempt, data_export, sensitive_data_access |

### Severidades

| Nivel | Accion |
|-------|--------|
| low | Solo log |
| medium | Notificar admin |
| high | Notificar + considerar bloqueo |
| critical | Bloquear + notificar urgente |

---

## Definicion de Done

- [ ] Detector de patrones (brute force, etc.)
- [ ] Clasificacion por severidad
- [ ] Creacion automatica de eventos
- [ ] Alertas a administradores
- [ ] Dashboard de seguridad
- [ ] Flujo de resolucion
- [ ] Integracion con bloqueo de cuentas
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| US-MGN007-002 | Logs de acceso (datos de entrada) |
| MGN-008 Notifications | Para alertas |
| Tabla security_events | Storage |

### Bloquea

| Item | Descripcion |
|------|-------------|
| US-MGN007-004 | Reportes de seguridad |

---

## Historial

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