OpenShell/docs/observability/ocsf-json-export.mdx

---
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
title: "OCSF JSON Export"
sidebar-title: "OCSF JSON Export"
description: "How to enable full OCSF JSON logging for SIEM integration, compliance, and structured analysis. Includes schema version downgrade for AWS Security Lake, Splunk, and CrowdStrike compatibility."
keywords: "Generative AI, Cybersecurity, OCSF, JSON, SIEM, Compliance, Observability"
---

The [shorthand log format](/observability/logging) 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:

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

Per-sandbox:

```shell
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:

```shell
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:

```toml
[openshell.drivers.mxc]
etw_audit = true
```

```powershell
$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:

```json
{
  "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:

```json
{
  "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"
  }
}
```

<Note>
The JSON examples above are formatted for readability. The actual JSONL file contains one JSON object per line with no whitespace formatting.
</Note>

## OCSF Event Classes in JSON

The `class_uid` field identifies the event type:

| `class_uid` | Class | Shorthand prefix |
|---|---|---|
| 4001 | Network Activity | `NET:` |
| 4002 | HTTP Activity | `HTTP:` |
| 4007 | SSH Activity | `SSH:` |
| 1007 | Process Activity | `PROC:` |
| 2004 | Detection Finding | `FINDING:` |
| 5019 | Device Config State Change | `CONFIG:` |
| 6002 | Application Lifecycle | `LIFECYCLE:` |

## 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:

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

Or per-sandbox:

```shell
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.

| SIEM | Required OCSF Version | `ocsf_schema_version` Value |
|---|---|---|
| AWS Security Lake | v1.1.0 | `1.1` |
| Splunk CIM Add-On | v1.1-v1.3 | `1.1` or `1.3` |
| CrowdStrike FDR | v1.5.0 | Not yet supported |
| Datadog Cloud SIEM | v1.5.0 (selectable) | Not yet supported |

<Warning>
Downgrading is lossy. The `ai_model` field and `ai_operation` profile are stripped for v1.1 and v1.3 targets, so AI model attribution is not present in downgraded events. If your audit workflow requires knowing which model handled a request, use the full schema version (leave `ocsf_schema_version` unset). OpenShell supports OCSF v1.8.0 natively; upgrade your SIEM's OCSF schema if you need AI attribution alongside backward-compatible ingestion.
</Warning>

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

```json
{
  "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:

| Tool | Integration Path |
|---|---|
| Splunk | Use the [Splunk OCSF Add-on](https://splunkbase.splunk.com/app/6943) to ingest OCSF JSONL files. Set `ocsf_schema_version` to `1.3` for CIM Add-On compatibility. |
| Amazon Security Lake | OCSF is the native schema for Security Lake. Set `ocsf_schema_version` to `1.1` for v1.1.0 compatibility. |
| CrowdStrike FDR | Ship JSONL files to Falcon Data Replicator. v1.5 downgrade target is not yet supported. |
| Elastic | Use Filebeat to ship JSONL files with the OCSF field mappings. |
| Custom pipelines | Parse the JSONL file with `jq`, Python, or any JSON-capable tool. |

Example with `jq` to extract all denied connections:

```shell
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](/observability/logging) for real-time monitoring.
- Refer to the [OCSF specification](https://schema.ocsf.io/) for the full schema reference.