pgAudit
Auditoria de Logs Open Source PostgreSQL

Introdução

A Extensão de Auditoria PostgreSQL (pgAudit) fornece registro detalhado de auditoria de sessão e/ou objeto por meio do recurso padrão de registro do PostgreSQL.

O objetivo do pgAudit é fornecer aos usuários do PostgreSQL a capacidade de produzir logs de auditoria frequentemente exigidos para cumprir certificações governamentais, financeiras ou ISO.

Uma auditoria é uma inspeção oficial das contas de um indivíduo ou organização, geralmente realizada por um órgão independente. As informações coletadas pelo pgAudit são propriamente chamadas de trilha de auditoria ou log de auditoria. O termo log de auditoria é usado nesta documentação.

Por que pgAudit?

O registro básico de instruções pode ser fornecido pelo recurso padrão de registro com log_statement = all. Isso é aceitável para monitoramento e outros usos, mas não fornece o nível de detalhe geralmente exigido para uma auditoria. Não basta ter uma lista de todas as operações realizadas contra o banco de dados. Também deve ser possível encontrar instruções específicas que sejam de interesse de um auditor. O recurso padrão de registro mostra o que o usuário solicitou, enquanto o pgAudit foca nos detalhes do que aconteceu enquanto o banco de dados estava atendendo à solicitação.

Por exemplo, um auditor pode querer verificar se uma tabela específica foi criada dentro de uma janela de manutenção documentada. Isso pode parecer uma tarefa simples para o grep, mas e se você for apresentado a algo como este exemplo (intencionalmente ofuscado):

DO $$
BEGIN
    EXECUTE 'CREATE TABLE import' || 'ant_table (id INT)';
END $$;

O registro padrão fornecerá isto:

LOG:  statement: DO $$
BEGIN
    EXECUTE 'CREATE TABLE import' || 'ant_table (id INT)';
END $$;

Parece que encontrar a tabela de interesse pode exigir algum conhecimento do código em casos onde as tabelas são criadas dinamicamente. Isso não é ideal, pois seria preferível pesquisar apenas pelo nome da tabela. É aqui que o pgAudit entra. Para a mesma entrada, ele produzirá esta saída no log:

AUDIT: SESSION,33,1,FUNCTION,DO,,,"DO $$
BEGIN
    EXECUTE 'CREATE TABLE import' || 'ant_table (id INT)';
END $$;"
AUDIT: SESSION,33,2,DDL,CREATE TABLE,TABLE,public.important_table,CREATE TABLE important_table (id INT)

Não apenas o bloco DO é registrado, mas a subinstrução 2 contém o texto completo do CREATE TABLE com o tipo de instrução, tipo de objeto e nome totalmente qualificado para facilitar as buscas.

Ao registrar instruções SELECT e DML, o pgAudit pode ser configurado para registrar uma entrada separada para cada relação referenciada em uma instrução. Nenhuma análise é necessária para encontrar todas as instruções que tocam uma tabela específica. Na verdade, o objetivo é que o texto da instrução seja fornecido principalmente para perícia forense aprofundada e não deve ser necessário para uma auditoria.

Considerações de Uso

Dependendo das configurações, é possível que o pgAudit gere um volume enorme de registros. Tenha cuidado ao determinar exatamente o que precisa ser auditado no seu ambiente para evitar registrar demais.

Por exemplo, ao trabalhar em um ambiente OLAP, provavelmente não seria sensato auditar inserções em uma grande tabela de fatos. O tamanho do arquivo de log será provavelmente muitas vezes o tamanho real dos dados das inserções, pois o arquivo de log é expresso em texto. Como os logs geralmente são armazenados com o sistema operacional, isso pode levar à exaustão do espaço em disco muito rapidamente. Em casos onde não é possível limitar o registro de auditoria a certas tabelas, certifique-se de avaliar o impacto no desempenho durante os testes e alocar bastante espaço no volume de log. Isso também pode ser verdade para ambientes OLTP. Mesmo que o volume de inserções não seja tão alto, o impacto no desempenho do registro de auditoria ainda pode afetar visivelmente a latência.

Para limitar o número de relações auditadas para instruções SELECT e DML, considere usar o registro de auditoria de objeto (veja Auditoria de Objeto). O registro de auditoria de objeto permite a seleção das relações a serem registradas, permitindo a redução do volume geral de logs. No entanto, quando novas relações são adicionadas, elas devem ser explicitamente adicionadas ao registro de auditoria de objeto. Uma solução programática onde tabelas especificadas são excluídas do registro e todas as outras são incluídas pode ser uma boa opção neste caso.

Compatibilidade de Versão do PostgreSQL

O pgAudit suporta PostgreSQL 14 ou superior.

Para suportar novas funcionalidades introduzidas em cada versão do PostgreSQL, o pgAudit mantém um branch separado para cada versão principal do PostgreSQL (atualmente PostgreSQL 14 - 19) que será mantido de maneira similar ao projeto PostgreSQL.

Exceto por correções de bugs, nenhum desenvolvimento adicional é permitido para branches estáveis. Novos desenvolvimentos, se houver, serão estritamente para a próxima versão principal não lançada do PostgreSQL.

As versões do pgAudit se relacionam com as versões principais do PostgreSQL da seguinte forma:

• pgAudit v19.X é destinado a suportar PostgreSQL 19.

• pgAudit v18.X é destinado a suportar PostgreSQL 18.

• pgAudit v17.X é destinado a suportar PostgreSQL 17.

• pgAudit v16.X é destinado a suportar PostgreSQL 16.

• pgAudit v1.7.X é destinado a suportar PostgreSQL 15.

• pgAudit v1.6.X é destinado a suportar PostgreSQL 14.

Compilar e Instalar

O pgAudit pode ser compilado contra uma cópia instalada do PostgreSQL com pacotes de desenvolvimento usando PGXS. As instruções a seguir devem funcionar na maioria dos sistemas operacionais do tipo Unix.

Clone a extensão pgAudit:

git clone https://github.com/pgaudit/pgaudit.git

Altere para o diretório pgAudit:

cd pgaudit

Faça checkout do branch REL_19_STABLE (note que o branch estável pode não existir para versões não lançadas do PostgreSQL):

git checkout REL_19_STABLE

Construa e instale o pgAudit:

make install USE_PGXS=1 PG_CONFIG=/usr/pgsql-19/bin/pg_config

Instruções para testes e desenvolvimento podem ser encontradas em test.

Configurações

As configurações podem ser modificadas apenas por um superusuário. Permitir que usuários normais alterem suas configurações anularia o propósito de um log de auditoria.

As configurações podem ser especificadas globalmente (em postgresql.conf ou usando ALTER SYSTEM ... SET), no nível do banco de dados (usando ALTER DATABASE ... SET) ou no nível da função (usando ALTER ROLE ... SET). Note que as configurações não são herdadas através da herança normal de funções e SET ROLE não alterará as configurações de pgAudit de um usuário. Esta é uma limitação do sistema de funções e não inerente ao pgAudit.

A extensão pgAudit deve ser carregada em shared_preload_libraries. Caso contrário, um erro será levantado no momento do carregamento e nenhum registro de auditoria ocorrerá.

Além disso, CREATE EXTENSION pgaudit deve ser chamado antes que pgaudit.log seja definido para garantir a funcionalidade adequada do pgaudit. A extensão instala gatilhos de evento que adicionam auditoria adicional para DDL. O pgAudit funcionará sem a extensão instalada, mas instruções DDL não terão informações sobre o tipo e nome do objeto.

Se a extensão pgaudit for removida e precisar ser recriada, então pgaudit.log deve ser desdefinido primeiro, caso contrário um erro será levantado.

pgaudit.log

Especifica quais classes de instruções serão registradas pelo registro de auditoria de sessão. Os valores possíveis são:

• READ: SELECT e COPY quando a origem é uma relação ou uma consulta.

• WRITE: INSERT, UPDATE, DELETE, TRUNCATE e COPY quando o destino é uma relação.