> ## Documentation Index
> Fetch the complete documentation index at: https://gotrebol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Log Stream
> Configura integraciones para recibir eventos de auditoría en tiempo real en plataformas como Splunk
# 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:
```json theme={"dark"}
{
"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": "usuario@ejemplo.com",
"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](#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:**
```json theme={"dark"}
{
"data": {
"email": "usuario@ejemplo.com",
"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:**
```json theme={"dark"}
{
"data": {
"email": "usuario@ejemplo.com",
"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
1. En Splunk, ve a **Settings → Data Inputs → HTTP Event Collector**
2. Haz clic en **New Token**
3. Configura el token:
* **Name**: `trebol-log-stream`
* **Source type**: `_json`
* **Index**: Selecciona o crea un índice para los eventos de Trébol
4. 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.
La URL del HEC tiene el siguiente formato:
```
https://: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.
Ingresa a [app.gotrebol.com/settings/integrations](https://app.gotrebol.com/settings/integrations) con un usuario que tenga los permisos necesarios.
1. Haz clic en **Nueva integración**
2. Selecciona **Splunk** como tipo de integración
3. 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
4. Configura el filtro de eventos según tus necesidades
5. 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](https://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:
```json theme={"dark"}
{
"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": "usuario@ejemplo.com",
"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
```spl theme={"dark"}
index=trebol source=trebol event_name="users.sign_in_failed"
| stats count by data.email, data.ip
| sort -count
```
````spl index=trebol source=trebol | stats count by event_name, data.email | theme={"dark"}
sort -count ```
```spl index=trebol source=trebol event_name="apikeys.create" | table
timestamp, data.email, data.ip ```
```spl index=trebol source=trebol event_name="verifications.*" | timechart
count by event_name ```
```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