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

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:

1
{
2
  "class_uid": 4001,
3
  "class_name": "Network Activity",
4
  "category_uid": 4,
5
  "category_name": "Network Activity",
6
  "activity_id": 1,
7
  "activity_name": "Open",
8
  "severity_id": 1,
9
  "severity": "Informational",
10
  "status_id": 1,
11
  "status": "Success",
12
  "time": 1775014138811,
13
  "message": "CONNECT allowed api.github.com:443",
14
  "metadata": {
15
    "product": {
16
      "name": "OpenShell Sandbox Supervisor",
17
      "vendor_name": "NVIDIA",
18
      "version": "0.3.0"
19
    },
20
    "version": "1.7.0"
21
  },
22
  "action_id": 1,
23
  "action": "Allowed",
24
  "disposition_id": 1,
25
  "disposition": "Allowed",
26
  "dst_endpoint": {
27
    "domain": "api.github.com",
28
    "port": 443
29
  },
30
  "src_endpoint": {
31
    "ip": "10.42.0.31",
32
    "port": 37494
33
  },
34
  "actor": {
35
    "process": {
36
      "name": "/usr/bin/curl",
37
      "pid": 57
38
    }
39
  },
40
  "firewall_rule": {
41
    "name": "github_api",
42
    "type": "opa"
43
  }
44
}

And a denied connection:

1
{
2
  "class_uid": 4001,
3
  "class_name": "Network Activity",
4
  "activity_id": 1,
5
  "activity_name": "Open",
6
  "severity_id": 3,
7
  "severity": "Medium",
8
  "status_id": 2,
9
  "status": "Failure",
10
  "action_id": 2,
11
  "action": "Denied",
12
  "disposition_id": 2,
13
  "disposition": "Blocked",
14
  "status_detail": "no matching policy",
15
  "message": "CONNECT denied httpbin.org:443",
16
  "dst_endpoint": {
17
    "domain": "httpbin.org",
18
    "port": 443
19
  },
20
  "actor": {
21
    "process": {
22
      "name": "/usr/bin/curl",
23
      "pid": 63
24
    }
25
  },
26
  "firewall_rule": {
27
    "name": "-",
28
    "type": "opa"
29
  }
30
}

OCSF Event Classes in JSON

The class_uid field identifies the event type:

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

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