Exportação da auditoria do Sherpa AI Server para um SIEM#

Um contêiner separado envia novos eventos do registro de auditoria para um sistema de gestão e análise de eventos de segurança (SIEM) por Syslog. Um administrador com acesso ao Docker Compose e ao PostgreSQL faz a configuração. O contêiner lê eventos da aplicação em orchestrator.audit. Ele não coleta os logs de consultas SQL do PostgreSQL.

Antes de começar#

Antes da configuração, obtenha com o suporte técnico um conjunto compatível de imagens e arquivos Compose que inclua aiserver-siem-exporter. Uma instalação do Sherpa AI Server sem esse contêiner não é suficiente para seguir as instruções.

Prepare o endereço, a porta e o protocolo do SIEM e, para TLS, um certificado confiável. Crie uma função separada do PostgreSQL somente para leitura:

CREATE ROLE sherpa_siem LOGIN PASSWORD '<новый пароль>';
GRANT CONNECT ON DATABASE postgres TO sherpa_siem;
GRANT USAGE ON SCHEMA orchestrator TO sherpa_siem;
GRANT SELECT ON TABLE orchestrator.audit TO sherpa_siem;

Substitua a senha e o nome do banco de dados pelos valores da sua instalação. Não use a função postgres nem a conta da aplicação.

O instalador padrão carrega as imagens principais. Carregue a imagem opcional do SIEM separadamente de um arquivo da mesma versão. Verifique a soma de verificação antes de carregar:

Substitua o marcador de VERSION pela versão do pacote recebido e execute os comandos:

VERSION='<версия из комплекта>'
docker load --input "aiserver-siem-exporter_${VERSION}.tar.gz"
docker tag "aiserver-siem-exporter:${VERSION}" aiserver-siem-exporter:latest

Adicione siem ao valor existente de COMPOSE_PROFILES em .env, por exemplo COMPOSE_PROFILES=gpu,siem. Assim, o atualizador padrão carregará a próxima versão da imagem.

Configuração e inicialização#

Os parâmetros do destinatário são definidos em .env. Depois de preparar os certificados, o contêiner separado do exportador é iniciado.

  1. No arquivo .env do diretório de instalação, informe um nome estável e exclusivo para a instalação, a senha da função e um destinatário:

    SIEM_INSTANCE_ID=<стабильное имя установки>
    SIEM_DB_USER=sherpa_siem
    SIEM_DB_PASSWORD=<пароль роли>
    SIEM_RECIPIENTS=[{"name":"primary","host":"siem.example.org","port":6514,"protocol":"tls"}]
    

    O banco interno usa SIEM_DB_HOST=aiserver-pg, SIEM_DB_PORT=5432, SIEM_DB_NAME=postgres e SIEM_DB_SCHEMA=orchestrator. Para um banco externo, defina estes parâmetros no mesmo arquivo .env:

    SIEM_DB_HOST=pg.example.org
    SIEM_DB_PORT=5432
    SIEM_DB_NAME=postgres
    SIEM_DB_SCHEMA=orchestrator
    

    SIEM_DB_HOST é o endereço do PostgreSQL acessível pelo contêiner do exportador. SIEM_DB_PORT é a porta do PostgreSQL. SIEM_DB_NAME identifica o banco que contém a tabela de auditoria. SIEM_DB_SCHEMA identifica seu esquema. Substitua pg.example.org pelo endereço do seu servidor. O nome do banco deve corresponder a GRANT CONNECT ON DATABASE postgres no SQL acima. Se o banco ou o esquema tiver outro nome, atualize os parâmetros e os comandos de permissões de forma consistente, incluindo o nome da tabela <esquema>.audit.

  2. Para TLS com uma CA privada, prepare um diretório siem-certs no diretório de instalação. Coloque nele o certificado confiável ca.crt e, se o SIEM exigir autenticação mútua, o certificado do cliente client.crt e a chave privada client.key. O usuário do contêiner com UID 10001 deve conseguir ler os arquivos. Não armazene a chave privada no repositório.

    Adicione a montagem ao arquivo local docker-compose.override.yml, preservando as configurações existentes:

    services:
      aiserver-siem-exporter:
        volumes:
          - ./siem-certs:/etc/siem:ro
    

    Exemplo de configuração do destinatário com uma CA privada e mTLS em .env:

    SIEM_RECIPIENTS=[{"name":"primary","host":"siem.example.org","port":6514,"protocol":"tls","ca_file":"/etc/siem/ca.crt","cert_file":"/etc/siem/client.crt","key_file":"/etc/siem/client.key"}]
    

    Substitua o endereço e a porta pelos parâmetros do seu SIEM. Se um certificado de cliente não for necessário, remova cert_file e key_file juntos. Para um banco externo, configure SIEM_DB_SSLMODE=verify-full e SIEM_DB_SSLROOTCERT com o caminho absoluto do certificado raiz dentro do contêiner. O certificado do banco também deve ser montado somente para leitura.

  3. Inicie o contêiner no diretório de instalação e consulte os logs:

    docker compose --profile siem up -d aiserver-siem-exporter
    docker compose logs --tail=100 aiserver-siem-exporter
    

Verificação e limitações#

Gere um evento de entrada de teste no Sherpa AI Server e verifique se o SIEM o recebeu. A mensagem deve conter app_name=sherpa-ai-server, event_id, o horário e o tipo de evento. Os campos originais message, diff e agent não são enviados. O contêiner não cria eventos ausentes do registro de auditoria da aplicação.

Por padrão, apenas novos registros são exportados. Para carregar registros existentes na primeira execução, configure SIEM_START_ID=0 antes de iniciar. Cada destinatário em SIEM_RECIPIENTS tem seu próprio cursor no volume aiserver-siem-state. Os nomes precisam ser exclusivos e estáveis. Quando um erro TCP/TLS é detectado, o cursor desse destinatário não avança. Após a recuperação, um evento pode ser repetido com o mesmo event_id: configure a deduplicação no SIEM. UDP não confirma a entrega e pode perder mensagens.

O exportador revisita os IDs anteriores e entrega registros que se tornam visíveis depois de um ID maior. A revisão lê até 10.000 IDs por ciclo. O tempo de detecção depende do tamanho do registro. Na primeira inicialização, latest marca os registros visíveis em um único snapshot do PostgreSQL sem enviá-los. Transações confirmadas depois são entregues mesmo com ID menor. Use SIEM_START_ID=0 para carregar registros já visíveis. O volume armazena os IDs processados e cresce com os registros e destinatários.

Se os eventos não chegarem, verifique os logs do contêiner, o endereço e a porta do destinatário, as permissões da função e os certificados. Não remova o volume aiserver-siem-state durante uma reinicialização normal: isso redefine os cursores. O envio bem-sucedido por TCP/TLS confirma a escrita na conexão, não o armazenamento no SIEM.

O campo protocol aceita os seguintes meios de transporte:

  • tls — entrega criptografada com verificação do certificado e do nome do servidor;
  • tcp — entrega por conexão sem criptografia;
  • udp — entrega sem confirmação.

Uma falha TLS não causa a mudança automática para uma conexão sem criptografia. É necessário selecionar um protocolo e uma porta compatíveis com o SIEM destinatário.

A retenção da tabela de auditoria deve cobrir o tempo máximo de indisponibilidade do destinatário. O exportador não consegue recuperar eventos excluídos da tabela antes do envio. Com UDP, o cursor continua avançando mesmo quando o destinatário está indisponível. Portanto, esse protocolo deve ser usado apenas quando a perda de mensagens for aceitável.

Somente uma instância do exportador deve usar o mesmo volume aiserver-siem-state. O administrador deve monitorar o espaço livre: o registro de IDs processados cresce com o volume da auditoria e o número de destinatários.

Para interromper a exportação, execute no diretório de instalação:

docker compose stop aiserver-siem-exporter

Depois, remova também siem de COMPOSE_PROFILES para desativar a inicialização automática, mantendo os outros perfis. O Sherpa AI Server continua funcionando. O volume de cursores e os registros de auditoria são preservados.