Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ ocsf_emit!(event);

- `crate::ocsf_ctx()` returns the process-wide `EventContext`. It is always available (falls back to defaults in tests).
- `ocsf_emit!()` is non-blocking and cannot panic. It stores the event in a thread-local and emits via `tracing::info!()`.
- In `openshell-supervisor-network`, emit with `crate::telemetry::egress_emit!` instead, or `crate::telemetry::emit_decision` for the records of one decision, so denied HTTP decisions get a deny span. Clippy rejects `ocsf_emit!` there.
- In `openshell-supervisor-network`, the inspected request scope automatically correlates all OCSF records at emission, including findings, and uses the request span without creating a denial-only span. Emit through `crate::telemetry::egress_emit!` or `crate::telemetry::emit_decision`; Clippy rejects direct `ocsf_emit!` calls there.
- The shorthand layer and JSONL layer extract the event from the thread-local. The shorthand format is derived automatically from the builder fields.
- For security findings, **dual-emit**: one domain event (e.g., `SshActivityBuilder`) AND one `DetectionFindingBuilder` for the same incident.
- Never log secrets, credentials, or query parameters in OCSF messages. The OCSF JSONL file may be shipped to external systems.
Expand Down
2 changes: 2 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

23 changes: 23 additions & 0 deletions crates/openshell-ocsf/src/events/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,29 @@ mod tests {
assert_eq!(deserialized.class_uid(), 2004);
}

#[test]
fn correlation_uid_can_be_set_on_any_event_class() {
let ctx = test_sandbox_context();
let mut event = AuthenticationBuilder::new(
&ctx,
User::other("user-1", "User"),
Service::new("gateway"),
)
.status(StatusId::Success)
.build();

event.base_mut().metadata.correlation_uid = Some("request-123".into());

assert_eq!(
event.base().metadata.correlation_uid.as_deref(),
Some("request-123")
);
assert_eq!(
serde_json::to_value(&event).unwrap()["metadata"]["correlation_uid"],
"request-123"
);
}

#[test]
fn test_roundtrip_application_lifecycle() {
let ctx = test_sandbox_context();
Expand Down
2 changes: 1 addition & 1 deletion crates/openshell-ocsf/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -74,5 +74,5 @@ pub use builders::{
pub use tracing_layers::{
OCSF_TARGET, OcsfJsonSettings, OcsfJsonlLayer, OcsfShorthandLayer, bind_thread_json_settings,
clear_current_event, clone_current_event, emit_ocsf_event, emit_ocsf_event_routed,
set_current_event,
register_event_enricher, set_current_event,
};
121 changes: 118 additions & 3 deletions crates/openshell-ocsf/src/tracing_layers/event_bridge.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,11 @@
//! layers intercept this target, clone the event, and format it.
//! After dispatch, `emit_ocsf_event` clears the thread-local.

use crate::events::OcsfEvent;
use std::sync::OnceLock;

use crate::events::{BaseEventData, OcsfEvent};

static EVENT_ENRICHER: OnceLock<fn(&mut BaseEventData)> = OnceLock::new();

std::thread_local! {
// Thread-local storage for the current OCSF event being emitted.
Expand All @@ -19,6 +23,27 @@ std::thread_local! {
/// Target string used to identify OCSF tracing events.
pub const OCSF_TARGET: &str = "ocsf";

/// Register optional process-wide event enrichment at startup.
///
/// The callback runs once per emission, before any output layer receives the
/// record, independently of trace sampling or export. It receives the common
/// base fields for every event class and should add only contextual fields,
/// preserving the record's content, classification, and timestamp. It must not
/// block, panic, or emit another OCSF event.
///
/// Returns `false` if an enricher is already registered. Without an enricher,
/// emission does not add application-specific context.
pub fn register_event_enricher(enricher: fn(&mut BaseEventData)) -> bool {
EVENT_ENRICHER.set(enricher).is_ok()
}

fn enrich(event: &mut OcsfEvent) {
crate::trace::enrich(event);
if let Some(enrich) = EVENT_ENRICHER.get() {
enrich(event.base_mut());
}
}

/// Clone the current thread-local OCSF event, if any.
///
/// Multiple layers can call this for the same event — each receives
Expand All @@ -35,7 +60,7 @@ pub fn clone_current_event() -> Option<OcsfEvent> {
///
/// Both layers receive the event — `clone_current_event()` is non-consuming.
pub fn emit_ocsf_event(mut event: OcsfEvent) {
crate::trace::enrich(&mut event);
enrich(&mut event);
// Store the event in thread-local so layers can access it
set_current_event(event);

Expand Down Expand Up @@ -83,7 +108,7 @@ pub fn clear_current_event() {
/// per-event `sandbox_id` field here instead. One tracing event feeds both the
/// JSONL audit file and the routing bus.
pub fn emit_ocsf_event_routed(sandbox_id: &str, mut event: OcsfEvent) {
crate::trace::enrich(&mut event);
enrich(&mut event);
let message = event.format_shorthand();
set_current_event(event);
tracing::info!(target: "ocsf", sandbox_id = %sandbox_id, message = %message);
Expand Down Expand Up @@ -111,6 +136,22 @@ mod tests {
use crate::events::{BaseEvent, OcsfEvent};
use crate::objects::{Metadata, Product};

std::thread_local! {
// Registration is process-wide, but this test's callback must be inert
// for unrelated tests running in parallel or reusing this thread later.
static TEST_ENRICHER_SEQUENCE: std::cell::Cell<Option<u64>> = const { std::cell::Cell::new(None) };
}

fn test_enricher(event: &mut BaseEventData) {
TEST_ENRICHER_SEQUENCE.with(|sequence| {
if let Some(next) = sequence.get() {
sequence.set(Some(next + 1));
event.metadata.correlation_uid = Some("emit-time-request".into());
event.add_unmapped("request_sequence", next);
}
});
}

fn test_event() -> OcsfEvent {
OcsfEvent::Base(BaseEvent {
base: BaseEventData::new(
Expand Down Expand Up @@ -238,4 +279,78 @@ mod tests {
"routed emit must match the bare path JSON"
);
}

#[test]
fn event_enrichment_runs_once_for_every_class_and_output_path() {
use crate::test_support::OcsfCapture;
use crate::tracing_layers::OcsfJsonlLayer;
use tracing_subscriber::prelude::*;

assert!(register_event_enricher(test_enricher));
assert!(!register_event_enricher(test_enricher));
let capture = OcsfCapture::default();
let bytes = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
let subscriber = tracing_subscriber::registry()
.with(capture.clone())
.with(OcsfJsonlLayer::new(SharedWriter(bytes.clone())));
let context = crate::builders::test_sandbox_context();
let mut expected = Vec::new();

tracing::subscriber::with_default(subscriber, || {
struct ResetEnricher;
impl Drop for ResetEnricher {
fn drop(&mut self) {
TEST_ENRICHER_SEQUENCE.with(|sequence| sequence.set(None));
}
}
let plain = test_event();
expected.push(plain.clone());
emit_ocsf_event(plain);

{
let _reset = ResetEnricher;
TEST_ENRICHER_SEQUENCE.with(|sequence| sequence.set(Some(1)));
let mut sequence = 1;
for routed in [false, true] {
for (_, mut event) in crate::builders::sample_events(&context) {
event.base_mut().add_unmapped("source_detail", "keep");
event
.base_mut()
.add_unmapped("http_event_kind", "original_kind");
let mut enriched = event.clone();
enriched.base_mut().metadata.correlation_uid =
Some("emit-time-request".into());
enriched
.base_mut()
.add_unmapped("request_sequence", sequence);
expected.push(enriched);
if routed {
emit_ocsf_event_routed("test-sandbox", event);
} else {
emit_ocsf_event(event);
}
assert!(clone_current_event().is_none());
sequence += 1;
}
}
TEST_ENRICHER_SEQUENCE.with(|next| assert_eq!(next.get(), Some(sequence)));
}

let plain = test_event();
expected.push(plain.clone());
emit_ocsf_event_routed("test-sandbox", plain);
});

assert_eq!(capture.events(), expected);
let expected_json: Vec<_> = expected
.iter()
.map(|event| event.to_json().unwrap())
.collect();
let output = String::from_utf8(bytes.lock().unwrap().clone()).unwrap();
let json: Vec<serde_json::Value> = output
.lines()
.map(|line| serde_json::from_str(line).unwrap())
.collect();
assert_eq!(json, expected_json);
}
}
2 changes: 1 addition & 1 deletion crates/openshell-ocsf/src/tracing_layers/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ mod shorthand_layer;

pub use event_bridge::{
OCSF_TARGET, clear_current_event, clone_current_event, emit_ocsf_event, emit_ocsf_event_routed,
set_current_event,
register_event_enricher, set_current_event,
};
pub use jsonl_layer::{OcsfJsonSettings, OcsfJsonlLayer, bind_thread_json_settings};
pub use shorthand_layer::OcsfShorthandLayer;
34 changes: 33 additions & 1 deletion crates/openshell-otel/src/ocsf.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ const MAX_EXPORT_ATTEMPTS: usize = 4;
const INITIAL_BACKOFF: Duration = Duration::from_millis(250);
const MAX_BACKOFF: Duration = Duration::from_secs(2);
const GAP_EVENT: &str = "openshell.ocsf.gap";
const CORRELATION_UID_ATTRIBUTE: &str = "ocsf.metadata.correlation_uid";

/// Exports OCSF events to an OTLP collector as log records.
pub struct OcsfOtlp {
Expand Down Expand Up @@ -391,6 +392,9 @@ fn log_record(
if let Some(uid) = &base.metadata.uid {
record.add_attribute("ocsf.metadata.uid", uid.clone());
}
if let Some(uid) = &base.metadata.correlation_uid {
record.add_attribute(CORRELATION_UID_ATTRIBUTE, uid.clone());
}
if let Some(sandbox_id) = event.sandbox_id() {
record.add_attribute("openshell.sandbox.id", sandbox_id.to_string());
}
Expand Down Expand Up @@ -629,6 +633,19 @@ mod tests {
assert_eq!(native(&event)["resources"][0]["uid"], "requested-sandbox");
}

#[test]
fn correlation_uid_is_a_stable_otlp_attribute() {
let mut event = event("sandbox-1", SeverityId::Informational);
let OcsfEvent::DeviceConfigStateChange(config) = &mut event else {
unreachable!("event fixture returns a configuration event");
};
config.base.metadata.correlation_uid = Some("request-123".into());
assert_eq!(
attribute(&record(&event), CORRELATION_UID_ATTRIBUTE),
Some(AnyValue::String("request-123".into()))
);
}

#[test]
fn events_without_a_sandbox_carry_no_sandbox_attribute() {
let record = record(&event("", SeverityId::Informational));
Expand Down Expand Up @@ -788,12 +805,27 @@ mod tests {
.with(otlp.layer());
let span_context = tracing::subscriber::with_default(subscriber, || {
let span = tracing::info_span!("decision");
span.in_scope(|| ocsf_emit!(event("sandbox-1", SeverityId::Medium)));
let mut event = event("sandbox-1", SeverityId::Medium);
let OcsfEvent::DeviceConfigStateChange(config) = &mut event else {
unreachable!("event fixture returns a configuration event");
};
config.base.metadata.correlation_uid =
Some("request-with-or-without-sampling".into());
span.in_scope(|| ocsf_emit!(event));
span.context().span().span_context().clone()
});
otlp.shutdown().await;

let records = exporter.exported();
assert_eq!(records.len(), 1);
assert_eq!(
attribute(&records[0].record, CORRELATION_UID_ATTRIBUTE),
Some(AnyValue::String("request-with-or-without-sampling".into()))
);
assert_eq!(
body(&records[0].record)["metadata"]["correlation_uid"],
"request-with-or-without-sampling"
);
let trace = records[0].record.trace_context();
if span_context.is_sampled() {
let trace = trace.expect("sampled span context is attached");
Expand Down
77 changes: 60 additions & 17 deletions crates/openshell-supervisor-middleware/src/headers.rs
Original file line number Diff line number Diff line change
Expand Up @@ -366,25 +366,31 @@ fn is_safe_value(value: &str) -> bool {
}

fn is_request_protected(name: &str) -> bool {
matches!(
name,
"authorization"
| "proxy-authorization"
| "proxy-authenticate"
| "cookie"
| "host"
| "content-length"
| "transfer-encoding"
| "connection"
| "proxy-connection"
| "keep-alive"
| "te"
| "trailer"
| "upgrade"
) || name.starts_with("x-amz-")
is_platform_correlation_header(name)
|| matches!(
name,
"authorization"
| "proxy-authorization"
| "proxy-authenticate"
| "cookie"
| "host"
| "content-length"
| "transfer-encoding"
| "connection"
| "proxy-connection"
| "keep-alive"
| "te"
| "trailer"
| "upgrade"
)
|| name.starts_with("x-amz-")
|| name.starts_with("x-openshell-credential")
}

fn is_platform_correlation_header(name: &str) -> bool {
name == "x-openshell-request-id"
}

/// Return whether a response header can carry authentication material and must
/// never be exposed to middleware.
#[must_use]
Expand All @@ -402,7 +408,8 @@ pub fn is_response_credential_header(name: &str) -> bool {
}

fn is_response_protected(name: &str) -> bool {
is_response_credential_header(name)
is_platform_correlation_header(name)
|| is_response_credential_header(name)
|| matches!(
name,
"connection"
Expand Down Expand Up @@ -488,6 +495,42 @@ mod tests {
);
}

#[test]
fn platform_request_id_is_immutable_for_all_http_phases() {
for authority in [
HeaderAuthority::Request,
HeaderAuthority::HookRequest,
HeaderAuthority::RequestTrailers,
HeaderAuthority::Response,
HeaderAuthority::HookResponse,
HeaderAuthority::ResponseTrailers,
] {
let name = "X-OpenShell-Request-ID";
let write_error = apply(
authority,
&[],
&[],
&[write(name, "forged", ExistingHeaderAction::Overwrite)],
)
.expect_err("platform request ID write");
assert_eq!(
write_error,
HeaderMutationError::Protected {
name: name.to_string()
}
);

let remove_error = apply(authority, &[], &[], &[remove(name)])
.expect_err("platform request ID removal");
assert_eq!(
remove_error,
HeaderMutationError::Protected {
name: name.to_string()
}
);
}
}

#[test]
fn unsafe_header_value_is_rejected() {
let error = apply(
Expand Down
Loading
Loading