SIEM Integration

The Audit Service integrates with external Security Information and Event Management (SIEM) systems through the SiemIntegration service. Audit events are forwarded in real-time to configured SIEM endpoints. The system supports Splunk, Datadog, Elasticsearch, and generic webhooks, with per-tenant configuration, batch forwarding, and retry logic.

Supported SIEM Types

Get Supported Types

Endpoint: GET /api/v1/audit/siem/types

Returns the list of supported SIEM types with their required and optional fields.

Register a SIEM Configuration

Endpoint: POST /api/v1/audit/siem/tenants/:tenantId/configurations

curl -X POST http://localhost:8086/api/v1/audit/siem/tenants/550e8400/configurations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "type": "SPLUNK",
    "endpoint": "https://splunk.acme.com:8088",
    "apiKey": "your-hec-token",
    "enabled": true,
    "settings": {
      "index": "matih-audit",
      "source": "matih-platform",
      "sourcetype": "matih:audit:event"
    }
  }'

Manage Configurations

List Configurations

Endpoint: GET /api/v1/audit/siem/tenants/:tenantId/configurations

Update Configuration

Endpoint: PUT /api/v1/audit/siem/tenants/:tenantId/configurations/:configId

Delete Configuration

Endpoint: DELETE /api/v1/audit/siem/tenants/:tenantId/configurations/:configId

Enable/Disable Configuration

Endpoint: PATCH /api/v1/audit/siem/tenants/:tenantId/configurations/:configId/enabled

curl -X PATCH "http://localhost:8086/api/v1/audit/siem/tenants/550e8400/configurations/cfg-001/enabled?enabled=false" \
  -H "Authorization: Bearer ${TOKEN}"

Test Connection

Endpoint: POST /api/v1/audit/siem/tenants/:tenantId/configurations/test

Tests connectivity to a SIEM endpoint before saving the configuration.

curl -X POST http://localhost:8086/api/v1/audit/siem/tenants/550e8400/configurations/test \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "type": "SPLUNK",
    "endpoint": "https://splunk.acme.com:8088",
    "apiKey": "your-hec-token",
    "enabled": true,
    "settings": {}
  }'

Response:

{
  "success": true,
  "message": "Connection successful",
  "latencyMs": 45
}

Forwarding Statistics

Endpoint: GET /api/v1/audit/siem/tenants/:tenantId/stats

{
  "totalEventsForwarded": 12500,
  "successfulForwards": 12480,
  "failedForwards": 20,
  "lastForwardTimestamp": 1707730200000,
  "forwardsByType": {
    "SPLUNK": 10000,
    "DATADOG": 2500
  }
}

Event Forwarding Details

Splunk Format

Events are formatted as Splunk HEC JSON with time, host, source, sourcetype, index, and event fields. Sent to /services/collector/event.

Datadog Format

Events are formatted as Datadog log entries with ddsource, ddtags, hostname, service, and message fields. Tags include tenant, event type, severity, and custom tags. Sent to /api/v2/logs.

Elasticsearch Format

Events are indexed as JSON documents into date-partitioned indices (default pattern: audit-events-yyyy.MM.dd). Bulk indexing uses the /_bulk API with application/x-ndjson content type.

Webhook Format

Events are wrapped in a standard payload with source, timestamp, and events array. Custom headers and authentication types are configurable.

Configuration

Retries use exponential backoff (1s, 2s, 3s).