py-ocsf-models

0.9.0 verified Fri May 01 auth: no python

Python implementation of the OCSF (Open Cybersecurity Schema Framework) models. Provides Pydantic v2-based data models representing OCSF schema objects (e.g., DetectionFinding, ComplianceFinding). Current version 0.9.0, supports Python 3.10–3.14, maintained by Prowler Cloud.

pip install py-ocsf-models

Common errors

error ImportError: cannot import name 'DetectionFinding' from 'py_ocsf_models' ↓

cause Incorrect import path; symbols are nested under 'events' submodule.

fix

Use: from py_ocsf_models.events.findings.detection_finding import DetectionFinding

error pydantic_core._pydantic_core.ValidationError: 1 validation error for DetectionFinding type_uid Field required [type=missing, input_value={...}, input_type=dict] ↓

cause DetectionFinding requires type_uid field (an integer). Not all OCSF fields are optional; required fields must be provided.

fix

Ensure you pass type_uid, time, metadata, severity, confidence (or adjust to match required fields). Check the model's schema.

Warnings

gotcha Pydantic v2 migration: Prior to 0.8.0, models used Pydantic v1. If you have serialized objects with Pydantic v1, they may not deserialize correctly with v2. Use model_validate instead of parse_raw. ↓

fix Upgrade to >=0.8.0 and use model_validate (v2 style) instead of parse_raw (v1).

gotcha Python 3.9 support was removed in 0.9.0. Required Python >=3.10 now. ↓

fix Use Python >=3.10.

deprecated The product_uid field was removed from DetectionFinding in 0.4.0. Do not rely on it. ↓

fix Remove product_uid from any model instantiation.

Imports

DetectionFinding

wrong

from py_ocsf_models import DetectionFinding

correct

from py_ocsf_models.events.findings.detection_finding import DetectionFinding

Top-level import may not work; models are under nested modules

ComplianceFinding

from py_ocsf_models.events.findings.compliance_finding import ComplianceFinding

Introduced in 0.5.0

Quickstart

Create a simple DetectionFinding instance and serialize to JSON.

from py_ocsf_models.events.findings.detection_finding import DetectionFinding

finding = DetectionFinding(
    metadata={'product': {'name': 'Test', 'vendor_name': 'Acme'}},
    severity='Medium',
    confidence='High',
    time=1234567890,
    type_uid=1
)
print(finding.model_dump(mode='json'))