Skip to content

Commit 5f5f094

Browse files
committed
feat(ocsf): configurable schema version for SIEM backward compatibility
Add a gateway-configurable OCSF schema version target that downgrades JSONL output for SIEMs that only support older schema versions. AWS Security Lake requires v1.1.0, Splunk CIM Add-On targets v1.1-v1.3. The downgrade filter strips profile-gated fields (ai_model, container, observation_point_id), removes unknown profiles from metadata.profiles, rewrites metadata.version, and adds an unmapped.downgraded_from breadcrumb so auditors can distinguish "no model involved" from "model attribution stripped." Supported target versions (1.1, 1.3) are enforced by an allow-list in the settings registry. Invalid values are rejected with a clear error. The setting flows to sandboxes via the settings bundle and takes effect on the next poll cycle. The shorthand log output is unaffected. Closes NVIDIA#2662 Signed-off-by: Adel Zaalouk <[email protected]> Signed-off-by: Adel Zaalouk <[email protected]>
1 parent 74960eb commit 5f5f094

9 files changed

Lines changed: 422 additions & 8 deletions

File tree

‎.agents/skills/openshell-cli/SKILL.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -764,6 +764,9 @@ openshell settings delete work-session --key ocsf_json_enabled
764764

765765
openshell settings get --global --json
766766
openshell settings set --global --key ocsf_json_enabled --value true
767+
768+
# OCSF schema version downgrade for SIEM compatibility (allowed: "1.1", "1.3")
769+
openshell settings set --global --key ocsf_schema_version --value "1.1"
767770
```
768771
769772
Global mutations prompt for confirmation. Use `--yes` only in reviewed automation.

‎crates/openshell-core/src/settings.rs‎

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,14 @@ pub const PROPOSAL_APPROVAL_MODE_KEY: &str = "proposal_approval_mode";
106106
/// fail-closes on unknown persisted values for defense in depth.
107107
pub const PROPOSAL_APPROVAL_MODE_VALUES: &[&str] = &["manual", "auto"];
108108

109+
/// Allowed values for `ocsf_schema_version`.
110+
///
111+
/// Only versions with actual downgrade transforms in
112+
/// `openshell_ocsf::format::downgrade` are accepted. Empty string disables
113+
/// downgrade (equivalent to unsetting the key). Malformed or unsupported
114+
/// versions (e.g. `"banana"`, `"1.6"`) are rejected at configure time.
115+
pub const OCSF_SCHEMA_VERSION_VALUES: &[&str] = &["", "1.1", "1.3"];
116+
109117
pub const REGISTERED_SETTINGS: &[RegisteredSetting] = &[
110118
// When true the sandbox writes OCSF v1.8.0 JSONL records to
111119
// `/var/log/openshell-ocsf*.log` (daily rotation, 3 files) in addition
@@ -115,6 +123,14 @@ pub const REGISTERED_SETTINGS: &[RegisteredSetting] = &[
115123
kind: SettingValueKind::Bool,
116124
allowed_string_values: None,
117125
},
126+
// Target OCSF schema version for JSONL downgrade. When set (e.g. "1.1"
127+
// or "1.3"), the JSONL layer strips fields and profiles that don't exist
128+
// in the target version. Empty or unset means no downgrade.
129+
RegisteredSetting {
130+
key: "ocsf_schema_version",
131+
kind: SettingValueKind::String,
132+
allowed_string_values: Some(OCSF_SCHEMA_VERSION_VALUES),
133+
},
118134
// Sandbox-level opt-in for the agent-driven policy proposal surface.
119135
// See AGENT_POLICY_PROPOSALS_ENABLED_KEY for details. Defaults to false.
120136
RegisteredSetting {
@@ -160,8 +176,9 @@ pub fn parse_bool_like(raw: &str) -> Option<bool> {
160176
#[cfg(test)]
161177
mod tests {
162178
use super::{
163-
PROPOSAL_APPROVAL_MODE_KEY, PROPOSAL_APPROVAL_MODE_VALUES, REGISTERED_SETTINGS,
164-
RegisteredSetting, SettingValueKind, parse_bool_like, registered_keys_csv, setting_for_key,
179+
OCSF_SCHEMA_VERSION_VALUES, PROPOSAL_APPROVAL_MODE_KEY, PROPOSAL_APPROVAL_MODE_VALUES,
180+
REGISTERED_SETTINGS, RegisteredSetting, SettingValueKind, parse_bool_like,
181+
registered_keys_csv, setting_for_key,
165182
};
166183

167184
#[test]
@@ -226,6 +243,36 @@ mod tests {
226243
}
227244
}
228245

246+
// ---- ocsf_schema_version validation ----
247+
248+
#[test]
249+
fn ocsf_schema_version_accepts_supported_versions() {
250+
let setting = setting_for_key("ocsf_schema_version")
251+
.expect("ocsf_schema_version should be registered");
252+
assert_eq!(setting.kind, SettingValueKind::String);
253+
assert_eq!(
254+
setting.allowed_string_values,
255+
Some(OCSF_SCHEMA_VERSION_VALUES)
256+
);
257+
assert!(setting.validate_string_value("").is_ok());
258+
assert!(setting.validate_string_value("1.1").is_ok());
259+
assert!(setting.validate_string_value("1.3").is_ok());
260+
}
261+
262+
#[test]
263+
fn ocsf_schema_version_rejects_malformed_and_unsupported() {
264+
let setting = setting_for_key("ocsf_schema_version")
265+
.expect("ocsf_schema_version should be registered");
266+
for bad in [
267+
"banana", "1.6", "1.5", "1.7", "1.7.0", "1.1.0", "2.0", " 1.1", "1.1 ", "v1.1",
268+
] {
269+
let err = setting
270+
.validate_string_value(bad)
271+
.expect_err(&format!("expected '{bad}' to be rejected"));
272+
assert_eq!(err, OCSF_SCHEMA_VERSION_VALUES);
273+
}
274+
}
275+
229276
// ---- parse_bool_like ----
230277

231278
#[test]
Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
//! OCSF schema version downgrade filter.
5+
//!
6+
//! Transforms serialized OCSF JSON events to conform to older schema versions
7+
//! by stripping fields and profiles that don't exist in the target version.
8+
9+
use serde_json::Value;
10+
11+
/// Fields to strip when downgrading to v1.3.0 or earlier.
12+
const STRIP_FOR_V1_3: &[&str] = &["ai_model", "container", "observation_point_id"];
13+
14+
/// Profile names to remove from `metadata.profiles` when downgrading to v1.3.0 or earlier.
15+
const STRIP_PROFILES_V1_3: &[&str] = &["ai_operation", "container"];
16+
17+
/// Downgrade a serialized OCSF event to the target schema version.
18+
///
19+
/// Modifies the JSON in place: strips fields that don't exist in the target
20+
/// version, removes unknown profile names from `metadata.profiles`, and
21+
/// rewrites `metadata.version` to match.
22+
///
23+
/// Returns `true` if the event was modified, `false` if no changes were needed
24+
/// (target is current version or newer).
25+
pub fn downgrade_event(event: &mut Value, target_version: &str) -> bool {
26+
let target = parse_version(target_version);
27+
let v1_3 = (1, 3, 0);
28+
29+
if target >= parse_version(crate::OCSF_VERSION) {
30+
return false;
31+
}
32+
33+
let Some(obj) = event.as_object_mut() else {
34+
return false;
35+
};
36+
37+
let mut modified = false;
38+
39+
if target <= v1_3 {
40+
for field in STRIP_FOR_V1_3 {
41+
if obj.remove(*field).is_some() {
42+
modified = true;
43+
}
44+
}
45+
46+
if let Some(profiles) = obj
47+
.get_mut("metadata")
48+
.and_then(Value::as_object_mut)
49+
.and_then(|m| m.get_mut("profiles"))
50+
.and_then(Value::as_array_mut)
51+
{
52+
let before = profiles.len();
53+
profiles.retain(|p| !p.as_str().is_some_and(|s| STRIP_PROFILES_V1_3.contains(&s)));
54+
if profiles.len() != before {
55+
modified = true;
56+
}
57+
}
58+
}
59+
60+
if modified && let Some(metadata) = obj.get_mut("metadata").and_then(Value::as_object_mut) {
61+
let original_version = metadata
62+
.get("version")
63+
.and_then(Value::as_str)
64+
.unwrap_or(crate::OCSF_VERSION)
65+
.to_string();
66+
metadata.insert(
67+
"version".to_string(),
68+
Value::String(target_version.to_string()),
69+
);
70+
71+
let unmapped = obj
72+
.entry("unmapped")
73+
.or_insert_with(|| Value::Object(serde_json::Map::new()));
74+
if let Some(u) = unmapped.as_object_mut() {
75+
u.insert(
76+
"downgraded_from".to_string(),
77+
Value::String(original_version),
78+
);
79+
}
80+
}
81+
82+
modified
83+
}
84+
85+
fn parse_version(v: &str) -> (u32, u32, u32) {
86+
let parts: Vec<u32> = v.split('.').filter_map(|s| s.parse().ok()).collect();
87+
(
88+
parts.first().copied().unwrap_or(0),
89+
parts.get(1).copied().unwrap_or(0),
90+
parts.get(2).copied().unwrap_or(0),
91+
)
92+
}
93+
94+
#[cfg(test)]
95+
mod tests {
96+
use super::*;
97+
98+
fn test_event() -> Value {
99+
serde_json::json!({
100+
"class_uid": 4002,
101+
"class_name": "HTTP Activity",
102+
"time": 1_234_567_890,
103+
"severity_id": 1,
104+
"metadata": {
105+
"version": "1.7.0",
106+
"profiles": ["security_control", "network_proxy", "container", "host"]
107+
},
108+
"device": {"hostname": "sandbox-1"},
109+
"container": {"name": "test-sandbox"},
110+
"observation_point_id": 2,
111+
"unmapped": {"key": "value"}
112+
})
113+
}
114+
115+
#[test]
116+
fn test_downgrade_to_v1_3_strips_fields() {
117+
let mut event = test_event();
118+
let modified = downgrade_event(&mut event, "1.3.0");
119+
120+
assert!(modified);
121+
assert!(event.get("container").is_none());
122+
assert!(event.get("observation_point_id").is_none());
123+
assert!(event.get("device").is_some());
124+
assert!(event.get("unmapped").is_some());
125+
}
126+
127+
#[test]
128+
fn test_downgrade_to_v1_1_strips_fields() {
129+
let mut event = test_event();
130+
let modified = downgrade_event(&mut event, "1.1.0");
131+
132+
assert!(modified);
133+
assert!(event.get("container").is_none());
134+
assert!(event.get("observation_point_id").is_none());
135+
}
136+
137+
#[test]
138+
fn test_downgrade_strips_profiles() {
139+
let mut event = test_event();
140+
downgrade_event(&mut event, "1.3.0");
141+
142+
let profiles = event["metadata"]["profiles"].as_array().unwrap();
143+
assert!(!profiles.iter().any(|p| p == "container"));
144+
assert!(profiles.iter().any(|p| p == "security_control"));
145+
assert!(profiles.iter().any(|p| p == "host"));
146+
}
147+
148+
#[test]
149+
fn test_downgrade_rewrites_version() {
150+
let mut event = test_event();
151+
downgrade_event(&mut event, "1.1.0");
152+
153+
assert_eq!(event["metadata"]["version"], "1.1.0");
154+
assert_eq!(event["unmapped"]["downgraded_from"], "1.7.0");
155+
}
156+
157+
#[test]
158+
fn test_no_downgrade_for_current_version() {
159+
let mut event = test_event();
160+
let modified = downgrade_event(&mut event, "1.7.0");
161+
162+
assert!(!modified);
163+
assert_eq!(event["metadata"]["version"], "1.7.0");
164+
}
165+
166+
#[test]
167+
fn test_no_downgrade_for_newer_version() {
168+
let mut event = test_event();
169+
let modified = downgrade_event(&mut event, "1.9.0");
170+
171+
assert!(!modified);
172+
}
173+
174+
#[test]
175+
fn test_downgrade_strips_ai_model_when_present() {
176+
let mut event = serde_json::json!({
177+
"class_uid": 6003,
178+
"metadata": {
179+
"version": "1.8.0",
180+
"profiles": ["container", "host", "ai_operation"]
181+
},
182+
"ai_model": {"name": "claude-3-haiku", "ai_provider": "anthropic"},
183+
"unmapped": {"latency_ms": 701}
184+
});
185+
let modified = downgrade_event(&mut event, "1.3.0");
186+
187+
assert!(modified);
188+
assert!(event.get("ai_model").is_none());
189+
assert!(
190+
!event["metadata"]["profiles"]
191+
.as_array()
192+
.unwrap()
193+
.iter()
194+
.any(|p| p == "ai_operation")
195+
);
196+
assert_eq!(event["metadata"]["version"], "1.3.0");
197+
assert_eq!(event["unmapped"]["downgraded_from"], "1.8.0");
198+
assert_eq!(event["unmapped"]["latency_ms"], 701);
199+
}
200+
201+
#[test]
202+
fn test_downgrade_creates_unmapped_when_absent() {
203+
let mut event = serde_json::json!({
204+
"class_uid": 4001,
205+
"metadata": {
206+
"version": "1.7.0",
207+
"profiles": ["container"]
208+
},
209+
"container": {"name": "sandbox-1"}
210+
});
211+
let modified = downgrade_event(&mut event, "1.1.0");
212+
213+
assert!(modified);
214+
assert_eq!(event["unmapped"]["downgraded_from"], "1.7.0");
215+
}
216+
217+
#[test]
218+
fn test_no_downgrade_omits_breadcrumb() {
219+
let mut event = test_event();
220+
downgrade_event(&mut event, "1.7.0");
221+
222+
assert!(
223+
event
224+
.get("unmapped")
225+
.and_then(Value::as_object)
226+
.and_then(|u| u.get("downgraded_from"))
227+
.is_none()
228+
);
229+
}
230+
}

‎crates/openshell-ocsf/src/format/mod.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33

44
//! OCSF event formatters: shorthand (human-readable) and JSONL.
55
6+
pub mod downgrade;
67
pub mod jsonl;
78
pub mod shorthand;

0 commit comments

Comments
 (0)