Skip to content

Commit 1c3d1fa

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 64a858d commit 1c3d1fa

9 files changed

Lines changed: 422 additions & 8 deletions

File tree

‎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;

‎crates/openshell-ocsf/src/tracing_layers/jsonl_layer.rs‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ use tracing::Subscriber;
1212
use tracing_subscriber::Layer;
1313
use tracing_subscriber::layer::Context;
1414

15+
use crate::format::downgrade::downgrade_event;
1516
use crate::tracing_layers::event_bridge::{OCSF_TARGET, clone_current_event};
1617

1718
/// A tracing `Layer` that intercepts OCSF events and writes JSONL output.
@@ -23,9 +24,15 @@ use crate::tracing_layers::event_bridge::{OCSF_TARGET, clone_current_event};
2324
/// `false`, the layer short-circuits without writing. This allows the sandbox
2425
/// to hot-toggle OCSF JSONL output at runtime via the `ocsf_json_enabled`
2526
/// setting without rebuilding the subscriber.
27+
///
28+
/// An optional target schema version can be set via
29+
/// [`with_target_version`](Self::with_target_version). When set, events are
30+
/// downgraded to the target version before writing (stripping fields and
31+
/// profiles that don't exist in older schema versions).
2632
pub struct OcsfJsonlLayer<W: Write + Send + 'static> {
2733
writer: Mutex<W>,
2834
enabled: Option<Arc<AtomicBool>>,
35+
target_version: Option<Arc<Mutex<String>>>,
2936
}
3037

3138
impl<W: Write + Send + 'static> OcsfJsonlLayer<W> {
@@ -35,6 +42,7 @@ impl<W: Write + Send + 'static> OcsfJsonlLayer<W> {
3542
Self {
3643
writer: Mutex::new(writer),
3744
enabled: None,
45+
target_version: None,
3846
}
3947
}
4048

@@ -47,6 +55,16 @@ impl<W: Write + Send + 'static> OcsfJsonlLayer<W> {
4755
self.enabled = Some(flag);
4856
self
4957
}
58+
59+
/// Attach a shared target schema version for downgrade filtering.
60+
///
61+
/// When set, events are downgraded to the target version before writing.
62+
/// The version can be changed at runtime via the shared mutex.
63+
#[must_use]
64+
pub fn with_target_version(mut self, version: Arc<Mutex<String>>) -> Self {
65+
self.target_version = Some(version);
66+
self
67+
}
5068
}
5169

5270
impl<S, W> Layer<S> for OcsfJsonlLayer<W>
@@ -67,9 +85,29 @@ where
6785
}
6886

6987
if let Some(ocsf_event) = clone_current_event()
70-
&& let Ok(line) = ocsf_event.to_json_line()
7188
&& let Ok(mut w) = self.writer.lock()
7289
{
90+
let line = if let Some(ref target) = self.target_version
91+
&& let Ok(version) = target.lock()
92+
&& !version.is_empty()
93+
{
94+
let Ok(mut json) = serde_json::to_value(&ocsf_event) else {
95+
return;
96+
};
97+
downgrade_event(&mut json, &version);
98+
match serde_json::to_string(&json) {
99+
Ok(mut s) => {
100+
s.push('\n');
101+
s
102+
}
103+
Err(_) => return,
104+
}
105+
} else {
106+
match ocsf_event.to_json_line() {
107+
Ok(l) => l,
108+
Err(_) => return,
109+
}
110+
};
73111
let _ = w.write_all(line.as_bytes());
74112
}
75113
}

0 commit comments

Comments
 (0)