Exporting Sherpa AI Server audit events to a SIEM#

A separate container sends new events from the audit log to a security information and event management (SIEM) system using Syslog. An installation administrator with Docker Compose and PostgreSQL access configures it. The container reads application events from orchestrator.audit. It does not collect PostgreSQL SQL query logs.

Before you begin#

Before configuration, obtain a compatible set of images and Compose files containing aiserver-siem-exporter from technical support. A Sherpa AI Server installation without this container is insufficient for this procedure.

Prepare the SIEM address, port, protocol and, for TLS, a trusted certificate. Create a separate read-only PostgreSQL role:

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;

Replace the password and database name with your installation values. Do not use the postgres role or the application account.

The standard installer loads core images. Load the optional SIEM image separately from an archive of the same version. Verify its checksum before loading:

Replace the placeholder in VERSION with the version of the supplied package, then run the commands:

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

Add siem to the existing COMPOSE_PROFILES value in .env, for example COMPOSE_PROFILES=gpu,siem. The standard updater will then load the next image version.

Configure and start#

Configure recipient parameters in .env. After preparing the certificates, start the separate exporter container.

  1. In the installation directory's .env file, set a unique stable installation name, the role password and a recipient:

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

    The internal database uses SIEM_DB_HOST=aiserver-pg, SIEM_DB_PORT=5432, SIEM_DB_NAME=postgres, and SIEM_DB_SCHEMA=orchestrator. For an external database, set these parameters in the same .env file:

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

    SIEM_DB_HOST is the PostgreSQL address reachable from the exporter container. SIEM_DB_PORT is the PostgreSQL port. SIEM_DB_NAME names the database containing the audit table. SIEM_DB_SCHEMA names its schema. Replace pg.example.org with your server address. The database name must match GRANT CONNECT ON DATABASE postgres in the SQL above. If your database or schema has another name, update both the parameters and privilege commands consistently, including the <schema>.audit table name.

  2. For TLS with a private CA, prepare a siem-certs directory in the installation directory. Place the trusted ca.crt there and, if the SIEM requires mutual authentication, the client certificate client.crt and private key client.key. The files must be readable by the container user with UID 10001. Do not store the private key in the repository.

    Add the mount to the local docker-compose.override.yml file, preserving existing settings:

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

    Example recipient configuration with a private CA and mTLS in .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"}]
    

    Replace the address and port with your SIEM settings. If a client certificate is not required, remove both cert_file and key_file. For an external database, set SIEM_DB_SSLMODE=verify-full and SIEM_DB_SSLROOTCERT to the absolute path of its root certificate inside the container. Mount the database certificate read-only as well.

  3. Start the container from the installation directory and inspect its logs:

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

Verify and limitations#

Create a test sign-in event in Sherpa AI Server and verify that the SIEM receives it. The message should contain app_name=sherpa-ai-server, event_id, the timestamp and event type. The original message, diff and agent are not sent. The container cannot create events missing from the application audit log.

Only new records are exported by default. To load stored records on the first run, set SIEM_START_ID=0 before starting. Each recipient in SIEM_RECIPIENTS has its own cursor in the aiserver-siem-state volume. Recipient names must be unique and stable. On a detected TCP/TLS error, that recipient's cursor does not advance. Recovery may replay an event with the same event_id: configure SIEM deduplication. UDP does not acknowledge delivery and can lose messages.

The exporter revisits previously passed IDs and delivers a record that becomes visible after a higher ID. The sweep reads up to 10,000 IDs per cycle. Detection time depends on audit log size. On first startup, latest marks records visible in a single PostgreSQL snapshot without sending them. Transactions committed after that snapshot are delivered even if their ID is lower. Use SIEM_START_ID=0 to load already visible records. The volume stores processed IDs and grows with the number of records and recipients.

If events do not arrive, check the container logs, recipient address and port, role privileges and certificates. Do not remove the aiserver-siem-state volume on a normal restart because that resets cursors. Successful TCP/TLS sending confirms a socket write, not storage in the SIEM.

The protocol field supports the following transport choices:

  • tls — encrypted delivery with certificate and server-name verification;
  • tcp — connection-based delivery without encryption;
  • udp — delivery without acknowledgements.

A TLS failure never causes an automatic fallback to an unencrypted connection. Select a protocol and port supported by the recipient SIEM.

Audit-table retention must cover the maximum recipient downtime. The exporter cannot recover events deleted from the table before delivery. With UDP, the cursor continues advancing even when the recipient is unavailable, so use it only where message loss is acceptable.

Run only one exporter instance against the same aiserver-siem-state volume. The administrator must monitor free space: the processed-ID journal grows with audit volume and recipient count.

To stop export, run this command from the installation directory:

docker compose stop aiserver-siem-exporter

After stopping it, also remove siem from COMPOSE_PROFILES to disable automatic startup, retaining the other profiles. Sherpa AI Server continues running. The cursor volume and audit records are retained.