Saltar al contenido principal

TEC-008 — Auditoría de Accesos

· 3 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

Implementación de la mejora TEC-008 (Auditoría de Accesos), dentro de 6.2 Seguridad. El sistema pasa de un log de peticiones (que había que interpretar) a un registro de accesos con resultado, usuario del intento e IP, escrito siempre desde el servidor, más una página de consulta con los filtros que exige el requerimiento.


📋 Alcance​

RFEntregable
RF-TEC-008-01Registrar los intentos de acceso, exitosos y fallidos
RF-TEC-008-02Registrar las acciones privilegiadas de los usuarios administrativos
RF-TEC-008-03Incluir IP, usuario, fecha y resultado en cada registro
RF-TEC-008-04Consultar con filtros por usuario, fecha y resultado

⚙️ Cómo funciona​

  • Tabla nueva auditoria_accesos (migración 034-create-auditoria-accesos), inmutable: la API solo inserta y consulta. Cada fila tiene categoria (ACCESO / ACCION_PRIVILEGIADA), evento, resultado (EXITOSO / FALLIDO / DENEGADO), motivo, ip, usuario escrito, usuario resuelto con su rol, contexto HTTP y fecha.
  • Los accesos se registran en el servidor: login (éxito, contraseña incorrecta y usuario inexistente), segundo factor (éxito, código inválido y agotamiento), enrolamiento, renovación de sesión, cierre de sesión y accesos denegados por rol desde RolesGuard.
  • Las acciones privilegiadas se auditan con un decorador: @AuditarAccionPrivilegiada({ evento, entidad, idParam }) sobre el endpoint, y un interceptor global que solo actúa sobre lo marcado. 73 endpoints administrativos en 19 controladores. Un intento fallido también queda auditado.
  • Consulta: GET /api/auditoria-accesos con filtros usuario, resultado, evento, categoria, ip, desde, hasta y search, en modo offset o cursor (TEC-003), más GET /api/auditoria-accesos/resumen para los totales. Reservado a Administrador y Auditor.
  • Página /auditoria-accesos: dos pestañas («Accesos» y «Acciones privilegiadas»), tarjetas de totales, rankings, filtros, «Cargar más» por cursor y exportación CSV de lo que está en pantalla.
  • Auditar no rompe nada: las escrituras son tolerantes a fallos y no alteran la respuesta; si el registro falla, queda en el log de la aplicación.

🗄️ Base de datos​

Migración 034-create-auditoria-accesos: tabla auditoria_accesos con FK a usuarios (ON DELETE SET NULL), CHECK de categoría y resultado, e índices por fecha, usuario, resultado, categoría y evento (los que sostienen los filtros de RF-04).

🔐 Seguridad​

  • Los intentos fallidos distinguen usuario inexistente de contraseña incorrecta en el motivo auditado, sin cambiar la respuesta HTTP (401/404 como antes: no se filtra al cliente si el usuario existe).
  • La contraseña nunca se persiste: el detalle del interceptor sustituye los campos sensibles (password, token, secreto, codigo…) por [omitido].
  • La consulta está restringida por rol; un intento sin permiso devuelve 403 y queda registrado como ACCESO_DENEGADO.

✅ Verificación​

  • Suites en verde: API (82 suites, 808 pruebas) y web (16 suites, 65 pruebas), 0 fallos; tsc --noEmit EXIT 0 en ambos. TEC-008 aporta 27 pruebas en el API y 9 en la web.
  • Integración real (scripts/verificar-auditoria-accesos.ts) contra la API y la base reales: 35/35 comprobaciones OK, con usuarios temporales creados y eliminados al terminar.

📚 Documentación​

  • Especificación: docs/mejoras/tec-008-auditoria-accesos.md
  • Manual de usuario: docs/manuales/auditoria/auditoria-accesos.md

⚠️ Limitaciones conocidas​

  1. Las peticiones con token caducado (401 de JwtAuthGuard) no generan fila.
  2. Una operación administrativa nueva debe marcarse con el decorador para ser auditada.
  3. El log de peticiones y la auditoría de loggers siguen existiendo en paralelo.
  4. Sin retención automática ni alerta por patrón sospechoso.