OCSF Schema Validator
A utility to validate contributions to the OCSF schema, intended to prevent human error when contributing to the schema in order to keep the schema machine-readable.
OCSF provides several include mechanisms to facilitate reuse, but this means individual schema files may be incomplete. This complicates using off-the-shelf schema definition tools for validation.
Query is a federated search solution that normalizes disparate security data to OCSF. This validator is adapted from active code and documentation generation tools written by the Query team.
Getting Started
Prerequisites
- python >3.11
- pip
- A copy of the OCSF schema
Installation
You can install the validator with pip:
$ pip install ocsf-validator
Usage
You can run the validator against your working copy of the schema to identify problems before submitting a PR. Invoke the validator using python and provide it with the path to the root of your working copy.
Examples:
$ python -m ocsf_validator .
$ python -m ocsf_validator ../ocsf-schema
Tests
The validator performs the following tests on a copy of the schema:
- The schema is readable and all JSON is valid. [FATAL]
- The directory structure meets expectations. [WARNING]
- The targets in
$include,profiles, andextendsdirectives can be found. [ERROR] - All required attributes in schema definition files are present. [WARNING]
- There are no unrecognized attributes in schema definition files. [WARNING]
- All attributes in the attribute dictionary are used. [WARNING]
- There are no name collisions within a record type. [WARNING]
- All attributes are defined in the attribute dictionary. [WARNING]
If any ERROR or FATAL tests fail, the validator exits with a non-zero exit code.
Technical Overview
The OCSF metaschema is represented as record types by filepath, achieved as follows:
- Record types are represented using Python's type system by defining them as Python
TypedDicts intypes.py. This allows the validator to take advantage of Python's reflection capabilities. - Files and record types are associated by pattern matching the file paths. These patterns are named in
matchers.pyto allow mistakes to be caught by a type checker. - Types are mapped to filepath patterns in
type_mapping.py.
The contents of the OCSF schema to be validated are primarily represented as a Reader defined in reader.py. Readers load the schema definitions to be validated from a source (usually from a filesystem) and contain them without judgement. The process_includes function and other contents of processor.py mutate the contents of a Reader by applying OCSF's various include mechanisms.
Validators are defined in validators.py and test the schema contents for various problematic conditions. Validators should pass Exceptions to a special error Collector defined in errors.py. This module also defines a number of custom exception types that represent problematic schema states. The Collector raises errors by default, but can also hold them until they're aggregated by a larger validation process (e.g., the ValidationRunner).
The ValidationRunner combines all of the building blocks above to read a proposed schema from a filesystem, validate the schema, and provide useful output and a non-zero exit code if any errors were encountered.
Contributing
After checking out, you'll want to install dependencies:
poetry install
Before committing, run the formatters and tests:
poetry run isort .
poetry run black .
poetry run pyright
poetry run pytest
If you're adding a validator, do the following:
- Write your
validate_function invalidate.pyto apply a function to the relevant keys in a reader that will run your desired validation. Seevalidators.pyfor examples. - Add any custom errors in
errors.py. - Create an option to change its severity level in
ValidatorOptionsand map it in the constructor ofValidationRunnerinrunner.py. - Invoke the new validator in
ValidationRunner.validate.
Metadata
Release files for ocsf-validator 0.2.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ocsf_validator-0.2.5.tar.gz | 24.6 kB | Without provenance | Details for ocsf_validator-0.2.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ocsf_validator-0.2.5-py3-none-any.whl | Python 3 | none | any | Details for ocsf_validator-0.2.5-py3-none-any.whl |
Total release size: 51.6 kB
Release files / ocsf_validator-0.2.5.tar.gz
| Download URL | ocsf_validator-0.2.5.tar.gz |
|---|---|
| Size | 24.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9c7563f7b5cd29bf45b14f78d1d257592265280701d118028a3c27398ec65b23
|
|
BLAKE2b-256 checksum How to use checksums |
a422fc14ad4442d461a7e2ca2d63be2fbb0546a46b386a6b0a233a4a1e855c7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.6.1 CPython/3.11.10 Darwin/25.5.0
|
Release files / ocsf_validator-0.2.5-py3-none-any.whl
| Download URL | ocsf_validator-0.2.5-py3-none-any.whl |
|---|---|
| Size | 27.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
523a23a02c3350f6e93d44e0a96862ee8cb442061e80d7988ac6a2e72346dfc5
|
|
BLAKE2b-256 checksum How to use checksums |
66b24b18f632cc13bc96c3148c2674ee625360e94e2e7b3ecd7d82637c8abe0f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.6.1 CPython/3.11.10 Darwin/25.5.0
|
Security for ocsf-validator 0.2.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.