Skip to content

Commit 9c3db52

Browse files
committed
feat(ocsf)!: emit OCSF 1.8.0 only and deprecate the schema version knobs
Remove the OCSF schema downgrade. OpenShell now writes native OCSF 1.8.0 records to supervisor JSONL and stderr, gateway JSONL, and OTLP log export regardless of configuration. The downgrade did not produce valid records: events it labelled 1.1 or 1.3 failed validation against those versions, because OpenShell's emitters rely on requirements that only 1.8 relaxed (#4284). It was also not shown to be required by any SIEM: of ten sinks and pipelines tested with real OpenShell records, none rejected native 1.8.0 or gated on metadata.version. The version knobs stay accepted so existing configuration still loads, but they are deprecated and ignored: - The ocsf_schema_version sandbox setting accepts any value; the supervisor reports a newly set value as a Device Config State Change event. - schema_version under [openshell.gateway.ocsf_log] and [openshell.gateway.otlp.ocsf], and the server.ocsfLog.schemaVersion Helm value, accept any value; the gateway logs a warning at startup. - The compute drivers' OPENSHELL_OTLP_OCSF_SCHEMA_VERSION flag and environment variable are hidden and ignored, with a warning, and are no longer forwarded to sandboxes. BREAKING CHANGE: Deployments that set an OCSF schema version now receive native OCSF 1.8.0 records instead of records labelled 1.1 or 1.3. Closes #4284 Signed-off-by: Kris Hicks <[email protected]>
1 parent 4d4c15c commit 9c3db52

39 files changed

Lines changed: 263 additions & 770 deletions

File tree

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

Lines changed: 3 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,6 @@ pub const OTLP_OCSF_ENDPOINT: &str = "OPENSHELL_OTLP_OCSF_ENDPOINT";
3838
/// keeps the relay inactive and leaves the workload environment unchanged.
3939
pub const OTLP_AGENT_ENDPOINT: &str = "OPENSHELL_OTLP_AGENT_ENDPOINT";
4040

41-
/// OCSF schema version that supervisors downgrade exported events to.
42-
pub const OTLP_OCSF_SCHEMA_VERSION: &str = "OPENSHELL_OTLP_OCSF_SCHEMA_VERSION";
43-
4441
/// Name of the gateway that launched the sandbox, reported as
4542
/// `openshell.gateway.name` on supervisor telemetry.
4643
pub const GATEWAY_NAME: &str = "OPENSHELL_GATEWAY_NAME";
@@ -49,19 +46,12 @@ pub const GATEWAY_NAME: &str = "OPENSHELL_GATEWAY_NAME";
4946
#[derive(Clone, Debug, Eq, PartialEq)]
5047
pub struct OcsfOtlpExport {
5148
pub endpoint: String,
52-
pub schema_version: Option<String>,
5349
}
5450

5551
impl OcsfOtlpExport {
5652
/// The supervisor environment variables for this export.
5753
pub fn environment(&self) -> Vec<(&'static str, String)> {
58-
std::iter::once((OTLP_OCSF_ENDPOINT, self.endpoint.clone()))
59-
.chain(
60-
self.schema_version
61-
.clone()
62-
.map(|version| (OTLP_OCSF_SCHEMA_VERSION, version)),
63-
)
64-
.collect()
54+
vec![(OTLP_OCSF_ENDPOINT, self.endpoint.clone())]
6555
}
6656
}
6757

@@ -392,23 +382,14 @@ mod tests {
392382
use super::*;
393383

394384
#[test]
395-
fn ocsf_export_environment_carries_the_schema_version_only_when_set() {
396-
let mut export = OcsfOtlpExport {
385+
fn ocsf_export_environment_carries_the_endpoint() {
386+
let export = OcsfOtlpExport {
397387
endpoint: "http://siem:4317".into(),
398-
schema_version: None,
399388
};
400389
assert_eq!(
401390
export.environment(),
402391
[(OTLP_OCSF_ENDPOINT, "http://siem:4317".to_string())]
403392
);
404-
export.schema_version = Some("1.3".into());
405-
assert_eq!(
406-
export.environment(),
407-
[
408-
(OTLP_OCSF_ENDPOINT, "http://siem:4317".to_string()),
409-
(OTLP_OCSF_SCHEMA_VERSION, "1.3".to_string()),
410-
]
411-
);
412393
}
413394

414395
#[test]

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

Lines changed: 10 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -106,14 +106,6 @@ 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-
117109
pub const REGISTERED_SETTINGS: &[RegisteredSetting] = &[
118110
// When true the supervisor emits OCSF-JSON records to stderr and writes
119111
// JSONL to `/var/log/openshell-ocsf*.jsonl` when file logging is available.
@@ -123,13 +115,12 @@ pub const REGISTERED_SETTINGS: &[RegisteredSetting] = &[
123115
kind: SettingValueKind::Bool,
124116
allowed_string_values: None,
125117
},
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.
118+
// Deprecated and ignored: OpenShell emits OCSF 1.8.0 only. Still
119+
// registered so existing values load; the supervisor reports a set value.
129120
RegisteredSetting {
130121
key: "ocsf_schema_version",
131122
kind: SettingValueKind::String,
132-
allowed_string_values: Some(OCSF_SCHEMA_VERSION_VALUES),
123+
allowed_string_values: None,
133124
},
134125
// Sandbox-level opt-in for the agent-driven policy proposal surface.
135126
// See AGENT_POLICY_PROPOSALS_ENABLED_KEY for details. Defaults to false.
@@ -176,9 +167,8 @@ pub fn parse_bool_like(raw: &str) -> Option<bool> {
176167
#[cfg(test)]
177168
mod tests {
178169
use super::{
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,
170+
PROPOSAL_APPROVAL_MODE_KEY, PROPOSAL_APPROVAL_MODE_VALUES, REGISTERED_SETTINGS,
171+
RegisteredSetting, SettingValueKind, parse_bool_like, registered_keys_csv, setting_for_key,
182172
};
183173

184174
#[test]
@@ -243,33 +233,15 @@ mod tests {
243233
}
244234
}
245235

246-
// ---- ocsf_schema_version validation ----
236+
// ---- ocsf_schema_version (deprecated) ----
247237

248238
#[test]
249-
fn ocsf_schema_version_accepts_supported_versions() {
239+
fn deprecated_ocsf_schema_version_accepts_any_value() {
250240
let setting = setting_for_key("ocsf_schema_version")
251-
.expect("ocsf_schema_version should be registered");
241+
.expect("ocsf_schema_version should stay registered while deprecated");
252242
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);
243+
for value in ["", "1.3", "anything"] {
244+
assert!(setting.validate_string_value(value).is_ok(), "{value}");
273245
}
274246
}
275247

‎crates/openshell-driver-docker/src/main.rs‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -51,12 +51,8 @@ struct Args {
5151
#[arg(long, env = "OPENSHELL_OTLP_OCSF_ENDPOINT")]
5252
otlp_ocsf_endpoint: Option<String>,
5353

54-
/// OCSF schema version that supervisors downgrade exported events to.
55-
#[arg(
56-
long,
57-
env = "OPENSHELL_OTLP_OCSF_SCHEMA_VERSION",
58-
requires = "otlp_ocsf_endpoint"
59-
)]
54+
/// Deprecated and ignored: `OpenShell` emits OCSF 1.8.0 only.
55+
#[arg(long, env = "OPENSHELL_OTLP_OCSF_SCHEMA_VERSION", hide = true)]
6056
otlp_ocsf_schema_version: Option<String>,
6157

6258
/// OTLP/gRPC collector endpoint that supervisors relay workload traces
@@ -80,6 +76,11 @@ async fn main() -> Result<()> {
8076
log_level: &args.log_level,
8177
},
8278
);
79+
if args.otlp_ocsf_schema_version.is_some() {
80+
tracing::warn!(
81+
"OPENSHELL_OTLP_OCSF_SCHEMA_VERSION is deprecated and ignored; OpenShell emits OCSF 1.8.0"
82+
);
83+
}
8384

8485
let config_source = std::fs::read_to_string(&args.config).into_diagnostic()?;
8586
let mut docker_config: DockerComputeConfig =
@@ -97,12 +98,10 @@ async fn main() -> Result<()> {
9798
docker_config.supervisor_otlp_endpoint = args.otlp_endpoint.clone();
9899
docker_config.supervisor_otlp_agent_endpoint = args.otlp_agent_endpoint.clone();
99100
docker_config.supervisor_gateway_name = args.gateway_name.clone();
100-
docker_config.supervisor_ocsf_export = args.otlp_ocsf_endpoint.clone().map(|endpoint| {
101-
openshell_core::sandbox_env::OcsfOtlpExport {
102-
endpoint,
103-
schema_version: args.otlp_ocsf_schema_version.clone(),
104-
}
105-
});
101+
docker_config.supervisor_ocsf_export = args
102+
.otlp_ocsf_endpoint
103+
.clone()
104+
.map(|endpoint| openshell_core::sandbox_env::OcsfOtlpExport { endpoint });
106105
let driver = DockerComputeDriver::new(args.gateway_bind, &args.log_level, &docker_config, None)
107106
.await
108107
.into_diagnostic()?;

‎crates/openshell-driver-docker/src/tests.rs‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1517,8 +1517,7 @@ fn docker_child_environment_strips_supervisor_control_keys() {
15171517
#[test]
15181518
fn supervisor_otlp_environment_carries_only_configured_signals() {
15191519
use openshell_core::sandbox_env::{
1520-
GATEWAY_NAME, OTLP_AGENT_ENDPOINT, OTLP_ENDPOINT, OTLP_OCSF_ENDPOINT,
1521-
OTLP_OCSF_SCHEMA_VERSION, OcsfOtlpExport,
1520+
GATEWAY_NAME, OTLP_AGENT_ENDPOINT, OTLP_ENDPOINT, OTLP_OCSF_ENDPOINT, OcsfOtlpExport,
15221521
};
15231522

15241523
let mut config = runtime_config();
@@ -1533,14 +1532,10 @@ fn supervisor_otlp_environment_carries_only_configured_signals() {
15331532
config.supervisor_otlp_endpoint = None;
15341533
config.supervisor_ocsf_export = Some(OcsfOtlpExport {
15351534
endpoint: "http://siem:4317".to_string(),
1536-
schema_version: Some("1.3".to_string()),
15371535
});
15381536
assert_eq!(
15391537
supervisor_otlp_environment(&config),
1540-
[
1541-
format!("{OTLP_OCSF_ENDPOINT}=http://siem:4317"),
1542-
format!("{OTLP_OCSF_SCHEMA_VERSION}=1.3"),
1543-
]
1538+
[format!("{OTLP_OCSF_ENDPOINT}=http://siem:4317")]
15441539
);
15451540

15461541
config.supervisor_ocsf_export = None;

‎crates/openshell-driver-kubernetes/src/driver.rs‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8978,9 +8978,7 @@ mod tests {
89788978

89798979
#[tokio::test]
89808980
async fn supervisor_otlp_environment_carries_only_configured_signals() {
8981-
use openshell_core::sandbox_env::{
8982-
OTLP_ENDPOINT, OTLP_OCSF_ENDPOINT, OTLP_OCSF_SCHEMA_VERSION, OcsfOtlpExport,
8983-
};
8981+
use openshell_core::sandbox_env::{OTLP_ENDPOINT, OTLP_OCSF_ENDPOINT, OcsfOtlpExport};
89848982

89858983
let names = |config: KubernetesComputeConfig| {
89868984
KubernetesComputeDriver::new_for_test(config)
@@ -9002,16 +9000,12 @@ mod tests {
90029000
let driver = KubernetesComputeDriver::new_for_test(KubernetesComputeConfig {
90039001
supervisor_ocsf_export: Some(OcsfOtlpExport {
90049002
endpoint: "http://siem:4317".into(),
9005-
schema_version: Some("1.1".into()),
90069003
}),
90079004
..Default::default()
90089005
});
90099006
assert_eq!(
90109007
driver.supervisor_otlp_environment(),
9011-
[
9012-
(OTLP_OCSF_ENDPOINT, "http://siem:4317".to_string()),
9013-
(OTLP_OCSF_SCHEMA_VERSION, "1.1".to_string()),
9014-
]
9008+
[(OTLP_OCSF_ENDPOINT, "http://siem:4317".to_string())]
90159009
);
90169010

90179011
let driver = KubernetesComputeDriver::new_for_test(KubernetesComputeConfig {

‎crates/openshell-driver-kubernetes/src/main.rs‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -49,12 +49,8 @@ struct Args {
4949
#[arg(long, env = "OPENSHELL_OTLP_OCSF_ENDPOINT")]
5050
otlp_ocsf_endpoint: Option<String>,
5151

52-
/// OCSF schema version that supervisors downgrade exported events to.
53-
#[arg(
54-
long,
55-
env = "OPENSHELL_OTLP_OCSF_SCHEMA_VERSION",
56-
requires = "otlp_ocsf_endpoint"
57-
)]
52+
/// Deprecated and ignored: `OpenShell` emits OCSF 1.8.0 only.
53+
#[arg(long, env = "OPENSHELL_OTLP_OCSF_SCHEMA_VERSION", hide = true)]
5854
otlp_ocsf_schema_version: Option<String>,
5955

6056
/// OTLP/gRPC collector endpoint that supervisors relay workload traces
@@ -248,6 +244,11 @@ async fn main() -> Result<()> {
248244
log_level: &args.log_level,
249245
},
250246
);
247+
if args.otlp_ocsf_schema_version.is_some() {
248+
tracing::warn!(
249+
"OPENSHELL_OTLP_OCSF_SCHEMA_VERSION is deprecated and ignored; OpenShell emits OCSF 1.8.0"
250+
);
251+
}
251252

252253
let managed_ssh_gateway_pod_selector = args
253254
.managed_ssh_gateway_pod_selector
@@ -305,12 +306,10 @@ async fn main() -> Result<()> {
305306
supervisor_otlp_endpoint: args.otlp_endpoint.clone(),
306307
supervisor_otlp_agent_endpoint: args.otlp_agent_endpoint.clone(),
307308
supervisor_gateway_name: args.gateway_name.clone(),
308-
supervisor_ocsf_export: args.otlp_ocsf_endpoint.clone().map(|endpoint| {
309-
openshell_core::sandbox_env::OcsfOtlpExport {
310-
endpoint,
311-
schema_version: args.otlp_ocsf_schema_version.clone(),
312-
}
313-
}),
309+
supervisor_ocsf_export: args
310+
.otlp_ocsf_endpoint
311+
.clone()
312+
.map(|endpoint| openshell_core::sandbox_env::OcsfOtlpExport { endpoint }),
314313
ssh_socket_path: args.sandbox_ssh_socket_path,
315314
client_tls_secret_name: args.client_tls_secret_name.unwrap_or_default(),
316315
host_gateway_ip: args.host_gateway_ip.unwrap_or_default(),

‎crates/openshell-driver-podman/src/container.rs‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2928,7 +2928,6 @@ mod tests {
29282928
let config = PodmanComputeConfig {
29292929
supervisor_ocsf_export: Some(openshell_core::sandbox_env::OcsfOtlpExport {
29302930
endpoint: "http://siem:4317".to_string(),
2931-
schema_version: Some("1.1".to_string()),
29322931
}),
29332932
..test_config()
29342933
};
@@ -2937,10 +2936,6 @@ mod tests {
29372936
spec["env"][openshell_core::sandbox_env::OTLP_OCSF_ENDPOINT],
29382937
"http://siem:4317"
29392938
);
2940-
assert_eq!(
2941-
spec["env"][openshell_core::sandbox_env::OTLP_OCSF_SCHEMA_VERSION],
2942-
"1.1"
2943-
);
29442939
assert!(
29452940
spec["env"]
29462941
.get(openshell_core::sandbox_env::OTLP_AGENT_ENDPOINT)

‎crates/openshell-driver-podman/src/driver.rs‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,6 @@ fn select_supervisor_ocsf_export(
109109
config.supervisor_ocsf_export.clone().map(|export| {
110110
openshell_core::sandbox_env::OcsfOtlpExport {
111111
endpoint: supervisor_collector_endpoint(&export.endpoint, environment),
112-
..export
113112
}
114113
})
115114
}
@@ -3575,7 +3574,6 @@ mod tests {
35753574
fn supervisor_ocsf_endpoint_uses_host_alias_for_loopback_on_podman_machine() {
35763575
let export = |endpoint: &str| openshell_core::sandbox_env::OcsfOtlpExport {
35773576
endpoint: endpoint.to_string(),
3578-
schema_version: Some("1.3".to_string()),
35793577
};
35803578
let config = PodmanComputeConfig {
35813579
supervisor_ocsf_export: Some(export("http://127.0.0.1:4317")),

‎crates/openshell-driver-podman/src/main.rs‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,8 @@ struct Args {
4646
#[arg(long, env = "OPENSHELL_OTLP_OCSF_ENDPOINT")]
4747
otlp_ocsf_endpoint: Option<String>,
4848

49-
/// OCSF schema version that supervisors downgrade exported events to.
50-
#[arg(
51-
long,
52-
env = "OPENSHELL_OTLP_OCSF_SCHEMA_VERSION",
53-
requires = "otlp_ocsf_endpoint"
54-
)]
49+
/// Deprecated and ignored: `OpenShell` emits OCSF 1.8.0 only.
50+
#[arg(long, env = "OPENSHELL_OTLP_OCSF_SCHEMA_VERSION", hide = true)]
5551
otlp_ocsf_schema_version: Option<String>,
5652

5753
/// OTLP/gRPC collector endpoint that supervisors relay workload traces
@@ -231,6 +227,11 @@ async fn main() -> Result<()> {
231227
log_level: &args.log_level,
232228
},
233229
);
230+
if args.otlp_ocsf_schema_version.is_some() {
231+
tracing::warn!(
232+
"OPENSHELL_OTLP_OCSF_SCHEMA_VERSION is deprecated and ignored; OpenShell emits OCSF 1.8.0"
233+
);
234+
}
234235

235236
// External drivers have no gateway-local staged artifact. Do not accept
236237
// a path or silently emulate destination-CA delivery outside the gateway.
@@ -245,12 +246,10 @@ async fn main() -> Result<()> {
245246
supervisor_otlp_endpoint: args.otlp_endpoint.clone(),
246247
supervisor_otlp_agent_endpoint: args.otlp_agent_endpoint.clone(),
247248
supervisor_gateway_name: args.gateway_name.clone(),
248-
supervisor_ocsf_export: args.otlp_ocsf_endpoint.clone().map(|endpoint| {
249-
openshell_core::sandbox_env::OcsfOtlpExport {
250-
endpoint,
251-
schema_version: args.otlp_ocsf_schema_version.clone(),
252-
}
253-
}),
249+
supervisor_ocsf_export: args
250+
.otlp_ocsf_endpoint
251+
.clone()
252+
.map(|endpoint| openshell_core::sandbox_env::OcsfOtlpExport { endpoint }),
254253
gateway_port: args.gateway_port,
255254
host_gateway_ip: args
256255
.host_gateway_ip

0 commit comments

Comments
 (0)