RF-AUDIT-002: Logs de Acceso

Identificacion

Campo	Valor
ID	RF-AUDIT-002
Modulo	MGN-007 Audit
Titulo	Logs de Acceso
Prioridad	P0 - Critica
Estado	Draft
Fecha	2025-12-05

Descripcion

El sistema debe registrar todos los accesos a recursos protegidos, incluyendo peticiones HTTP, accesos a APIs, y consultas a datos sensibles, para monitoreo de seguridad y cumplimiento normativo.

Requisitos Funcionales

RF-AUDIT-002.1: Estructura del Log de Acceso

Campo	Tipo	Descripcion
id	UUID	Identificador unico
tenant_id	UUID	Tenant (si aplica)
user_id	UUID	Usuario (si autenticado)
session_id	UUID	ID de sesion
request_id	UUID	ID unico de la peticion
method	VARCHAR(10)	GET, POST, PUT, DELETE
path	VARCHAR(500)	Ruta del recurso
query_params	JSONB	Parametros de query
status_code	INTEGER	Codigo de respuesta HTTP
response_time_ms	INTEGER	Tiempo de respuesta
ip_address	INET	IP del cliente
user_agent	TEXT	User agent
referer	VARCHAR(500)	Referer header
country_code	VARCHAR(2)	Pais (geo-ip)
created_at	TIMESTAMPTZ	Timestamp

RF-AUDIT-002.2: Niveles de Logging

enum AccessLogLevel {
  MINIMAL = 'minimal',   // Solo errores y auth
  STANDARD = 'standard', // Todo excepto GET de listas
  VERBOSE = 'verbose',   // Todo incluyendo GETs
  DEBUG = 'debug'        // Todo + request body
}

Configurable por tenant y globalmente.

RF-AUDIT-002.3: Recursos a Monitorear

Tipo	Ejemplos	Prioridad
Autenticacion	/auth/login, /auth/logout	Siempre
Admin APIs	/admin/, /settings/	Siempre
Datos sensibles	/users/, /contacts/	Siempre
APIs publicas	/api/v1/*	Configurable
Assets estaticos	/assets/, /public/	Nunca

RF-AUDIT-002.4: Excepcion de Logging

Ciertos paths se excluyen por defecto:

const EXCLUDED_PATHS = [
  '/health',
  '/metrics',
  '/favicon.ico',
  '/assets/*',
  '/static/*'
];

RF-AUDIT-002.5: Request Body Logging

Para operaciones criticas, se puede registrar el body:

// Solo para operaciones de escritura en recursos criticos
// Body se sanitiza (passwords -> ****)
// Maximo 10KB de body almacenado
{
  "requestBody": {
    "email": "user@example.com",
    "password": "****",
    "name": "John Doe"
  }
}

RF-AUDIT-002.6: Metricas de Acceso

El sistema calcula metricas en tiempo real:

interface AccessMetrics {
  requestsPerMinute: number;
  errorRate: number;
  avgResponseTime: number;
  uniqueUsers: number;
  topEndpoints: { path: string; count: number }[];
  topErrors: { statusCode: number; count: number }[];
}

Operaciones

Consultar Logs de Acceso

GET /api/v1/audit/access?from=2025-12-01&to=2025-12-05&userId=uuid&statusCode=500

Response:
{
  "data": [
    {
      "id": "uuid",
      "method": "POST",
      "path": "/api/v1/users",
      "statusCode": 201,
      "responseTimeMs": 45,
      "user": { "id": "...", "name": "Admin" },
      "ipAddress": "192.168.1.100",
      "createdAt": "2025-12-05T10:00:00Z"
    }
  ],
  "meta": { "total": 1000, "page": 1 }
}

Consultar Metricas

GET /api/v1/audit/access/metrics?period=1h

Response:
{
  "period": "1h",
  "requestsTotal": 5000,
  "requestsPerMinute": 83.3,
  "errorRate": 0.02,
  "avgResponseTime": 120,
  "p99ResponseTime": 450,
  "uniqueUsers": 150,
  "topEndpoints": [
    { "path": "/api/v1/users", "count": 500 }
  ]
}

Consultar Sesiones de Usuario

GET /api/v1/audit/access/user/:userId/sessions

Response:
{
  "sessions": [
    {
      "sessionId": "uuid",
      "startedAt": "2025-12-05T08:00:00Z",
      "lastActivityAt": "2025-12-05T10:30:00Z",
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0...",
      "requestCount": 150
    }
  ]
}

Reglas de Negocio

ID	Regla	Severidad
BR-001	Logs de acceso son inmutables	Critical
BR-002	Retencion: 90 dias por defecto	Compliance
BR-003	Body de request sanitizado	Security
BR-004	Solo admins acceden a logs	Security
BR-005	Rate limit en consultas de logs	Performance

Criterios de Aceptacion

Logging automatico de todas las peticiones
Filtrado por paths excluidos
Sanitizacion de datos sensibles
Metricas en tiempo real
Consulta con filtros multiples
Geo-IP para ubicacion
Performance < 5ms overhead

Historial

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

4.7 KiB Raw Blame History