SIEM Integration

The SIEM integration delivers Aegis attestations to enterprise security information and event management (SIEM) systems using the OCSF (Open Cybersecurity Schema Framework) standard. Any SIEM that speaks OCSF can ingest Aegis decisions natively.

How It Works

OCSF Mapping (`siem_mapper.py`)

The attestation_to_ocsf_2001() function maps Aegis attestation fields to OCSF Class 2001 (Security Finding):

from epistom.aegis_proxy.siem_mapper import attestation_to_ocsf_2001
 
ocsf_event = attestation_to_ocsf_2001(attestation)
# Returns OCSF 2001 event with:
#   class_uid: 2001
#   type_uid: based on verdict
#   severity_id: based on impact severity
#   finding: attestation details
#   actor: agent identity
#   resources: affected entities

Outbox Pattern (`siem_enqueue.py`)

SIEM delivery uses the transactional outbox pattern for reliability:

When an attestation is recorded, siem_enqueue writes a pending delivery row to the aegis_siem_outbox table for each active SIEM destination
A background worker reads pending rows and delivers them to the configured SIEM endpoints
Successful deliveries are marked as delivered; failures are retried with exponential backoff

This pattern ensures SIEM delivery never blocks the attestation hot path. The attestation is always recorded even if SIEM delivery fails.

SIEM Connectors (`siem_connectors.py`)

Two built-in connectors:

Splunk HEC (HTTP Event Collector):

Sends OCSF events to the Splunk HEC endpoint
Supports batching for throughput
Uses stdlib urllib.request (no external dependencies)

Microsoft Sentinel:

Sends OCSF events to the Azure Monitor HTTP Data Collector API
Supports HMAC-SHA256 authentication
Uses stdlib urllib.request and base64 for authentication

Both connectors accept a list of OCSF events for batch delivery. Authentication configuration is decrypted by the caller before passing to the connector.

Architecture

Attestation Store
    ↓ (append-only INSERT)
SIEM Outbox (transactional write)
    ↓ (background worker)
OCSF Mapper (attestation → OCSF 2001)
    ↓
SIEM Connectors
    ├── Splunk HEC
    └── Microsoft Sentinel

Configuration

SIEM destinations are configured via the REST API:

POST /api/v1/aegis/siem-destinations
{
  "workspace_id": "ws-1",
  "type": "splunk_hec",
  "endpoint": "https://splunk.company.com:8088/services/collector",
  "auth_config": {"token": "your-hec-token"},
  "enabled": true
}

Technical Details

SIEM enqueue MUST never raise — it is wrapped in try/except in the evaluate() hot path with warning logging on failure
The outbox table (aegis_siem_outbox) uses nullable attestation foreign keys to support delivery of non-attestation events
OCSF Class 2001 was chosen because it maps naturally to "a security system made a finding about an action"
Verdict-to-severity mapping: ALLOW=informational, DENY=medium, ESCALATE=high, REWRITE=low
Connectors use stdlib only (no requests, no httpx) to minimize the security-critical dependency surface

How It Works

OCSF Mapping (siem_mapper.py)

Outbox Pattern (siem_enqueue.py)