fix(sandbox): add explicit logging when symlink resolution fails and improve deny messages

When /proc/<pid>/root/ is inaccessible (restricted ptrace, rootless
containers, hardened hosts), resolve_binary_in_container now logs a
per-binary warning with the specific error, the path it tried, and
actionable guidance (use canonical path or grant CAP_SYS_PTRACE).
Previously this was completely silent.

The Rego deny reason for binary mismatches now leads with 'SYMLINK HINT'
and includes a concrete fix command ('readlink -f' inside the sandbox)
plus what to look for in logs if automatic resolution isn't working.

Author: johntmyers

crates/openshell-sandbox/data/sandbox-policy.rego

@@ -47,7 +47,7 @@ deny_reason := reason if {
 		policy := data.network_policies[name]
 		endpoint_allowed(policy, input.network)
 		not binary_allowed(policy, input.exec)
-		r := sprintf("binary '%s' (ancestors: [%s], cmdline: [%s]) not allowed in policy '%s' (hint: binary path is kernel-resolved via /proc/<pid>/exe; if you specified a symlink like /usr/bin/python3, the actual binary may be /usr/bin/python3.11)", [input.exec.path, ancestors_str, cmdline_str, name])
+		r := sprintf("binary '%s' not allowed in policy '%s' (ancestors: [%s], cmdline: [%s]). SYMLINK HINT: the binary path is the kernel-resolved target from /proc/<pid>/exe, not the symlink. If your policy specifies a symlink (e.g., /usr/bin/python3) but the actual binary is /usr/bin/python3.11, either: (1) use the canonical path in your policy (run 'readlink -f /usr/bin/python3' inside the sandbox), or (2) ensure symlink resolution is working (check sandbox logs for 'Cannot access container filesystem')", [input.exec.path, name, ancestors_str, cmdline_str])
 	]
 	all_reasons := array.concat(endpoint_misses, binary_misses)
 	count(all_reasons) > 0

crates/openshell-sandbox/src/lib.rs

@@ -718,17 +718,24 @@ pub async fn run_sandbox(
     // accessible via /proc/<pid>/root/. This expands symlinks like
     // /usr/bin/python3 → /usr/bin/python3.11 in the OPA policy data so that
     // either path matches at evaluation time.
+    //
+    // If /proc/<pid>/root/ is inaccessible (restricted ptrace, rootless
+    // container, etc.), resolve_binary_in_container logs a warning per binary
+    // and falls back to literal path matching. The reload itself still
+    // succeeds — only the symlink expansion is skipped.
     if let (Some(engine), Some(proto)) = (&opa_engine, &retained_proto) {
         let pid = handle.pid();
         if let Err(e) = engine.reload_from_proto_with_pid(proto, pid) {
             warn!(
                 error = %e,
-                "Failed to resolve binary symlinks in policy (non-fatal)"
+                "Failed to rebuild OPA engine with symlink resolution (non-fatal, \
+                 falling back to literal path matching)"
             );
         } else {
             info!(
                 pid = pid,
-                "Resolved policy binary symlinks via container filesystem"
+                "Policy binary symlink resolution attempted via container filesystem \
+                 (check logs above for per-binary results)"
             );
         }
     }

crates/openshell-sandbox/src/opa.rs

@@ -645,14 +645,45 @@ fn resolve_binary_in_container(policy_path: &str, entrypoint_pid: u32) -> Option
 
     let container_path = format!("/proc/{entrypoint_pid}/root{policy_path}");
 
-    // Quick check: is this even a symlink?
-    let meta = std::fs::symlink_metadata(&container_path).ok()?;
+    // Check if we can access the container filesystem at all.
+    // Failure here means /proc/<pid>/root/ is inaccessible (missing
+    // CAP_SYS_PTRACE, restricted ptrace scope, rootless container, etc.).
+    let meta = match std::fs::symlink_metadata(&container_path) {
+        Ok(m) => m,
+        Err(e) => {
+            tracing::warn!(
+                path = %policy_path,
+                container_path = %container_path,
+                pid = entrypoint_pid,
+                error = %e,
+                "Cannot access container filesystem for symlink resolution; \
+                 binary paths in policy will be matched literally. If a policy \
+                 binary is a symlink (e.g., /usr/bin/python3 -> python3.11), \
+                 use the canonical path instead, or run with CAP_SYS_PTRACE"
+            );
+            return None;
+        }
+    };
+
+    // Not a symlink — no expansion needed (this is the common, expected case)
     if !meta.file_type().is_symlink() {
         return None;
     }
 
     // Resolve through the container's filesystem (handles multi-level symlinks)
-    let canonical = std::fs::canonicalize(&container_path).ok()?;
+    let canonical = match std::fs::canonicalize(&container_path) {
+        Ok(c) => c,
+        Err(e) => {
+            tracing::warn!(
+                path = %policy_path,
+                pid = entrypoint_pid,
+                error = %e,
+                "Symlink detected but canonicalize failed; \
+                 binary will be matched by original path only"
+            );
+            return None;
+        }
+    };
 
     // Strip the /proc/<pid>/root prefix to get the in-container absolute path
     let prefix = format!("/proc/{entrypoint_pid}/root");
@@ -663,7 +694,7 @@ fn resolve_binary_in_container(policy_path: &str, entrypoint_pid: u32) -> Option
     if resolved_str == policy_path {
         None
     } else {
-        tracing::debug!(
+        tracing::info!(
             original = %policy_path,
             resolved = %resolved_str,
             pid = entrypoint_pid,
@@ -3251,7 +3282,7 @@ network_policies:
 
     #[test]
     fn deny_reason_includes_symlink_hint() {
-        // Verify the deny reason includes the symlink hint for debugging
+        // Verify the deny reason includes an actionable symlink hint
         let engine = test_engine();
         let input = NetworkInput {
             host: "api.anthropic.com".into(),
@@ -3264,8 +3295,13 @@ network_policies:
         let decision = engine.evaluate_network(&input).unwrap();
         assert!(!decision.allowed);
         assert!(
-            decision.reason.contains("kernel-resolved"),
-            "Deny reason should include symlink hint, got: {}",
+            decision.reason.contains("SYMLINK HINT"),
+            "Deny reason should include prominent symlink hint, got: {}",
+            decision.reason
+        );
+        assert!(
+            decision.reason.contains("readlink -f"),
+            "Deny reason should include actionable fix command, got: {}",
             decision.reason
         );
     }