Skip to content

Commit 0dcc165

Browse files
authored
feat(proxy): support plain HTTP forward proxy for private IP endpoints (#158)
* feat(proxy): support plain HTTP forward proxy for private IP endpoints Add forward proxy mode to the sandbox proxy so that standard HTTP libraries (httpx, requests, etc.) work with HTTP_PROXY for plain HTTP calls to private IP endpoints. Previously, non-CONNECT methods were unconditionally rejected with 403. The forward proxy path requires all three conditions to be met: - OPA policy explicitly allows the destination - The matched endpoint has allowed_ips configured - All resolved IPs are RFC 1918 private This ensures plain HTTP never reaches the public internet while enabling seamless access to internal services without custom CONNECT tunnel code. Implementation: - parse_proxy_uri(): parses absolute-form URIs into components - rewrite_forward_request(): rewrites to origin-form, strips hop-by-hop headers, adds Via and Connection: close - handle_forward_proxy(): full handler with OPA eval, SSRF checks, private-IP gate, upstream connect, and bidirectional relay - Updated dispatch in handle_tcp_connection to route non-CONNECT methods Includes 14 unit tests and 6 E2E tests (FWD-1 through FWD-6). CONNECT path remains completely untouched. Closes #155 * fix(proxy): remove InspectForInference match arm removed by #146 The inference routing simplification in #146 reduced NetworkAction to Allow/Deny, removing InspectForInference. Drop the dead match arm from handle_forward_proxy. * fix(sandbox): restore BestEffort as default Landlock compatibility The Landlock V2 upgrade in #151 changed the default from BestEffort to HardRequirement. This causes all proxy-mode sandboxes to crash with Permission denied when the policy omits the landlock field, because the child process gets locked to only /etc/navigator-tls and /sandbox. Restore BestEffort as the default so policies without an explicit landlock field degrade gracefully. Fixes #161 * fix(sandbox): inject baseline filesystem paths for proxy-mode sandboxes Proxy-mode sandboxes need baseline filesystem paths (/usr, /lib, /etc, /app, /var/log read-only; /sandbox, /tmp read-write) for the child process to function under Landlock. Without these, the child can't exec binaries, resolve DNS, or load shared libraries. The supervisor now enriches the policy with these baseline paths at startup, covering both standalone (file) and gateway (gRPC) modes. For gateway mode, the enriched policy is synced back so users see the effective policy via 'nemoclaw sandbox get'. The gateway validation is relaxed to allow additive filesystem changes (new paths can be added, existing paths cannot be removed) to support the supervisor's enrichment sync-back. Includes 2 E2E tests: BFS-1 (missing filesystem_policy) and BFS-2 (incomplete filesystem_policy). Fixes #161 * fix(e2e): update assertion for relaxed filesystem validation message --------- Co-authored-by: John Myers <[email protected]>
1 parent 683c569 commit 0dcc165

8 files changed

Lines changed: 1397 additions & 35 deletions

File tree

‎architecture/security-policy.md‎

Lines changed: 133 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -492,13 +492,22 @@ When `network_policies` is empty, the OPA engine denies all outbound connections
492492

493493
**Gateway-side validation**: The `validate_network_mode_unchanged()` function on the server still rejects live policy updates that would add `network_policies` to a sandbox created without them or remove all `network_policies` from a sandbox created with them. This prevents unexpected behavioral changes in the OPA allow/deny logic. See `crates/navigator-server/src/grpc.rs` -- `validate_network_mode_unchanged()`.
494494

495+
**Proxy sub-modes**: In proxy mode, the proxy handles two distinct request types:
496+
497+
| Client sends | Proxy behavior | Typical use case |
498+
|---|---|---|
499+
| `CONNECT host:port` | CONNECT tunnel (bidirectional TCP relay or L7 inspection) | HTTPS to any destination, HTTP through an opaque tunnel |
500+
| `GET http://host/path HTTP/1.1` (absolute-form) | **Forward proxy** — rewrites to origin-form & relays | Plain HTTP to private IP endpoints |
501+
502+
See [Behavioral Trigger: Forward Proxy Mode](#behavioral-trigger-forward-proxy-mode) for full details on the forward proxy path.
503+
495504
```mermaid
496505
flowchart LR
497506
SANDBOX[Sandbox Startup] --> PROXY[Proxy Mode<br/>Always Active]
498507
499508
PROXY --> SECCOMP_ALLOW["seccomp: allow AF_INET + AF_INET6<br/>block AF_NETLINK, AF_PACKET, etc."]
500509
PROXY --> NETNS["Create network namespace<br/>veth pair: 10.200.0.1 ↔ 10.200.0.2"]
501-
PROXY --> START_PROXY["Start HTTP CONNECT proxy<br/>bound to veth host IP"]
510+
PROXY --> START_PROXY["Start HTTP proxy<br/>bound to veth host IP"]
502511
PROXY --> ENVVARS["Set HTTP_PROXY, HTTPS_PROXY,<br/>ALL_PROXY on child process"]
503512
504513
START_PROXY --> CONNECT{CONNECT request}
@@ -522,6 +531,94 @@ This is the single most important behavioral trigger in the policy language. An
522531

523532
**Validation requirement**: When `protocol` is set, either `rules` or `access` must also be present. An endpoint with `protocol` but no rules/access is rejected at validation time because it would deny all traffic (no allow rules means nothing matches). See `crates/navigator-sandbox/src/l7/mod.rs` -- `validate_l7_policies()`.
524533

534+
### Behavioral Trigger: Forward Proxy Mode
535+
536+
**Trigger**: A non-CONNECT HTTP method with an absolute-form URI (e.g., `GET http://host:port/path HTTP/1.1`).
537+
538+
When a client sets `HTTP_PROXY` and makes a plain `http://` request, standard HTTP libraries send a **forward proxy request** instead of a CONNECT tunnel. The proxy handles these requests via the forward proxy path rather than the CONNECT path.
539+
540+
**Security constraint**: Forward proxy mode is restricted to **private IP endpoints** that are explicitly allowed by policy. Plain HTTP traffic never reaches the public internet. All three conditions must be true:
541+
542+
1. OPA policy explicitly allows the destination (`action=allow`)
543+
2. The matched endpoint has `allowed_ips` configured
544+
3. All resolved IP addresses are RFC 1918 private (`10/8`, `172.16/12`, `192.168/16`)
545+
546+
If any condition fails, the proxy returns `403 Forbidden`.
547+
548+
| Condition | Forward proxy | CONNECT |
549+
|---|---|---|
550+
| Public IP, no `allowed_ips` | 403 | Allowed (standard SSRF check) |
551+
| Public IP, with `allowed_ips` | 403 (private-IP gate) | Allowed if IP in allowlist |
552+
| Private IP, no `allowed_ips` | 403 | 403 (SSRF block) |
553+
| Private IP, with `allowed_ips` | **Allowed** | Allowed |
554+
| `https://` scheme | 403 (must use CONNECT) | N/A |
555+
556+
**Request processing**: When a forward proxy request is accepted, the proxy:
557+
558+
1. Parses the absolute-form URI to extract scheme, host, port, and path (`parse_proxy_uri`)
559+
2. Rejects `https://` — clients must use CONNECT for TLS
560+
3. Evaluates OPA policy (same `evaluate_opa_tcp` as CONNECT)
561+
4. Requires `allowed_ips` on the matched endpoint
562+
5. Resolves DNS and validates all IPs are private and within `allowed_ips`
563+
6. Connects to upstream
564+
7. Rewrites the request: absolute-form → origin-form (`GET /path HTTP/1.1`), strips hop-by-hop headers, adds `Via: 1.1 navigator-sandbox` and `Connection: close`
565+
8. Forwards the rewritten request, then relays bidirectionally using `tokio::io::copy_bidirectional` (supports chunked transfer, SSE streams, and other long-lived responses with no idle timeout)
566+
567+
**V1 simplifications**: Forward proxy v1 injects `Connection: close` (no keep-alive) and does not perform L7 inspection on the forwarded traffic. Every forward proxy connection handles exactly one request-response exchange.
568+
569+
**Implementation**: See `crates/navigator-sandbox/src/proxy.rs` -- `handle_forward_proxy()`, `parse_proxy_uri()`, `rewrite_forward_request()`.
570+
571+
**Logging**: Forward proxy requests are logged distinctly from CONNECT:
572+
573+
```
574+
FORWARD method=GET dst_host=10.86.8.223 dst_port=8000 path=/screenshot/ action=allow policy=computer-control
575+
```
576+
577+
```mermaid
578+
flowchart TD
579+
A["Non-CONNECT request received<br/>e.g. GET http://host/path"] --> B["parse_proxy_uri(uri)"]
580+
B --> C{Scheme = http?}
581+
C -- No --> D["403 Forbidden<br/>(HTTPS must use CONNECT)"]
582+
C -- Yes --> E["OPA policy evaluation"]
583+
E --> F{Allowed?}
584+
F -- No --> G["403 Forbidden"]
585+
F -- Yes --> H{allowed_ips on endpoint?}
586+
H -- No --> I["403 Forbidden<br/>(forward proxy requires allowed_ips)"]
587+
H -- Yes --> J["resolve_and_check_allowed_ips()"]
588+
J --> K{All IPs private<br/>AND in allowlist?}
589+
K -- No --> L["403 Forbidden"]
590+
K -- Yes --> M["TCP connect to upstream"]
591+
M --> N["Rewrite request to origin-form<br/>Add Via + Connection: close"]
592+
N --> O["Forward request + copy_bidirectional"]
593+
```
594+
595+
#### Example: Forward Proxy Policy
596+
597+
The same policy that enables CONNECT to a private endpoint also enables forward proxy access. No new policy fields are needed:
598+
599+
```yaml
600+
network_policies:
601+
computer_control:
602+
name: computer-control
603+
endpoints:
604+
- host: 10.86.8.223
605+
port: 8000
606+
allowed_ips:
607+
- "10.86.8.223/32"
608+
binaries:
609+
- { path: /usr/local/bin/python3.12 }
610+
```
611+
612+
With this policy, both work:
613+
614+
```python
615+
# CONNECT tunnel (httpx with HTTPS, or explicit tunnel code)
616+
# Forward proxy (httpx with HTTP_PROXY set for http:// URLs)
617+
import httpx
618+
resp = httpx.get("http://10.86.8.223:8000/screenshot/",
619+
proxy="http://10.200.0.1:3128")
620+
```
621+
525622
### Behavioral Trigger: TLS Termination
526623

527624
**Trigger**: The `tls` field on a `NetworkEndpoint`.
@@ -765,11 +862,15 @@ Functions in `crates/navigator-sandbox/src/proxy.rs` implement the SSRF checks:
765862

766863
### Placement in Proxy Flow
767864

865+
The SSRF check applies to both CONNECT and forward proxy requests. For forward proxy, an additional private-IP gate requires all resolved IPs to be RFC 1918 private.
866+
768867
```mermaid
769868
flowchart TD
770-
A[CONNECT request received] --> B{inference.local?}
771-
B -- Yes --> C["InferenceContext: route locally"]
772-
B -- No --> D[OPA policy evaluation]
869+
A["Request received"] --> B{CONNECT?}
870+
B -- Yes --> INF{inference.local?}
871+
INF -- Yes --> C["InferenceContext: route locally"]
872+
INF -- No --> D[OPA policy evaluation]
873+
B -- No --> FP["Forward proxy path<br/>(see Forward Proxy Mode)"]
773874
D --> E{Allowed?}
774875
E -- No --> F["403 Forbidden"]
775876
E -- Yes --> G{allowed_ips on endpoint?}
@@ -781,7 +882,13 @@ flowchart TD
781882
L --> M{All IPs public?}
782883
M -- No --> J
783884
M -- Yes --> K
784-
K --> N[200 Connection Established]
885+
K --> N["200 Connection Established"]
886+
887+
FP --> FP_OPA["OPA evaluation + require allowed_ips"]
888+
FP_OPA --> FP_RESOLVE["resolve_and_check_allowed_ips"]
889+
FP_RESOLVE --> FP_PRIVATE{All IPs private?}
890+
FP_PRIVATE -- No --> J
891+
FP_PRIVATE -- Yes --> FP_CONNECT["TCP connect + rewrite + relay"]
785892
```
786893

787894
### Private IP Access via `allowed_ips`
@@ -970,6 +1077,23 @@ network_policies:
9701077
binaries:
9711078
- { path: /usr/bin/curl }
9721079
1080+
# Forward proxy + CONNECT: private service accessible via plain HTTP or tunnel
1081+
# With allowed_ips set and the destination being a private IP, both
1082+
# `http://10.86.8.223:8000/path` (forward proxy) and
1083+
# `CONNECT 10.86.8.223:8000` (tunnel) work.
1084+
computer_control:
1085+
name: computer-control
1086+
endpoints:
1087+
- host: 10.86.8.223
1088+
port: 8000
1089+
allowed_ips:
1090+
- "10.86.8.223/32"
1091+
binaries:
1092+
- { path: /usr/local/bin/python3.12 }
1093+
1094+
inference:
1095+
allowed_routes:
1096+
- local
9731097
```
9741098
9751099
---
@@ -1018,7 +1142,9 @@ This ordering is intentional: privilege dropping needs `/etc/group` and `/etc/pa
10181142

10191143
The OPA engine evaluates two categories of rules:
10201144

1021-
### L4 Rules (per-CONNECT)
1145+
### L4 Rules (per-connection)
1146+
1147+
Evaluated on every CONNECT request and every forward proxy request. The same OPA input is used in both cases.
10221148

10231149
| Rule | Signature | Returns |
10241150
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
@@ -1108,3 +1234,4 @@ An empty `sources`/`log_sources` list means no source filtering (all sources pas
11081234
- [Gateway Architecture](gateway.md) -- How the gateway stores and delivers policies via gRPC
11091235
- [Inference Routing](inference-routing.md) -- How `inference.local` requests are routed to model backends
11101236
- [Overview](README.md) -- System-level context for how policies fit into the platform
1237+
- [Plain HTTP Forward Proxy Plan](plans/plain-http-forward-proxy.md) -- Design document for the forward proxy feature

‎crates/navigator-sandbox/src/grpc_client.rs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,16 @@ pub async fn discover_and_sync_policy(
160160
})
161161
}
162162

163+
/// Sync an enriched policy back to the gateway.
164+
///
165+
/// Used by the supervisor to push baseline-path-enriched policies so the
166+
/// gateway stores the effective policy users see via `nemoclaw sandbox get`.
167+
pub async fn sync_policy(endpoint: &str, sandbox: &str, policy: &ProtoSandboxPolicy) -> Result<()> {
168+
debug!(endpoint = %endpoint, sandbox = %sandbox, "Syncing enriched policy to gateway");
169+
let mut client = connect(endpoint).await?;
170+
sync_policy_with_client(&mut client, sandbox, policy).await
171+
}
172+
163173
/// Fetch provider environment variables for a sandbox from NemoClaw server via gRPC.
164174
///
165175
/// Returns a map of environment variable names to values derived from provider

‎crates/navigator-sandbox/src/lib.rs‎

Lines changed: 109 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ pub async fn run_sandbox(
137137

138138
// Load policy and initialize OPA engine
139139
let navigator_endpoint_for_proxy = navigator_endpoint.clone();
140-
let (mut policy, opa_engine) = load_policy(
140+
let (policy, opa_engine) = load_policy(
141141
sandbox_id.clone(),
142142
sandbox,
143143
navigator_endpoint.clone(),
@@ -180,8 +180,9 @@ pub async fn run_sandbox(
180180
let tls_dir = std::path::Path::new("/etc/navigator-tls");
181181
match write_ca_files(&ca, tls_dir) {
182182
Ok(paths) => {
183-
// Make the TLS directory readable under Landlock
184-
policy.filesystem.read_only.push(tls_dir.to_path_buf());
183+
// /etc/navigator-tls is subsumed by the /etc baseline
184+
// path injected by enrich_*_baseline_paths(), so no
185+
// explicit Landlock entry is needed here.
185186

186187
let upstream_config = build_upstream_client_config();
187188
let cert_cache = CertCache::new(ca);
@@ -680,6 +681,87 @@ fn spawn_route_refresh(
680681
});
681682
}
682683

684+
// ============================================================================
685+
// Baseline filesystem path enrichment
686+
// ============================================================================
687+
688+
/// Minimum read-only paths required for a proxy-mode sandbox child process to
689+
/// function: dynamic linker, shared libraries, DNS resolution, CA certs,
690+
/// Python venv, and navigator logs.
691+
const PROXY_BASELINE_READ_ONLY: &[&str] = &["/usr", "/lib", "/etc", "/app", "/var/log"];
692+
693+
/// Minimum read-write paths required for a proxy-mode sandbox child process:
694+
/// user working directory and temporary files.
695+
const PROXY_BASELINE_READ_WRITE: &[&str] = &["/sandbox", "/tmp"];
696+
697+
/// Ensure a proto `SandboxPolicy` includes the baseline filesystem paths
698+
/// required for proxy-mode sandboxes. Paths are only added if missing;
699+
/// user-specified paths are never removed.
700+
///
701+
/// Returns `true` if the policy was modified (caller may want to sync back).
702+
fn enrich_proto_baseline_paths(proto: &mut navigator_core::proto::SandboxPolicy) -> bool {
703+
// Only enrich if network_policies are present (proxy mode indicator).
704+
if proto.network_policies.is_empty() {
705+
return false;
706+
}
707+
708+
let fs = proto
709+
.filesystem
710+
.get_or_insert_with(|| navigator_core::proto::FilesystemPolicy {
711+
include_workdir: true,
712+
..Default::default()
713+
});
714+
715+
let mut modified = false;
716+
for &path in PROXY_BASELINE_READ_ONLY {
717+
if !fs.read_only.iter().any(|p| p.as_str() == path) {
718+
fs.read_only.push(path.to_string());
719+
modified = true;
720+
}
721+
}
722+
for &path in PROXY_BASELINE_READ_WRITE {
723+
if !fs.read_write.iter().any(|p| p.as_str() == path) {
724+
fs.read_write.push(path.to_string());
725+
modified = true;
726+
}
727+
}
728+
729+
if modified {
730+
info!("Enriched policy with baseline filesystem paths for proxy mode");
731+
}
732+
733+
modified
734+
}
735+
736+
/// Ensure a `SandboxPolicy` (Rust type) includes the baseline filesystem
737+
/// paths required for proxy-mode sandboxes. Used for the local-file code
738+
/// path where no proto is available.
739+
fn enrich_sandbox_baseline_paths(policy: &mut SandboxPolicy) {
740+
if !matches!(policy.network.mode, NetworkMode::Proxy) {
741+
return;
742+
}
743+
744+
let mut modified = false;
745+
for &path in PROXY_BASELINE_READ_ONLY {
746+
let p = std::path::PathBuf::from(path);
747+
if !policy.filesystem.read_only.contains(&p) {
748+
policy.filesystem.read_only.push(p);
749+
modified = true;
750+
}
751+
}
752+
for &path in PROXY_BASELINE_READ_WRITE {
753+
let p = std::path::PathBuf::from(path);
754+
if !policy.filesystem.read_write.contains(&p) {
755+
policy.filesystem.read_write.push(p);
756+
modified = true;
757+
}
758+
}
759+
760+
if modified {
761+
info!("Enriched policy with baseline filesystem paths for proxy mode");
762+
}
763+
}
764+
683765
/// Load sandbox policy from local files or gRPC.
684766
///
685767
/// Priority:
@@ -706,7 +788,7 @@ async fn load_policy(
706788
std::path::Path::new(data_file),
707789
)?;
708790
let config = engine.query_sandbox_config()?;
709-
let policy = SandboxPolicy {
791+
let mut policy = SandboxPolicy {
710792
version: 1,
711793
filesystem: config.filesystem,
712794
network: NetworkPolicy {
@@ -716,6 +798,7 @@ async fn load_policy(
716798
landlock: config.landlock,
717799
process: config.process,
718800
};
801+
enrich_sandbox_baseline_paths(&mut policy);
719802
return Ok((policy, Some(Arc::new(engine))));
720803
}
721804

@@ -728,14 +811,17 @@ async fn load_policy(
728811
);
729812
let proto_policy = grpc_client::fetch_policy(endpoint, id).await?;
730813

731-
let proto_policy = match proto_policy {
814+
let mut proto_policy = match proto_policy {
732815
Some(p) => p,
733816
None => {
734817
// No policy configured on the server. Discover from disk or
735818
// fall back to the restrictive default, then sync to the
736819
// gateway so it becomes the authoritative baseline.
737820
info!("Server returned no policy; attempting local discovery");
738-
let discovered = discover_policy_from_disk_or_default();
821+
let mut discovered = discover_policy_from_disk_or_default();
822+
// Enrich before syncing so the gateway baseline includes
823+
// baseline paths from the start.
824+
enrich_proto_baseline_paths(&mut discovered);
739825
let sandbox = sandbox.as_deref().ok_or_else(|| {
740826
miette::miette!(
741827
"Cannot sync discovered policy: sandbox not available.\n\
@@ -749,6 +835,23 @@ async fn load_policy(
749835
}
750836
};
751837

838+
// Ensure baseline filesystem paths are present for proxy-mode
839+
// sandboxes. If the policy was enriched, sync the updated version
840+
// back to the gateway so users can see the effective policy.
841+
let enriched = enrich_proto_baseline_paths(&mut proto_policy);
842+
if enriched {
843+
if let Some(sandbox_name) = sandbox.as_deref() {
844+
if let Err(e) =
845+
grpc_client::sync_policy(endpoint, sandbox_name, &proto_policy).await
846+
{
847+
warn!(
848+
error = %e,
849+
"Failed to sync enriched policy back to gateway (non-fatal)"
850+
);
851+
}
852+
}
853+
}
854+
752855
// Build OPA engine from baked-in rules + typed proto data.
753856
// In cluster mode, proxy networking is always enabled so OPA is
754857
// always required for allow/deny decisions.

‎crates/navigator-sandbox/src/policy.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,8 @@ pub struct ProcessPolicy {
8686

8787
#[derive(Debug, Clone, Default)]
8888
pub enum LandlockCompatibility {
89-
BestEffort,
9089
#[default]
90+
BestEffort,
9191
HardRequirement,
9292
}
9393

0 commit comments

Comments
 (0)