Ligar PostgreSQL (pgaudit)

Guia detalhado por conector para observar acesso a bases de dados PostgreSQL através de pgAudit — configuração de formato de registo, ingestão por streaming.

O conector pgAudit faz tail do registo de auditoria estruturado do PostgreSQL e emite uma aresta de mapa de acesso por acesso a dados auditado. O modo leitura/escrita e retirado verbatim da classe do pgAudit (READ, WRITE, DDL) — nunca inferido do texto SQL. O conector e apenas leitura sobre o ficheiro de registo e nunca abre uma conexão a base de dados.

Para o modelo geral de fontes e estrutura de config, comece com Ligar uma fonte. Esta página cobre pre-requisitos do lado PostgreSQL, a superficie completa de config, mecanica de atribuição e consideracoes operacionais para ambientes de produção.

Pre-requisitos PostgreSQL

O conector le a saída do pgAudit, portanto o PostgreSQL deve ser configurado para a produzir. Instale a extensão (apt install postgresql-<version>-pgaudit em Debian/Ubuntu), carregue-a via shared_preload_libraries, reinicie, depois CREATE EXTENSION pgaudit em cada base de dados que queira observar.

As definições mínimas de postgresql.conf para saída útil:

shared_preload_libraries = 'pgaudit'
pgaudit.log = 'read, write'       # READ e WRITE cobrem acesso a dados
log_destination = 'jsonlog'        # recomendado para streaming; csvlog tambem funciona
logging_collector = on
log_directory = '/var/log/postgresql'
log_filename = 'postgresql.json'

Reinicie após shared_preload_libraries; recarregue (SELECT pg_reload_conf()) após o resto. Verifique executando uma query e confirmando que aparece uma entrada pgAudit no registo — o campo message da entrada contém a linha estruturada do pgAudit (classe, comando, nome do objeto). Se aparecem apenas mensagens padrão do PostgreSQL, a extensão não esta carregada ou não esta configurada.

Configuração

O conector e selecionado por kind: "pgaudit" no ficheiro JSON OLIVARES_SOURCES_CONFIG. Um exemplo 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 os valores de config são strings. As chaves pertencem ao conector pgAudit:

log_path (obrigatório) — caminho absoluto para o ficheiro de registo PostgreSQL. O conector le este ficheiro; não descobre ficheiros de registo por convencao.
format — csvlog ou jsonlog. Predefinido csvlog. Controla o parser que o conector usa; deve corresponder ao log_destination que o PostgreSQL esta realmente a escrever.
follow — quando "true", faz tail do ficheiro continuamente (modo streaming). Aplica-se apenas a jsonlog. Um ficheiro csvlog e lido como batch porque registos CSV podem abranger novas linhas, tornando um tail em streaming não fiável. Veja Batch vs streaming abaixo.
shared_accounts — lista separada por virgulas de papeis PostgreSQL ou valores application_name que são agrupados ou partilhados entre multiplos chamadores. O acesso atribuído a qualquer um destes e marcado approximate deliberadamente. Veja Atribuição e contas partilhadas.

Não invente chaves de config além destas quatro. A superficie de config do conector e intencionalmente estreita — le um ficheiro de registo, não gere PostgreSQL.

Atribuição e contas partilhadas

O mapa de acesso precisa de responder “qual agente fez isto.” As entradas de registo pgAudit transportam o papel (utilizador) PostgreSQL e, quando definido, o application_name da sessão. O conector usa ambos para construir a origem da aresta.

Identidade por agente ganha uma aresta firme. Quando cada agente define um application_name distinto na sua conexão (ou usa um papel dedicado), o conector atribui cada acesso inequivocamente e a aresta e firm.

Papeis partilhados colapsam para aproximado. Quando multiplos agentes partilham um pool de conexões, uma conta de serviço comum, ou um application_name genérico, o conector não pode separar chamadores. Cada acesso através dessa identidade e marcado approximate, e o produto di-lo abertamente em vez de fingir que consegue distinguir agentes que não consegue. E por isso que shared_accounts existe: declarar identidades agrupadas antecipadamente diz ao conector para as marcar approximate imediatamente.

A implicacao de governança e direta: uma aresta approximate não pode suportar um achado firme de menor privilégio. Se precisa de governança por agente sobre acesso a bases de dados, emita credenciais ou valores application_name por agente. Veja Fidelidade para o modelo completo de atribuição.

Nível de cobertura

pgAudit e cobertura clean. As classes READ, WRITE e DDL são autoritativas — o subsistema de auditoria do PostgreSQL classifica a instrucao, e o conector toma essa classificação verbatim. Não há inferência, não há parsing de SQL e não há heurística.

O mode de uma aresta e R (leitura), RW (leitura-escrita, para classes WRITE e DDL), ou como a classe dita. O conector nunca eleva ou rebaixa o que pgAudit reportou. Veja Fidelidade — cobertura para como clean se compara com fontes lossy e opaque.

Batch vs streaming

csvlog — batch. Registos CSV podem abranger novas linhas (uma query com novas linhas embebidas produz uma linha multi-linha), portanto um tail em streaming não pode dividir registos de forma fiável. O conector le o ficheiro como um batch completo; defina poll_seconds na entrada de fonte para re-executar num intervalo.
jsonlog com follow: "true" — streaming. Cada entrada JSON e uma única linha, portanto um tail e seguro. O conector mantém o ficheiro aberto e emite arestas a medida que o PostgreSQL as escreve.

Para arestas quase em tempo real, jsonlog com follow e a configuração recomendada. Para auditorias periodicas ou bases de dados de menor volume, batch csvlog e suficiente.

Como são as arestas

Cada entrada de registo pgAudit que o conector analisa produz uma aresta de mapa de acesso com estes campos:

Origem — o papel PostgreSQL, qualificado por application_name quando presente. Exemplo: reporting_agent ou app_pool/invoice-service.
Recurso — o objeto totalmente qualificado: database.schema.table. Exemplo: prod.public.orders.
Modo — R (de pgAudit classe READ) ou RW (de pgAudit classe WRITE ou DDL).
Atribuição — firm se a origem resolve para uma única identidade de agente, approximate se corresponde a uma entrada shared_accounts ou não pode ser desambiguada.
Fonte — identifica esta instancia de conector pelo nome.

A aresta não transporta texto SQL, dados de linhas nem parametros de query. Regista apenas o facto estrutural de que uma identidade acedeu a um objeto num dado modo.

Notas operacionais

Rotação de registos. Quando o PostgreSQL roda o seu ficheiro de registo (via log_rotation_age ou log_rotation_size), o conector deve ser apontado para o ficheiro atual. Se a sua rotação renomeia o ficheiro ativo, o tail follow continuara a ler o antigo descritor de ficheiro até se esgotar e depois para. Aponte log_path para um symlink estavel ou use uma convencao de nomeação que o conector possa seguir. O conector não gere a rotação por si.

Ambientes de alto volume. pgAudit pode produzir volume de registo substancial em bases de dados ocupadas, especialmente com pgaudit.log = 'all'. Defina o escopo de pgaudit.log para as classes que precisa (tipicamente read, write) e considere filtragem por base de dados ou por papel via pgaudit.log_relation para reduzir ruido sem perder cobertura.

Multiplas instancias PostgreSQL. Cada instancia precisa da sua própria entrada de fonte em OLIVARES_SOURCES_CONFIG com um name distinto e o seu próprio log_path. Não há descoberta multi-instancia — cada fonte observa exatamente um ficheiro de registo.

Permissões. O processo coletor precisa de acesso de leitura ao ficheiro de registo PostgreSQL. Não precisa de conexão a base de dados, papel PostgreSQL, nem qualquer acesso de rede ao servidor de base de dados. Permissão de leitura no sistema de ficheiros e o único requisito.

Relacionado

Ligar uma fonte — o modelo geral de fontes e estrutura de config.
O mapa de acesso — o que estas arestas constroem.
Fidelidade — níveis de cobertura e atribuição.
Honestidade e limites — o que é verificado versus em fase de design.