Audit logs y consultas

Módulo 7 · Administración y medición · Lección 5 de 6

Al terminar esta lección podrás explicar qué capturan los registros de auditoría, distinguirlos de OTel y de la Compliance API, y elegir el patrón de acceso adecuado para cada escenario de cliente.

Los registros de auditoría responden a otra pregunta.

Qué capturan

El registro de eventos administrativos. No el de conversaciones.

Cuando un cliente pregunta “¿puedes mostrarme quién inició sesión y cambió los ajustes de las claves de API la semana pasada?”, la respuesta son los registros de auditoría. Cuando pregunta “¿puedes mostrarme lo que un desarrollador le dijo a Claude?”, no lo son.

Los registros de auditoría registran la vida administrativa de la organización: quién se unió, quién cambió los ajustes, quién creó un proyecto. Están disponibles para todos los Owner y Primary Owner como exportación CSV, sin configuración adicional ni clave de API.

Categorías de eventos

Inicios de sesión, cambios de miembros y ajustes de administración

33 tipos de evento registrados que cubren inicios de sesión, eventos de proyectos y archivos, altas y bajas de miembros, y cambios en los ajustes de administración. No hay nada a nivel de conversación ni de llamadas a herramientas.

Retención

Ventana rodante de 180 días

Los eventos antiguos se eliminan automáticamente. Si un cliente necesita eventos con más de 180 días de antigüedad, debería haber estado exportando periódicamente o enrutando los eventos administrativos a su pipeline SIEM de OTel desde el momento en que se habilitó.

Quién puede acceder

Owner y Primary Owner

No requiere clave de API ni configuración adicional. Se descarga como CSV desde Organization settings › Data and Privacy. Cualquier Owner puede obtener la exportación sin involucrar a ingeniería.

Qué no contienen

Ni contenido de conversaciones ni llamadas a herramientas

Sin texto de conversaciones, sin detalle de llamadas a herramientas, sin comandos bash y sin texto de prompts ni de respuestas. Para el contenido de las conversaciones, usa la Compliance API. Para los eventos de ejecución de herramientas, usa OTel.

Regla de trabajo

Los registros de auditoría responden “qué cambió en la organización”. OTel responde “qué se ejecutó”. La Compliance API responde “qué se discutió”.

Patrones de acceso

Una fuente. Tres formas de llegar a ella.

El patrón de acceso adecuado depende del escenario: una solicitud puntual, una extracción programática con filtros de fecha o de usuario, o un feed SIEM en tiempo real. El siguiente diagrama resume cuándo usar cada uno, según los casos de uso de cada vía.

flowchart TD
    Q["Solicitud del cliente sobre registros administrativos"] --> P{"Es una solicitud puntual?"}
    P -->|"Sí"| CSV["Exportación CSV desde Organization settings"]
    P -->|"No"| R{"Consulta programática por usuario, tipo de evento o rango de fechas?"}
    R -->|"Sí"| API["Compliance API (clave de Primary Owner)"]
    R -->|"No, necesita un feed en tiempo real"| OTEL["OTel / SIEM"]

1. Exportación CSV (puntual)

La vía más rápida para solicitudes puntuales. Un Owner descarga un CSV completo de 180 días desde Organization settings. No requiere clave de API. No hay nada que configurar.

Cuándo usarla:

• Una revisión de seguridad que pide historial de inicios de sesión o registros de cambios administrativos
• Una pregunta puntual de gobernanza por parte de legal o de compliance
• Una comprobación ad hoc de quién cambió ajustes o aprovisionó usuarios

La exportación cubre la ventana completa de 180 días, sin filtro de fecha. Para consultas dirigidas por usuario, rango de fechas o tipo de evento, analiza el CSV localmente o usa la Compliance API.

2. Compliance API (programática)

La Compliance API devuelve eventos de auditoría junto con los datos de conversaciones en una única interfaz programática. Úsala cuando necesites consultas dirigidas: un usuario concreto, un tipo de evento concreto o un rango de fechas que vaya más allá de la ventana de 180 días del CSV.

Cuándo usarla:

• Legal necesita 18 meses de actividad de un usuario concreto para una auditoría regulatoria
• Compliance necesita consultar los fallos de inicio de sesión por rango de fechas
• Seguridad necesita confirmar si un ajuste administrativo concreto fue cambiado y por quién

Requiere que la Compliance API esté habilitada y una clave de acceso del Primary Owner. La documentación completa de los endpoints está en platform.claude.com/docs/en/manage-claude/compliance-api. Se cubre en la lección 7.3.

3. OTel / SIEM (tiempo real)

OTel transmite eventos de tipo administrativo (cambios de modo de permisos, conexiones a servidores MCP, eventos de autenticación) junto con los eventos de ejecución de herramientas, en el mismo flujo OTLP. Si el SIEM del cliente ya recibe datos de OTel, la alerta en tiempo real sobre estos eventos no requiere una exportación aparte.

Cuándo usarla:

• El equipo de seguridad necesita alertas en tiempo real cuando se cambia un modo de permisos
• El SIEM ya está conectado al pipeline de OTel de la lección 7.4
• El cliente quiere una visibilidad unificada de la ejecución de herramientas y de los eventos administrativos en un único dashboard

OTel solo captura eventos desde el momento en que se habilitó el pipeline. No rellena datos históricos. Para cualquier periodo anterior a la puesta en marcha del pipeline, usa la exportación CSV o la Compliance API.

Registros de auditoría frente a OTel

Mismo sistema. Datos distintos. Preguntas distintas.

Ambas superficies capturan señales sobre lo que ocurre en la organización. Lo que contienen es distinto, y conviene saber dónde se detiene cada una.

Aspecto	Audit logs	OTel
Qué cubre	Cambios administrativos	Ejecución
Acceso	CSV de 180 días, sin configuración	Opt-in, en tiempo real
Qué responde	Quién se unió, se fue o cambió ajustes. Historial de inicios de sesión. Creación y eliminación de proyectos. Cambios en la configuración administrativa. Disponible al instante para cualquier Owner.	Cada llamada a herramienta, comando bash, invocación MCP, cambio de modo de permisos y solicitud de API, en tiempo real. Sin límite de 180 días; la retención la define el SIEM.
Se detiene en	Llamadas a herramientas, comandos bash, contenido de conversaciones y eventos con más de 180 días de antigüedad.	Cambios administrativos a nivel de organización que no figuran en el esquema de eventos, eventos anteriores a la habilitación del pipeline y contenido de conversaciones.

Comprueba tu comprensión

Escenario · Decisiones sobre el patrón de acceso

Tres solicitudes del cliente. La superficie equivocada tiene los datos incorrectos o un modelo de entrega incorrecto. Seis puntos en total. Cada opción vale 2 puntos (mejor), 1 (parcial) o 0 (incorrecta). Elige una opción en cada decisión y compara tu criterio con la explicación.

Decisión 1 de 3 · Solicitud de actividad de un desarrollador

Un desarrollador pide un registro de todos los comandos bash ejecutados mediante Claude Code durante la última semana. ¿Qué superficie tiene esos datos?

• A. Exportar los registros de auditoría desde Organization settings
• B. Consultar el feed SIEM de OTel con las herramientas de ese usuario
• C. Extraer los eventos de actividad de la Compliance API

Ver respuesta

Mejor opción: B (2 puntos). Parcial: C (1 punto). Incorrecta: A (0 puntos).

A. Exportar los registros de auditoría desde Organization settings (incorrecta, 0 puntos). Los registros de auditoría cubren 180 días de eventos a nivel de organización y están disponibles sin configuración adicional.

Retroalimentación: Los registros de auditoría recogen eventos administrativos: inicios de sesión, cambios de membresía y actualizaciones de ajustes. No contienen datos de llamadas a herramientas ni comandos bash. OTel es la superficie para la visibilidad a nivel de ejecución.

B. Consultar el feed SIEM de OTel con las herramientas de ese usuario (mejor, 2 puntos). Con OTEL_LOG_TOOL_DETAILS=1 habilitado, cada comando bash se captura como evento estructurado en el SIEM. Filtra por usuario y rango de fechas.

Retroalimentación: Correcto. OTel con OTEL_LOG_TOOL_DETAILS=1 captura cada comando bash como evento estructurado. Los registros de auditoría contienen eventos a nivel de organización, como inicios de sesión y cambios de ajustes, no llamadas individuales a herramientas. El SIEM es el lugar adecuado para los datos de ejecución a nivel de comando.

C. Extraer los eventos de actividad de la Compliance API (parcial, 1 punto). La Compliance API captura eventos del feed de actividad y permite filtrar por usuario. Incluye la actividad de sesión y se puede consultar de forma programática.

Retroalimentación: La Compliance API captura eventos del feed de actividad, pero no el contenido del comando bash en sí. OTel con OTEL_LOG_TOOL_DETAILS=1 es la superficie que captura la ejecución de herramientas a nivel de comando en tiempo real.

Decisión 2 de 3 · Solicitud de auditoría regulatoria de 18 meses

Legal necesita 18 meses de conversaciones de un empleado concreto para una auditoría regulatoria. ¿Qué superficie puede proporcionarlas?

• A. Exportar los registros de auditoría que cubran el periodo de 18 meses
• B. Consultar la Compliance API con un ID de usuario y un filtro de rango de fechas
• C. Consultar el feed SIEM de OTel de ese usuario durante los 18 meses

Ver respuesta

Mejor opción: B (2 puntos). Parcial: C (1 punto). Incorrecta: A (0 puntos).

A. Exportar los registros de auditoría que cubran el periodo de 18 meses (incorrecta, 0 puntos). Los registros de auditoría capturan eventos a nivel de organización y están disponibles como exportación CSV de hasta 180 días de historial.

Retroalimentación: Los registros de auditoría tienen una ventana de 180 días y no contienen contenido de conversaciones. No pueden cubrir 18 meses ni proporcionar lo que legal necesita. La Compliance API es el único mecanismo con retención suficiente y acceso al contenido.

B. Consultar la Compliance API con un ID de usuario y un filtro de rango de fechas (mejor, 2 puntos). La Compliance API da acceso al contenido de las conversaciones, con retención de hasta seis años. Admite filtrar por usuario y rango de fechas para extracciones dirigidas.

Retroalimentación: Correcto. La Compliance API admite retención de hasta seis años y permite consultas dirigidas por usuario y rango de fechas. Es la única superficie que incluye el contenido de las conversaciones para la recuperación programática. Los registros de auditoría llegan como máximo a 180 días y no contienen datos de conversaciones.

C. Consultar el feed SIEM de OTel de ese usuario durante los 18 meses (parcial, 1 punto). El SIEM lleva 18 meses funcionando y conserva todos los eventos de OTel. Filtra por identidad de usuario para encontrar toda la actividad relevante.

Retroalimentación: OTel captura eventos de ejecución, no contenido de conversaciones. El SIEM tendrá 18 meses de llamadas a herramientas y eventos de sesión para este usuario, pero no lo que se dijo. Legal necesita las conversaciones, que solo proporciona la Compliance API.

Decisión 3 de 3 · Alerta de seguridad en tiempo real

El equipo de seguridad quiere alertas en Slack en menos de 60 segundos cada vez que un desarrollador cambie Claude Code del modo de permisos por defecto al modo bypass. ¿Qué arquitectura lo admite?

• A. Configurar una revisión diaria de los registros de auditoría y marcar los cambios de permisos
• B. Escribir un webhook que consulte la Compliance API cada minuto
• C. Crear una regla SIEM sobre el evento de OTel claude_code.permission_mode_changed

Ver respuesta

Mejor opción: C (2 puntos). Parcial: B (1 punto). Incorrecta: A (0 puntos).

A. Configurar una revisión diaria de los registros de auditoría y marcar los cambios de permisos (incorrecta, 0 puntos). Una exportación y revisión diarias automatizadas detectarían los cambios de permisos en 24 horas. Es manejable con un script sencillo.

Retroalimentación: Una revisión diaria no puede cumplir un requisito de alerta de 60 segundos. Además, los registros de auditoría no incluyen cambios de modo de permisos a nivel de comando para Claude Code. El flujo de eventos de OTel es la arquitectura adecuada para la alerta de seguridad en tiempo real.

B. Escribir un webhook que consulte la Compliance API cada minuto (parcial, 1 punto). La Compliance API captura eventos de actividad, incluidos los cambios de permisos. Un intervalo de sondeo de un minuto detectaría los cambios en 60 segundos.

Retroalimentación: Sondear la Compliance API cada minuto es técnicamente posible, pero introduce carga de sondeo y consideraciones de límites de la API. OTel es un modelo push, no pull. La alerta en tiempo real es para lo que se diseñó el stream del SIEM.

C. Crear una regla SIEM sobre el evento de OTel claude_code.permission_mode_changed (mejor, 2 puntos). OTel transmite permission_mode_changed como evento de log en tiempo real. Una regla del SIEM dispara una alerta en Slack en segundos desde que llega el evento.

Retroalimentación: Correcto. OTel transmite claude_code.permission_mode_changed como evento de log en tiempo real. Una regla del SIEM dispara la alerta en Slack en segundos desde la llegada del evento. Es la arquitectura diseñada específicamente para la alerta en tiempo real sobre eventos de ejecución.

Ver debrief y texto de cierre

La fuente asigna un texto de cierre según la puntuación final, sobre un máximo de 6 puntos.

Navegador de patrones de acceso (5 o 6 puntos). Enrutaste las tres solicitudes a la superficie correcta. La distinción que importa en cada engagement: los registros de auditoría sirven para la gobernanza de la organización, OTel para los eventos de ejecución y la Compliance API para el contenido de las conversaciones y las consultas de retención larga.

Buenos instintos, una discrepancia (3 o 4 puntos). Dos de tres es sólido. La decisión que falló probablemente confundió OTel con la Compliance API, o los registros de auditoría con OTel. Repasa los temas y vuelve después.

Conviene volver a repasarlo (0 a 2 puntos). La regla de trabajo que conviene repasar: los registros de auditoría responden qué cambió en la organización; OTel responde qué se ejecutó; la Compliance API responde qué se discutió. El tema 1 y las tarjetas del tema 3 lo cubren por completo.

Ideas clave

Tres superficies. Tres preguntas distintas.

• Los registros de auditoría contienen eventos administrativos, y su ventana de 180 días limita lo que pueden responder.
• La exportación CSV sirve para consultas puntuales, la Compliance API para consultas programáticas con filtros y OTel/SIEM para la ejecución y las alertas en tiempo real.
• Los registros de auditoría tratan las preguntas de gobernanza, OTel las de ejecución y la Compliance API las de contenido. Cada una tiene su carril.
• Los registros de auditoría no contienen conversaciones ni llamadas a herramientas; para eso están la Compliance API y OTel.

La lección 6 cubre las tres capas de visibilidad del gasto, cómo la métrica cost.usage impulsa la atribución entre equipos y cómo configurar límites de gasto mediante la Admin API.

Siguiente: Monitoreo de costos, atribución y controles de gasto