Skip to content

Commit 9105099

Browse files
committed
fix(ocsf): correlate companion deny records per decision
Group companion audit records and terminal response findings under one denial span. Keep ordinary transport errors out of enforced-denial spans, retain available HTTP policy context, and export the OCSF class as an integer. Clarify propagated context and the additional Trace-profile applicability, with regression coverage and operator documentation. Signed-off-by: Harry Turner <[email protected]>
1 parent 36cc028 commit 9105099

20 files changed

Lines changed: 1741 additions & 391 deletions

File tree

‎crates/openshell-ocsf/schemas/ocsf/README.md‎

Lines changed: 17 additions & 7 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎crates/openshell-ocsf/src/events/base_event.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ use crate::objects::{AiModel, Container, Device, Metadata};
1313
/// Every event class embeds this struct via `#[serde(flatten)]`.
1414
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
1515
pub struct BaseEventData {
16-
/// Trusted trace correlation (Trace profile).
16+
/// Optional trace correlation from the OCSF producer (Trace profile).
1717
#[serde(default, skip_serializing_if = "Option::is_none")]
1818
pub trace: Option<crate::TraceCorrelation>,
1919

@@ -208,7 +208,7 @@ impl BaseEventData {
208208
self.ai_model = Some(ai_model);
209209
}
210210

211-
/// Set explicit trusted trace correlation and add the Trace profile once.
211+
/// Set explicit trace correlation and add the Trace profile once.
212212
pub fn set_trace(&mut self, trace: crate::TraceCorrelation) {
213213
self.trace = Some(trace);
214214
if !self

‎crates/openshell-ocsf/src/trace.rs‎

Lines changed: 111 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,12 @@ use std::sync::OnceLock;
77

88
use serde::{Deserialize, Serialize};
99

10-
/// Trace ID supplied by a trusted producer.
10+
/// Trace ID supplied by an OCSF producer.
1111
///
12-
/// The registered extractor must return valid, sampled context from trusted
13-
/// spans. Explicit callers are responsible for validating their trace IDs.
12+
/// The registered extractor returns valid, sampled context from the active
13+
/// span. Gateway context may inherit a caller's traceparent, including before
14+
/// authentication: this value is a correlation hint, not an identity assertion.
15+
/// Explicit callers are responsible for validating their trace IDs.
1416
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1517
pub struct TraceCorrelation {
1618
/// W3C trace ID: 32 lowercase hexadecimal characters.
@@ -19,7 +21,7 @@ pub struct TraceCorrelation {
1921

2022
static EXTRACTOR: OnceLock<fn() -> Option<TraceCorrelation>> = OnceLock::new();
2123

22-
/// Register the process-wide trusted trace extractor at startup.
24+
/// Register the process-wide trace extractor at startup.
2325
///
2426
/// Returns `false` if an extractor is already registered. Without an extractor,
2527
/// events receive only explicitly supplied correlation.
@@ -48,97 +50,114 @@ mod tests {
4850
let trace = TraceCorrelation {
4951
uid: "0af7651916cd43dd8448eb211c80319c".to_string(),
5052
};
51-
let events = [
52-
NetworkActivityBuilder::new(&ctx)
53-
.trace(trace.clone())
54-
.dst_endpoint(Endpoint::from_domain("example.com", 443))
55-
.build(),
56-
HttpActivityBuilder::new(&ctx)
57-
.trace(trace.clone())
58-
.http_request(HttpRequest::new(
59-
"GET",
60-
Url::new("https", "example.com", "/", 443),
61-
))
62-
.build(),
63-
BaseEventBuilder::new(&ctx).trace(trace.clone()).build(),
64-
AppLifecycleBuilder::new(&ctx).trace(trace.clone()).build(),
65-
ConfigStateChangeBuilder::new(&ctx)
66-
.trace(trace.clone())
67-
.build(),
68-
DetectionFindingBuilder::new(&ctx)
69-
.trace(trace.clone())
70-
.build(),
71-
ProcessActivityBuilder::new(&ctx)
72-
.trace(trace.clone())
73-
.actor_process(Process::new("openshell-sandbox", 1))
74-
.process(Process::new("workload", 2))
75-
.build(),
76-
SshActivityBuilder::new(&ctx)
77-
.trace(trace.clone())
78-
.dst_endpoint(Endpoint::from_ip("192.0.2.1".parse().unwrap(), 22))
79-
.build(),
80-
AuthenticationBuilder::new(
81-
&ctx,
82-
User::unidentified(),
83-
Service::new("openshell-gateway"),
84-
)
85-
.trace(trace.clone())
86-
.build(),
87-
ApiActivityBuilder::new(&ctx, "GET /")
53+
for context in [
54+
ContextRef::from(&ctx),
55+
ContextRef::from(std::sync::Arc::new(ctx.clone())),
56+
] {
57+
let events = [
58+
NetworkActivityBuilder::new(context.clone())
59+
.trace(trace.clone())
60+
.dst_endpoint(Endpoint::from_domain("example.com", 443))
61+
.build(),
62+
HttpActivityBuilder::new(context.clone())
63+
.trace(trace.clone())
64+
.http_request(HttpRequest::new(
65+
"GET",
66+
Url::new("https", "example.com", "/", 443),
67+
))
68+
.build(),
69+
BaseEventBuilder::new(context.clone())
70+
.trace(trace.clone())
71+
.build(),
72+
AppLifecycleBuilder::new(context.clone())
73+
.trace(trace.clone())
74+
.build(),
75+
ConfigStateChangeBuilder::new(context.clone())
76+
.trace(trace.clone())
77+
.build(),
78+
DetectionFindingBuilder::new(context.clone())
79+
.trace(trace.clone())
80+
.build(),
81+
ProcessActivityBuilder::new(context.clone())
82+
.trace(trace.clone())
83+
.actor_process(Process::new("openshell-sandbox", 1))
84+
.process(Process::new("workload", 2))
85+
.build(),
86+
SshActivityBuilder::new(context.clone())
87+
.trace(trace.clone())
88+
.dst_endpoint(Endpoint::from_ip("192.0.2.1".parse().unwrap(), 22))
89+
.build(),
90+
AuthenticationBuilder::new(
91+
context.clone(),
92+
User::unidentified(),
93+
Service::new("openshell-gateway"),
94+
)
8895
.trace(trace.clone())
8996
.build(),
90-
];
91-
let schema = load_object_schema("trace");
92-
let profile: serde_json::Value =
93-
serde_json::from_str(include_str!("../schemas/ocsf/v1.8.0/profiles/trace.json"))
94-
.unwrap();
95-
assert_eq!(profile["attributes"]["trace"]["object_type"], "trace");
96-
for event in events {
97-
let value = event.to_json().unwrap();
98-
let class = match value["class_uid"].as_u64().unwrap() {
99-
0 => "base_event",
100-
4001 => "network_activity",
101-
4002 => "http_activity",
102-
4007 => "ssh_activity",
103-
1007 => "process_activity",
104-
3002 => "authentication",
105-
2004 => "detection_finding",
106-
6002 => "application_lifecycle",
107-
5019 => "device_config_state_change",
108-
6003 => "api_activity",
109-
uid => panic!("missing schema coverage for class {uid}"),
110-
};
111-
let class_schema = load_class_schema(class);
112-
validate_required_fields(&value, &class_schema);
113-
// Check correlation separately from native conformance work in #4283.
114-
validate_known_fields(
115-
&serde_json::json!({
116-
"metadata": value["metadata"],
117-
"trace": value["trace"],
118-
}),
119-
&class_schema,
120-
);
121-
validate_required_fields(&value["trace"], &schema);
122-
assert_eq!(value["trace"]["uid"], trace.uid);
123-
assert_eq!(value["trace"].as_object().unwrap().len(), 1);
124-
let decoded: OcsfEvent = serde_json::from_value(value.clone()).unwrap();
125-
assert_eq!(decoded.to_json().unwrap(), value);
126-
assert_eq!(
127-
value["metadata"]["profiles"]
128-
.as_array()
97+
ApiActivityBuilder::new(context, "GET /")
98+
.trace(trace.clone())
99+
.build(),
100+
];
101+
let schema = load_object_schema("trace");
102+
let profile: serde_json::Value =
103+
serde_json::from_str(include_str!("../schemas/ocsf/v1.8.0/profiles/trace.json"))
104+
.unwrap();
105+
assert_eq!(profile["attributes"]["trace"]["object_type"], "trace");
106+
for event in events {
107+
let value = event.to_json().unwrap();
108+
assert_eq!(value["device"]["hostname"], ctx.hostname);
109+
if value["class_uid"] == 3002 {
110+
// Authentication's schema does not allow the container profile.
111+
assert!(value.get("container").is_none());
112+
} else {
113+
assert_eq!(value["container"]["uid"], ctx.sandbox_id);
114+
assert_eq!(value["container"]["name"], ctx.sandbox_name);
115+
}
116+
let class = match value["class_uid"].as_u64().unwrap() {
117+
0 => "base_event",
118+
4001 => "network_activity",
119+
4002 => "http_activity",
120+
4007 => "ssh_activity",
121+
1007 => "process_activity",
122+
3002 => "authentication",
123+
2004 => "detection_finding",
124+
6002 => "application_lifecycle",
125+
5019 => "device_config_state_change",
126+
6003 => "api_activity",
127+
uid => panic!("missing schema coverage for class {uid}"),
128+
};
129+
let class_schema = load_class_schema(class);
130+
validate_required_fields(&value, &class_schema);
131+
// Check correlation separately from native conformance work in #4283.
132+
validate_known_fields(
133+
&serde_json::json!({
134+
"metadata": value["metadata"],
135+
"trace": value["trace"],
136+
}),
137+
&class_schema,
138+
);
139+
validate_required_fields(&value["trace"], &schema);
140+
assert_eq!(value["trace"]["uid"], trace.uid);
141+
assert_eq!(value["trace"].as_object().unwrap().len(), 1);
142+
let decoded: OcsfEvent = serde_json::from_value(value.clone()).unwrap();
143+
assert_eq!(decoded.to_json().unwrap(), value);
144+
assert_eq!(
145+
value["metadata"]["profiles"]
146+
.as_array()
147+
.unwrap()
148+
.iter()
149+
.filter(|p| *p == "trace")
150+
.count(),
151+
1
152+
);
153+
let mut plain = value;
154+
plain.as_object_mut().unwrap().remove("trace");
155+
plain["metadata"]["profiles"]
156+
.as_array_mut()
129157
.unwrap()
130-
.iter()
131-
.filter(|p| *p == "trace")
132-
.count(),
133-
1
134-
);
135-
let mut plain = value;
136-
plain.as_object_mut().unwrap().remove("trace");
137-
plain["metadata"]["profiles"]
138-
.as_array_mut()
139-
.unwrap()
140-
.retain(|name| name != "trace");
141-
validate_required_fields(&plain, &class_schema);
158+
.retain(|name| name != "trace");
159+
validate_required_fields(&plain, &class_schema);
160+
}
142161
}
143162
}
144163

‎crates/openshell-otel/src/correlation.rs‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
22
// SPDX-License-Identifier: Apache-2.0
33

4-
//! Trusted, sampled trace correlation for OCSF producers.
4+
//! Sampled trace correlation for OCSF producers.
55
66
use opentelemetry::trace::TraceContextExt as _;
77
use tracing_opentelemetry::OpenTelemetrySpanExt as _;
@@ -10,7 +10,9 @@ use tracing_opentelemetry::OpenTelemetrySpanExt as _;
1010
///
1111
/// Returns `None` unless the current span has valid, sampled context. This reads
1212
/// the current span without extracting workload HTTP headers or environment
13-
/// variables. A sampled ID does not guarantee export or retention.
13+
/// variables. The active span may already inherit a gateway caller's context,
14+
/// including before authentication. This is a correlation hint, not proof of
15+
/// origin. A sampled ID does not guarantee export or retention.
1416
#[must_use]
1517
pub fn current_ocsf_trace_correlation() -> Option<openshell_ocsf::TraceCorrelation> {
1618
let context = tracing::Span::current().context();

0 commit comments

Comments
 (0)