Conectar PostgreSQL (pgaudit)

El conector pgAudit lee el log de auditoría estructurado de PostgreSQL y emite un edge en el access map por cada acceso a datos auditado. El modo lectura/escritura se toma literalmente de la clase de pgAudit (READ, WRITE, DDL) — nunca se infiere del texto SQL. El conector es de solo lectura sobre el fichero de log y nunca abre una conexión a la base de datos.

Para el modelo general de fuentes y la estructura de configuración, empieza por Conectar una fuente. Esta página cubre los prerrequisitos del lado de PostgreSQL, la superficie de configuración completa, la mecánica de atribución y las consideraciones operativas para entornos en producción.

Prerrequisitos de PostgreSQL

El conector lee la salida de pgAudit, por lo que PostgreSQL debe estar configurado para generarla. Instala la extensión (apt install postgresql-<version>-pgaudit en Debian/Ubuntu), cargala con shared_preload_libraries, reinicia, y ejecuta CREATE EXTENSION pgaudit en cada base de datos que quieras observar.

La configuración mínima en postgresql.conf para obtener una salida útil:

shared_preload_libraries = 'pgaudit'
pgaudit.log = 'read, write'       # READ y WRITE cubren el acceso a datos
log_destination = 'jsonlog'        # recomendado para streaming; csvlog también funciona
logging_collector = on
log_directory = '/var/log/postgresql'
log_filename = 'postgresql.json'

Reinicia tras modificar shared_preload_libraries; recarga (SELECT pg_reload_conf()) tras el resto. Verifica ejecutando una consulta y confirmando que aparece una entrada de pgAudit en el log — el campo message de la entrada contiene la línea estructurada de pgAudit (class, command, object name). Si solo aparecen mensajes estándar de PostgreSQL, la extensión no esta cargada o no esta configurada.

Configuración

El conector se selecciona con kind: "pgaudit" en el fichero JSON OLIVARES_SOURCES_CONFIG. Un ejemplo completo:

{
  "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"
      }
    }
  ]
}

Todos los valores de config son strings. Las claves pertenecen al conector pgAudit:

• log_path (obligatorio) — ruta absoluta al fichero de log de PostgreSQL. El conector lee este fichero; no descubre ficheros de log por convención.
• format — csvlog o jsonlog. Por defecto csvlog. Controla el parser que usa el conector; debe coincidir con el log_destination que PostgreSQL esta escribiendo realmente.
• follow — cuando es "true", sigue el fichero de forma continua (modo streaming). Esto solo aplica a jsonlog. Un fichero csvlog se lee como batch porque los registros CSV pueden abarcar varias líneas, lo que hace que un tail en streaming no pueda separar registros de forma fiable. Consulta Batch vs streaming más abajo.
• shared_accounts — lista separada por comas de roles de PostgreSQL o valores de application_name que son compartidos o agrupados entre varios llamantes. Los accesos atribuidos a cualquiera de ellos se marcan como approximate deliberadamente. Consulta Atribución y cuentas compartidas.

No inventes claves de configuración más alla de estas cuatro. La superficie de configuración del conector es intencionalmente reducida — lee un fichero de log, no gestiona PostgreSQL.

Atribución y cuentas compartidas

El access map necesita responder “que agente hizo esto.” Las entradas del log de pgAudit incluyen el rol de PostgreSQL (usuario) y, cuando esta definido, el application_name de la sesión. El conector usa ambos para construir el origen del edge.

Una identidad por agente obtiene un edge firm. Cuando cada agente establece un application_name distinto en su conexión (o usa un rol dedicado), el conector atribuye cada acceso de forma inequívoca y el edge es firm.

Los roles compartidos colapsan a approximate. Cuando varios agentes comparten un pool de conexiones, una cuenta de servicio común o un application_name genérico, el conector no puede separar a los llamantes. Cada acceso a través de esa identidad se marca como approximate, y el producto lo indica abiertamente en lugar de aparentar que puede distinguir agentes que no puede. Por eso existe shared_accounts: declarar las identidades agrupadas de antemano indica al conector que las marque como approximate de inmediato.

La implicación para la gobernanza es directa: un edge approximate no puede respaldar un hallazgo firm de mínimo privilegio. Si necesitas gobernanza por agente sobre el acceso a la base de datos, emite credenciales o valores de application_name por agente. Consulta Fidelity para el modelo completo de atribución.

Coverage tier

pgAudit proporciona cobertura clean. Las clases READ, WRITE y DDL son autoritativas — el subsistema de auditoría de PostgreSQL clasifica la sentencia, y el conector toma esa clasificación literalmente. No hay inferencia, no hay parsing de SQL y no hay heurística.

El mode de un edge es R (read), RW (readwrite, para las clases WRITE y DDL), o se deja según dicte la clase. El conector nunca eleva ni degrada lo que pgAudit informó. Consulta Fidelity — coverage para ver como clean se compara con fuentes lossy y opaque.

Batch vs streaming

• csvlog — batch. Los registros CSV pueden abarcar varias líneas (una consulta con saltos de línea incrustados produce una fila multilinia), por lo que un tail en streaming no puede separar registros de forma fiable. El conector lee el fichero como un batch completo; establece poll_seconds en la entrada de la fuente para re-ejecutar a intervalos.
• jsonlog con follow: "true" — streaming. Cada entrada JSON es una única línea, por lo que un tail es seguro. El conector mantiene el fichero abierto y emite edges a medida que PostgreSQL los escribe.

Para edges en tiempo casi real, jsonlog con follow es la configuración recomendada. Para auditorías periódicas o bases de datos con menor volumen, el batch con csvlog es suficiente.

Aspecto de los edges

Cada entrada del log de pgAudit que el conector parsea produce un edge en el access map con estos campos:

• Origin — el rol de PostgreSQL, cualificado por application_name cuando esta presente. Ejemplo: reporting_agent o app_pool/invoice-service.
• Resource — el objeto completamente cualificado: database.schema.table. Ejemplo: prod.public.orders.
• Mode — R (de la clase READ de pgAudit) o RW (de la clase WRITE o DDL de pgAudit).
• Attribution — firm si el origen se resuelve a una única identidad de agente, approximate si coincide con una entrada de shared_accounts o no se puede desambiguar.
• Source — identifica esta instancia del conector por nombre.

El edge no lleva texto SQL, ni datos de filas, ni parámetros de consulta. Registra únicamente el hecho estructural de que una identidad accedió a un objeto en un modo determinado.

Notas operativas

Rotacion de logs. Cuando PostgreSQL rota su fichero de log (mediante log_rotation_age o log_rotation_size), el conector debe apuntar al fichero actual. Si tu rotacion renombra el fichero activo, el tail de follow continuara leyendo el antiguo descriptor de fichero hasta que se agote y luego se detendra. Apunta log_path a un symlink estable o usa una convención de nombres que el conector pueda seguir. El conector no gestiona la rotacion por si mismo.

Entornos de alto volumen. pgAudit puede generar un volumen de log considerable en bases de datos con mucha actividad, especialmente con pgaudit.log = 'all'. Limita pgaudit.log a las clases que necesites (normalmente read, write) y considera el filtrado por base de datos o por rol mediante pgaudit.log_relation para reducir ruido sin perder cobertura.

Multiples instancias de PostgreSQL. Cada instancia necesita su propia entrada de fuente en OLIVARES_SOURCES_CONFIG con un name distinto y su propio log_path. No hay descubrimiento multi-instancia — cada fuente vigila exactamente un fichero de log.

Permisos. El proceso del collector necesita acceso de lectura al fichero de log de PostgreSQL. No necesita conexión a la base de datos, ni un rol de PostgreSQL, ni acceso de red al servidor de base de datos. El permiso de lectura en el sistema de ficheros es el único requisito.

Relacionado

• Conectar una fuente — el modelo general de fuentes y la estructura de configuración.
• El access map — lo que estos edges construyen.
• Fidelity — tiers de cobertura y atribución.
• Honestidad y limites — que esta verificado frente a lo que esta en fase de diseno.