Saltar al contenido

Guías

Conectar una fuente

Conecta una fuente de observación real a Olivares AI, comprende el modelo de conector read-first y configura pgaudit y s3cloudtrail con los source kinds correctos

Una fuente observa un sistema externo y emite observaciones normalizadas; nunca se sitúa en el data path, hace de proxy del tráfico ni lee payloads. Esta página cubre el modelo de conector y cómo conectar una fuente real mediante OLIVARES_SOURCES_CONFIG. Si solo quieres conectar un agente de programación, empieza por Conectar Claude Code; eso es una fuente en el cooperative path, y este es el modelo que hay por debajo.

Qué hace una fuente

Una fuente observa un sistema y reporta lo que vio como observaciones tipadas. El access map de lectura/escritura se construye a partir de lo que la fuente reporta, no de interceptar lo que fluye. El engine es el dueño del scheduling: una fuente de streaming (un tail de log) se bloquea hasta que se cancela; una fuente batch hace su trabajo y retorna, y el engine decide cuándo volver a ejecutarla.

Una observación lleva únicamente identificadores y una clasificación de lectura/escritura; nunca cuerpos de SQL, payloads de petición, secretos ni PII. Eso es una propiedad del vocabulario de wire que habla el conector, no un ajuste que puedas activar. Consulta Permitido vs observado para ver cómo aterrizan estas observaciones en el mapa.

Cada edge registra qué fuente lo produjo y un nivel de confianza, y el producto muestra ambos. La atribución es firm cuando el acceso está ligado a una identidad por agente y approximate cuando es inferida o con pérdidas (una cuenta de servicio compartida, una conexión en pool). El modo de acceso es uno de unknown, read, write o readwrite: unknown es explícito y nunca se adivina. Consulta Fidelidad.

Dónde se ejecuta

Los collectors que ejecutan estas fuentes siempre se ejecutan en tu infraestructura. El control plane que las ingiere puede ser un único binario self-hosted, un despliegue distribuido o air-gapped: los datos del estate observado nunca salen de tu perímetro. Consulta Self-host y la visión general de la arquitectura.

El fichero de configuración

Las fuentes reales (no de demo) se conectan desde un único fichero de configuración del operador, nombrado por la variable de entorno OLIVARES_SOURCES_CONFIG, que se lee antes de que arranque el engine. Es un documento JSON que declara una lista de sources. Cada entrada selecciona un conector por kind, nombra el tenant al que pertenecen sus observaciones, da a la fuente un name y lleva el config propio del conector. Un poll_seconds opcional vuelve a ejecutar una fuente batch a intervalos; una fuente de streaming lo ignora.

Los source kinds son nombres registrados en el engine. Los dos observadores de ficheros de la clean tier son pgaudit (PostgreSQL) y s3cloudtrail (AWS S3). Usa esas cadenas exactas: docs anteriores que escribían pg_audit o cloudtrail estaban equivocados y esas cadenas no resuelven.

Una fuente pgaudit real

La fuente pgAudit hace tail del log de auditoría estructurado de PostgreSQL y emite un edge por cada acceso a datos auditado. El modo de lectura/escritura se toma literalmente de la clase de pgAudit (READ, WRITE, DDL); nunca se infiere del texto SQL. Es de solo lectura sobre el fichero de log y nunca conecta con la base de datos.

{
  "sources": [
    {
      "name": "prod-postgres",
      "kind": "pgaudit",
      "tenant": "acme",
      "config": {
        "log_path": "/var/log/postgresql/postgresql.json",
        "format": "jsonlog",
        "follow": "true",
        "shared_accounts": "app_pool,reporting"
      }
    }
  ]
}

Los valores de config son cadenas. Las claves anteriores pertenecen al conector pgAudit:

  • log_path (obligatorio): ruta al fichero de log de PostgreSQL a leer.
  • format: csvlog o jsonlog; por defecto es csvlog.
  • follow: hace tail de forma continua. Esto aplica solo a jsonlog; un fichero csvlog se lee como batch porque sus registros pueden abarcar varios saltos de línea.
  • shared_accounts: roles o application_names separados por comas que están en pool o compartidos. El acceso atribuido a uno de estos se marca como approximate, deliberadamente, porque el trail no puede separar a los llamantes reales detrás de una identidad compartida.

Un application_name distintivo es el puente por agente que gana un edge firm. Si muchos agentes comparten un rol o un pool de conexiones, cada acceso colapsa sobre esa identidad y la atribución pasa a ser approximate: el producto lo dice en lugar de fingir que puede distinguir entre los agentes.

Una fuente s3cloudtrail real

La fuente CloudTrail lee ficheros de log de AWS CloudTrail y emite un edge por cada evento de S3, tomando lectura/escritura literalmente del campo readOnly de CloudTrail. El origen es el principal IAM; un rol asumido compartido entre varios llamantes se marca como approximate.

{
  "sources": [
    {
      "name": "prod-s3",
      "kind": "s3cloudtrail",
      "tenant": "acme",
      "config": {
        "path": "/var/log/cloudtrail/",
        "shared_accounts": "shared-pipeline-role"
      }
    }
  ]
}

La clave path (obligatoria) es un fichero de log de CloudTrail o un directorio de ficheros *.json / *.json.gz. shared_accounts se comporta igual que para pgAudit.

Cuando no hay nada conectado, el engine avisa

El engine falla de forma segura, no ruidosa:

  • Si OLIVARES_SOURCES_CONFIG no está definida, el engine arranca sin fuentes.
  • Si el fichero falta, no se puede leer o no es JSON válido, el engine avisa y continúa sin fuentes; no se cae en el arranque.
  • Si la lista de fuentes está vacía, avisa de que ningún conector ingerirá y de que el estate está funcionando sin tráfico en vivo.

En todos los casos el log de arranque te dice claramente que no hay nada real conectado. Un access map vacío nunca debería parecerse a uno limpio.

No todos los conectores in-tree están conectados al serve estándar

Olivares AI incluye más conectores in-tree de los que un binario serve estándar registra como source kinds seleccionables. Los observadores de ficheros pgaudit, s3cloudtrail, el backstop de kernel ebpf, el lector de runtime del host y la introspección mcp están conectados al serve estándar, junto con un conjunto de observadores de data-platform, secrets, red e identidad. Otros conectores existen en el árbol pero todavía no están conectados al registro de fuentes del serve estándar: eso es un follow-up registrado, no una afirmación de que todo sea seleccionable hoy. Si un kind que esperas no resuelve, trátalo como aún no conectado en lugar de mal configurado, y confírmalo contra el descriptor propio del conector antes de depender de él.

Esta página describe solo claves verificadas contra los conectores anteriores. Las claves de config exactas de cualquier otro conector pertenecen a ese conector; lee su descriptor en lugar de copiar un esquema no verificado.

Relacionado