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.
No arquivo
.envdo 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=postgreseSIEM_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=orchestratorSIEM_DB_HOSTé o endereço do PostgreSQL acessível pelo contêiner do exportador.SIEM_DB_PORTé a porta do PostgreSQL.SIEM_DB_NAMEidentifica o banco que contém a tabela de auditoria.SIEM_DB_SCHEMAidentifica seu esquema. Substituapg.example.orgpelo endereço do seu servidor. O nome do banco deve corresponder aGRANT CONNECT ON DATABASE postgresno 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.Para TLS com uma CA privada, prepare um diretório
siem-certsno diretório de instalação. Coloque nele o certificado confiávelca.crte, se o SIEM exigir autenticação mútua, o certificado do clienteclient.crte a chave privadaclient.key. O usuário do contêiner com UID10001deve 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:roExemplo 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_fileekey_filejuntos. Para um banco externo, configureSIEM_DB_SSLMODE=verify-fulleSIEM_DB_SSLROOTCERTcom o caminho absoluto do certificado raiz dentro do contêiner. O certificado do banco também deve ser montado somente para leitura.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.