S006: HTTP Proxy

Overview

Provide L7 (application layer) inspection of outbound HTTP and HTTPS traffic from agent containers. The proxy runs as a Tokio task inside outcalld -- there is no separate process. Agent containers reach the proxy via standard HTTP_PROXY / HTTPS_PROXY environment variables.

For plain HTTP, the proxy sees the full request (method, path, headers, hostname) and evaluates it against the rule engine before forwarding. For HTTPS, the proxy receives an HTTP CONNECT request, peeks at the TLS ClientHello to extract the SNI hostname, evaluates rules, and either tunnels the raw bytes or returns a 403.

How it works

1. outcalld starts the proxy listener as part of its normal startup.
2. Agent containers are launched with HTTP_PROXY and HTTPS_PROXY pointing at the proxy address (e.g. http://10.200.0.1:8080).
3. The proxy receives requests:
   • HTTP: direct request with full URL -- proxy inspects and forwards.
   • HTTPS: CONNECT host:443 -- proxy peeks at TLS SNI, inspects, then tunnels if allowed.
4. Each request is evaluated against the rule engine (S003). The CEL context is populated with network.hostname, http.method, http.path, and http.headers.*.
5. If the verdict is ALLOW, traffic is forwarded/tunneled.
6. If the verdict is BLOCK, the proxy returns HTTP 403 with a reason body.

Tech stack

• httparse plus structured URL parsing for bounded HTTP/1.1 request handling
• A bounded TLS-record and ClientHello parser for SNI peeking (no decryption)

User Scenarios

S006-US-001 [P1] As a host operator, I want all outbound HTTP/HTTPS traffic from agent containers to pass through an inspecting proxy so that rule-based access control is enforced at the application layer.

S006-US-002 [P1] As a host operator, I want the proxy to evaluate each request against the rule engine so that I can allow or block traffic by hostname, path, method, or header values.

S006-US-003 [P1] As a host operator, I want HTTPS connections to be inspected by SNI without decrypting the traffic so that hostname-based rules work while preserving end-to-end encryption.

S006-US-004 [P2] As a host operator, I want the proxy to log blocked requests with the reason so that I can audit policy violations.

S006-US-005 [P2] As a host operator, I want connection limits and timeouts so that a misbehaving agent cannot exhaust proxy resources.

Requirements Summary

Out of Scope

• TLS decryption / MITM -- the proxy inspects SNI only, never decrypts
• Request body inspection -- L7 inspection covers method, path, headers, hostname; not body content
• WebSocket upgrade handling -- HTTP Upgrade requests are rejected
• HTTP/2 multiplexing -- the proxy operates at HTTP/1.1 level between client and proxy
• Caching -- the proxy is not a caching proxy
• Content modification -- the proxy does not rewrite request or response bodies
• Non-HTTP protocols -- only HTTP and HTTPS (via CONNECT) are handled
• Per-container proxy bypass -- all containers on the network use the same proxy; bypass is not supported

Cross-Spec Dependencies

• Depends on: S003 (rule evaluation for each request)
• Depends on: S002 (proxy binds to the network gateway address)
• Required by: Container management (future spec -- sets HTTP_PROXY/HTTPS_PROXY env vars)

Shared Types (outcall-api)

Constants

pub const PROXY_DEFAULT_PORT: u16 = 8080;
pub const PROXY_CONNECT_TIMEOUT_SECS: u64 = 10;
pub const PROXY_IDLE_TIMEOUT_SECS: u64 = 300;
pub const PROXY_MAX_CONNECTIONS: usize = 1024;
pub const PROXY_MAX_HEADER_SIZE: usize = 8192;

Types

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProxyConfig {
    pub listen_addr: SocketAddr,
    pub connect_timeout_secs: u64,
    pub idle_timeout_secs: u64,
    pub max_connections: usize,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProxyStatus {
    pub listening: bool,
    pub listen_addr: SocketAddr,
    pub active_connections: usize,
    pub total_requests: u64,
    pub total_blocked: u64,
}

/// Populated for each request and passed to the rule engine.
#[derive(Debug, Clone)]
pub struct ProxyRequestContext {
    pub hostname: String,
    pub method: Option<String>,
    pub path: Option<String>,
    pub headers: HashMap<String, String>,
    pub is_connect: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ProxyVerdict {
    Allow,
    Block { reason: String },
}