SIEM Integration¶

AegisAI exports security events to external SIEM systems for centralized monitoring, correlation, and compliance.

Overview¶

The SIEM exporter runs as a background service inside the API process. It batches events and sends them asynchronously so authentication and API requests are not blocked.

flowchart LR
    subgraph AegisAI
        API[API / Services]
        EXP[SIEM Exporter]
        BATCH[Batch Queue]
    end
    subgraph Destinations
        SYS[Syslog TCP/UDP]
        SPL[Splunk HEC]
        ELK[Elasticsearch]
    end
    API -->|fire-and-forget| EXP
    EXP --> BATCH
    BATCH --> SYS & SPL & ELK

Event Sources¶

Events are emitted from:

Domain	Examples
User	login, logout, SSO login, login_failed, role changes
API keys	generate, revoke
Policies	create, update, delete, violations
Agents	register, update
WebSocket	anomaly.detected, hitl.resolved, policy.violated

Output Formats¶

Format	Env `SIEM_FORMAT`	Use Case
Syslog (RFC 5424)	`syslog`	Generic SIEM, rsyslog
CEF	`cef`	ArcSight, QRadar
LEEF	`leef`	IBM QRadar
JSONL	`jsonl`	Splunk HEC, ELK

Configuration¶

Enable and transport¶

SIEM_ENABLED=true
SIEM_FORMAT=jsonl
SIEM_TRANSPORT=auto
SIEM_BATCH_SIZE=100
SIEM_BATCH_TIMEOUT=5
SIEM_MAX_RETRIES=3
SIEM_CONNECT_TIMEOUT=5.0

Variable	Description
`SIEM_TRANSPORT`	`auto`, `syslog`, `splunk`, or `elk`
`SIEM_HOST` / `SIEM_PORT`	Syslog destination (default TCP 514)
`SIEM_TLS`	Enable TLS for syslog TCP

auto selects Splunk HEC if SPLUNK_HEC_URL is set, else ELK if ELK_URL is set, else syslog.

Splunk HEC¶

SIEM_FORMAT=jsonl
SPLUNK_HEC_URL=https://splunk.example.com:8088/services/collector/event
SPLUNK_HEC_TOKEN=your-hec-token
SPLUNK_HEC_SOURCETYPE=aegisai:security

Elasticsearch / ELK¶

SIEM_FORMAT=jsonl
ELK_URL=https://elasticsearch.example.com:9200
ELK_INDEX=aegisai-%Y.%m.%d
ELK_USERNAME=elastic
ELK_PASSWORD=your-password

Placeholder URLs

Do not enable SIEM with unreachable hostnames (e.g. https://splunk:8088 in Docker without a Splunk service). Failed exports are retried in the background but generate log noise. Use SIEM_ENABLED=false until a real destination is configured.

API (Admin)¶

Requires Super Admin JWT or X-Admin-Key.

GET `/siem/status`¶

curl https://aegisai.example.com/api/v1/siem/status \
  -H "X-Admin-Key: <admin-api-key>"

Returns enabled state, format, transport, batch settings.

POST `/siem/test`¶

curl -X POST https://aegisai.example.com/api/v1/siem/test \
  -H "X-Admin-Key: <admin-api-key>"

Sends a test event and flushes the batch.

CEF Example¶

CEF:0|AegisAI|AegisAI|1.0|user.login|User Login|3|rt=2026-07-04T... cs1=tenant-uuid ...

Performance Notes¶

User audit and auth events use fire-and-forget export — login is not blocked on SIEM timeouts
Batch lock is held only while queuing; network I/O runs outside the lock
Tune SIEM_BATCH_SIZE and SIEM_BATCH_TIMEOUT for throughput vs latency

Load Testing¶

Baseline load tests live in scripts/load_test/. Run via:

./scripts/run_load_test.sh