Skip to content

feat: Configurable OCSF schema version for SIEM compatibility (v1.1/v1.3) #2662

Description

@zanetworker

Problem

OpenShell hardcodes OCSF_VERSION = "1.7.0" in crates/openshell-ocsf/src/lib.rs. The two largest OCSF consumers in the market expect earlier schema versions:

  • AWS Security Lake: requires OCSF v1.1.0
  • Splunk OCSF-CIM Add-On (splunkbase.splunk.com/app/6943): targets v1.1.0-v1.3.0
  • CrowdStrike Falcon Next-Gen SIEM: ingests via Security Lake (v1.1.0)

OCSF v1.7.0 is not backward-compatible with v1.1.0 (field renames, new required fields, structural changes). Enterprise customers with existing OCSF-based security automation cannot use OpenShell events without building a custom transformation layer.

What works vs. what doesn't

In a PoC integrating OpenShell OCSF events with Splunk:

  • What worked: Posting v1.7.0 events as raw JSON to Splunk HEC (sourcetype=ocsf) and building custom SPL dashboards that query field names directly (class_uid, sandbox_id, dst_endpoint.hostname, etc.). Splunk HEC accepts any JSON regardless of schema version.

  • What didn't work: The Splunk OCSF-CIM Add-On could not map v1.7.0 events to CIM data models. The Add-On expects v1.1.0-v1.3.0 field names and structure. This means customers with existing OCSF-CIM dashboards, correlation rules, or automated workflows built on the Add-On cannot use OpenShell events without either (a) custom dashboards that bypass CIM, or (b) an external transformation layer.

The distinction matters because "events appear in Splunk" is not the same as "events integrate with the customer's existing OCSF automation." The raw JSON approach works for a PoC but breaks in production environments where security teams have invested in CIM-based workflows.

Proposed Solution

Add a gateway-level configuration option to control the OCSF schema version used for event emission:

[openshell.gateway]
ocsf_schema_version = "1.1"  # or "1.3", "1.7" (default)

When set to an older version:

  • Downgrade field names to match the target schema (e.g., renamed fields between versions)
  • Omit fields that don't exist in the target version
  • Set metadata.version to the configured version

The default should remain the latest version (currently 1.7.0).

Alternatives Considered

  • External transformation layer (Cribl, custom Lambda): Works but adds operational complexity and cost for every deployment. The transformation should happen at the source.
  • Wait for SIEMs to catch up: Splunk and AWS move slowly on OCSF version adoption. v1.7.0 support may be months or years away.
  • Custom dashboards over raw JSON: Works for PoCs but doesn't integrate with existing CIM-based automation, correlation rules, or compliance workflows.

Impact

Enterprise deployments evaluating OpenShell for production need SIEM integration. The top 3 OCSF consumers all require v1.1.0. This blocks adoption unless operators build custom dashboards (losing CIM integration) or deploy external transformation pipelines.

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:acceptedA maintainer decided OpenShell should pursue this issue

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions