Actividad, historial y auditoría

MonoPbx mantiene dos registros relacionados de la actividad administrativa.

• El registro de auditoría indica quién hizo qué, cuándo, desde dónde y cómo. Guarda un hash de cada cambio, nunca los valores, así que se puede conservar mucho tiempo (7 años) sin guardar secretos.
• El historial de configuración guarda el antes y el después de cada cambio de configuración, con los datos enmascarados, para que pueda ver la diferencia y revertirla.

Registro de auditoría

La página de historial de llamadas con sus filtros y botones de exportación.

Cada registro tiene un actor (user, api_key, device, job o anonymous), un canal (ui, api, cli, mcp o system), la dirección del cliente, una action como auth.login o config.updated, el objeto (entity_type, entity_id), un outcome (success, denied o error) y algunos detalles, como los nombres de los campos cambiados. El canal ui, cli o api es el que declara un cliente autenticado en el encabezado X-Mpbx-Channel; una clave de API siempre es api.

Hoy se registra:

• cambios de configuración: usuarios, departamentos, extensiones, dispositivos, roles y asignaciones de roles (creados, actualizados, eliminados);
• inicios de sesión, exitosos y rechazados (con un motivo como wrong_password o locked), bloqueos, cierres de sesión, reutilización de tokens de renovación, y cambios de contraseña o de verificación en dos pasos;
• administración de roles, claves de API y roles del sistema, y un principal del sistema que entra a una empresa;
• administración de certificados y respaldos;
• administración de proveedores y números de SMS.

Todavía no se registra: el uso de claves de API, la autenticación bearer fallida, la creación y la suspensión de empresas.

Consultarlo

Ruta	Permiso	Devuelve
GET /api/v1/audit-log	audit:read (Propietario por omisión; un Administrador de departamento no lo tiene)	Su empresa, del más reciente al más antiguo
GET /api/v1/system/audit-log	system.audit:read (Administrador del sistema y Propietario del sistema), token de ámbito de sistema	Solo los registros de toda la instalación

Se aplican los parámetros habituales de lista: limit, cursor, filter=campo:operador:valor y sort. Los campos de filtro son ts (gt gte lt lte, RFC 3339), actor_type, actor_id, channel, entity_type, entity_id, outcome (eq) y action (eq o starts_with).

GET /api/v1/audit-log?filter=action:starts_with:auth.&filter=outcome:eq:denied&limit=50

El registro de auditoría se guarda en ClickHouse. Sin clickhouse.url configurado, las rutas responden 503 MPBX-API-NOT-CONFIGURED; los registros esperan en Postgres hasta que ClickHouse esté disponible. Un registro existe si y solo si su cambio se confirmó. El registro no tiene ruta de escritura. No está implementada una cadena de hashes que detecte manipulaciones por alguien con permiso de escritura en ClickHouse.

Historial de configuración y reversión

GET  /api/v1/config-history?filter=entity_type:eq:department&filter=entity_id:eq:<id>&sort=seq
GET  /api/v1/config-history/{id}
POST /api/v1/config-history/{id}/revert

Cada entrada muestra quién, cómo y cuándo, y el antes y el después de los campos que cambiaron, para departamentos, usuarios, extensiones, dispositivos, roles, asignaciones de roles y paquetes de idioma. Para leer se necesita audit:read más el permiso de lectura del tipo de objeto (por ejemplo users:read). Las entradas de un tipo que no puede leer responden 404, no 403.

• Los secretos nunca aparecen. Cualquier campo que nombre un secreto (contraseña, token, TOTP, credenciales, hash y similares) se muestra como [masked]. Un cambio en uno de ellos aparece solo por su nombre: el historial puede indicar que la contraseña cambió, pero nada más.
• Una reversión es un cambio nuevo. Nunca se reescribe nada, y la propia reversión queda en el historial y en el registro de auditoría.
• La tabla de historial es solo de adición para el rol de la empresa.

La consola web tiene una página de historial para esto.

Eventos en vivo

Los registros de auditoría y los cambios de configuración también se transmiten por los temas audit y config del WebSocket de eventos a quienes tengan los permisos correspondientes.