OCSF Library

Common errors

• AttributeError: 'Extension' object has no attribute 'description'

  cause You are attempting to access the `description` attribute of an `OCSFExtension` object after upgrading to `ocsf-lib` v0.10.0 or newer.
  fix The `description` attribute was renamed to `caption`. Replace `extension.description` with `extension.caption`.

• TypeError: '<' not supported between instances of 'NoneType' and 'str'

  cause This or similar errors (e.g., related to `yaml.YAMLError`) can occur if you're trying to load OCSF extensions from YAML files using `OCSFExtension.from_file()` after upgrading to `ocsf-lib` v0.9.0 or newer.
  fix As of v0.9.0, OCSF extension files must be in TOML format. Convert your `.yaml` extension files to `.toml` format.

• jsonschema.ValidationError: 'type' is a required property

  cause The OCSF event dictionary you are trying to validate against the schema is missing a required field, or a field is malformed. This specific error indicates a missing `type` property (which is often nested).
  fix Carefully review the OCSF schema documentation for the event type you are trying to create. Ensure all required fields are present, correctly named, and conform to the expected data types. Inspect the `e.path` attribute of the `ValidationError` for the exact location of the missing/incorrect field.

• ModuleNotFoundError: No module named 'ocsf_lib.schema.v1_0_0'

  cause You are attempting to directly import a specific version of the OCSF schema, e.g., `from ocsf_lib.schema.v1_0_0 import OCSFSchema`.
  fix The OCSF schema versions are loaded internally by the `OCSFSchema` class. Instantiate `OCSFSchema` and pass the desired version as a parameter if needed: `schema = OCSFSchema(version='1.0.0-rc.3')` or simply `schema = OCSFSchema()` for the latest.

Warnings

• breaking The `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`.
• breaking OCSF 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.
• breaking The `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.
• breaking The 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.
• gotcha When 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.

Install

• pip install ocsf-lib Install latest version

Imports

• OCSFSchema

  from ocsf_lib.schema import OCSFSchema

• OCSFEvent

  from ocsf_lib.events import OCSFEvent

• OCSFExtension

  from ocsf_lib.extensions import OCSFExtension

• OCSFError

  from ocsf_lib.exceptions import OCSFError

  While Schema.validate no longer directly raises OCSFError (it raises jsonschema.ValidationError since v0.8.0), it's still the base exception class for other library errors.

Quickstart

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}")