Log Stream

El Log Stream de Trébol te permite recibir eventos de auditoría en tiempo real directamente en tu plataforma de análisis de logs preferida. Actualmente soportamos integración con Splunk. Esta funcionalidad es ideal para:

Monitoreo de seguridad: Detecta actividad sospechosa en tu cuenta
Cumplimiento normativo: Mantén un registro completo de todas las acciones en tu cuenta
Análisis de uso: Entiende cómo tu equipo utiliza Trébol
Alertas personalizadas: Configura alertas basadas en eventos específicos

Estructura de eventos

Todos los eventos enviados por el Log Stream siguen una estructura consistente:

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_name": "users.sign_in",
  "event_source": "auth0",
  "timestamp": "2026-01-12T10:30:00.000Z",
  "account_id": "account-123",
  "user_id": "user-456",
  "data": {
    "email": "[email protected]",
    "ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0..."
  }
}

Campos del evento

Campo	Tipo	Descripción
`event_id`	`string`	Identificador único del evento (UUID)
`event_name`	`string`	Nombre del evento (ver Eventos disponibles)
`event_source`	`string`	Origen del evento: `b-v` (Trébol) o `auth0`
`timestamp`	`string`	Fecha y hora del evento en formato ISO 8601
`account_id`	`string`	ID de la cuenta donde ocurrió el evento
`user_id`	`string`	ID del usuario que generó el evento (opcional)
`data`	`object`	Datos adicionales específicos del evento

Eventos disponibles

El Log Stream captura eventos de dos fuentes: Trébol (eventos de la plataforma) y Auth0 (eventos de autenticación).

Eventos de autenticación (Auth0)

Estos eventos se generan cuando los usuarios interactúan con el sistema de autenticación.

Autenticación

Evento	Descripción	Códigos Auth0
`users.sign_in`	Usuario inició sesión exitosamente	`s`
`users.sign_in_failed`	Intento de inicio de sesión fallido	`f`, `fp`, `fu`
`users.cross_origin_auth_failed`	Error de autenticación cross-origin	`fcoa`
`users.sign_out`	Usuario cerró sesión	`slo`
`users.sign_out_failed`	Error al cerrar sesión	`flo`

Datos adicionales para eventos de autenticación:

{
  "data": {
    "email": "[email protected]",
    "ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    "description": "Login successful",
    "connection": "Username-Password-Authentication",
    "client_id": "abc123",
    "client_name": "Trébol Dashboard"
  }
}

Ciclo de vida de usuarios

Evento	Descripción	Código Auth0
`users.deleted`	Usuario eliminado	`sdu`
`users.email_changed`	Dirección de email cambiada	`sce`
`users.phone_changed`	Número de teléfono cambiado	`scpn`

Contraseñas

Evento	Descripción	Código Auth0
`users.password_change_failed`	Error al cambiar contraseña	`fcp`
`users.password_reset_failed`	Error al restablecer contraseña	`fcpr`
`security.password_leak_detected`	Contraseña encontrada en base de datos de filtraciones	`pwd_leak`

Autenticación multifactor (MFA)

Evento	Descripción	Código Auth0
`mfa.failed`	Autenticación MFA fallida	`gd_auth_failed`
`mfa.recovery_failed`	Código de recuperación MFA fallido	`gd_recovery_failed`
`mfa.otp_rate_limited`	Demasiados intentos de OTP	`gd_otp_rate_limit_exceed`

Seguridad y rate limiting

Evento	Descripción	Código Auth0
`security.account_blocked`	Cuenta bloqueada (demasiados intentos fallidos)	`limit_wc`
`security.suspicious_login_blocked`	Inicio de sesión sospechoso bloqueado	`limit_sul`

Tokens

Evento	Descripción	Código Auth0
`token.exchange_failed`	Error en intercambio de token	`feacft`

Eventos de Trébol (B-V)

Estos eventos se generan por acciones realizadas en la plataforma de Trébol.

API Keys

Evento	Descripción
`apikeys.create`	API Key creada
`apikeys.delete`	API Key eliminada
`apikeys.list`	Listado de API Keys consultado

Verificaciones

Evento	Descripción	Metadatos
`verifications.get_all`	Listado de verificaciones consultado	`has_status_filter`, `has_date_filter`, `has_search_filter`, `has_tag_filter`, `has_flow_filter`, `has_label_filter`, `is_paginated`, `has_pagination`
`verifications.get_by_id`	Verificación consultada por ID	`verification_id`
`verifications.update`	Verificación actualizada	`verification_id`, `fields_changed`, `fields_changed_count`
`verifications.add_items`	Items agregados a verificación	`verification_id`, `items_count`, `item_types`
`verifications.add_key_people`	Personas clave agregadas	`verification_id`, `key_people_count`, `scopes_used`
`verifications.delete_subjects`	Sujetos eliminados	`verification_id`, `shareholders_deleted_count`, `signatories_deleted_count`, `shareholders_ids`, `signatories_ids`
`verifications.get_entity`	Entidad consultada	`entity`, `version`
`verifications.update_labels`	Etiquetas actualizadas	`verification_id`, `labels_count`

Ejemplo de datos para eventos de verificaciones:

{
  "data": {
    "email": "[email protected]",
    "ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "api_source": "frontend-api",
    "verification_id": "98d9010e-092c-4a01-bf24-d3e0c4e4f618",
    "fields_changed": ["status", "tags"],
    "fields_changed_count": 2
  }
}

Items de verificación

Evento	Descripción	Metadatos
`verification_items.create_user_event`	Evento de usuario creado	`event_name`
`verification_items.get_all`	Items listados	`has_item_type_filter`, `has_item_status_filter`, `has_tag_filter`, `has_pagination`
`verification_items.update`	Item actualizado	`has_value_update`, `has_options_update`, `has_tags_update`, `value_fields_updated`, `options_fields_updated`

Empresa

Evento	Descripción	Metadatos
`company.get_section`	Sección de empresa consultada	`section`

Configurar integración con Splunk

Para recibir eventos en Splunk, necesitas configurar un HTTP Event Collector (HEC) en tu instancia de Splunk y luego crear la integración en Trébol.

Requisitos previos

Configurar HTTP Event Collector en Splunk

En Splunk, ve a Settings → Data Inputs → HTTP Event Collector
Haz clic en New Token
Configura el token:
- Name: trebol-log-stream
- Source type: _json
- Index: Selecciona o crea un índice para los eventos de Trébol
Guarda y copia el Token Value generado

Importante: Guarda el token de forma segura. Lo necesitarás para configurar la integración en Trébol.

Obtener la URL del HEC

La URL del HEC tiene el siguiente formato:

https://<tu-instancia-splunk>:8088/services/collector/event

Por ejemplo:

Splunk Cloud: https://http-inputs-acme.splunkcloud.com:443/services/collector/event
Splunk Enterprise: https://splunk.tuempresa.com:8088/services/collector/event

Asegúrate de que el puerto 8088 (o el puerto configurado para HEC) esté accesible desde internet si usas Splunk Enterprise on-premise.

Crear la integración en Trébol

Para configurar la integración con Splunk, debes usar la aplicación web de Trébol.

Permisos requeridos: Tu usuario debe tener los siguientes permisos para gestionar integraciones:

integration-configurations:list
integration-configurations:create
integration-configurations:update
integration-configurations:delete

Si no tienes estos permisos, contacta al administrador de tu cuenta para que te los asigne.

Accede a la página de integraciones

Ingresa a app.gotrebol.com/settings/integrations con un usuario que tenga los permisos necesarios.

Crea una nueva integración

Haz clic en Nueva integración
Selecciona Splunk como tipo de integración
Completa los campos requeridos:
- HEC URL: La URL de tu HTTP Event Collector (ej: https://http-inputs-acme.splunkcloud.com:443/services/collector/event)
- HEC Token: El token que generaste en Splunk
Configura el filtro de eventos según tus necesidades
Guarda la configuración

Filtrado de eventos

Puedes configurar qué eventos deseas recibir:

Recibir todos los eventos

Selecciona la opción “Todos los eventos” para recibir todos los eventos de auditoría.

Recibir solo eventos específicos

Selecciona la opción “Eventos específicos” y elige los eventos que deseas recibir, por ejemplo:

users.sign_in
users.sign_in_failed
security.account_blocked
verifications.update
apikeys.create
apikeys.delete

Te recomendamos empezar recibiendo todos los eventos y luego filtrar según tus necesidades de monitoreo y alertas.

Gestionar la integración

Desde la página de integraciones en app.gotrebol.com/settings/integrations puedes:

Ver integraciones: Consulta todas las integraciones configuradas en tu cuenta
Editar integración: Modifica la URL, token o filtro de eventos de una integración existente
Eliminar integración: Elimina una integración que ya no necesites

Formato de eventos en Splunk

Los eventos llegan a Splunk con el siguiente formato:

{
  "event": {
    "source": "trebol",
    "event_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_name": "users.sign_in",
    "event_source": "auth0",
    "timestamp": "2026-01-12T10:30:00.000Z",
    "account_id": "account-123",
    "user_id": "user-456",
    "data": {
      "email": "[email protected]",
      "ip": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "description": "Login successful"
    }
  }
}

El campo source en el payload de Splunk (siempre "trebol") es un campo de metadatos específico de Splunk. Este es diferente al campo event_source dentro del evento, que indica el origen real del evento (b-v o auth0).

Búsquedas útiles en Splunk

Intentos de inicio de sesión fallidos

index=trebol source=trebol event_name="users.sign_in_failed"
| stats count by data.email, data.ip
| sort -count

Actividad por usuario

index=trebol source=trebol | stats count by event_name, data.email |

sort -count ```
</Accordion>

<Accordion title="Creación de API Keys">
```spl index=trebol source=trebol event_name="apikeys.create" | table
timestamp, data.email, data.ip ```
</Accordion>

<Accordion title="Eventos de verificaciones">
```spl index=trebol source=trebol event_name="verifications.*" | timechart
count by event_name ```
</Accordion>

<Accordion title="Eventos de seguridad">
  ```spl
  index=trebol source=trebol event_name IN ("security.account_blocked", "security.mfa_rate_limited", "security.suspicious_login_blocked", "security.password_leak_detected")
  | stats count by event_name, data.email, data.ip
  | sort -count

Reintentos y manejo de errores

El Log Stream implementa un sistema de reintentos automáticos para garantizar la entrega de eventos:

Reintentos: 3 intentos con backoff exponencial
Delay inicial: 1 segundo
Delay máximo: 10 segundos
Multiplicador: 2x
Timeout por request: 30 segundos

Si tu endpoint de Splunk no está disponible por un período prolongado, los eventos pueden perderse. Asegúrate de que tu instancia de Splunk tenga alta disponibilidad.

Mejores prácticas

Seguridad

Rota el token HEC periódicamente: Actualiza el token en Splunk y luego en la configuración de Trébol
Usa HTTPS: Siempre configura la URL del HEC con HTTPS
Limita el acceso al índice: Configura permisos apropiados en Splunk para el índice de eventos de Trébol

Monitoreo

Configura alertas para eventos críticos: Crea alertas en Splunk para users.sign_in_failed repetidos o apikeys.delete
Revisa periódicamente los logs: Monitorea patrones inusuales de actividad
Valida la integridad del flujo: Verifica que los eventos lleguen correctamente a Splunk después de configurar la integración

Filtrado de eventos

Empieza con todos los eventos: Usa mode: "*" inicialmente para entender el volumen y tipos de eventos
Filtra según necesidades: Una vez que entiendas los patrones, filtra solo los eventos relevantes para reducir costos de almacenamiento
Incluye siempre eventos de seguridad: Mantén al menos los eventos de autenticación (users.sign_in, users.sign_in_failed) para auditoría de seguridad

Intro al API de Trébol

Log Stream

​Log Stream

​Estructura de eventos

​Campos del evento

​Eventos disponibles

​Eventos de autenticación (Auth0)

​Autenticación

​Ciclo de vida de usuarios

​Contraseñas

​Autenticación multifactor (MFA)

​Seguridad y rate limiting

​Tokens

​Eventos de Trébol (B-V)

​API Keys

​Verificaciones

​Items de verificación

​Empresa

​Configurar integración con Splunk

​Requisitos previos

​Crear la integración en Trébol

​Filtrado de eventos

​Recibir todos los eventos

​Recibir solo eventos específicos

​Gestionar la integración

​Formato de eventos en Splunk

​Búsquedas útiles en Splunk

​Reintentos y manejo de errores

​Mejores prácticas

​Seguridad

​Monitoreo

​Filtrado de eventos

Log Stream

Estructura de eventos

Campos del evento

Eventos disponibles

Eventos de autenticación (Auth0)

Autenticación

Ciclo de vida de usuarios

Contraseñas

Autenticación multifactor (MFA)

Seguridad y rate limiting

Tokens

Eventos de Trébol (B-V)

API Keys

Verificaciones

Items de verificación

Empresa

Configurar integración con Splunk

Requisitos previos

Crear la integración en Trébol

Filtrado de eventos

Recibir todos los eventos

Recibir solo eventos específicos

Gestionar la integración

Formato de eventos en Splunk

Búsquedas útiles en Splunk

Reintentos y manejo de errores

Mejores prácticas

Seguridad

Monitoreo

Filtrado de eventos