Canonical Event Schema

Stable telemetry · Validation · Efficient routing

Overview

1SEC modules don’t parse raw logs directly. Instead, collectors normalize input into a canonicalSecurityEvent. This keeps detections consistent across deployments and prevents “schema drift” between sources.

If you’re integrating a new data source, map it to the canonical schema first. Start with Collectors.

Event Shape

The canonical shape includes stable top-level fields (timestamp, type, severity) plus a structured details map for type-specific data.

Conceptual shape

{
  "id": "evt-...",
  "timestamp": "2026-02-21T03:40:00Z",
  "source": "collector.nginx",
  "module": "external",
  "type": "http_request",
  "severity": "INFO",
  "summary": "GET /api/users 200",
  "source_ip": "203.0.113.10",
  "dest_ip": "10.0.0.5",
  "user_agent": "...",
  "details": {
    "path": "/api/users",
    "status": 200,
    "method": "GET"
  }
}

Event Types

Event types are intentionally explicit (e.g., auth_failure,dns_query,http_request). Modules declare the types they consume and will not receive irrelevant traffic.

You can browse the authoritative schema via the API:GET /api/v1/event-schemas.

Validation

The schema is designed to be “strict where it matters”:

Required top-level fields must be present (id, timestamp, type, severity).
Event-type specific required keys live under details.
Unknown keys are allowed, but detectors should not rely on them.

Routing & Fanout

Canonical typing enables efficient routing: modules subscribe only to the event types they declare. This prevents O(N-modules) fanout and keeps JetStream overhead stable as you add more modules.

Examples

Query schemas

curl -s http://localhost:1780/api/v1/event-schemas | jq .

Ingest an external event

curl -X POST http://localhost:1780/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "module": "external_scanner",
    "type": "vulnerability_found",
    "severity": "HIGH",
    "summary": "CVE detected on host 10.0.0.5"
  }'