fix(sandbox): log L7 parse denials (#1072)

Signed-off-by: John Myers <9696606+johntmyers@users.noreply.github.com>

Author: johntmyers

architecture/sandbox.md

@@ -1227,7 +1227,7 @@ Implements `L7Provider` for HTTP/1.1:
 
 `relay_with_inspection()` in `crates/openshell-sandbox/src/l7/relay.rs` is the main relay loop:
 
-1. Parse one HTTP request from client via the provider
+1. Parse one HTTP request from client via the provider. Parser and path-canonicalization failures close the connection and emit a denied OCSF network event with the rejection reason in `status_detail`.
 2. Resolve credential placeholders in the request target via `rewrite_target_for_eval()`. OPA receives the redacted path (`[CREDENTIAL]` markers); the resolved path goes only to upstream. If resolution fails, return HTTP 500 and close the connection.
 3. Build L7 input JSON with `request.method`, the **redacted** `request.path`, `request.query_params`, plus the CONNECT-level context (host, port, binary, ancestors, cmdline)
 4. Evaluate `data.openshell.sandbox.allow_request` and `data.openshell.sandbox.request_deny_reason`
@@ -1580,7 +1580,7 @@ The sandbox uses `miette` for error reporting and `thiserror` for typed errors.
 | Credential injection: resolved value contains CR/LF/null | Placeholder treated as unresolvable, fail-closed |
 | Credential injection: path credential contains traversal/separator | HTTP 500, connection closed (fail-closed) |
 | Credential injection: percent-encoded placeholder bypass attempt | HTTP 500, connection closed (fail-closed) |
-| L7 parse error | Close the connection |
+| L7 parse or path-canonicalization error | Emit denied OCSF network event with `status_detail`, close the connection |
 | SSH socket bind failure | Fatal -- reported through the readiness channel and aborts startup |
 | SSH server accept failure | Async task error logged, main process unaffected |
 | Supervisor session: connect failure | Emit `session_failed` OCSF event, sleep with exponential backoff (1s -> 30s) and reconnect |

crates/openshell-sandbox/src/l7/relay.rs

@@ -13,7 +13,7 @@ use crate::secrets::{self, SecretResolver};
 use miette::{IntoDiagnostic, Result, miette};
 use openshell_ocsf::{
     ActionId, ActivityId, DispositionId, Endpoint, HttpActivityBuilder, HttpRequest,
-    NetworkActivityBuilder, SeverityId, Url as OcsfUrl, ocsf_emit,
+    NetworkActivityBuilder, SeverityId, StatusId, Url as OcsfUrl, ocsf_emit,
 };
 use std::sync::{Arc, Mutex};
 use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt};
@@ -37,6 +37,50 @@ pub struct L7EvalContext {
     pub(crate) secret_resolver: Option<Arc<SecretResolver>>,
 }
 
+#[derive(Debug, Clone, Copy)]
+enum ParseRejectionMode {
+    L7Endpoint,
+    Passthrough,
+}
+
+fn parse_rejection_detail(error: &str, mode: ParseRejectionMode) -> String {
+    if error.contains("encoded '/' (%2F)") {
+        match mode {
+            ParseRejectionMode::L7Endpoint => format!(
+                "{error}; set allow_encoded_slash: true on this endpoint if the upstream requires encoded slashes"
+            ),
+            ParseRejectionMode::Passthrough => format!(
+                "{error}; passthrough credential relay uses strict path parsing, so configure this endpoint with protocol: rest and allow_encoded_slash: true for encoded-slash APIs, or use tls: skip if HTTP parsing is not needed"
+            ),
+        }
+    } else {
+        error.to_string()
+    }
+}
+
+fn emit_parse_rejection(ctx: &L7EvalContext, detail: &str, engine_type: &str) {
+    let policy_name = if ctx.policy_name.is_empty() {
+        "-"
+    } else {
+        &ctx.policy_name
+    };
+    let event = NetworkActivityBuilder::new(crate::ocsf_ctx())
+        .activity(ActivityId::Open)
+        .action(ActionId::Denied)
+        .disposition(DispositionId::Blocked)
+        .severity(SeverityId::Medium)
+        .status(StatusId::Failure)
+        .dst_endpoint(Endpoint::from_domain(&ctx.host, ctx.port))
+        .firewall_rule(policy_name, engine_type)
+        .message(format!(
+            "HTTP request rejected before policy evaluation for {}:{}",
+            ctx.host, ctx.port
+        ))
+        .status_detail(detail)
+        .build();
+    ocsf_emit!(event);
+}
+
 /// Run protocol-aware L7 inspection on a tunnel.
 ///
 /// This replaces `copy_bidirectional` for L7-enabled endpoints.
@@ -150,13 +194,9 @@ where
                         "L7 connection closed"
                     );
                 } else {
-                    let event = NetworkActivityBuilder::new(crate::ocsf_ctx())
-                        .activity(ActivityId::Fail)
-                        .severity(SeverityId::Low)
-                        .dst_endpoint(Endpoint::from_domain(&ctx.host, ctx.port))
-                        .message(format!("HTTP parse error in L7 relay: {e}"))
-                        .build();
-                    ocsf_emit!(event);
+                    let detail =
+                        parse_rejection_detail(&e.to_string(), ParseRejectionMode::L7Endpoint);
+                    emit_parse_rejection(ctx, &detail, "l7");
                 }
                 return Ok(()); // Close connection on parse error
             }
@@ -394,7 +434,10 @@ where
                 if is_benign_connection_error(&e) {
                     break;
                 }
-                return Err(e);
+                let detail =
+                    parse_rejection_detail(&e.to_string(), ParseRejectionMode::Passthrough);
+                emit_parse_rejection(ctx, &detail, "http-parser");
+                return Ok(());
             }
         };
 
@@ -468,3 +511,41 @@ where
 
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_rejection_detail_adds_l7_hint_for_encoded_slash() {
+        let detail = parse_rejection_detail(
+            "HTTP request-target rejected: request-target contains an encoded '/' (%2F) which is not allowed on this endpoint",
+            ParseRejectionMode::L7Endpoint,
+        );
+
+        assert!(detail.contains("allow_encoded_slash: true"));
+        assert!(detail.contains("upstream requires encoded slashes"));
+    }
+
+    #[test]
+    fn parse_rejection_detail_adds_passthrough_hint_for_encoded_slash() {
+        let detail = parse_rejection_detail(
+            "HTTP request-target rejected: request-target contains an encoded '/' (%2F) which is not allowed on this endpoint",
+            ParseRejectionMode::Passthrough,
+        );
+
+        assert!(detail.contains("protocol: rest"));
+        assert!(detail.contains("allow_encoded_slash: true"));
+        assert!(detail.contains("tls: skip"));
+    }
+
+    #[test]
+    fn parse_rejection_detail_preserves_other_errors() {
+        let error = "HTTP headers contain invalid UTF-8";
+
+        assert_eq!(
+            parse_rejection_detail(error, ParseRejectionMode::L7Endpoint),
+            error
+        );
+    }
+}

docs/observability/logging.mdx

@@ -169,6 +169,7 @@ Common reason phrases emitted by the sandbox include:
 | `resolves to <ip> which is not in allowed_ips, connection rejected` | The destination resolved to an IP outside the policy's `allowed_ips` allowlist. |
 | `DNS resolution failed for <host>:<port>` | The proxy could not resolve the destination. |
 | `port <n> is a blocked control-plane port, connection rejected` | The destination port matches a control-plane port (etcd, Kubernetes API, kubelet) and is always blocked. |
+| `request-target contains an encoded '/' (%2F)` | The L7 HTTP parser rejected an encoded slash. Configure `allow_encoded_slash: true` on a REST endpoint when the upstream requires encoded slashes. |
 | `l7 deny` | An L7 policy rule denied the request. |
 
 Invalid `allowed_ips` entries and entries that overlap always-blocked ranges are rejected at policy-load time, so they never reach the runtime denial path. The phrases above come from the proxy's per-CONNECT `allowed_ips` and SSRF checks, not from policy validation.