OCSF

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

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, path: "../ocsf"}
  ]
end

When published to hex.pm:

{:ocsf, "~> 0.1"}

Quick start

Check the OCSF version

OCSF.version()
#=> "1.8.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 (M1 -- coming soon)

{: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]
#   ]

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

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 targets one OCSF version:

• ocsf 0.x.y targets OCSF 1.8
• ocsf 1.x.y will target OCSF 1.9 when it ships

OCSF.version/0 returns the pinned version. Every emitted event carries metadata.version so stored rows identify which schema they conform to.

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.8 Schema
• OCSF GitHub
• ecto_ch -- ClickHouse Ecto adapter (Plausible)
• uuid_v7 -- UUIDv7 generation

License

Apache-2.0