imagy-audit — Auditoria

Proposito

imagy-audit es el servicio compartido que provee un trail de auditoria inmutable para toda la plataforma Imagy. Cada accion relevante ejecutada en cualquier dominio (ImagFlow, ImagLend, ImagSign, ImagID, Identity, Notifications) queda registrada como un evento estandarizado bajo el formato OCSF (Open Cybersecurity Schema Framework), garantizando trazabilidad completa, compliance regulatorio y compatibilidad con herramientas de seguridad enterprise.

El servicio opera bajo un principio fundamental: append-only. Los eventos de auditoria no pueden ser modificados ni eliminados una vez registrados.

Responsabilidades

Responsabilidad	Descripcion
Registro automatico	Consume eventos de todos los dominios via RabbitMQ y los persiste en formato OCSF
Registro manual	API para crear entradas de auditoria custom desde cualquier servicio
Consulta	API de busqueda con filtros por actor, recurso, periodo, severidad, categoria
Reportes	Generacion de reportes agregados por actor, recurso, tipo de evento y periodo
Exportacion	Exportacion en formato OCSF JSON y CSV para integracion con SIEMs
Security Hub	Envio de findings a AWS Security Hub (requisito FTR)
Retencion	Politicas de retencion configurables por tenant
Inmutabilidad	Garantia a nivel de base de datos de que los registros no pueden alterarse

OCSF — Open Cybersecurity Schema Framework

La plataforma adopta OCSF como formato estandar para todos los eventos de auditoria (ver ADR-009). OCSF es un framework respaldado por AWS y Splunk que define una taxonomia estructurada para eventos de seguridad.

Estructura Taxonomica

OCSF organiza los eventos en tres niveles jerarquicos:

Nivel	Descripcion	Ejemplo
Category	Agrupacion de alto nivel	Identity & Access Management (3)
Class	Tipo especifico de evento dentro de la categoria	Account Change (3001)
Activity	Accion concreta realizada	Create (1), Update (2), Delete (3)

Categorias Utilizadas en la Plataforma

Campos Principales de un Evento

Cada evento OCSF registrado contiene:

• class_uid / class_name — Tipo de evento
• category_uid / category_name — Categoria
• activity_id / activity_name — Accion realizada
• severity_id — Nivel de severidad (1=Informational, 2=Low, 3=Medium, 4=High, 5=Critical)
• time — Timestamp del evento (epoch ms)
• actor — Quien ejecuto la accion (usuario, sistema, servicio)
• src_endpoint — Servicio o IP de origen
• metadata — Producto, version, tenant, profiles
• unmapped — Campos de extension para datos de dominio (financieros, operativos)

Modos de Operacion

imagy-audit opera en dos modos complementarios:

Modo Automatico (Event-Driven)

El servicio consume eventos de todos los dominios a traves de RabbitMQ. Cada evento de dominio es transformado automaticamente al formato OCSF y persistido.

Eventos consumidos de cada dominio:

Dominio	Eventos
ImagLend	application.created, credit.disbursed, payment.received, product.updated
ImagFlow	execution.completed, execution.failed, flow.published
ImagSign	signature.requested, signature.completed, signature.rejected
ImagID	subject.created, subject.verified, subject.blacklisted
Identity	user.created, user.login, user.logout, role.assigned, permission.changed
Notifications	notification.sent, notification.failed

Modo Manual (API Directa)

Para eventos custom que no se generan automaticamente, los servicios pueden registrar entradas de auditoria directamente via API:

POST /api/v1/audit/events
POST /internal/audit/record

Esto es util para:

• Acciones administrativas que no producen eventos de dominio
• Eventos de compliance custom definidos por el tenant
• Integraciones externas que necesitan registrar actividad

Integracion con AWS Security Hub

imagy-audit envia findings a AWS Security Hub en formato OCSF nativo, cumpliendo con el requisito FTR (Foundational Technical Review) de AWS Partner. Los eventos con severidad >= Medium se envian automaticamente como findings.

Exportacion

El servicio soporta exportacion de eventos para integracion con sistemas externos:

Formato	Descripcion	Uso
OCSF JSON	Formato nativo, compatible con SIEMs modernos	Splunk, Datadog, Elastic
CSV	Formato tabular para analisis	Excel, BI tools, reportes regulatorios

Las exportaciones se ejecutan como jobs asincrono. El tenant solicita una exportacion con filtros (periodo, categoria, actor) y recibe una URL de descarga cuando el job finaliza.

Reportes

imagy-audit genera reportes agregados bajo demanda:

• Por actor — Top actores por volumen de actividad en un periodo
• Por recurso — Recursos mas accedidos o modificados
• Por tipo de evento — Distribucion de eventos por categoria y clase
• Por periodo — Timeline de actividad con granularidad configurable

Retencion

Las politicas de retencion son configurables por tenant:

Tier	Periodo	Almacenamiento	Acceso
Hot	0-90 dias	PostgreSQL (particiones activas)	Consulta directa via API
Warm	91-365 dias	PostgreSQL (particiones archivadas)	Consulta via API (mas lento)
Cold	> 365 dias	S3 Glacier	Solo via exportacion bajo demanda

Arquitectura Interna

Repositorio

• Repo: imagy-audit
• Base de datos: imagy_audit
• Puerto local: 4006
• Equipo: Team Platform

Documentos Relacionados

• Modelo de Datos — Tablas, particionamiento e indices
• API Reference — Endpoints de consulta, reportes y exportacion
• ADR-009: OCSF como Estandar — Decision arquitectonica