Pydantic Models for OCSF

0.0.6 · active · verified Fri Apr 17

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.

Common errors

```
ModuleNotFoundError: No module named 'pydantic.v1'
```
cause You have Pydantic V1 installed, but `ocsf-pydantic` requires Pydantic V2.

fix Upgrade Pydantic to version 2: `pip install --upgrade 'pydantic>=2,<3'`.
```
pydantic_core._pydantic_core.ValidationError: 1 validation error for FileActivity\nactivity_id\n  Field required
```
cause A required field for the OCSF event model was omitted or set to `None` where not allowed.

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.
```
AttributeError: 'FileActivity' object has no attribute 'non_existent_field'
```
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.

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.

Warnings

breaking 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.
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.
gotcha `ocsf-pydantic` strictly requires Pydantic V2 (>=2.0.0). It is incompatible with Pydantic V1.
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.
gotcha 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.
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.

Install

pip install ocsf-pydantic Install latest version

Imports

FileActivity
wrong:
```
from ocsf_pydantic.events import FileActivity
```
correct:
```
from ocsf_pydantic.events.file_activity import FileActivity
```
Specific event types are nested under their respective modules (e.g., `file_activity` for `FileActivity`). Direct import from `ocsf_pydantic.events` will fail.
User
wrong:
```
from ocsf_pydantic.objects import User
```
correct:
```
from ocsf_pydantic.objects.user import User
```
Specific OCSF objects are nested under their respective modules (e.g., `user` for `User`). Direct import from `ocsf_pydantic.objects` will fail.

Quickstart

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.

from datetime import datetime, timezone
from ocsf_pydantic.events.file_activity import FileActivity
from ocsf_pydantic.objects.file import File
from ocsf_pydantic.objects.user import User

# Create an OCSF FileActivity event
file_activity_event = FileActivity(
    time=datetime.now(timezone.utc),
    correlation_uid="example-correlation-id-456",
    activity_id=1,  # Represents FileActivityId.CREATE
    file=File(
        name="report.pdf",
        path="/home/user/documents/report.pdf",
        size=10240,
        hash_md5="d41d8cd98f00b204e9800998ecf8427e"
    ),
    user=User(name="analyst_user", uid="U007"),
    message="New report generated by analyst_user"
)

# Print the event as JSON
print(file_activity_event.model_dump_json(indent=2))

# Access a specific field
print(f"\nEvent Type Name: {file_activity_event.activity_name}")
print(f"File Name: {file_activity_event.file.name}")

view raw JSON →