{"id":9998,"library":"ocsf-lib","title":"OCSF Library","description":"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.","status":"active","version":"0.10.4","language":"en","source_language":"en","source_url":"https://github.com/ocsf/ocsf-lib-python","tags":["OCSF","cybersecurity","schema","validation","security","pydantic"],"install":[{"cmd":"pip install ocsf-lib","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for schema validation.","package":"jsonschema","optional":false},{"reason":"Core dependency for data modeling (Pydantic v2+).","package":"pydantic","optional":false},{"reason":"Used for parsing OCSF extension files in TOML format (replaced PyYAML in v0.9.0).","package":"tomli","optional":false},{"reason":"Used for high-performance JSON serialization/deserialization (replaced python-rapidjson in v0.9.0).","package":"orjson","optional":false}],"imports":[{"symbol":"OCSFSchema","correct":"from ocsf_lib.schema import OCSFSchema"},{"symbol":"OCSFEvent","correct":"from ocsf_lib.events import OCSFEvent"},{"symbol":"OCSFExtension","correct":"from ocsf_lib.extensions import OCSFExtension"},{"note":"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.","symbol":"OCSFError","correct":"from ocsf_lib.exceptions import OCSFError"}],"quickstart":{"code":"from ocsf_lib.schema import OCSFSchema\nfrom jsonschema import ValidationError\nimport json\n\n# An example minimal OCSF event (Process Activity Create)\n# This example is simplified; real OCSF events are more complex and follow specific OCSF types.\nexample_event = {\n    \"activity_id\": 1,\n    \"activity_name\": \"Create\",\n    \"category_uid\": 1,\n    \"category_name\": \"Audit Activity\",\n    \"class_uid\": 1001,\n    \"class_name\": \"Process Activity\",\n    \"metadata\": {\n        \"product\": {\n            \"name\": \"MyApplication\",\n            \"vendor_name\": \"MyVendor\",\n            \"version\": \"1.0.0\"\n        },\n        \"version\": \"1.0.0-rc.3\" # OCSF Schema version this event conforms to\n    },\n    \"severity_id\": 1,\n    \"severity\": \"Informational\",\n    \"start_time\": \"2023-10-27T10:00:00Z\",\n    \"time\": \"2023-10-27T10:00:00Z\",\n    \"type_uid\": 100101,\n    \"type_name\": \"Process Activity: Create\",\n    \"process\": {\n        \"pid\": 1234,\n        \"name\": \"example_process\",\n        \"command_line\": \"/usr/bin/example --flag\"\n    }\n}\n\ntry:\n    # 1. Load the OCSF schema\n    # By default, it loads the latest recommended version. \n    # You can specify a version, e.g., OCSFSchema(version=\"1.0.0-rc.3\")\n    schema = OCSFSchema()\n    print(f\"Successfully loaded OCSF Schema version: {schema.version}\")\n\n    # 2. Validate an OCSF event against the loaded schema\n    print(f\"\\nAttempting to validate event:\\n{json.dumps(example_event, indent=2)}\")\n    schema.validate(example_event)\n    print(\"\\nSUCCESS: The example event is valid according to the OCSF schema.\")\n\nexcept ValidationError as e:\n    print(f\"\\nVALIDATION ERROR: The event is NOT valid.\")\n    print(f\"  Message: {e.message}\")\n    print(f\"  Path: {list(e.path)}\")\n    print(f\"  Validator: {e.validator} (value: {e.validator_value})\")\nexcept Exception as e:\n    print(f\"\\nAn unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update any code accessing `OCSFExtension` objects to use `extension.caption` instead of `extension.description`.","message":"The `Extension.description` property was renamed to `Extension.caption` to align with the OCSF Schema specification.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"Convert any existing OCSF extension definition files from YAML to TOML format. The `OCSFExtension.from_file()` method now expects a TOML file.","message":"OCSF extension files must now be in TOML format instead of YAML. The `pyyaml` dependency was removed and replaced with `tomli`/`tomli_w`.","severity":"breaking","affected_versions":">=0.9.0"},{"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.","message":"The `Schema.validate` method now raises `jsonschema.ValidationError` for invalid events instead of the custom `OCSFError`.","severity":"breaking","affected_versions":">=0.8.0"},{"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.","message":"The library switched its internal data modeling to Pydantic v2, which introduced many breaking changes to Pydantic's API.","severity":"breaking","affected_versions":">=0.7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"The `description` attribute was renamed to `caption`. Replace `extension.description` with `extension.caption`.","cause":"You are attempting to access the `description` attribute of an `OCSFExtension` object after upgrading to `ocsf-lib` v0.10.0 or newer.","error":"AttributeError: 'Extension' object has no attribute 'description'"},{"fix":"As of v0.9.0, OCSF extension files must be in TOML format. Convert your `.yaml` extension files to `.toml` format.","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.","error":"TypeError: '<' not supported between instances of 'NoneType' and 'str'"},{"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.","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).","error":"jsonschema.ValidationError: 'type' is a required property"},{"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.","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`.","error":"ModuleNotFoundError: No module named 'ocsf_lib.schema.v1_0_0'"}]}