microsandbox-rb 0.16.0 → 0.17.0

data/DESIGN.md

@@ -184,7 +184,7 @@ extension.
 
 `ext/microsandbox/Cargo.toml` depends on the core crate via a **pinned git tag**
 (`microsandbox` / `microsandbox-network`, pinned to the same tag as
-`Microsandbox::RUNTIME_VERSION` — currently `v0.6.16`), so the gem builds anywhere
+`Microsandbox::RUNTIME_VERSION` — currently `v0.6.18`), so the gem builds anywhere
 — CI, `rake-compiler-dock` release containers, and end-user source installs —
 without an adjacent checkout. For fast local development against a sibling
 microsandbox checkout, copy `.cargo/config.toml.example` to `.cargo/config.toml`

data/README.md

@@ -245,6 +245,47 @@ Microsandbox::Sandbox.create(
 end
 ```
 
+**Outbound proxy** (runtime `v0.6.17`) — route the sandbox's egress through a
+SOCKS4 (TCP) or SOCKS5 (TCP + non-DNS UDP) proxy with `proxy:`. The proxy is
+dialed by the runtime's host-side network stack, so its address is resolved
+from the host (`127.0.0.1` is the host's loopback), and the egress policy
+(`network:`) still governs which destinations may be reached. A SOCKS5 password
+comes from a host environment variable via `SecretSource.env` — only the
+variable's *name* is handed to the runtime. Local backend only.
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: Microsandbox::OutboundProxy.socks5("127.0.0.1:1080"))
+
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: Microsandbox::OutboundProxy.socks5("10.0.0.5:1080")
+    .credentials("sandbox", Microsandbox::SecretSource.env("PROXY_PASSWORD")))
+
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: Microsandbox::OutboundProxy.socks4("127.0.0.1:1080", user_id: "ci"))
+
+# The equivalent plain Hash works too:
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: { protocol: :socks5, address: "10.0.0.5:1080",
+           credentials: { username: "sandbox", password: { env: "PROXY_PASSWORD" } } })
+```
+
+**Strict hostname policy** (runtime `v0.6.18`) — `strict: true` makes a
+hostname-rule allow fail closed unless the runtime can actually see the request
+authority (plain-HTTP `Host`, or SNI/`:authority` under TLS interception); a
+bypassed or non-intercepted HTTPS flow allowed only by a hostname rule is then
+denied before the upstream dial. Default `false`; create-only. Independently of
+`strict:`, any policy with domain rules now checks plain-HTTP `Host` headers
+against it.
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "python",
+  network: Microsandbox::NetworkPolicy.custom(default_egress: :deny,
+    rules: [{ action: :allow, direction: :egress, protocol: :tcp, port: 443,
+              destination: Microsandbox::Destination.domain("api.example.com") }]),
+  strict: true)
+```
+
 ### Executing commands
 
 ```ruby
@@ -559,8 +600,8 @@ change diverged the two numbers — the gem version is **not** a reliable indica
 of the embedded runtime version. To learn which runtime a build wraps, ask it:
 
 ```ruby
-Microsandbox::VERSION          # => "0.16.0"  (the gem's own version)
-Microsandbox.runtime_version   # => "v0.6.16" (the embedded upstream runtime tag)
+Microsandbox::VERSION          # => "0.17.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.6.18" (the embedded upstream runtime tag)
 ```
 
 The companion [`microsandbox-rb-binaries`](#the-runtime-binaries) gem is
@@ -594,6 +635,7 @@ stale.
 | `0.14.0` | `v0.6.9` | two-gem split: SDK-only gem (no build-time runtime download) + companion `microsandbox-rb-binaries` platform gems |
 | `0.15.0` | `v0.6.14` | adopts upstream `v0.6.10`–`v0.6.14` step by step: bind-mount correctness, guest bootstrap off the kernel command line, DNS pins for deferred domain allows, Linux glibc 2.28 baseline for the prebuilt runtime, legacy ext4 upper-disk resize, `msb_krun` 0.1.32. Parity: `ssh.open_client`/`prepare_server` accept `inactivity_timeout:` (seconds; `0` disables, `nil` inherits the 600s global default) |
 | `0.16.0` | `v0.6.16` | adopts upstream `v0.6.15`+`v0.6.16` step by step: mount fallback ownership, readonly-mount write-probe fix, log retrieval rerouted through the SDK backends, config overlaid by field presence, network-slot recycling. Parity: per-mount `uid:`/`gid:`, and the convergent lifecycle — `Sandbox.connect_or_create`, `#id`, `#wait_for_status`, `#restart`, `#destroy`, `SandboxHandle#connect_or_start`, `SandboxReplacedError` |
+| `0.17.0` | `v0.6.18` | adopts upstream `v0.6.17`+`v0.6.18` step by step: outbound SOCKS4/SOCKS5 proxies (SOCKS5 UDP + credentials), migration-order fix for databases last opened by a `v0.6.15` `msb`, security hardening — plain-HTTP `Host`/`:authority` now checked against domain-rule policies even in non-strict mode, plus fail-closed strict hostname mode. Parity: `proxy:` (`Microsandbox::OutboundProxy` / `SecretSource`), `strict:` |
 
 **Going forward** — the gem version moves on its own semver track and no longer
 mirrors the upstream tag:
@@ -708,7 +750,8 @@ image-pull progress (`Sandbox.create_with_progress` → `PullSession`),
 (`root_disk:` managed/tmpfs/disk via `Microsandbox::RootDisk`), **network
 configuration** (composable profiles, custom per-rule
 `Microsandbox::NetworkPolicy`/`Rule`/`Destination`, plus DNS, TLS interception,
-IPv4/IPv6 pools, `max_connections`, `trust_host_cas`), **secrets** (multi-host /
+IPv4/IPv6 pools, `max_connections`, `trust_host_cas`, `strict` hostname mode,
+outbound SOCKS4/SOCKS5 `proxy:`), **secrets** (multi-host /
 wildcard allow-lists, injection toggles, per-secret + sandbox-level violation
 policy), **SSH** (`Sandbox#ssh` → `SshClient`/`SftpClient`/`SshServer`), and the
 **raw agent client** (`Microsandbox::AgentClient`). Create options span

data/ext/microsandbox/Cargo.toml

@@ -7,7 +7,7 @@ description = "Ruby SDK native extension for microsandbox — secure, fast micro
 # Must equal Microsandbox::VERSION (lib/microsandbox/version.rb) — Native.version
 # returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
 # The core-crate dependency below stays pinned at its own tag (v0.6.16).
-version = "0.16.0"
+version = "0.17.0"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -42,8 +42,8 @@ rb-sys = "0.9"
 # first-use download into ~/.microsandbox (`setup::install`, which is not
 # gated on "prebuilt"). "net"/"ssh"/"keyring" are the features the official
 # SDKs ship with.
-microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.16", default-features = false, features = ["keyring", "net", "ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.16" }
+microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.18", default-features = false, features = ["keyring", "net", "ssh"] }
+microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.18" }
 # The *guest* agent (`agentd`, PID 1 inside every microVM) is embedded into the
 # extension by microsandbox-filesystem's build.rs, which without its "prebuilt"
 # feature demands a locally built `build/agentd` (workspace-only, `just
@@ -52,7 +52,7 @@ microsandbox-network = { git = "https://github.com/superradcompany/microsandbox"
 # prebuilt agentd for the target arch is fetched (same behaviour as before)
 # while the SDK-level msb download above stays off. Feature unification means
 # this adds no new crates; keep it on the same tag as the deps above.
-microsandbox-runtime = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.16", default-features = false, features = ["prebuilt"] }
+microsandbox-runtime = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.18", default-features = false, features = ["prebuilt"] }
 
 # Async core bridged to Ruby's synchronous API via a blocking tokio runtime.
 tokio = { version = "1", features = ["rt-multi-thread", "sync", "time"] }

data/ext/microsandbox/src/error.rs

@@ -7,6 +7,7 @@
 
 use magnus::{value::ReprValue, Error, ExceptionClass, Module, RClass, RModule, Ruby};
 use microsandbox::{AgentClientError, MicrosandboxError, Operation, UnsupportedReason};
+use microsandbox_network::policy::BuildError;
 
 /// The Ruby class (relative to the `Microsandbox` module) for a core error.
 /// `"Error"` is the base class; anything else is a named subclass.
@@ -60,6 +61,12 @@ fn class_name(err: &MicrosandboxError) -> &'static str {
         // migration (run at backend connect / artifact open) failed and needs
         // repair. Mirrors the Python `SnapshotMigrationError`.
         SnapshotMigration { .. } => "SnapshotMigrationError",
+        // v0.6.17: a malformed `proxy:` (unparseable `IP:port`, invalid SOCKS4
+        // user ID, ...) also arrives as a `NetworkBuilder` error, but it is a
+        // *configuration* mistake, not a policy one — route it to
+        // `InvalidConfigError` like every other bad create option. Matched on
+        // the variant, never on the message text.
+        NetworkBuilder(BuildError::InvalidOutboundProxy { .. }) => "InvalidConfigError",
         // Give the already-defined-but-orphaned `NetworkPolicyError` a mapping:
         // a builder parse/validation error from `network(|n| ...)`. The gem
         // unconditionally enables the core's `net` feature (default-features),

data/ext/microsandbox/src/sandbox.rs

@@ -390,12 +390,22 @@ impl Sandbox {
             .transpose()?;
         let max_connections = conv::opt::<usize>(opts, "max_connections")?;
         let trust_host_cas = conv::opt::<bool>(opts, "trust_host_cas")?;
+        // strict: fail-closed hostname-policy enforcement (v0.6.18). A
+        // hostname-rule allow must be backed by an inspectable request
+        // authority (plain-HTTP Host, or SNI/authority under TLS interception);
+        // otherwise the flow is denied before the upstream dial. Mirrors the
+        // Python SDK's `Network(strict=...)`. Create-only here to match the
+        // Python SDK's `modify` surface, which does not expose `strict`; the
+        // core's generated network config patch (ConfigPatch derive) does
+        // carry a `strict` field, so this is SDK parity, not a core limit.
+        let strict = conv::opt::<bool>(opts, "strict")?;
         if dns.is_some()
             || tls.is_some()
             || ipv4_pool.is_some()
             || ipv6_pool.is_some()
             || max_connections.is_some()
             || trust_host_cas.is_some()
+            || strict.is_some()
         {
             b = b.network(move |mut n| {
                 if let Some(dns) = dns {
@@ -450,6 +460,9 @@ impl Sandbox {
                 if let Some(t) = trust_host_cas {
                     n = n.trust_host_cas(t);
                 }
+                if let Some(s) = strict {
+                    n = n.strict(s);
+                }
                 n
             });
         }
@@ -475,6 +488,18 @@ impl Sandbox {
                 })
             });
         }
+        // proxy: outbound SOCKS4/SOCKS5 proxy for egress traffic (v0.6.17,
+        // upstream #1234/#1507). The Ruby layer (`OutboundProxy.coerce`) has
+        // already validated the shape and normalized it to the Python SDK's
+        // `_to_dict()` wire form: {protocol:, address:, user_id?:,
+        // credentials?: {username:, password: {kind: "env", var:}}}. Only the
+        // password's env var NAME travels; the core resolves it host-side.
+        // Applied exactly as sdk/python/src/helpers.rs does; the address is
+        // parsed by the core's proxy builder (an invalid one surfaces as
+        // NetworkBuilder(InvalidOutboundProxy) → InvalidConfigError, see error.rs).
+        if let Some(proxy) = conv::opt::<RHash>(opts, "proxy")? {
+            b = apply_outbound_proxy(b, proxy)?;
+        }
         // init: hand guest PID 1 to an init system. The Ruby layer normalizes
         // `init:` to a Hash { cmd:, args?:, env?: }. `init_with` with empty
         // args/env builds the same HandoffInit as the plain `init(cmd)`, so route
@@ -1420,6 +1445,63 @@ fn parse_dns(d: RHash) -> Result<DnsSpec, Error> {
     })
 }
 
+/// Apply the normalized `proxy` create option (v0.6.17) to the builder.
+/// Mirrors `sdk/python/src/helpers.rs`: `socks4` takes an optional `user_id`,
+/// `socks5` optional `credentials` whose password is an env-backed
+/// [`SecretSource`] (the only kind). Unknown protocols and non-env password
+/// sources are rejected here (the Ruby layer already does, so these are
+/// belt-and-braces for callers of the native API).
+fn apply_outbound_proxy(b: SandboxBuilder, proxy: RHash) -> Result<SandboxBuilder, Error> {
+    let protocol = conv::opt_string(proxy, "protocol")?
+        .ok_or_else(|| error::base_error("proxy requires protocol:"))?;
+    let address = conv::opt_string(proxy, "address")?
+        .ok_or_else(|| error::base_error("proxy requires address:"))?;
+    match protocol.as_str() {
+        "socks4" => {
+            let user_id = conv::opt_string(proxy, "user_id")?;
+            Ok(b.proxy(move |p| {
+                let p = p.socks4(address);
+                match user_id {
+                    Some(user_id) => p.user_id(user_id),
+                    None => p,
+                }
+            }))
+        }
+        "socks5" => {
+            let credentials = match conv::opt::<RHash>(proxy, "credentials")? {
+                None => None,
+                Some(c) => {
+                    let username = conv::opt_string(c, "username")?
+                        .ok_or_else(|| error::base_error("SOCKS5 credentials require username:"))?;
+                    let password = conv::opt::<RHash>(c, "password")?
+                        .ok_or_else(|| error::base_error("SOCKS5 credentials require password:"))?;
+                    let kind = conv::opt_string(password, "kind")?.ok_or_else(|| {
+                        error::base_error("SOCKS5 password source requires kind:")
+                    })?;
+                    if kind != "env" {
+                        return Err(error::base_error(format!(
+                            "unsupported SOCKS5 password source {kind:?}; only env is supported"
+                        )));
+                    }
+                    let var = conv::opt_string(password, "var")?
+                        .ok_or_else(|| error::base_error("SOCKS5 password source requires var:"))?;
+                    Some((username, SecretSource::env(var)))
+                }
+            };
+            Ok(b.proxy(move |p| {
+                let p = p.socks5(address);
+                match credentials {
+                    Some((username, password)) => p.credentials(username, password),
+                    None => p,
+                }
+            }))
+        }
+        other => Err(error::base_error(format!(
+            "unsupported outbound proxy protocol {other:?}; expected socks4 or socks5"
+        ))),
+    }
+}
+
 /// One token bucket of the `rate_limiter` create option (v0.6.9):
 /// `(size, refill_time_ms, one_time_burst)`. Size is bytes for bandwidth
 /// buckets, frames for ops buckets.

data/lib/microsandbox/outbound_proxy.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Host-side source for secret material (runtime v0.6.17). The only kind is
+  # `env`: the secret is read from an environment variable of the **host**
+  # process (the one running this gem) when the sandbox is created — the
+  # variable's *name* travels to the runtime, never its value.
+  #
+  # Used for the password of an authenticated SOCKS5 {OutboundProxy}. Mirrors
+  # the Python SDK's frozen `SecretSource` dataclass.
+  #
+  # @example
+  #   Microsandbox::SecretSource.env("PROXY_PASSWORD")
+  class SecretSource
+    KINDS = %w[env].freeze
+
+    # @return [String] the source kind (always `"env"`)
+    attr_reader :kind
+    # @return [String] the host environment variable name
+    attr_reader :var
+
+    # Resolve the secret from a host environment variable.
+    # @param variable [String, Symbol] the variable name (non-empty)
+    # @return [SecretSource]
+    def self.env(variable)
+      new("env", variable)
+    end
+
+    # Coerce a user-facing value into a {SecretSource}: an instance passes
+    # through, a Hash must be `{ env: "VAR" }` or the wire form
+    # `{ kind: "env", var: "VAR" }`.
+    #
+    # A rejected value is NEVER rendered into the error: a caller who reaches
+    # for `{ value: "hunter2" }` or `{ store: ... }` by analogy with other
+    # secret APIs has just handed us a real password, and the exception
+    # message is the one place it must not resurface (logs, bug reports).
+    # Errors describe the expected shape and, at most, the offending class.
+    # @api private
+    def self.coerce(value, context = "password")
+      case value
+      when SecretSource then value
+      when Hash
+        env = fetch_key(value, :env)
+        return new("env", env) unless env.nil?
+
+        kind = fetch_key(value, :kind)
+        var = fetch_key(value, :var)
+        if kind.nil? && var.nil?
+          raise ArgumentError,
+            "#{context}: expects { env: \"VAR\" } naming a host environment variable " \
+            "(got a Hash without env:; plaintext password values are not accepted)"
+        end
+        new(kind, var)
+      else
+        raise ArgumentError,
+          "#{context}: expects a Microsandbox::SecretSource (SecretSource.env(\"VAR\")) " \
+          "or a Hash { env: \"VAR\" } (got #{value.class}; plaintext password values " \
+          "are not accepted)"
+      end
+    end
+
+    # @api private
+    def self.fetch_key(hash, key)
+      hash.key?(key) ? hash[key] : hash[key.to_s]
+    end
+    private_class_method :fetch_key
+
+    # @api private — use {.env}.
+    #
+    # Retained Strings are private frozen copies: the caller's originals are
+    # neither frozen nor aliased, so mutating them later (or a String obtained
+    # from {#var}/{#to_h}) cannot change this object's state. Only a
+    # String/Symbol kind or var is described in an error, and only by the
+    # allowed-shape wording — a nested Hash/other object is named by class so
+    # a misplaced secret is never rendered.
+    def initialize(kind, var)
+      unless kind.is_a?(String) || kind.is_a?(Symbol)
+        raise ArgumentError,
+          "secret source kind must be \"env\" (got #{kind.class})"
+      end
+      # An unsupported kind is reported by class only, never by value: a
+      # caller who mis-keys a password into `kind:` must not see it echoed.
+      unless KINDS.include?(kind.to_s)
+        raise ArgumentError,
+          "secret source kind must be \"env\" (only environment-backed secret sources " \
+          "are supported; got an unsupported #{kind.class})"
+      end
+      kind = kind.to_s
+      unless var.is_a?(String) || var.is_a?(Symbol)
+        raise ArgumentError,
+          "secret source environment variable must be a String name (got #{var.class})"
+      end
+      var = var.to_s
+      raise ArgumentError, "secret source environment variable must not be empty" if var.empty?
+      @kind = kind.dup.freeze
+      @var = var.dup.freeze
+      freeze
+    end
+
+    # Wire form for the native layer (Python's `_to_dict`).
+    # @return [Hash{String => String}]
+    def to_h
+      {"kind" => @kind, "var" => @var}
+    end
+
+    def ==(other)
+      other.is_a?(SecretSource) && other.kind == kind && other.var == var
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [SecretSource, @kind, @var].hash
+    end
+
+    def inspect
+      "#<Microsandbox::SecretSource env=#{@var}>"
+    end
+  end
+
+  # An outbound proxy for a sandbox's egress traffic (runtime v0.6.17, upstream
+  # #1234 / #1507), passed to {Sandbox.create} via `proxy:`. The runtime's
+  # host-side network stack dials the proxy — so the address is resolved from
+  # the **host**, and `127.0.0.1` names the host's loopback, not the guest's.
+  #
+  # - {socks4} — SOCKS4 for TCP, with an optional `user_id:` sent in the
+  #   handshake.
+  # - {socks5} — SOCKS5 for TCP and non-DNS UDP; chain {#credentials} for
+  #   username/password authentication, the password coming from a host
+  #   {SecretSource} (only its variable name reaches the runtime).
+  #
+  # The proxy applies uniformly to TLS-intercepted and bypassed/plain TCP; the
+  # egress policy (`network:`) still decides which destinations may be reached.
+  # Not accepted by the cloud backend (`UnsupportedError`).
+  #
+  # Instances are immutable: {#credentials} returns a new proxy. `proxy:` also
+  # accepts the equivalent plain Hash (see {.coerce}).
+  #
+  # @example
+  #   Sandbox.create("worker", image: "python",
+  #     proxy: Microsandbox::OutboundProxy.socks5("127.0.0.1:1080"))
+  #   Sandbox.create("worker", image: "python",
+  #     proxy: Microsandbox::OutboundProxy.socks5("10.0.0.5:1080")
+  #       .credentials("sandbox", Microsandbox::SecretSource.env("PROXY_PASSWORD")))
+  #   Sandbox.create("worker", image: "python",
+  #     proxy: { protocol: :socks4, address: "127.0.0.1:1080", user_id: "ci" })
+  #
+  # Mirrors the Python SDK's frozen `OutboundProxy` dataclass (`socks4` /
+  # `socks5` / `credentials`).
+  class OutboundProxy
+    PROTOCOLS = %w[socks4 socks5].freeze
+
+    # @return [String] `"socks4"` or `"socks5"`
+    attr_reader :protocol
+    # @return [String] the proxy's `IP:port` address, as seen from the host
+    attr_reader :address
+    # @return [String, nil] SOCKS4 user ID
+    attr_reader :user_id
+    # @return [String, nil] SOCKS5 username
+    attr_reader :username
+    # @return [SecretSource, nil] SOCKS5 password source
+    attr_reader :password
+
+    # A SOCKS4 outbound proxy.
+    # @param address [String] `IP:port` of the proxy, resolved from the host
+    # @param user_id [String, nil] optional user ID sent in the SOCKS4 handshake
+    # @return [OutboundProxy]
+    def self.socks4(address, user_id: nil)
+      new(protocol: "socks4", address: address, user_id: user_id)
+    end
+
+    # A SOCKS5 outbound proxy (unauthenticated; chain {#credentials}).
+    # @param address [String] `IP:port` of the proxy, resolved from the host
+    # @return [OutboundProxy]
+    def self.socks5(address)
+      new(protocol: "socks5", address: address)
+    end
+
+    # Coerce a user-facing `proxy:` value into the normalized wire Hash:
+    # an {OutboundProxy}, or a Hash `{ protocol: :socks4|:socks5, address:,
+    # user_id:, credentials: { username:, password: SecretSource | { env: } } }`.
+    # @api private
+    # @return [Hash{String => untyped}]
+    def self.coerce(value)
+      case value
+      # No re-validation for an existing instance, and none is needed: the
+      # constructor is the only writer, the object is frozen (no ivar can be
+      # reassigned), and every retained String is a private frozen copy, so
+      # {#to_h} is a pure function of already-validated state. Re-running the
+      # checks would only re-examine data the constructor itself produced.
+      when OutboundProxy then value.to_h
+      when Hash then from_hash(value).to_h
+      else
+        raise ArgumentError,
+          "proxy: expects a Microsandbox::OutboundProxy (OutboundProxy.socks4/socks5) " \
+          "or a Hash { protocol:, address:, ... } (got #{value.class})"
+      end
+    end
+
+    # @api private
+    def self.from_hash(hash)
+      protocol = fetch_key(hash, :protocol)
+      raise ArgumentError, "proxy: requires protocol: (:socks4 or :socks5)" if protocol.nil?
+      address = fetch_key(hash, :address)
+      raise ArgumentError, "proxy: requires address:" if address.nil?
+      user_id = fetch_key(hash, :user_id)
+      credentials = fetch_key(hash, :credentials)
+      username = nil
+      password = nil
+      unless credentials.nil?
+        unless credentials.is_a?(Hash)
+          raise ArgumentError,
+            "proxy credentials: must be a Hash { username:, password: } (got #{credentials.class})"
+        end
+        username = fetch_key(credentials, :username)
+        password = fetch_key(credentials, :password)
+        if username.nil? || password.nil?
+          raise ArgumentError, "proxy credentials: requires both username: and password:"
+        end
+        password = SecretSource.coerce(password, "proxy credentials password")
+      end
+      new(protocol: protocol, address: address, user_id: user_id,
+        username: username, password: password)
+    end
+
+    # @api private
+    def self.fetch_key(hash, key)
+      hash.key?(key) ? hash[key] : hash[key.to_s]
+    end
+    private_class_method :fetch_key
+
+    # @api private — use {.socks4} / {.socks5}.
+    def initialize(protocol:, address:, user_id: nil, username: nil, password: nil)
+      unless protocol.is_a?(String) || protocol.is_a?(Symbol)
+        raise ArgumentError,
+          "unsupported outbound proxy protocol (got #{protocol.class}; expected :socks4 or :socks5)"
+      end
+      protocol = protocol.to_s.downcase
+      unless PROTOCOLS.include?(protocol)
+        raise ArgumentError,
+          "unsupported outbound proxy protocol (expected :socks4 or :socks5)"
+      end
+      unless address.is_a?(String)
+        raise ArgumentError,
+          "proxy address must be a non-empty \"IP:port\" String (got #{address.class})"
+      end
+      if address.empty?
+        raise ArgumentError, "proxy address must be a non-empty \"IP:port\" String (got \"\")"
+      end
+      # Same rules as the Python SDK's OutboundProxy.__post_init__; the address
+      # itself is parsed by the core (which reports e.g. "invalid SOCKS5 proxy
+      # address" as an InvalidConfigError at create time).
+      # Identifiers are documented as Strings (RBS: String?). A misplaced
+      # container (a credentials Hash, an Array) must not be stringified into
+      # the wire hash / #inspect; reject it by class, never rendering it.
+      unless user_id.nil? || user_id.is_a?(String) || user_id.is_a?(Symbol)
+        raise ArgumentError, "SOCKS4 user_id must be a String (got #{user_id.class})"
+      end
+      unless username.nil? || username.is_a?(String) || username.is_a?(Symbol)
+        raise ArgumentError, "SOCKS5 username must be a String (got #{username.class})"
+      end
+      if protocol != "socks4" && !user_id.nil?
+        raise ArgumentError, "user_id is only supported for SOCKS4 proxies"
+      end
+      if protocol != "socks5" && !(username.nil? && password.nil?)
+        raise ArgumentError, "credentials are only supported for SOCKS5 proxies"
+      end
+      if username.nil? != password.nil?
+        raise ArgumentError, "SOCKS5 username and password must be provided together"
+      end
+      unless password.nil? || password.is_a?(SecretSource)
+        raise ArgumentError,
+          "SOCKS5 password must be a Microsandbox::SecretSource (SecretSource.env(\"VAR\")), " \
+          "got #{password.class}"
+      end
+      # Private frozen copies (see SecretSource#initialize): the caller keeps
+      # its own, unfrozen Strings; readers and {#to_h} hand out these frozen
+      # ones, so neither side can mutate stored state after construction.
+      @protocol = protocol.dup.freeze
+      @address = address.dup.freeze
+      @user_id = user_id&.to_s&.dup&.freeze
+      @username = username&.to_s&.dup&.freeze
+      @password = password
+      freeze
+    end
+
+    # Username/password authentication for a SOCKS5 proxy. Returns a **new**
+    # proxy; the receiver is unchanged.
+    # @param username [String]
+    # @param password [SecretSource] host-side password source
+    #   ({SecretSource.env}); its variable *name* is what reaches the runtime
+    # @return [OutboundProxy]
+    # @raise [ArgumentError] on a SOCKS4 proxy
+    def credentials(username, password)
+      raise ArgumentError, "credentials are only supported for SOCKS5 proxies" unless socks5?
+      self.class.new(protocol: @protocol, address: @address,
+        username: username, password: SecretSource.coerce(password, "proxy credentials password"))
+    end
+
+    def socks4? = @protocol == "socks4"
+
+    def socks5? = @protocol == "socks5"
+
+    # Wire form for the native layer (Python's `_to_dict`): `user_id` only when
+    # set, `credentials` only when both halves are set.
+    # @return [Hash{String => untyped}]
+    def to_h
+      h = {"protocol" => @protocol, "address" => @address}
+      h["user_id"] = @user_id unless @user_id.nil?
+      if @username && @password
+        h["credentials"] = {"username" => @username, "password" => @password.to_h}
+      end
+      h
+    end
+
+    def ==(other)
+      other.is_a?(OutboundProxy) && other.to_h == to_h
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [OutboundProxy, to_h].hash
+    end
+
+    # Never renders a password value — there is none; only the env var name.
+    def inspect
+      parts = ["#{@protocol} #{@address}"]
+      parts << "user_id=#{@user_id}" if @user_id
+      parts << "username=#{@username} password=env:#{@password.var}" if @username
+      "#<Microsandbox::OutboundProxy #{parts.join(" ")}>"
+    end
+  end
+end

data/lib/microsandbox/sandbox.rb

@@ -408,12 +408,28 @@ module Microsandbox
       # @param ipv6_pool [String, nil] guest IPv6 address pool CIDR
       # @param max_connections [Integer, nil] cap on concurrent proxied connections
       # @param trust_host_cas [Boolean, nil] trust the host's CA bundle for upstream TLS
+      # @param strict [Boolean, nil] strict hostname-policy mode (runtime
+      #   v0.6.18, default false): a hostname-rule allow must be backed by an
+      #   inspectable request authority — plain-HTTP `Host`, or SNI/authority
+      #   under TLS interception. Without that visibility (e.g. bypassed or
+      #   non-intercepted HTTPS) a flow allowed only by a hostname rule is
+      #   denied before the upstream dial. Create-only; `modify` cannot change it.
       # @param rate_limiter [Hash, nil] per-sandbox egress/ingress token-bucket
       #   limits (runtime v0.6.9, local backend):
       #   `{ egress: { bandwidth: { size: 1_048_576, refill_time_ms: 1000,
       #   one_time_burst: 0 }, ops: { size: 1000, refill_time_ms: 1000 } },
       #   ingress: { ... } }`. `bandwidth` buckets meter bytes, `ops` buckets
       #   meter network frames; an omitted bucket or direction is unlimited.
+      # @param proxy [OutboundProxy, Hash, nil] outbound SOCKS proxy for the
+      #   sandbox's egress traffic (runtime v0.6.17, local backend):
+      #   {OutboundProxy.socks4}(address, user_id:) or {OutboundProxy.socks5}
+      #   (address), optionally `.credentials(username, SecretSource.env("VAR"))`
+      #   — or the equivalent Hash `{ protocol: :socks5, address: "IP:port",
+      #   credentials: { username:, password: { env: "VAR" } } }`. The address is
+      #   dialed from the host; only the password's env var *name* is sent. The
+      #   cloud backend rejects it with {UnsupportedError}. An unparseable
+      #   address is rejected by the core at create time with
+      #   {InvalidConfigError}, before any boot.
       # @param vsock [Hash, Array, nil] host sockets exposed on guest-to-host
       #   vsock ports (runtime v0.6.9): `{ "/host/api.sock" => 5000 }` (stream
       #   sockets), or an Array of
@@ -576,7 +592,8 @@ module Microsandbox
         shell: nil, user: nil, hostname: nil, labels: nil, scripts: nil,
         entrypoint: nil, cmd: nil, ports: nil, ports_udp: nil, volumes: nil, network: nil,
         dns: nil, tls: nil, ipv4_pool: nil, ipv6_pool: nil,
-        max_connections: nil, trust_host_cas: nil, rate_limiter: nil, vsock: nil,
+        max_connections: nil, trust_host_cas: nil, strict: nil, rate_limiter: nil, proxy: nil,
+        vsock: nil,
         patches: nil,
         from_snapshot: nil, fstype: nil, init: nil, ephemeral: false,
         log_level: nil, quiet_logs: false, security: nil,
@@ -637,7 +654,9 @@ module Microsandbox
         opts["ipv6_pool"] = ipv6_pool.to_s if ipv6_pool
         opts["max_connections"] = Integer(max_connections) if max_connections
         set_bool(opts, "trust_host_cas", trust_host_cas)
+        set_bool(opts, "strict", strict)
         opts["rate_limiter"] = normalize_rate_limiter(rate_limiter) if rate_limiter
+        opts["proxy"] = OutboundProxy.coerce(proxy) unless proxy.nil?
         opts["vsock"] = normalize_vsock(vsock) if vsock
         opts["log_level"] = log_level.to_s if log_level
         opts["quiet_logs"] = true if quiet_logs

data/lib/microsandbox/version.rb

@@ -8,12 +8,12 @@ module Microsandbox
   # Versioning section of the README for the full gem-to-runtime map. Must equal
   # the native ext's Cargo crate version (`Native.version`), enforced by
   # spec/unit/version_spec.rb.
-  VERSION = "0.16.0"
+  VERSION = "0.17.0"
 
   # The upstream microsandbox runtime release this gem build embeds — the `tag`
   # pinned on the `microsandbox`/`microsandbox-network` git deps in
   # ext/microsandbox/Cargo.toml. Exposed at runtime as
   # {Microsandbox.runtime_version}. spec/unit/version_spec.rb asserts it stays in
   # sync with the Cargo tag so it can't silently drift out of date.
-  RUNTIME_VERSION = "v0.6.16"
+  RUNTIME_VERSION = "v0.6.18"
 end

data/lib/microsandbox.rb

@@ -30,6 +30,7 @@ require_relative "microsandbox/snapshot"
 require_relative "microsandbox/patch"
 require_relative "microsandbox/root_disk"
 require_relative "microsandbox/network"
+require_relative "microsandbox/outbound_proxy"
 require_relative "microsandbox/agent"
 require_relative "microsandbox/ssh"
 require_relative "microsandbox/modification"