{"id":9999,"library":"ocsf-pydantic","title":"Pydantic Models for OCSF","description":"ocsf-pydantic provides Pydantic v2 models for the Open Cybersecurity Schema Framework (OCSF). It enables type-safe Python representations of OCSF schemas, facilitating event parsing, validation, and generation in cybersecurity applications. The current version is 0.0.6, and its release cadence is irregular, typically aligned with updates to the OCSF specification or bug fixes.","status":"active","version":"0.0.6","language":"en","source_language":"en","source_url":"https://github.com/crowdalert/ocsf-pydantic","tags":["OCSF","Pydantic","Cybersecurity","Schema","Validation","Event Logging"],"install":[{"cmd":"pip install ocsf-pydantic","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for model definition and validation.","package":"pydantic","optional":false}],"imports":[{"note":"Specific event types are nested under their respective modules (e.g., `file_activity` for `FileActivity`). Direct import from `ocsf_pydantic.events` will fail.","wrong":"from ocsf_pydantic.events import FileActivity","symbol":"FileActivity","correct":"from ocsf_pydantic.events.file_activity import FileActivity"},{"note":"Specific OCSF objects are nested under their respective modules (e.g., `user` for `User`). Direct import from `ocsf_pydantic.objects` will fail.","wrong":"from ocsf_pydantic.objects import User","symbol":"User","correct":"from ocsf_pydantic.objects.user import User"}],"quickstart":{"code":"from datetime import datetime, timezone\nfrom ocsf_pydantic.events.file_activity import FileActivity\nfrom ocsf_pydantic.objects.file import File\nfrom ocsf_pydantic.objects.user import User\n\n# Create an OCSF FileActivity event\nfile_activity_event = FileActivity(\n    time=datetime.now(timezone.utc),\n    correlation_uid=\"example-correlation-id-456\",\n    activity_id=1,  # Represents FileActivityId.CREATE\n    file=File(\n        name=\"report.pdf\",\n        path=\"/home/user/documents/report.pdf\",\n        size=10240,\n        hash_md5=\"d41d8cd98f00b204e9800998ecf8427e\"\n    ),\n    user=User(name=\"analyst_user\", uid=\"U007\"),\n    message=\"New report generated by analyst_user\"\n)\n\n# Print the event as JSON\nprint(file_activity_event.model_dump_json(indent=2))\n\n# Access a specific field\nprint(f\"\\nEvent Type Name: {file_activity_event.activity_name}\")\nprint(f\"File Name: {file_activity_event.file.name}\")","lang":"python","description":"This quickstart demonstrates how to create a `FileActivity` OCSF event using the `ocsf-pydantic` models. It populates essential fields like time, correlation ID, file details, and user information, then prints the resulting event in JSON format. It also shows how to access nested fields."},"warnings":[{"fix":"Always review release notes for new versions and test your code against new releases, especially for breaking changes in model fields or required arguments.","message":"This library is pre-1.0, and its API is subject to change without strict adherence to semantic versioning. Updates to the underlying OCSF specification can also lead to breaking changes in model structure.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure `pydantic` is installed at version 2.x. If you have Pydantic V1 installed, upgrade it (`pip install --upgrade 'pydantic>=2,<3'`) or use a virtual environment.","message":"`ocsf-pydantic` strictly requires Pydantic V2 (>=2.0.0). It is incompatible with Pydantic V1.","severity":"gotcha","affected_versions":"*"},{"fix":"Trust the default values set by the models for these common event fields. Focus on providing data for the specific fields relevant to your event type. If you need to manipulate common fields, do so carefully after model instantiation, or ensure your data strictly adheres to OCSF enum values.","message":"Many common OCSF event fields (e.g., `type_id`, `class_name`, `severity`, `category_name`) are automatically set by the specific event models (e.g., `FileActivity`) based on the OCSF specification. Attempting to manually override these can lead to unexpected behavior or validation errors.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Upgrade Pydantic to version 2: `pip install --upgrade 'pydantic>=2,<3'`.","cause":"You have Pydantic V1 installed, but `ocsf-pydantic` requires Pydantic V2.","error":"ModuleNotFoundError: No module named 'pydantic.v1'"},{"fix":"Refer to the OCSF specification for the event type you are using and ensure all required fields are provided with valid data. For `FileActivity`, `activity_id` is mandatory.","cause":"A required field for the OCSF event model was omitted or set to `None` where not allowed.","error":"pydantic_core._pydantic_core.ValidationError: 1 validation error for FileActivity\\nactivity_id\\n  Field required"},{"fix":"Consult the OCSF specification or the generated `ocsf-pydantic` model's attributes (e.g., using `dir(event_object)` or inspecting the class definition) to confirm valid field names.","cause":"You are trying to access a field that is not part of the OCSF schema for the specific event or object model, or the field name is misspelled.","error":"AttributeError: 'FileActivity' object has no attribute 'non_existent_field'"}]}