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 (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 (default: 10 seconds). No sandbox restart is required.

To disable:

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

Output Location#

When enabled, OCSF JSON records are written to /var/log/openshell-ocsf.YYYY-MM-DD.log inside the sandbox. The file rotates daily and retains the 3 most recent files, matching the main log file rotation.

JSON Record Structure#

Each line is a complete OCSF v1.7.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.7.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",
  "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.

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:

Integration with External Tools#

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

  • Splunk: Use the Splunk OCSF Add-on to ingest OCSF JSONL files.

  • Amazon Security Lake: OCSF is the native schema for Security Lake.

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

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

Relationship to Shorthand Logs#

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 complete record. Both are generated at the same time from the same event data.

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

Next Steps#