Skip to content

Commit cbf0263

Browse files
authored
fix(ocsf): require network activity endpoints (NVIDIA#3355)
Previously, Network Activity could be constructed without a source or destination endpoint, allowing connection, accept, relay, and configuration events to violate the OCSF 1.8 endpoint constraint. Now, NetworkActivityBuilder requires a source or destination endpoint at compile time. Connection failures identify the workload peer or genuine transparent destination, listener failures identify the listening endpoint, and mediation-lane failures use Application Lifecycle rather than fabricated network endpoints. Malformed forward requests use HTTP Activity with a method-only request, generated 400 response, and workload peer. Additionally, Unix relay-channel events use Base Event, policy-validation warnings use Config State Change, and the unused bypass monitor is removed because the current isolation architecture no longer uses it. Signed-off-by: Kris Hicks <khicks@nvidia.com>
1 parent 484f076 commit cbf0263

10 files changed

Lines changed: 499 additions & 154 deletions

File tree

‎architecture/sandbox.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -604,6 +604,11 @@ HTTP Activity records contain a request or response; early rejections with only
604604
connection context use Network Activity. Producer regression tests validate
605605
required fields and `at_least_one` constraints against the vendored OCSF 1.8
606606
schemas.
607+
Network Activity records identify at least one observed endpoint; connection
608+
failures retain their known peer or listening endpoint.
609+
Configuration diagnostics use Config State Change.
610+
Unix socket relay and relay-control notifications, plus proxy and mediation
611+
failures without an observed network endpoint, use Base Event.
607612

608613
## Policy Proposals
609614

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

Lines changed: 0 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -134,20 +134,6 @@ macro_rules! impl_src_endpoint_addr_setter {
134134
};
135135
}
136136

137-
/// Generate the `firewall_rule` setter shared by network and HTTP builders.
138-
macro_rules! impl_firewall_rule_setter {
139-
($builder:ident) => {
140-
impl<'a> $builder<'a> {
141-
/// Set the firewall rule that matched this event.
142-
#[must_use]
143-
pub fn firewall_rule(mut self, name: &str, rule_type: &str) -> Self {
144-
self.firewall_rule = Some($crate::objects::FirewallRule::new(name, rule_type));
145-
self
146-
}
147-
}
148-
};
149-
}
150-
151137
mod api_activity;
152138
mod base;
153139
mod config;

‎crates/openshell-ocsf/src/builders/network.rs‎

Lines changed: 163 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ use crate::events::{NetworkActivityEvent, OcsfEvent};
1010
use crate::objects::{Actor, ConnectionInfo, Endpoint, FirewallRule};
1111

1212
/// Builder for Network Activity [4001] events.
13-
pub struct NetworkActivityBuilder<'a> {
13+
pub struct NetworkActivityBuilder<'a, EndpointState = MissingNetworkEndpoint> {
1414
ctx: &'a EventContext,
1515
activity: ActivityId,
1616
activity_name: Option<String>,
@@ -28,10 +28,35 @@ pub struct NetworkActivityBuilder<'a> {
2828
status_detail: Option<String>,
2929
unmapped: Option<serde_json::Map<String, serde_json::Value>>,
3030
log_source: Option<String>,
31+
endpoint_state: std::marker::PhantomData<EndpointState>,
3132
}
3233

33-
impl<'a> NetworkActivityBuilder<'a> {
34+
/// Marker for a Network Activity builder without an endpoint.
35+
pub struct MissingNetworkEndpoint;
36+
37+
/// Marker for a Network Activity builder with a source or destination endpoint.
38+
pub struct HasNetworkEndpoint;
39+
40+
impl<'a> NetworkActivityBuilder<'a, MissingNetworkEndpoint> {
3441
/// Start building a Network Activity event.
42+
///
43+
/// A Network Activity must include a source or destination endpoint before
44+
/// it can be built.
45+
///
46+
/// ```compile_fail
47+
/// use openshell_ocsf::{EventContext, NetworkActivityBuilder};
48+
///
49+
/// let ctx = EventContext {
50+
/// sandbox_id: String::new(),
51+
/// sandbox_name: String::new(),
52+
/// container_image: String::new(),
53+
/// hostname: String::new(),
54+
/// product_version: String::new(),
55+
/// proxy_ip: "127.0.0.1".parse().unwrap(),
56+
/// proxy_port: 3128,
57+
/// };
58+
/// NetworkActivityBuilder::new(&ctx).build();
59+
/// ```
3560
#[must_use]
3661
pub fn new(ctx: &'a EventContext) -> Self {
3762
Self {
@@ -52,6 +77,92 @@ impl<'a> NetworkActivityBuilder<'a> {
5277
status_detail: None,
5378
unmapped: None,
5479
log_source: None,
80+
endpoint_state: std::marker::PhantomData,
81+
}
82+
}
83+
84+
#[must_use]
85+
pub fn src_endpoint_addr(
86+
self,
87+
ip: std::net::IpAddr,
88+
port: u16,
89+
) -> NetworkActivityBuilder<'a, HasNetworkEndpoint> {
90+
self.with_src_endpoint(Endpoint::from_ip(ip, port))
91+
}
92+
93+
#[must_use]
94+
pub fn dst_endpoint(
95+
self,
96+
endpoint: Endpoint,
97+
) -> NetworkActivityBuilder<'a, HasNetworkEndpoint> {
98+
self.with_dst_endpoint(endpoint)
99+
}
100+
}
101+
102+
impl NetworkActivityBuilder<'_, HasNetworkEndpoint> {
103+
#[must_use]
104+
pub fn src_endpoint_addr(mut self, ip: std::net::IpAddr, port: u16) -> Self {
105+
self.src_endpoint = Some(Endpoint::from_ip(ip, port));
106+
self
107+
}
108+
109+
#[must_use]
110+
pub fn dst_endpoint(mut self, endpoint: Endpoint) -> Self {
111+
self.dst_endpoint = Some(endpoint);
112+
self
113+
}
114+
}
115+
116+
impl<'a, EndpointState> NetworkActivityBuilder<'a, EndpointState> {
117+
fn with_src_endpoint(
118+
self,
119+
endpoint: Endpoint,
120+
) -> NetworkActivityBuilder<'a, HasNetworkEndpoint> {
121+
NetworkActivityBuilder {
122+
ctx: self.ctx,
123+
activity: self.activity,
124+
activity_name: self.activity_name,
125+
action: self.action,
126+
disposition: self.disposition,
127+
severity: self.severity,
128+
status: self.status,
129+
src_endpoint: Some(endpoint),
130+
dst_endpoint: self.dst_endpoint,
131+
actor: self.actor,
132+
firewall_rule: self.firewall_rule,
133+
connection_info: self.connection_info,
134+
observation_point_id: self.observation_point_id,
135+
message: self.message,
136+
status_detail: self.status_detail,
137+
unmapped: self.unmapped,
138+
log_source: self.log_source,
139+
endpoint_state: std::marker::PhantomData,
140+
}
141+
}
142+
143+
fn with_dst_endpoint(
144+
self,
145+
endpoint: Endpoint,
146+
) -> NetworkActivityBuilder<'a, HasNetworkEndpoint> {
147+
NetworkActivityBuilder {
148+
ctx: self.ctx,
149+
activity: self.activity,
150+
activity_name: self.activity_name,
151+
action: self.action,
152+
disposition: self.disposition,
153+
severity: self.severity,
154+
status: self.status,
155+
src_endpoint: self.src_endpoint,
156+
dst_endpoint: Some(endpoint),
157+
actor: self.actor,
158+
firewall_rule: self.firewall_rule,
159+
connection_info: self.connection_info,
160+
observation_point_id: self.observation_point_id,
161+
message: self.message,
162+
status_detail: self.status_detail,
163+
unmapped: self.unmapped,
164+
log_source: self.log_source,
165+
endpoint_state: std::marker::PhantomData,
55166
}
56167
}
57168

@@ -90,6 +201,56 @@ impl<'a> NetworkActivityBuilder<'a> {
90201
self
91202
}
92203

204+
#[must_use]
205+
pub fn activity(mut self, id: ActivityId) -> Self {
206+
self.activity = id;
207+
self
208+
}
209+
210+
#[must_use]
211+
pub fn action(mut self, id: ActionId) -> Self {
212+
self.action = Some(id);
213+
self
214+
}
215+
216+
#[must_use]
217+
pub fn disposition(mut self, id: DispositionId) -> Self {
218+
self.disposition = Some(id);
219+
self
220+
}
221+
222+
#[must_use]
223+
pub fn actor_process(mut self, process: crate::objects::Process) -> Self {
224+
self.actor = Some(Actor { process });
225+
self
226+
}
227+
228+
#[must_use]
229+
pub fn firewall_rule(mut self, name: &str, rule_type: &str) -> Self {
230+
self.firewall_rule = Some(FirewallRule::new(name, rule_type));
231+
self
232+
}
233+
234+
#[must_use]
235+
pub fn severity(mut self, id: SeverityId) -> Self {
236+
self.severity = id;
237+
self
238+
}
239+
240+
#[must_use]
241+
pub fn status(mut self, id: StatusId) -> Self {
242+
self.status = Some(id);
243+
self
244+
}
245+
246+
#[must_use]
247+
pub fn message(mut self, msg: impl Into<String>) -> Self {
248+
self.message = Some(msg.into());
249+
self
250+
}
251+
}
252+
253+
impl NetworkActivityBuilder<'_, HasNetworkEndpoint> {
93254
/// Finalize and return the `OcsfEvent`.
94255
#[must_use]
95256
pub fn build(self) -> OcsfEvent {
@@ -139,14 +300,6 @@ impl<'a> NetworkActivityBuilder<'a> {
139300
}
140301
}
141302

142-
impl_activity_setter!(NetworkActivityBuilder);
143-
impl_action_disposition_setters!(NetworkActivityBuilder);
144-
impl_actor_process_setter!(NetworkActivityBuilder);
145-
impl_dst_endpoint_setter!(NetworkActivityBuilder);
146-
impl_src_endpoint_addr_setter!(NetworkActivityBuilder);
147-
impl_firewall_rule_setter!(NetworkActivityBuilder);
148-
impl_builder_setters!(NetworkActivityBuilder);
149-
150303
#[cfg(test)]
151304
mod tests {
152305
use super::*;

‎crates/openshell-ocsf/tests/event_identity.rs‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55
66
use std::net::{IpAddr, Ipv4Addr};
77

8-
use openshell_ocsf::{ActivityId, EventContext, NetworkActivityBuilder, OcsfEvent, SeverityId};
8+
use openshell_ocsf::{
9+
ActivityId, Endpoint, EventContext, NetworkActivityBuilder, OcsfEvent, SeverityId,
10+
};
911

1012
fn sandbox_ctx(container_image: &str) -> EventContext {
1113
EventContext {
@@ -23,6 +25,7 @@ fn event(ctx: &EventContext) -> OcsfEvent {
2325
NetworkActivityBuilder::new(ctx)
2426
.activity(ActivityId::Open)
2527
.severity(SeverityId::Medium)
28+
.dst_endpoint(Endpoint::from_domain("api.example.com", 443))
2629
.message("CONNECT api.example.com:443")
2730
.build()
2831
}

‎crates/openshell-supervisor-network/src/l7/mod.rs‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -308,9 +308,10 @@ pub fn parse_l7_config(val: &regorus::Value) -> Option<L7EndpointConfig> {
308308
let tls = match tls_value.as_str() {
309309
"skip" => TlsMode::Skip,
310310
"terminate" => {
311-
let event = openshell_ocsf::NetworkActivityBuilder::new(openshell_ocsf::ctx::ctx())
312-
.activity(openshell_ocsf::ActivityId::Other)
311+
let event = openshell_ocsf::ConfigStateChangeBuilder::new(openshell_ocsf::ctx::ctx())
313312
.severity(openshell_ocsf::SeverityId::Medium)
313+
.status(openshell_ocsf::StatusId::Success)
314+
.state(openshell_ocsf::StateId::Other, "deprecated")
314315
.message(
315316
"'tls: terminate' is deprecated; TLS termination is now automatic. \
316317
Use 'tls: skip' to explicitly disable. This field will be removed in a future version.",
@@ -320,9 +321,10 @@ pub fn parse_l7_config(val: &regorus::Value) -> Option<L7EndpointConfig> {
320321
TlsMode::Auto
321322
}
322323
"passthrough" => {
323-
let event = openshell_ocsf::NetworkActivityBuilder::new(openshell_ocsf::ctx::ctx())
324-
.activity(openshell_ocsf::ActivityId::Other)
324+
let event = openshell_ocsf::ConfigStateChangeBuilder::new(openshell_ocsf::ctx::ctx())
325325
.severity(openshell_ocsf::SeverityId::Medium)
326+
.status(openshell_ocsf::StatusId::Success)
327+
.state(openshell_ocsf::StateId::Other, "deprecated")
326328
.message(
327329
"'tls: passthrough' is deprecated; TLS termination is now automatic. \
328330
Use 'tls: skip' to explicitly disable. This field will be removed in a future version.",
@@ -374,9 +376,10 @@ pub fn parse_l7_config(val: &regorus::Value) -> Option<L7EndpointConfig> {
374376
Some("sigv4:body") => CredentialSigning::SigV4Body,
375377
Some("sigv4:no_body") => CredentialSigning::SigV4NoBody,
376378
Some(other) if !other.is_empty() => {
377-
let event = openshell_ocsf::NetworkActivityBuilder::new(openshell_ocsf::ctx::ctx())
378-
.activity(openshell_ocsf::ActivityId::Other)
379+
let event = openshell_ocsf::ConfigStateChangeBuilder::new(openshell_ocsf::ctx::ctx())
379380
.severity(openshell_ocsf::SeverityId::High)
381+
.status(openshell_ocsf::StatusId::Failure)
382+
.state(openshell_ocsf::StateId::Disabled, "invalid")
380383
.message(format!(
381384
"rejecting endpoint: unrecognized credential_signing value {other:?}"
382385
))
@@ -391,9 +394,10 @@ pub fn parse_l7_config(val: &regorus::Value) -> Option<L7EndpointConfig> {
391394
let signing_region = get_object_str(val, "signing_region").unwrap_or_default();
392395

393396
if credential_signing.is_sigv4() && signing_service.is_empty() {
394-
let event = openshell_ocsf::NetworkActivityBuilder::new(openshell_ocsf::ctx::ctx())
395-
.activity(openshell_ocsf::ActivityId::Other)
397+
let event = openshell_ocsf::ConfigStateChangeBuilder::new(openshell_ocsf::ctx::ctx())
396398
.severity(openshell_ocsf::SeverityId::High)
399+
.status(openshell_ocsf::StatusId::Failure)
400+
.state(openshell_ocsf::StateId::Disabled, "invalid")
397401
.message("rejecting endpoint: credential_signing requires signing_service".to_string())
398402
.build();
399403
openshell_ocsf::ocsf_emit!(event);

0 commit comments

Comments
 (0)