ocsf

Open Cybersecurity Schema Framework - LinkML Schema

(reproducible)

Documentation Website

https://lmodel.github.io/ocsf

Repository Structure

• docs/ - mkdocs-managed documentation
  • elements/ - generated schema documentation
• examples/ - Examples of using the schema
• project/ - project files (these files are auto-generated, do not edit)
• src/ - source files (edit these)
  • ocsf
    • schema/ -- LinkML schema (edit this)
    • datamodel/ -- generated Python datamodel
• tests/ - Python tests
  • data/ - Example data

Developer Tools

There are several pre-defined command-recipes available. They are written for the command runner just. To list all pre-defined commands, run just or just --list.

Schema Generation Notes

The LinkML schema under src/ocsf/schema/ is generated from the upstream OCSF JSON sources at upstream/ocsf-schema/ by tools/generate_ocsf_schema.py.

Class-scoped enum overrides extend (rather than replace) the dictionary base

OCSF semantically inherits the implicit 0/Unknown and 99/Other codes from base_event.activity_id (and similar slots) into every event subclass that declares its own activity values. The upstream JSON only stores the new values explicitly (e.g. Authentication.activity_id declares 1..7), expecting consumers to merge the base codes back in.

The generator merges base_event / dictionary-level enum codes into each class-scoped override, so that AuthenticationActivityIdEnum, DnsActivityActivityIdEnum, etc. include UNKNOWN and OTHER alongside their class-specific values. Without this merge, valid OCSF data using activity_id: UNKNOWN would be rejected by the generated validator. See _extract_enum and its base_values parameter in tools/generate_ocsf_schema.py.

Known upstream LinkML issues

A small number of generator/runtime bugs in upstream LinkML currently affect the Python datamodel produced from this schema. They are tracked upstream.

Credits

This project uses the template linkml-project-copier.