diff --git a/crates/openshell-core/src/config.rs b/crates/openshell-core/src/config.rs index 6ffeaf1dce..f72ba14ed9 100644 --- a/crates/openshell-core/src/config.rs +++ b/crates/openshell-core/src/config.rs @@ -321,6 +321,9 @@ pub struct Config { /// sandbox identity is always carried by gateway-minted sandbox JWTs. pub mtls_auth: MtlsAuthConfig, + /// Optional details gateway mutation records capture. + pub audit: GatewayAuditConfig, + /// Gateway-minted sandbox JWT configuration. When `Some`, the gateway /// loads the signing key from disk and accepts gateway-issued sandbox /// JWTs as `Principal::Sandbox`. Required for the per-sandbox identity @@ -626,6 +629,17 @@ pub struct OidcConfig { pub scopes_claim: String, } +/// `[openshell.gateway.audit]`: optional details gateway mutation records +/// capture. Secrets are never captured. +#[derive(Debug, Clone, Default, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct GatewayAuditConfig { + /// Record the values of gateway and sandbox settings that `UpdateConfig` + /// sets. Bytes values are never recorded. + #[serde(default)] + pub capture_setting_values: bool, +} + /// mTLS user authentication for gateway users. #[derive(Debug, Clone, Default, Serialize, Deserialize)] #[serde(deny_unknown_fields)] @@ -1114,6 +1128,7 @@ impl Config { gateway_interceptors: Vec::new(), provider_profile_sources: vec![GatewayProviderProfileSourceConfig::User], mtls_auth: MtlsAuthConfig::default(), + audit: GatewayAuditConfig::default(), gateway_jwt: None, database_url: String::new(), database_auth: DatabaseAuthMode::default(), diff --git a/crates/openshell-core/src/lib.rs b/crates/openshell-core/src/lib.rs index 12473a702c..09d85c2f55 100644 --- a/crates/openshell-core/src/lib.rs +++ b/crates/openshell-core/src/lib.rs @@ -73,7 +73,7 @@ pub mod transport_errors; pub mod upload; pub use config::{ - AppArmorProfile, Config, ExtensionBindingPolicy, GatewayAuthConfig, + AppArmorProfile, Config, ExtensionBindingPolicy, GatewayAuditConfig, GatewayAuthConfig, GatewayInterceptorBindingOverride, GatewayInterceptorBindingPolicy, GatewayInterceptorConfig, GatewayInterceptorFailurePolicy, GatewayInterceptorPhaseConfig, GatewayJwtConfig, GatewayProviderProfileSourceConfig, ImagePullPolicy, MetricsTlsConfig, MtlsAuthConfig, diff --git a/crates/openshell-ocsf/src/objects/resource.rs b/crates/openshell-ocsf/src/objects/resource.rs index 894806fd2c..fd69dd7ac4 100644 --- a/crates/openshell-ocsf/src/objects/resource.rs +++ b/crates/openshell-ocsf/src/objects/resource.rs @@ -22,6 +22,10 @@ pub struct ResourceDetails { /// Resource type (e.g. "sandbox", "workspace"). #[serde(rename = "type", skip_serializing_if = "Option::is_none")] pub type_label: Option, + + /// Additional details about the resource. + #[serde(skip_serializing_if = "Option::is_none")] + pub data: Option, } impl ResourceDetails { @@ -32,6 +36,7 @@ impl ResourceDetails { uid: Some(uid.into()), name: None, type_label: Some(type_label.into()), + data: None, } } @@ -42,8 +47,16 @@ impl ResourceDetails { uid: None, name: Some(name.into()), type_label: Some(type_label.into()), + data: None, } } + + /// This resource with additional details. + #[must_use] + pub fn with_data(mut self, data: serde_json::Value) -> Self { + self.data = Some(data); + self + } } #[cfg(test)] @@ -56,6 +69,17 @@ mod tests { assert_eq!(json, serde_json::json!({"uid": "sb-1", "type": "sandbox"})); } + #[test] + fn resource_carries_data() { + let resource = ResourceDetails::named("setting", "log_level") + .with_data(serde_json::json!({"value": "debug"})); + let json = serde_json::to_value(resource).unwrap(); + assert_eq!( + json, + serde_json::json!({"name": "log_level", "type": "setting", "data": {"value": "debug"}}) + ); + } + #[test] fn named_resource_has_no_uid() { let json = serde_json::to_value(ResourceDetails::named("workspace", "default")).unwrap(); diff --git a/crates/openshell-server/src/auth/audit.rs b/crates/openshell-server/src/auth/audit.rs index 2a2d07a165..abef33edd3 100644 --- a/crates/openshell-server/src/auth/audit.rs +++ b/crates/openshell-server/src/auth/audit.rs @@ -699,10 +699,10 @@ impl AuthzDenial<'_> { } } -/// Longest identifier recorded on an event. +/// Longest identifier or value recorded on an event. const MAX_ID_LEN: usize = 128; -/// Cap an identifier so a caller cannot inflate events. +/// Cap a value so a caller cannot inflate events. fn bounded(value: &str) -> String { if value.len() <= MAX_ID_LEN { return value.to_string(); @@ -775,16 +775,20 @@ fn emit_denial( .request_id .clone() .or_else(|| finding.then(|| uuid::Uuid::new_v4().to_string())); + if let Some(resource) = denial.resource().filter(|r| !resources.contains(r)) { + resources.push(resource); + } + let (resources, omitted) = limited_resources(resources); let mut builder = api_activity(&ctx, path, origin, principal) .action(ActionId::Denied) .disposition(DispositionId::Blocked) .severity(SeverityId::Medium) .status(StatusId::Failure) .status_detail(category) - .message(format!("authorization denied: {category}")); - if let Some(resource) = denial.resource().filter(|r| !resources.contains(r)) { - resources.push(resource); - } + .message(with_omitted( + format!("authorization denied: {category}"), + omitted, + )); for resource in resources { builder = builder.resource(resource); } @@ -870,9 +874,52 @@ fn api_activity<'a>( builder } -/// Most resources one mutation record lists. +/// Most resources one record lists: the first ones recorded and the last, +/// which is what the change produced. const MAX_RECORDED_RESOURCES: usize = 16; +/// `data` with every string in it bounded. +fn bounded_data(data: serde_json::Value) -> serde_json::Value { + use serde_json::Value; + match data { + Value::String(value) => Value::String(bounded(&value)), + Value::Array(values) => values.into_iter().map(bounded_data).collect(), + Value::Object(fields) => fields + .into_iter() + .map(|(key, value)| (bounded(&key), bounded_data(value))) + .collect(), + scalar => scalar, + } +} + +/// At most [`MAX_RECORDED_RESOURCES`] of `resources`, every field bounded, +/// and how many were left out. +fn limited_resources(mut resources: Vec) -> (Vec, usize) { + let omitted = resources.len().saturating_sub(MAX_RECORDED_RESOURCES); + if omitted > 0 { + resources.drain(MAX_RECORDED_RESOURCES - 1..resources.len() - 1); + } + let resources = resources + .into_iter() + .map(|resource| ResourceDetails { + name: resource.name.as_deref().map(bounded), + uid: resource.uid.as_deref().map(bounded), + type_label: resource.type_label, + data: resource.data.map(bounded_data), + }) + .collect(); + (resources, omitted) +} + +/// `message`, noting the `omitted` resources a record does not list. +fn with_omitted(message: String, omitted: usize) -> String { + if omitted == 0 { + message + } else { + format!("{message}; {omitted} more resources not listed") + } +} + /// Emit the record of a mutation that ended with `code`, or that never /// finished when `code` is `None`. fn emit_mutation(request: &RequestContext, principal: &Principal, code: Option) { @@ -880,16 +927,9 @@ fn emit_mutation(request: &RequestContext, principal: &Principal, code: Option rejected, @@ -922,12 +962,10 @@ fn emit_mutation(request: &RequestContext, principal: &Principal, code: Option, #[serde(default)] + pub audit: Option, + #[serde(default)] pub gateway_jwt: Option, #[serde(default)] pub otlp: Option, @@ -2123,6 +2125,14 @@ service_name = "openshell-gateway-dev" assert_eq!(otlp.service_name.as_deref(), Some("openshell-gateway-dev")); } + #[test] + fn gateway_audit_capture_is_opt_in() { + let tmp = write_tmp("[openshell.gateway.audit]\ncapture_setting_values = true\n"); + let audit = load(tmp.path()).unwrap().openshell.gateway.audit.unwrap(); + assert!(audit.capture_setting_values); + assert!(!GatewayAuditConfig::default().capture_setting_values); + } + #[test] fn gateway_accepts_a_single_ocsf_log_destination() { let tmp = write_tmp("[openshell.gateway.ocsf_log]\npath = 'events.jsonl'\n"); diff --git a/crates/openshell-server/src/grpc/mod.rs b/crates/openshell-server/src/grpc/mod.rs index 3cfae86954..c61cb62e26 100644 --- a/crates/openshell-server/src/grpc/mod.rs +++ b/crates/openshell-server/src/grpc/mod.rs @@ -683,7 +683,19 @@ impl OpenShell for OpenShellService { &self, request: Request, ) -> Result, Status> { - mutation_replay::run(&self.state, request).await + let targets = { + let request = request.get_ref(); + let name = request + .provider + .as_ref() + .and_then(|provider| provider.metadata.as_ref()) + .map_or("", |metadata| metadata.name.as_str()); + mutation_audit::scoped( + request.workspace_scope.as_ref(), + [mutation_audit::requested("provider", name)], + ) + }; + mutation_audit::audited(targets, mutation_replay::run(&self.state, request)).await } async fn get_provider_credentials( @@ -754,7 +766,19 @@ impl OpenShell for OpenShellService { &self, request: Request, ) -> Result, Status> { - mutation_replay::run(&self.state, request).await + let targets = { + let request = request.get_ref(); + let name = request + .provider + .as_ref() + .and_then(|provider| provider.metadata.as_ref()) + .map_or("", |metadata| metadata.name.as_str()); + mutation_audit::scoped( + request.workspace_scope.as_ref(), + [mutation_audit::requested("provider", name)], + ) + }; + mutation_audit::audited(targets, mutation_replay::run(&self.state, request)).await } async fn get_provider_refresh_status( @@ -768,14 +792,34 @@ impl OpenShell for OpenShellService { &self, request: Request, ) -> Result, Status> { - mutation_replay::run(&self.state, request).await + let targets = { + let request = request.get_ref(); + mutation_audit::scoped( + request.workspace_scope.as_ref(), + [ + mutation_audit::requested("provider", &request.provider), + mutation_audit::requested("provider_credential", &request.credential_key), + ], + ) + }; + mutation_audit::audited(targets, mutation_replay::run(&self.state, request)).await } async fn rotate_provider_credential( &self, request: Request, ) -> Result, Status> { - mutation_replay::run(&self.state, request).await + let targets = { + let request = request.get_ref(); + mutation_audit::scoped( + request.workspace_scope.as_ref(), + [ + mutation_audit::requested("provider", &request.provider), + mutation_audit::requested("provider_credential", &request.credential_key), + ], + ) + }; + mutation_audit::audited(targets, mutation_replay::run(&self.state, request)).await } async fn delete_provider_refresh( @@ -857,7 +901,19 @@ impl OpenShell for OpenShellService { &self, request: Request, ) -> Result, Status> { - mutation_replay::run(&self.state, request).await + let targets = mutation_audit::update_config_targets( + request.get_ref(), + self.state.config.audit.capture_setting_values, + ); + let deleting_only = mutation_audit::deletes_only_a_setting(request.get_ref()); + mutation_audit::audited( + targets, + mutation_audit::record_absent_delete( + deleting_only, + mutation_replay::run(&self.state, request), + ), + ) + .await } async fn get_sandbox_policy_status( @@ -931,42 +987,101 @@ impl OpenShell for OpenShellService { &self, request: Request, ) -> Result, Status> { - mutation_replay::run(&self.state, request).await + let targets = { + let request = request.get_ref(); + mutation_audit::scoped( + request.workspace_scope.as_ref(), + [ + mutation_audit::requested("sandbox", &request.sandbox), + mutation_audit::requested("draft_chunk", &request.chunk_id), + ], + ) + }; + mutation_audit::audited(targets, mutation_replay::run(&self.state, request)).await } async fn reject_draft_chunk( &self, request: Request, ) -> Result, Status> { - mutation_replay::run(&self.state, request).await + let targets = { + let request = request.get_ref(); + mutation_audit::scoped( + request.workspace_scope.as_ref(), + [ + mutation_audit::requested("sandbox", &request.sandbox), + mutation_audit::requested("draft_chunk", &request.chunk_id), + ], + ) + }; + mutation_audit::audited(targets, mutation_replay::run(&self.state, request)).await } async fn approve_all_draft_chunks( &self, request: Request, ) -> Result, Status> { - Box::pin(mutation_replay::run(&self.state, request)).await + let targets = { + let request = request.get_ref(); + let chunks = request + .approvals + .iter() + .map(|approval| mutation_audit::requested("draft_chunk", &approval.chunk_id)); + mutation_audit::scoped( + request.workspace_scope.as_ref(), + std::iter::once(mutation_audit::requested("sandbox", &request.sandbox)) + .chain(chunks), + ) + }; + mutation_audit::audited(targets, mutation_replay::run(&self.state, request)).await } async fn edit_draft_chunk( &self, request: Request, ) -> Result, Status> { - mutation_replay::run(&self.state, request).await + let targets = { + let request = request.get_ref(); + mutation_audit::scoped( + request.workspace_scope.as_ref(), + [ + mutation_audit::requested("sandbox", &request.sandbox), + mutation_audit::requested("draft_chunk", &request.chunk_id), + ], + ) + }; + mutation_audit::audited(targets, mutation_replay::run(&self.state, request)).await } async fn undo_draft_chunk( &self, request: Request, ) -> Result, Status> { - mutation_replay::run(&self.state, request).await + let targets = { + let request = request.get_ref(); + mutation_audit::scoped( + request.workspace_scope.as_ref(), + [ + mutation_audit::requested("sandbox", &request.sandbox), + mutation_audit::requested("draft_chunk", &request.chunk_id), + ], + ) + }; + mutation_audit::audited(targets, mutation_replay::run(&self.state, request)).await } async fn clear_draft_chunks( &self, request: Request, ) -> Result, Status> { - mutation_replay::run(&self.state, request).await + let targets = { + let request = request.get_ref(); + mutation_audit::scoped( + request.workspace_scope.as_ref(), + [mutation_audit::requested("sandbox", &request.sandbox)], + ) + }; + mutation_audit::audited(targets, mutation_replay::run(&self.state, request)).await } async fn get_draft_history( diff --git a/crates/openshell-server/src/grpc/mutation_audit.rs b/crates/openshell-server/src/grpc/mutation_audit.rs index 1bf828e035..6f51302b3f 100644 --- a/crates/openshell-server/src/grpc/mutation_audit.rs +++ b/crates/openshell-server/src/grpc/mutation_audit.rs @@ -8,17 +8,23 @@ use std::future::Future; use openshell_core::proto::datamodel::v1::ObjectMeta; use openshell_core::proto::{ - AddWorkspaceMemberResponse, AttachSandboxProviderResponse, BeginRootfsTarStagingResponse, - CreateWorkspaceResponse, DeleteProviderProfileResponse, DeleteProviderRefreshResponse, - DeleteProviderResponse, DeleteSandboxResponse, DeleteSandboxTemplateResponse, - DeleteServiceResponse, DeleteWorkspaceResponse, DeletionOutcome, DetachSandboxProviderResponse, - ImportProviderProfilesResponse, ProviderProfile, RemoveWorkspaceMemberResponse, Sandbox, - SandboxResponse, SandboxTemplateResponse, ServiceEndpointResponse, - UpdateProviderProfilesResponse, WorkspaceSelector, workspace_selector::Selection, + AddWorkspaceMemberResponse, ApproveAllDraftChunksResponse, ApproveDraftChunkResponse, + AttachSandboxProviderResponse, BeginRootfsTarStagingResponse, ClearDraftChunksResponse, + ConfigureProviderRefreshResponse, CreateWorkspaceResponse, DeleteProviderProfileResponse, + DeleteProviderRefreshResponse, DeleteProviderResponse, DeleteSandboxResponse, + DeleteSandboxTemplateResponse, DeleteServiceResponse, DeleteWorkspaceResponse, DeletionOutcome, + DetachSandboxProviderResponse, EditDraftChunkResponse, ImportProviderProfilesResponse, + ProviderCredentialRefreshStatus, ProviderProfile, ProviderResponse, RejectDraftChunkResponse, + RemoveWorkspaceMemberResponse, RotateProviderCredentialResponse, Sandbox, SandboxResponse, + SandboxTemplateResponse, ServiceEndpointResponse, UndoDraftChunkResponse, UpdateConfigRequest, + UpdateConfigResponse, UpdateProviderProfilesResponse, WorkspaceSelector, setting_value, + workspace_selector::Selection, }; +use openshell_core::settings::{self, SettingValueKind}; use openshell_ocsf::ResourceDetails; use tonic::{Code, Response, Status}; +use super::policy::POLICY_SETTING_KEY; pub(super) use crate::auth::audit::requested; use crate::auth::audit::{self, Outcome}; @@ -212,6 +218,165 @@ impl Audited for AddWorkspaceMemberResponse { impl Audited for BeginRootfsTarStagingResponse {} +impl Audited for ProviderResponse { + fn produced(&self) -> Vec> { + stored( + "provider", + self.provider + .as_ref() + .and_then(|provider| provider.metadata.as_ref()), + ) + } +} + +fn refreshed_provider(status: Option<&ProviderCredentialRefreshStatus>) -> Vec> { + status + .map(|status| Produced { + type_label: "provider", + name: &status.provider, + uid: &status.provider_id, + }) + .into_iter() + .collect() +} + +impl Audited for ConfigureProviderRefreshResponse { + fn produced(&self) -> Vec> { + refreshed_provider(self.status.as_ref()) + } +} + +impl Audited for RotateProviderCredentialResponse { + fn produced(&self) -> Vec> { + refreshed_provider(self.status.as_ref()) + } +} + +/// The policy a call left in place, identified by its hash. +fn stored_policy(hash: &str) -> Vec> { + (!hash.is_empty()) + .then_some(Produced { + type_label: "policy", + name: "", + uid: hash, + }) + .into_iter() + .collect() +} + +impl Audited for UpdateConfigResponse { + fn produced(&self) -> Vec> { + stored_policy(&self.policy_hash) + } +} + +impl Audited for ApproveDraftChunkResponse { + fn produced(&self) -> Vec> { + stored_policy(&self.policy_hash) + } +} + +impl Audited for UndoDraftChunkResponse { + fn produced(&self) -> Vec> { + stored_policy(&self.policy_hash) + } +} + +impl Audited for ApproveAllDraftChunksResponse { + fn produced(&self) -> Vec> { + stored_policy(&self.policy_hash) + } + + fn outcome(&self) -> Option { + (self.chunks_approved == 0).then_some(Outcome::Detail("no_op:unchanged")) + } +} + +impl Audited for ClearDraftChunksResponse { + fn outcome(&self) -> Option { + (self.chunks_cleared == 0).then_some(Outcome::Detail("no_op:already_absent")) + } +} + +impl Audited for RejectDraftChunkResponse {} +impl Audited for EditDraftChunkResponse {} + +/// The resources an `UpdateConfig` call changes, with the setting value it +/// sets when `capture_values` is on. +pub(super) fn update_config_targets( + request: &UpdateConfigRequest, + capture_values: bool, +) -> Vec { + let scope = if request.global { + "global" + } else { + request.sandbox.as_str() + }; + let key = request.setting_key.trim(); + let mut targets = Vec::new(); + if !request.global { + targets.push(requested("sandbox", &request.sandbox)); + } + if key == POLICY_SETTING_KEY { + targets.push(requested("policy", scope)); + } else if !key.is_empty() { + let mut setting = requested("setting", key); + if capture_values + && !request.delete_setting + && let Some(value) = request + .setting_value + .as_ref() + .and_then(|value| value.value.as_ref()) + && let Some(value) = captured_value(key, value) + { + setting = setting.with_data(serde_json::json!({ "value": value })); + } + targets.push(setting); + } + if request.policy.is_some() || !request.merge_operations.is_empty() { + targets.push(requested("policy", scope)); + } + scoped(request.workspace_scope.as_ref(), targets) +} + +/// The value of a registered setting when it has the registered kind and is +/// allowed. Bytes and unregistered keys are never recorded. +fn captured_value(key: &str, value: &setting_value::Value) -> Option { + let setting = settings::setting_for_key(key)?; + match (setting.kind, value) { + (SettingValueKind::String, setting_value::Value::StringValue(value)) + if setting.validate_string_value(value).is_ok() => + { + Some(value.as_str().into()) + } + (SettingValueKind::Bool, setting_value::Value::BoolValue(value)) => Some((*value).into()), + (SettingValueKind::Int, setting_value::Value::IntValue(value)) => Some((*value).into()), + _ => None, + } +} + +/// Whether an `UpdateConfig` call only deletes a setting. +pub(super) fn deletes_only_a_setting(request: &UpdateConfigRequest) -> bool { + request.delete_setting && request.annotations.is_empty() +} + +/// Run an `UpdateConfig` call, recording a delete that removed no setting +/// and changed nothing else as a no-op. +pub(super) async fn record_absent_delete( + deleting_only: bool, + call: impl Future, Status>>, +) -> Result, Status> { + let response = call.await; + if deleting_only + && response + .as_ref() + .is_ok_and(|response| !response.get_ref().deleted) + { + audit::record_outcome(Outcome::Detail("no_op:already_absent")); + } + response +} + /// Run `call`, recording the requested `targets` that have a name before it /// starts, then what it produced and how it ended. The call is boxed because /// handler futures are large. @@ -257,6 +422,7 @@ fn complete(targets: &mut Vec, produced: Vec>) { uid: None, name: None, type_label: Some(produced.type_label.to_string()), + data: None, }); targets.last_mut().expect("target just added") }; @@ -284,7 +450,7 @@ pub(super) fn scoped( #[cfg(test)] mod tests { use super::*; - use crate::auth::audit::test_support::{audited_mutation, cancelled_mutation}; + use crate::auth::audit::test_support::{assert_redacted, audited_mutation, cancelled_mutation}; use crate::auth::principal::Principal; use crate::grpc::OpenShellService; use crate::grpc::test_support::{authed_request, test_server_state}; @@ -304,7 +470,16 @@ mod tests { StartSandboxRequest, StopSandboxRequest, SuspendSandboxRequest, UpdateProviderProfilesRequest, UpdateSandboxRequest, WorkspaceRole, workspace_selector, }; + use openshell_core::proto::{ + ApproveAllDraftChunksRequest, ApproveDraftChunkRequest, ClearDraftChunksRequest, + ConfigureProviderRefreshRequest, CreateProviderRequest, DraftChunkApproval, + EditDraftChunkRequest, NetworkPolicyRule, Provider, RejectDraftChunkRequest, + RotateProviderCredentialRequest, SandboxPolicy, SettingValue, UndoDraftChunkRequest, + UpdateConfigRequest, UpdateProviderRequest, setting_value, + }; use serde_json::{Value, json}; + use std::collections::HashMap; + use std::sync::Arc; fn principal() -> Principal { authed_request(()) @@ -1066,7 +1241,8 @@ mod tests { .await; assert_eq!(event["resources"].as_array().unwrap().len(), 16, "{event}"); - assert_eq!(event["resources"][15]["name"], "profile-15", "{event}"); + assert_eq!(event["resources"][14]["name"], "profile-14", "{event}"); + assert_eq!(event["resources"][15]["name"], "profile-39", "{event}"); assert_eq!( event["message"], "mutation succeeded; 24 more resources not listed", "{event}" @@ -1155,4 +1331,508 @@ mod tests { assert_eq!(event["status_detail"], "no_op:already_absent", "{event}"); assert_eq!(event["resources"], json!([sandbox_with_uid, provider])); } + + const CANARY: &str = "audit-canary-6c1f9e2d"; + + fn named(event: &Value) -> Vec { + event["resources"] + .as_array() + .unwrap() + .iter() + .map(|resource| { + format!( + "{}:{}", + resource["type"].as_str().unwrap(), + resource["name"].as_str().unwrap_or_default() + ) + }) + .collect() + } + + #[tokio::test] + async fn provider_records_name_the_provider_but_never_its_secrets() { + let service = OpenShellService::new(test_server_state().await); + let scope = || Some(workspace_selector("default")); + let provider = Provider { + metadata: Some(ObjectMeta { + name: "audit-openai".into(), + ..Default::default() + }), + r#type: "openai".into(), + credentials: HashMap::from([("OPENAI_API_KEY".into(), CANARY.into())]), + ..Default::default() + }; + + let (result, event) = record( + "CreateProvider", + service.create_provider(authed_request(CreateProviderRequest { + workspace_scope: scope(), + provider: Some(provider), + ..Default::default() + })), + ) + .await; + let created = result.unwrap().into_inner().provider.unwrap(); + assert_eq!( + event["resources"], + json!([ + default_workspace(), + stored_json("provider", created.metadata.as_ref().unwrap()) + ]) + ); + assert_redacted(&event, CANARY); + + let mut update = created.clone(); + update.credential_handles.clear(); + update.credentials = HashMap::from([("OPENAI_API_KEY".into(), format!("{CANARY}-2"))]); + let (_, event) = record( + "UpdateProvider", + service.update_provider(authed_request(UpdateProviderRequest { + workspace_scope: scope(), + provider: Some(update), + ..Default::default() + })), + ) + .await; + assert_eq!( + named(&event), + ["workspace:default", "provider:audit-openai"] + ); + assert_redacted(&event, CANARY); + + let (_, event) = record( + "ConfigureProviderRefresh", + service.configure_provider_refresh(authed_request(ConfigureProviderRefreshRequest { + workspace_scope: scope(), + provider: "audit-openai".into(), + credential_key: "OPENAI_API_KEY".into(), + material: HashMap::from([("client_secret".into(), CANARY.into())]), + ..Default::default() + })), + ) + .await; + assert_eq!( + named(&event), + [ + "workspace:default", + "provider:audit-openai", + "provider_credential:OPENAI_API_KEY" + ] + ); + assert_redacted(&event, CANARY); + + let (_, event) = record( + "RotateProviderCredential", + service.rotate_provider_credential(authed_request(RotateProviderCredentialRequest { + workspace_scope: scope(), + provider: "audit-openai".into(), + credential_key: "OPENAI_API_KEY".into(), + ..Default::default() + })), + ) + .await; + assert_eq!( + named(&event), + [ + "workspace:default", + "provider:audit-openai", + "provider_credential:OPENAI_API_KEY" + ] + ); + } + + #[test] + fn update_config_targets_name_setting_sandbox_and_policy() { + let setting = |key: &str, value| UpdateConfigRequest { + global: true, + setting_key: key.into(), + setting_value: Some(SettingValue { value: Some(value) }), + ..Default::default() + }; + let text = |value: &str| setting_value::Value::StringValue(value.into()); + let targets = |request: &UpdateConfigRequest, capture| { + serde_json::to_value(update_config_targets(request, capture)).unwrap() + }; + + assert_eq!( + targets(&setting("ocsf_schema_version", text("1.8.0")), false), + json!([{"type": "setting", "name": "ocsf_schema_version"}]) + ); + assert_eq!( + targets(&setting("ocsf_schema_version", text("1.8.0")), true), + json!([{"type": "setting", "name": "ocsf_schema_version", "data": {"value": "1.8.0"}}]) + ); + assert_eq!( + targets( + &setting(" ocsf_json_enabled ", setting_value::Value::BoolValue(true)), + true + ), + json!([{"type": "setting", "name": "ocsf_json_enabled", "data": {"value": true}}]) + ); + for rejected in [ + setting("OPENAI_API_KEY", text(CANARY)), + setting("ocsf_json_enabled", text(CANARY)), + setting("proposal_approval_mode", text(CANARY)), + setting( + "ocsf_schema_version", + setting_value::Value::BytesValue(CANARY.into()), + ), + ] { + assert!( + targets(&rejected, true)[0].get("data").is_none(), + "{rejected:?}" + ); + } + let mut delete = setting("ocsf_schema_version", text("1.8.0")); + delete.delete_setting = true; + assert_eq!( + targets(&delete, true), + json!([{"type": "setting", "name": "ocsf_schema_version"}]) + ); + + let sandbox_policy = UpdateConfigRequest { + workspace_scope: Some(workspace_selector("default")), + sandbox: "agent-01".into(), + policy: Some(SandboxPolicy::default()), + ..Default::default() + }; + assert_eq!( + targets(&sandbox_policy, false), + json!([ + default_workspace(), + {"type": "sandbox", "name": "agent-01"}, + {"type": "policy", "name": "agent-01"}, + ]) + ); + let global_policy = UpdateConfigRequest { + global: true, + policy: Some(SandboxPolicy::default()), + ..Default::default() + }; + assert_eq!( + targets(&global_policy, false), + json!([{"type": "policy", "name": "global"}]) + ); + let global_policy_delete = UpdateConfigRequest { + global: true, + setting_key: "policy".into(), + delete_setting: true, + ..Default::default() + }; + assert_eq!( + targets(&global_policy_delete, true), + json!([{"type": "policy", "name": "global"}]) + ); + } + + #[tokio::test] + async fn gateway_records_setting_values_when_configured_to_capture_them() { + let mut state = test_server_state().await; + Arc::get_mut(&mut state) + .expect("unshared test state") + .config + .audit + .capture_setting_values = true; + let service = OpenShellService::new(state); + + let (result, event) = record( + "UpdateConfig", + service.update_config(authed_request(UpdateConfigRequest { + global: true, + setting_key: "ocsf_json_enabled".into(), + setting_value: Some(SettingValue { + value: Some(setting_value::Value::BoolValue(true)), + }), + ..Default::default() + })), + ) + .await; + + result.unwrap(); + assert_eq!( + event["resources"], + json!([{"type": "setting", "name": "ocsf_json_enabled", "data": {"value": true}}]), + "{event}" + ); + } + + #[tokio::test] + async fn long_setting_values_are_bounded() { + let request = UpdateConfigRequest { + global: true, + setting_key: "ocsf_schema_version".into(), + setting_value: Some(SettingValue { + value: Some(setting_value::Value::StringValue("v".repeat(300))), + }), + ..Default::default() + }; + let (_, event) = record( + "UpdateConfig", + audited(update_config_targets(&request, true), async { + Ok(Response::new(UpdateConfigResponse::default())) + }), + ) + .await; + + assert_eq!( + event["resources"][0]["data"]["value"], + format!("{}...", "v".repeat(128)), + "{event}" + ); + } + + #[tokio::test] + async fn denied_setting_values_are_bounded() { + let request = UpdateConfigRequest { + global: true, + setting_key: "ocsf_schema_version".into(), + setting_value: Some(SettingValue { + value: Some(setting_value::Value::StringValue("v".repeat(300))), + }), + ..Default::default() + }; + let (result, event) = record( + "UpdateConfig", + audited(update_config_targets(&request, true), async { + Err::, _>(audit::deny( + &principal(), + audit::AuthzDenial::MissingRole, + "admin role required", + )) + }), + ) + .await; + + assert_eq!(result.unwrap_err().code(), Code::PermissionDenied); + assert_eq!(event["status_detail"], "missing_role", "{event}"); + assert_eq!( + event["resources"][0]["data"]["value"], + format!("{}...", "v".repeat(128)), + "{event}" + ); + } + + #[tokio::test] + async fn deleting_a_setting_while_annotating_is_not_a_no_op() { + let request = UpdateConfigRequest { + sandbox: "agent-01".into(), + setting_key: "ocsf_json_enabled".into(), + delete_setting: true, + annotations: HashMap::from([("ticket".into(), "OPS-1".into())]), + ..Default::default() + }; + let (_, event) = record( + "UpdateConfig", + record_absent_delete(deletes_only_a_setting(&request), async { + Ok(Response::new(UpdateConfigResponse::default())) + }), + ) + .await; + + assert!(event.get("status_detail").is_none(), "{event}"); + } + + #[tokio::test] + async fn deleting_an_absent_global_setting_records_a_no_op() { + let service = OpenShellService::new(test_server_state().await); + + let (result, event) = record( + "UpdateConfig", + service.update_config(authed_request(UpdateConfigRequest { + global: true, + setting_key: "ocsf_json_enabled".into(), + delete_setting: true, + ..Default::default() + })), + ) + .await; + + assert!(!result.unwrap().into_inner().deleted); + assert_eq!(event["status_detail"], "no_op:already_absent", "{event}"); + assert_eq!( + event["resources"], + json!([{"type": "setting", "name": "ocsf_json_enabled"}]) + ); + } + + #[tokio::test] + async fn draft_chunk_records_name_chunks_but_never_tokens_or_rules() { + let service = OpenShellService::new(test_server_state().await); + let scope = || Some(workspace_selector("default")); + let chunk_targets = [ + "workspace:default", + "sandbox:missing-sbx", + "draft_chunk:chunk-1", + ]; + + let (_, event) = record( + "ApproveDraftChunk", + service.approve_draft_chunk(authed_request(ApproveDraftChunkRequest { + workspace_scope: scope(), + sandbox: "missing-sbx".into(), + chunk_id: "chunk-1".into(), + review_token: CANARY.into(), + ..Default::default() + })), + ) + .await; + assert_eq!(named(&event), chunk_targets); + assert_redacted(&event, CANARY); + + let (_, event) = record( + "RejectDraftChunk", + service.reject_draft_chunk(authed_request(RejectDraftChunkRequest { + workspace_scope: scope(), + sandbox: "missing-sbx".into(), + chunk_id: "chunk-1".into(), + reason: CANARY.into(), + ..Default::default() + })), + ) + .await; + assert_eq!(named(&event), chunk_targets); + assert_redacted(&event, CANARY); + + let (_, event) = record( + "EditDraftChunk", + service.edit_draft_chunk(authed_request(EditDraftChunkRequest { + workspace_scope: scope(), + sandbox: "missing-sbx".into(), + chunk_id: "chunk-1".into(), + proposed_rule: Some(NetworkPolicyRule { + name: CANARY.into(), + ..Default::default() + }), + ..Default::default() + })), + ) + .await; + assert_eq!(named(&event), chunk_targets); + assert_redacted(&event, CANARY); + + let (_, event) = record( + "UndoDraftChunk", + service.undo_draft_chunk(authed_request(UndoDraftChunkRequest { + workspace_scope: scope(), + sandbox: "missing-sbx".into(), + chunk_id: "chunk-1".into(), + ..Default::default() + })), + ) + .await; + assert_eq!(named(&event), chunk_targets); + + let (_, event) = record( + "ApproveAllDraftChunks", + service.approve_all_draft_chunks(authed_request(ApproveAllDraftChunksRequest { + workspace_scope: scope(), + sandbox: "missing-sbx".into(), + approvals: vec![DraftChunkApproval { + chunk_id: "chunk-1".into(), + review_token: CANARY.into(), + }], + ..Default::default() + })), + ) + .await; + assert_eq!(named(&event), chunk_targets); + assert_redacted(&event, CANARY); + + let (_, event) = record( + "ClearDraftChunks", + service.clear_draft_chunks(authed_request(ClearDraftChunksRequest { + workspace_scope: scope(), + sandbox: "missing-sbx".into(), + ..Default::default() + })), + ) + .await; + assert_eq!(named(&event), ["workspace:default", "sandbox:missing-sbx"]); + } + + #[tokio::test] + async fn draft_chunk_responses_name_the_policy_or_record_a_no_op() { + let (_, event) = record( + "ApproveDraftChunk", + audited(Vec::new(), async { + Ok(Response::new(ApproveDraftChunkResponse { + policy_version: 4, + policy_hash: "sha256:abc".into(), + })) + }), + ) + .await; + assert_eq!( + event["resources"], + json!([{"type": "policy", "uid": "sha256:abc"}]) + ); + + let (_, event) = record( + "ApproveAllDraftChunks", + audited(Vec::new(), async { + Ok(Response::new(ApproveAllDraftChunksResponse::default())) + }), + ) + .await; + assert_eq!(event["status_detail"], "no_op:unchanged", "{event}"); + + let (_, event) = record( + "ClearDraftChunks", + audited(Vec::new(), async { + Ok(Response::new(ClearDraftChunksResponse::default())) + }), + ) + .await; + assert_eq!(event["status_detail"], "no_op:already_absent", "{event}"); + } + + #[tokio::test] + async fn bulk_approvals_keep_the_resulting_policy() { + let targets = scoped( + Some(&workspace_selector("default")), + std::iter::once(requested("sandbox", "agent-01")) + .chain((0..20).map(|n| requested("draft_chunk", &format!("chunk-{n}")))), + ); + let (_, event) = record( + "ApproveAllDraftChunks", + audited(targets, async { + Ok(Response::new(ApproveAllDraftChunksResponse { + policy_hash: "sha256:abc".into(), + chunks_approved: 20, + ..Default::default() + })) + }), + ) + .await; + + assert_eq!(event["resources"].as_array().unwrap().len(), 16, "{event}"); + assert_eq!( + event["resources"][15], + json!({"type": "policy", "uid": "sha256:abc"}) + ); + assert_eq!( + event["message"], "mutation succeeded; 7 more resources not listed", + "{event}" + ); + } + + #[tokio::test] + async fn refresh_status_errors_are_never_recorded() { + let (_, event) = record( + "ConfigureProviderRefresh", + audited(Vec::new(), async { + Ok(Response::new(ConfigureProviderRefreshResponse { + status: Some(ProviderCredentialRefreshStatus { + provider: "audit-openai".into(), + last_error: CANARY.into(), + ..Default::default() + }), + })) + }), + ) + .await; + + assert_eq!(named(&event), ["provider:audit-openai"]); + assert_redacted(&event, CANARY); + } } diff --git a/crates/openshell-server/src/grpc/policy.rs b/crates/openshell-server/src/grpc/policy.rs index 547dfa1808..40819e7b37 100644 --- a/crates/openshell-server/src/grpc/policy.rs +++ b/crates/openshell-server/src/grpc/policy.rs @@ -133,7 +133,7 @@ const GLOBAL_SETTINGS_NAME: &str = "global"; pub const SANDBOX_SETTINGS_OBJECT_TYPE: &str = "sandbox_settings"; const PROVIDER_COMPOSITION_VALIDATION_PAGE_SIZE: u32 = 1000; /// Reserved settings key used to store global policy payload. -const POLICY_SETTING_KEY: &str = "policy"; +pub(super) const POLICY_SETTING_KEY: &str = "policy"; /// Sentinel `sandbox_id` used to store global policy revisions. const GLOBAL_POLICY_SANDBOX_ID: &str = "__global__"; /// Stable labels used when stored policy state fails validation. diff --git a/docs/how-it-works/gateways/configuration.mdx b/docs/how-it-works/gateways/configuration.mdx index 52bb44113d..e78171ba15 100644 --- a/docs/how-it-works/gateways/configuration.mdx +++ b/docs/how-it-works/gateways/configuration.mdx @@ -435,6 +435,9 @@ allow_unauthenticated_users = false enabled = false operator_enabled = false # Opt-in: trusted OU=operator grants gateway-wide administration. +[openshell.gateway.audit] +capture_setting_values = false # Opt-in: record setting values in mutation records. + # OTLP export. Omit this table entirely to disable it. [openshell.gateway.otlp] endpoint = "http://otel-collector.observability.svc:4317" @@ -797,6 +800,21 @@ Metrics include `openshell_ocsf_log_queued_total`, `openshell_ocsf_log_written_t Allow enough retention and disk space for shipper outages. Graceful shutdown allows five seconds for draining; outstanding OS writes remain uncertain if they outlast that budget. Flush does not mean fsync. The file is a best-effort collection boundary, not durable acceptance, a replay protocol, or proof of a complete audit history. See [OCSF JSON export](/observability/ocsf-json-export) for the separate sandbox-local output. +## Gateway Mutation Records + +`[openshell.gateway.audit]` adds optional details to [gateway mutation records](/observability/ocsf-json-export#gateway-mutation-records). + +```toml +[openshell.gateway.audit] +capture_setting_values = true +``` + +| Field | Default | Behavior | +|---|---|---| +| `capture_setting_values` | `false` | Record the value an `UpdateConfig` call sets for a registered setting. | + +Unknown fields are rejected. Restart the gateway after changing this configuration. + ## OTLP Export `[openshell.gateway.otlp]` enables OpenTelemetry export over OTLP. Omit the table to disable export. Its `endpoint` is the default collector for each signal and, on its own, enables trace export. `[openshell.gateway.otlp.traces]` sends spans to a different collector. OTLP metrics are off until `[openshell.gateway.otlp.metrics]` sets `enabled = true`, OCSF log export is off until `[openshell.gateway.otlp.ocsf]` sets `enabled = true`, and the [agent trace relay](#agent-trace-relay) is off until `[openshell.gateway.otlp.agent]` sets `enabled = true`. Each signal can use its own collector. [OTLP Collectors](/observability/overview#otlp-collectors) shows where each signal goes. diff --git a/docs/observability/ocsf-json-export.mdx b/docs/observability/ocsf-json-export.mdx index 875bc04812..2d89f728c8 100644 --- a/docs/observability/ocsf-json-export.mdx +++ b/docs/observability/ocsf-json-export.mdx @@ -66,7 +66,7 @@ The gateway also emits an API Activity event for each call a user or mTLS operat `resources` names the workspace and the resources the call acted on. -Records never include request or response bodies. +Records never include credentials, tokens, environment variables, or standard input. Setting values appear only when [enabled](/how-it-works/gateways/configuration#gateway-mutation-records). Without JSONL enabled, gateway OCSF events still appear as shorthand in console output, subject to the diagnostic log filter. Events associated with a sandbox also appear in its gateway log stream; gateway-wide events have no sandbox association.