OCSF

Elixir library modelling the Open Cybersecurity Schema Framework (OCSF 1.9).

Build, validate, and serialize security events that are OCSF-compliant out of the box. Persistence-agnostic core with optional companion libraries for Postgres and ClickHouse sinks.

Why

• Normalized audit / security events -- one struct shape across auth flows, provisioning, access control, and API activity.
• SIEM-ready JSON -- Jason.encode!/1 produces a schema-valid OCSF payload. No post-processing.
• Compliance-aware -- fields carry PII classification from day 1. Sink policies enforce deny-by-default redaction before events reach storage.
• Persistence-agnostic -- the core library has zero database deps. Consumers choose ocsf_ecto (Postgres) and/or ocsf_clickhouse (ClickHouse) as needed.

Installation

# mix.exs
def deps do
  [
    {:ocsf, "~> 0.2"}
  ]
end

Quick start

Check the OCSF version

OCSF.version()
#=> "1.9.0"

Explore enums

OCSF.Category.name(3)
#=> :"Identity & Access Management"

OCSF.Class.name(3002)
#=> :Authentication

OCSF.Activity.label(3002, 1)
#=> :Logon

OCSF.Severity.name(1)
#=> :Informational

Build an Authentication event

{:ok, event} =
  OCSF.Events.Authentication.logon(
    user: %{
      uid:        "018f19fe-6d4c-71c2-a84b-5d2d8c7f1e90",
      email_addr: "jane@example.com",
      org:        %{uid: "communitiz-app"}
    },
    http_request: %{url: "/oauth/token", http_method: "POST"},
    src_endpoint: %{ip: {10, 0, 0, 1}},
    status:        :Success,
    auth_protocol: :"OAUTH 2.0",
    severity:      :Informational,
    event_code_format: :default
  )

# Serialize to OCSF-compliant JSON
Jason.encode!(event)

Correlation across a flow

correlation_uid = OCSF.UUID.v7_string()

OCSF.Correlation.with(correlation_uid, fn ->
  # Every event created here gets the same correlation_uid
  emit_challenge_created(...)
  emit_challenge_answered(...)
  emit_logon_success(...)
end)

PII classification

OCSF.Classification.pii?(:contact)
#=> true

OCSF.Classification.default_policy(:contact)
#=> :deny

OCSF.User.__ocsf_fields__()
#=> [
#     uid:        [class: :identifier, erasable: false],
#     name:       [class: :identity,   erasable: true],
#     email_addr: [class: :contact,    erasable: true],
#     org:        [class: :tenant,     erasable: false],
#     type_id:    [class: :taxonomic,  erasable: false]
#   ]

Emitting & persisting events

ocsf is the modelling core — it builds and validates events but does not write them anywhere. To emit events from a running app and persist them, add a sink and (for buffered, batched, back-pressured emission on a hot path) the ingestion pipeline:

The end-to-end adoption guide (deps, config, supervision, dispatch, DB-load tuning) lives in the ocsf_ingest README. For low-volume or one-off writes you can call a sink directly (OCSF.Ecto.Sink.write/1) without the pipeline.

Architecture

ocsf              structs, enums, validation, serialization, PII classification
                  runtime dep: jason, uuid_v7

ocsf_ecto         Ecto schema + Ecto.Type shims for Postgres
(optional)        deps: ecto_sql, postgrex

ocsf_clickhouse   Ecto schema + DDL helpers for ClickHouse
(optional)        deps: ecto_sql, ecto_ch

Events flow through three stages:

Emit              Build an %OCSF.Event{} via a class builder
    |
Redact            Apply sink policy: deny PII, transform network fields
    |
Write             Project to flat columns, bulk-insert via sink adapter

Core modules

Nested object structs

Every struct exposes __ocsf_fields__/0 for PII classification metadata.

Supported OCSF classes

Each builder exposes one function per OCSF activity and returns {:ok, %OCSF.Event{}} or {:error, %OCSF.Error{}}. OCSF.validate/1 enforces the class's required fields (e.g. user on 3002/3003/3007, iam_role on 3008, api/actor/src_endpoint on 6003) and its at_least_one constraints (service or dst_endpoint on 3002; privileges, groups or iam_roles on 3003). Only the attributes a class defines are emitted: the caller identity goes in actor.user, the called service in api.service, affected resources in resources (a list of OCSF.ResourceDetails).

Compliance model

Every field on every struct is tagged with a data class (:contact, :identity, :network, :credential, etc.). Sinks declare policies -- allow/deny rules per class with optional transforms (:truncate_v4_24, :hash_salted, :ua_parse_only).

• :contact and :identity fields are denied by default on all sinks. Postgres stores them AES-encrypted; ClickHouse never receives them.
• :network fields (IP, user agent) are denied by default -- sinks must explicitly opt in with a transform.
• :credential fields are always denied -- not configurable.

Right-to-erasure (GDPR Art. 17): Postgres crypto-shreds via per-user AES key rotation. ClickHouse never stores erasable PII.

See OCSF.Classification for the full taxonomy.

OCSF version policy

One library release emits one OCSF version:

• ocsf 0.1.x emitted OCSF 1.8.0
• ocsf 0.2.x and later emit OCSF 1.9.0
• a breaking OCSF change (none expected within 1.x) means a major bump of the library

OCSF.version/0 returns the emitted version. Every event carries metadata.version so stored rows identify which schema they conform to. Because OCSF minor releases are additive, OCSF.validate/1 and OCSF.from_map/1 accept every version in OCSF.supported_versions/0 (["1.8.0", "1.9.0"]), so rows written by an earlier release still read back as full events.

Naming conventions

The library uses __ (double underscore) as the universal segment separator for flat-projected column names, table prefixes, and index names:

Single _ only appears inside OCSF leaf segment names (email_addr, user_agent, class_uid).

Glossary

Authoritative definitions. All project documentation uses these terms verbatim.

Links

• OCSF 1.9 Schema
• OCSF GitHub
• ecto_ch -- ClickHouse Ecto adapter
• uuid_v7 -- UUIDv7 generation

License

Apache-2.0