OCSF JSON Export

The shorthand log format is optimized for humans and agents reading logs in real time. For machine consumption, compliance archival, or SIEM integration, you can enable full OCSF JSON export. This writes every OCSF event as a complete JSON record in JSONL format, one JSON object per line.

Enable JSON Export

Use the ocsf_json_enabled setting to toggle JSON export. The setting can be applied globally, for all sandboxes, or per-sandbox.

Global:

openshell settings set --global --key ocsf_json_enabled --value true

Per-sandbox:

openshell settings set my-sandbox --key ocsf_json_enabled --value true

The setting takes effect on the next poll cycle, by default every 10 seconds. No sandbox restart is required.

To disable:

openshell settings set --global --key ocsf_json_enabled --value false

Windows MXC gateways

MXC audit events originate in the Windows gateway rather than an in-sandbox supervisor. Enable the MXC ETW consumer in gateway.toml, then explicitly opt the gateway into durable JSONL output:

[openshell.drivers.mxc]
etw_audit = true

$env:OPENSHELL_OCSF_JSON = "1"
# Optional; defaults to %PROGRAMDATA%\OpenShell\logs.
$env:OPENSHELL_OCSF_LOG_DIR = "D:\OpenShell\audit"
openshell-gateway --drivers mxc --config gateway.toml

The sink is available only when Windows selects the MXC driver. It rotates daily and retains the three most recent files. Diagnostic --log-level values do not suppress records in this explicitly enabled audit sink.

Output Location

For sandbox supervisors, OCSF JSON records are written to /var/log/openshell-ocsf.YYYY-MM-DD.log inside the sandbox. Windows MXC gateway records use %PROGRAMDATA%\OpenShell\logs or OPENSHELL_OCSF_LOG_DIR. Both sinks rotate daily and retain the three most recent files.

JSON Record Structure

metadata.uid uniquely identifies an event and stays unchanged when that record is serialized again. Use container.uid to associate the event with its sandbox, not metadata.uid. Records without a sandbox association omit the container; unknown images are omitted rather than represented by an empty image name.

Each line is a complete OCSF v1.8.0 JSON object. Here is an example of a network connection event:

{
  "class_uid": 4001,
  "class_name": "Network Activity",
  "category_uid": 4,
  "category_name": "Network Activity",
  "activity_id": 1,
  "activity_name": "Open",
  "severity_id": 1,
  "severity": "Informational",
  "status_id": 1,
  "status": "Success",
  "time": 1775014138811,
  "message": "CONNECT allowed api.github.com:443",
  "metadata": {
    "product": {
      "name": "OpenShell Sandbox Supervisor",
      "vendor_name": "NVIDIA",
      "version": "0.3.0"
    },
    "version": "1.8.0"
  },
  "action_id": 1,
  "action": "Allowed",
  "disposition_id": 1,
  "disposition": "Allowed",
  "dst_endpoint": {
    "domain": "api.github.com",
    "port": 443
  },
  "src_endpoint": {
    "ip": "10.42.0.31",
    "port": 37494
  },
  "actor": {
    "process": {
      "name": "/usr/bin/curl",
      "pid": 57
    }
  },
  "firewall_rule": {
    "name": "github_api",
    "type": "opa"
  }
}

And a denied connection:

{
  "class_uid": 4001,
  "class_name": "Network Activity",
  "activity_id": 1,
  "activity_name": "Open",
  "severity_id": 3,
  "severity": "Medium",
  "status_id": 2,
  "status": "Failure",
  "action_id": 2,
  "action": "Denied",
  "disposition_id": 2,
  "disposition": "Blocked",
  "status_detail": "no matching policy",
  "message": "CONNECT denied httpbin.org:443",
  "dst_endpoint": {
    "domain": "httpbin.org",
    "port": 443
  },
  "actor": {
    "process": {
      "name": "/usr/bin/curl",
      "pid": 63
    }
  },
  "firewall_rule": {
    "name": "-",
    "type": "opa"
  }
}

OCSF Event Classes in JSON

The class_uid field identifies the event type:

SIEM Schema Version Compatibility

OpenShell emits OCSF v1.8.0 events internally, but many SIEMs only support older schema versions. The ocsf_schema_version setting tells the JSONL layer to downgrade events before writing, stripping fields and profiles that don’t exist in the target version.

Set the target version globally:

openshell settings set --global --key ocsf_schema_version --value "1.1"

Or per-sandbox:

openshell settings set my-sandbox --key ocsf_schema_version --value "1.3"

The setting takes effect on the next poll cycle, by default every 10 seconds. No sandbox restart is required.

Supported target versions are 1.1 and 1.3. When set, the JSONL layer applies the following transformations:

• Strips fields added after the target version: ai_model, container, observation_point_id
• Removes unknown profile names from metadata.profiles: ai_operation, container
• Rewrites metadata.version to match the target version

The shorthand log output is unaffected. The internal event model stays at v1.8.0; only the serialized JSONL is transformed.

When unset or empty, no downgrade is applied and events are written at the current schema version.

Downgraded events include a downgraded_from marker in the unmapped object so auditors can distinguish “no model was involved” from “model attribution was stripped”:

{
  "unmapped": {
    "downgraded_from": "1.8.0"
  }
}

The core OCSF event structure (class UIDs, activity IDs, network and HTTP fields) is identical across v1.1 through v1.8. The stripped fields are all profile-gated additions.

Integration with External Tools

The JSONL file can be shipped to any tool that accepts OCSF-formatted data:

Example with jq to extract all denied connections:

cat /var/log/openshell-ocsf.2026-04-01.log | \
  jq -c 'select(.action == "Denied")'

Relationship to Shorthand Logs

Sandbox events identify the sandbox environment with device.type_id: 99 (Other) and device.type: "Sandbox". The operating system is reported separately in device.os.name; the device type does not classify the underlying host or compute backend.

The shorthand format in openshell.YYYY-MM-DD.log and the JSON format in openshell-ocsf.YYYY-MM-DD.log are derived from the same OCSF events. The shorthand is a human-readable projection; the JSON is the full structured record when no schema downgrade is configured. When ocsf_schema_version is set, the JSON export is a lossy projection of the internal event model. Both formats are generated at the same time from the same event data.

The shorthand log is always active. The JSON export is opt-in through ocsf_json_enabled.

Next Steps

• Learn how to read the shorthand format for real-time monitoring.
• Refer to the OCSF specification for the full schema reference.