ocsf-lib

library0.10.4pypypiunverified

A Python library for working with the Open Cybersecurity Schema Framework (OCSF) JSON schema. It provides tools for validating OCSF events, loading schemas, and managing OCSF extensions. The current version is 0.10.4, and it has an active, though irregular, release cadence with significant updates between minor versions.

serialization auth-security observability

pip install ocsf-lib

package ↗

INSTALL

IMPORT

SIG · OCSF-LIB

ocsf-lib

serializationpythonv0.10.4

Install

1.8s avg

Import

—

Disk

16MB

Pass rate

6/ 10

Env Coverage6 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.10.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

py 3.11

✓ —

✓ 1.9s

py 3.12

✓ —

✓ 1.7s

py 3.13

✓ —

✓ 1.7s

py 3.9

✕ build_error

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OCSFSchema

✓ from ocsf import OCSFSchema

✗ from ocsf import OCSFSchema

This quickstart demonstrates how to load the OCSF schema and validate an example OCSF event against it. It highlights the primary use case of the `ocsf-lib` for ensuring OCSF event compliance.

from ocsf_lib.schema import OCSFSchema from jsonschema import ValidationError import json # An example minimal OCSF event (Process Activity Create) # This example is simplified; real OCSF events are more complex and follow specific OCSF types. example_event = { "activity_id": 1, "activity_name": "Create", "category_uid": 1, "category_name": "Audit Activity", "class_uid": 1001, "class_name": "Process Activity", "metadata": { "product": { "name": "MyApplication", "vendor_name": "MyVendor", "version": "1.0.0" }, "version": "1.0.0-rc.3" # OCSF Schema version this event conforms to }, "severity_id": 1, "severity": "Informational", "start_time": "2023-10-27T10:00:00Z", "time": "2023-10-27T10:00:00Z", "type_uid": 100101, "type_name": "Process Activity: Create", "process": { "pid": 1234, "name": "example_process", "command_line": "/usr/bin/example --flag" } } try: # 1. Load the OCSF schema # By default, it loads the latest recommended version. # You can specify a version, e.g., OCSFSchema(version="1.0.0-rc.3") schema = OCSFSchema() print(f"Successfully loaded OCSF Schema version: {schema.version}") # 2. Validate an OCSF event against the loaded schema print(f"\nAttempting to validate event:\n{json.dumps(example_event, indent=2)}") schema.validate(example_event) print("\nSUCCESS: The example event is valid according to the OCSF schema.") except ValidationError as e: print(f"\nVALIDATION ERROR: The event is NOT valid.") print(f" Message: {e.message}") print(f" Path: {list(e.path)}") print(f" Validator: {e.validator} (value: {e.validator_value})") except Exception as e: print(f"\nAn unexpected error occurred: {e}")

Debug

Known issues

breakingThe `Extension.description` property was renamed to `Extension.caption` to align with the OCSF Schema specification.

fix

Update any code accessing `OCSFExtension` objects to use `extension.caption` instead of `extension.description`.

affects: >=0.10.0

breakingOCSF extension files must now be in TOML format instead of YAML. The `pyyaml` dependency was removed and replaced with `tomli`/`tomli_w`.

fix

Convert any existing OCSF extension definition files from YAML to TOML format. The `OCSFExtension.from_file()` method now expects a TOML file.

affects: >=0.9.0

breakingThe `Schema.validate` method now raises `jsonschema.ValidationError` for invalid events instead of the custom `OCSFError`.

fix

Update error handling code that catches validation failures. Replace `except OCSFError:` with `except jsonschema.ValidationError:` for schema validation errors. `OCSFError` is still used for other library-specific exceptions.

affects: >=0.8.0

breakingThe library switched its internal data modeling to Pydantic v2, which introduced many breaking changes to Pydantic's API.

fix

If your code directly interacts with the Pydantic models generated by `ocsf-lib` (e.g., `OCSFEvent` subclasses or internal schema components), you may need to update your code to be compatible with Pydantic v2 conventions. Refer to Pydantic v2 migration guides.

affects: >=0.7.0

gotchaWhen instantiating `OCSFSchema`, the library will automatically download the schema files if not found locally. This requires an internet connection on the first run or if schema cache is cleared.

fix

Ensure network connectivity for initial schema loading. For environments without internet access, pre-populate the schema cache or package the schema files with your application.

affects: All versions

Upgrade

Version history

0.10.4latest on PyPI · released Jul 7, 2025

Audit

Dependencies

jsonschemarequiredCore dependency for schema validation.

pydanticrequiredCore dependency for data modeling (Pydantic v2+).

tomlirequiredUsed for parsing OCSF extension files in TOML format (replaced PyYAML in v0.9.0).

orjsonrequiredUsed for high-performance JSON serialization/deserialization (replaced python-rapidjson in v0.9.0).

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/ocsf-lib/ ↗