security_box 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9949a172b6bf1ddf1eddd9756c8dcbad273d8f2409669304227bb2f981c9fef6
-  data.tar.gz: 499c948e3fd57c221f8aef7f8ad6dd63757b36e9d5a4a62d8c8a70823908f86d
+  metadata.gz: 6c7d1c1387ec5b1dffdb9781552e489d4b3d45e7066fdd3c7932e6ba39a8432f
+  data.tar.gz: 7770652a22e98d5067c851b5a1c790896b986b6dc7a68ca03ea4a0c3c4bb2110
 SHA512:
-  metadata.gz: 1cf51781bb108aa6849ae24bd1db5b812c7e0a7e94f0d1876eb1a860cabc4a6b00241fdc19b4b142b88da8bdf86ed6e9c5dc53009237f36706a4ff637fe96d5f
-  data.tar.gz: 39dfd3af95bc8bfd2e3bd79ac57b118ee706b2f7da3aee98854aea832094b29342e751b2a41bf630c593fd07289ecf7ac041b1d416682924f276a29be4a7259b
+  metadata.gz: 2d4f7f357bc27692a392251edfd887c310f94f6b0e5f47dccd01c9ea420c427f307888791205d82ee54a12ad117351464b6deefc06211cdabcf6c2bdeb86779e
+  data.tar.gz: b61989d1e43f6f801b1522643239a96118128825837f680bc57122ea8874be4f6229bde01c8af81f53bcbc8d9985e3100f329e2bcbc56797067d6584ed58cca8

data/CHANGELOG.md

@@ -5,6 +5,84 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-09-20
+
+### Added
+
+- Folder mounts (read-only by default): `c.mount "host/path" => "/data"` in the
+  register DSL (or `mounts:` in `Configuration.build`), with `c.mount_rw` for an
+  opt-in writable mount. Guest code can read a mounted host directory
+  (`File.read`, `Dir[]`, `File.open`); write attempts into a read-only mount fail
+  guest-side with `Errno::EPERM` and leave the host directory untouched.
+- `Configuration#mounts`: a frozen array of frozen `{host:, guest:, mode:}` hashes.
+  Mounts are config values — they flow through `#with`, `#fingerprint` (equal
+  mounts → equal fingerprint) and RactorPool requests. Relative host paths are
+  expanded against `Dir.pwd` at DSL time.
+- Mount validation (`SecurityBox::InvalidConfiguration` on violation): mode must be
+  `:read_only`/`:read_write` (wasmtime silently accepts unknown symbols, so the mode
+  is never trusted to the runtime); guest paths must be absolute and normalized
+  (no `..`, no trailing `/`, not `/`); guest paths must not overlap the reserved
+  `/work`, `/usr` or `/src` trees (exact or nested — a collision with the embedded
+  VFS is silently shadowed, a mount inside `/usr` breaks the guest boot, and inside
+  `/work` it would create a read-only subtree); duplicate guest paths are rejected
+  (wasmtime's last-mount-wins is silently surprising); at most 16 mounts.
+- Per-eval host-path validation: a mount whose host directory vanished returns a
+  `:sandbox_error` Result with a `security_box:` note instead of raising
+  `Wasmtime::Error` out of `#eval` (the store creation now also sits inside the
+  eval's rescue, so wasmtime setup failures can never raise).
+
+### Changed
+
+- `Sandbox#eval` (and pool equivalents) accept `mounts:` as a per-call override
+  (replaces the configuration's mounts, like `env:`).
+- README: new "Folder mounts" section + updated isolation matrix and defense notes
+  (a mounted folder's content is fully readable by guest code).
+
+### Investigation (no change needed, documented)
+
+- Q6 probe (stage 5): the embedded VFS is **not** guest-writable (`File.write`
+  into `/usr`, `/src` or `/` fails with `Errno::ENOENT`; deletes with `ENOTSUP`),
+  so no prelude File-write restriction is warranted; WASI remains the primary
+  enforcement. Symlink escapes from a mounted directory are blocked by wasmtime
+  (`Errno::EPERM`); the guest cannot even create symlinks. Measured mount cost:
+  none (warm-boot p50 ~260ms with 0/1/4/8 mounts). Evidence and probes in
+  `docs/plan/stages/stage_5.md` and `bin/spike_stage5_mounts.rb`.
+
+## [0.4.0] - 2026-09-15
+
+### Added
+
+- `SecurityBox::Pool` (`SecurityBox.pool`): a bounded pool of `:oneshot` sandboxes —
+  hard cap on concurrent evals (`size:`), sandbox reuse, `checkout` block and metrics
+  (`created`/`evals`/`total_ms`/`avg_ms`). Evals serialize on the GVL (documented).
+- `SecurityBox::RactorPool` (`SecurityBox.ractor_pool`): real parallelism — worker
+  Ractors sharing one Ractor-shareable Engine + compiled Module (stage-3 "Plan C").
+  Measured ≈0.52–0.53 parallel/serial wall ratio at 4 workers on 6 cores (~1.9x),
+  RSS ≈57MB; per-call overrides, statuses and trap recovery behave like
+  `Sandbox#eval`; a dead worker degrades to a `:sandbox_error` Result instead of a
+  hang.
+- `Configuration#fuel_ms`: rate-based fuel budgeting (~4e6 fuel/ms from the stage-3
+  calibration table + ~1e9 boot allowance), exposed via `Configuration#effective_fuel`
+  and usable per call. `fuel` and `fuel_ms` are mutually exclusive in the builder DSL
+  and in `#with`; switch back with `with(fuel_ms: nil, fuel: ...)`.
+- `docs/plan/stages/stage_4.md` with the worker-mode feasibility investigation.
+
+### Changed
+
+- The eval core was extracted from `Sandbox` into `SecurityBox::EvalRun` (shared by
+  `Sandbox` and `RactorPool` workers); `Sandbox` is now a thin, thread-safe wrapper.
+- README: the "Ractor note" roadmap item is delivered; concurrency guidance rewritten
+  around `Pool`/`RactorPool`.
+
+### Investigation (negative result, documented)
+
+- `:worker` mode (long-lived instance amortizing the ~240ms boot) is infeasible on
+  wasmtime-rb 48 (sync WASI): `invoke` holds the GVL during compute *and* while the
+  guest is blocked on a WASI read; epoch deadlines never fire inside a blocking
+  syscall; and per-request limits would require mutating a live Store from another
+  thread (unsafe). Evidence and probes in `docs/plan/stages/stage_4.md` and
+  `bin/spike_stage4_worker.rb`.
+
 ## [0.3.0] - 2026-09-14
 
 ### Added

data/README.md

@@ -119,7 +119,8 @@ sandbox.eval("3 * 3").value # => 9
 ### Per-call limits
 
 Options can be passed per call (derived from the configuration without mutating it):
-`timeout_ms`, `fuel`, `memory_size`, `stdout_limit`, `stderr_limit`.
+`timeout_ms`, `fuel`, `fuel_ms`, `memory_size`, `stdout_limit`, `stderr_limit`,
+`mounts`.
 
 ```ruby
 # Wall-clock limit via epoch interruption
@@ -182,6 +183,49 @@ Profiles are immutable: duplicate names and unknown names raise
 `SecurityBox::Configuration#fingerprint` gives every configuration a stable
 identity (equal settings → equal fingerprint), used to share runtime artifacts.
 
+### Folder mounts
+
+Host folders can be mounted into the sandbox explicitly. **Mounts are read-only
+by default**; `mount_rw` is the opt-in writable form:
+
+```ruby
+SecurityBox.register(:reader) do |c|
+  c.mount    "./data" => "/data"   # read-only (host path expanded at DSL time)
+  c.mount_rw "./state" => "/state" # opt-in writable
+end
+
+box = SecurityBox.spawn(:reader)
+box.eval('File.read("/data/input.csv")')      # guest reads mounted content
+box.eval('File.write("/state/last.txt", Time.now.to_i)')
+
+# Per-call override (replaces the configuration's mounts, like env:)
+SecurityBox.eval('File.read("/data/a.txt")',
+                 mounts: [{ host: "./data", guest: "/data", mode: :read_only }])
+```
+
+Rules (violations raise `SecurityBox::InvalidConfiguration` at registration):
+
+- A mount is one `{host:, guest:, mode:}` pair; `mode` is `:read_only` or
+  `:read_write` and the DSL defaults to read-only.
+- Guest paths must be absolute and normalized, must not overlap the reserved
+  `/work` (sandbox tmpdir), `/usr` (embedded stdlib) or `/src` (entrypoint)
+  trees — exact or nested — and must be unique.
+- At most 16 mounts per configuration.
+- The host path must exist and be a directory at eval time; otherwise the eval
+  returns `:sandbox_error` with a `security_box:` note on stderr (instead of
+  raising).
+
+Security notes:
+
+- **A mounted folder's content is fully readable by guest code** — only mount
+  directories whose content you are willing to expose to the executed code.
+- Read-only mounts are enforced by wasmtime: writes fail guest-side with
+  `Errno::EPERM` and the host directory is never touched. Symlinks inside a
+  mounted directory cannot escape it (wasmtime caps path resolution at the
+  preopen root), and guest code cannot create symlinks at all.
+- Mounted content can also be **written by the guest** in `mount_rw` mounts —
+  treat a writable mount as part of the guest's blast radius.
+
 ### Configuration
 
 `SecurityBox::Configuration` is immutable; use `.build` to create and `#with` to derive:
@@ -189,12 +233,14 @@ identity (equal settings → equal fingerprint), used to share runtime artifacts
 ```ruby
 config = SecurityBox::Configuration.build(
   fuel: 10_000_000_000,             # deterministic CPU budget
+  fuel_ms: nil,                     # or a millisecond-based budget (mutually exclusive with fuel)
   timeout_ms: 2_000,                # wall-clock limit (epoch interruption)
   memory_size: 512 * 1024 * 1024,   # wasm linear memory limit
   stdout_limit: 1 << 20,            # stdout capture capacity in bytes
   stderr_limit: 1 << 16,            # stderr capture capacity in bytes
   epoch_interval_ms: 25,            # epoch timer granularity
-  env: { "LANG" => "C" }            # guest environment (empty by default)
+  env: { "LANG" => "C" },           # guest environment (empty by default)
+  mounts: []                        # host-folder mounts (see "Folder mounts")
 )
 
 lean = config.with(timeout_ms: 500, fuel: 5_000_000)
@@ -221,6 +267,8 @@ string.
 |---|---|
 | `File.write("/etc/passwd", ...)` | `Errno::ENOENT` (guest does not see the host FS) |
 | `Dir["/*"]` | `[]` (empty root) |
+| `File.write` into a read-only mount | `Errno::EPERM` (wasmtime-enforced; host dir untouched) |
+| symlink escape from a mounted directory | `Errno::EPERM` (path resolution capped at the preopen root) |
 | `system("ls")` / backticks / `IO.popen` / `Process.spawn` | `SecurityError` (hardening prelude) |
 | `Kernel#open(...)` | `SecurityError` (pipe form; use `File.open`) |
 | `fork` | `NotImplementedError` |
@@ -233,12 +281,16 @@ string.
 Notes:
 
 - The guest Ruby version is the one from ruby.wasm (4.0), not necessarily the host's.
-- Concurrency: `invoke` holds the GVL, so executions serialize per host process. Scale
-  horizontally with multiple processes (e.g., Puma workers); a stuck guest still can't
-  hang the process thanks to the epoch deadline.
-- Ractor note: wasmtime `Engine`/`Module` are Ractor-shareable and Ractors run wasm in
-  parallel (measured ≈3.6x with 4 Ractors on 6 cores); a supported Ractor pool is on
-  the roadmap (see `docs/plan/stages/stage_3.md`).
+- Mounts widen the trust surface: a mounted folder's content is fully readable by
+  guest code (see "Folder mounts" above). Read-only by default; nothing outside
+  `/work` is writable without an explicit `mount_rw`.
+- Concurrency: `invoke` holds the GVL, so executions on threads serialize — use
+  `RactorPool` (below) for parallelism inside one process, or scale horizontally with
+  multiple processes (e.g., Puma workers). A stuck guest still can't hang the process
+  thanks to the epoch deadline.
+- Ractor: wasmtime `Engine`/`Module` are Ractor-shareable and Ractors run wasm in
+  parallel — measured ≈1.9x wall-time speedup at 4 workers on 6 cores through
+  `RactorPool` (see `docs/plan/stages/stage_3.md` and `stage_4.md`).
 - Memory: the packed image declares a 1528-page (~95.5 MiB) minimum; `memory_size`
   below that fails instantiation (reported as `:sandbox_error`). Practical minimum is
   ~128–144MB for small workloads; the 512MB default leaves comfortable headroom.
@@ -246,7 +298,57 @@ Notes:
   and every eval costs ~1e9 fuel for boot — see the calibration table in
   `docs/plan/stages/stage_3.md`. Consequently `fuel` below ~1e9 cannot even boot, and
   `timeout_ms` below ~300ms times out during the guest boot (~500ms is a practical
-  floor).
+  floor). Prefer thinking in milliseconds? Use `fuel_ms` (below).
+
+## Concurrency
+
+Two pools are available, with honestly different guarantees (measured in stage 4 —
+`invoke` holds the GVL, so a long-lived `:worker` instance is impossible on the current
+wasmtime-rb; one wasm boot per eval stays on the hot path):
+
+### `Pool` — bounded concurrency on threads
+
+```ruby
+pool = SecurityBox.pool(:lean, size: 4)
+pool.eval("40 + 2").value    # => 42
+pool.checkout { |sandbox| sandbox.eval("1 + 1") }
+pool.metrics                 # => {size:, created:, evals:, total_ms:, avg_ms:}
+pool.shutdown
+```
+
+Caps concurrent evals at `size` and reuses sandbox objects, but evals serialize on the
+GVL — one at a time.
+
+### `RactorPool` — real parallelism
+
+```ruby
+pool = SecurityBox.ractor_pool(:lean, size: 4)
+pool.eval("40 + 2").value    # => 42
+pool.shutdown
+```
+
+Worker Ractors share one Engine + compiled Module and run wasm truly in parallel
+(~1.9x wall-time speedup at 4 workers on 6 cores; measured ≈0.53 parallel/serial wall
+ratio across 1M–4M-iteration workloads). Per-call overrides, user errors, timeouts and
+fuel exhaustion behave exactly like `Sandbox#eval`, and the worker survives traps and
+keeps serving. Costs one module deserialize at creation (~0.5s via the disk cache);
+each eval still pays the ~240ms guest boot.
+
+### `fuel_ms` — rate-based fuel budgeting
+
+Instead of counting raw fuel, budget approximate wall-time of compute:
+
+```ruby
+config = SecurityBox::Configuration.build(fuel_ms: 100) # ≈100ms of compute + boot allowance
+SecurityBox.spawn(config).eval("i = 0; while i < 5_000_000; i += 1; end").status
+# => :fuel_exhausted (5M tight iterations ≈ 2.4e9 fuel > the 100ms budget)
+```
+
+`fuel_ms` converts to fuel with the conservative stage-3 calibration rate
+(4e6 fuel/ms ≈ 4e9 fuel/s) plus a ~1e9 boot allowance (`Configuration#effective_fuel`).
+The epoch `timeout_ms` remains the mandatory wall-clock backstop. `fuel` and `fuel_ms`
+are mutually exclusive in the builder DSL and in `#with` overrides; a `fuel_ms`
+configuration can be switched back with `with(fuel_ms: nil, fuel: ...)`.
 
 ## Running the tests
 
@@ -284,3 +386,7 @@ bundle exec ruby bin/spike.rb
   integrity, compiled-module disk cache)
 - `docs/plan/stages/stage_3.md` — stage 3 findings (named profiles, Ractor
   parallelism, memory floor, fuel calibration, backtrace)
+- `docs/plan/stages/stage_4.md` — stage 4 findings (worker-mode feasibility, pools,
+  `fuel_ms`)
+- `docs/plan/stages/stage_5.md` — stage 5 findings (folder mounts: read-only
+  enforcement, reserved-path collisions, symlink escapes, mount cost)

data/lib/security_box/configuration.rb

@@ -13,35 +13,70 @@ module SecurityBox
     DEFAULTS = {
       image_path: nil, # resolved dynamically (project's build/security_box.wasm)
       fuel: 10_000_000_000,
+      fuel_ms: nil, # rate-based fuel ergonomics (see FUEL_PER_MS); nil = use :fuel
       timeout_ms: 2_000,
       memory_size: 512 * 1024 * 1024,
       stdout_limit: 1 << 20,
       stderr_limit: 1 << 16,
       epoch_interval_ms: 25,
-      env: {}.freeze
+      env: {}.freeze,
+      mounts: [].freeze
     }.freeze
 
-    attr_reader :image_path, :fuel, :timeout_ms, :memory_size,
-                :stdout_limit, :stderr_limit, :epoch_interval_ms, :env
+    # Fuel-per-ms conversion for #fuel_ms, from the stage-3 calibration table
+    # (docs/plan/stages/stage_3.md): compute workloads burn 3.2e9–8.4e9 fuel/s;
+    # 4e9/s is the conservative floor. The guest boot baseline (~9.1e8 fuel)
+    # is added on top so the budget covers boot even for trivial evals.
+    FUEL_PER_MS = 4_000_000
+    BOOT_FUEL_ALLOWANCE = 1_000_000_000
+
+    attr_reader :image_path, :fuel, :fuel_ms, :timeout_ms, :memory_size,
+                :stdout_limit, :stderr_limit, :epoch_interval_ms, :env, :mounts
 
     def self.build(**options)
       new(**DEFAULTS.merge(options)).freeze
     end
 
-    def initialize(image_path: nil, fuel:, timeout_ms:, memory_size:,
-                   stdout_limit:, stderr_limit:, epoch_interval_ms:, env:)
+    def initialize(image_path: nil, fuel:, fuel_ms:, timeout_ms:, memory_size:,
+                   stdout_limit:, stderr_limit:, epoch_interval_ms:, env:, mounts:)
       @image_path = image_path || default_image_path
       @fuel = Integer(fuel)
+      @fuel_ms = fuel_ms.nil? ? nil : Integer(fuel_ms)
       @timeout_ms = Integer(timeout_ms)
       @memory_size = Integer(memory_size)
       @stdout_limit = Integer(stdout_limit)
       @stderr_limit = Integer(stderr_limit)
       @epoch_interval_ms = Integer(epoch_interval_ms)
       @env = env.freeze
+      @mounts = Mounts.normalize(mounts)
       freeze
     end
 
+    # The fuel budget actually applied to each evaluation. When :fuel_ms is
+    # set it takes precedence: an approximate millisecond-based budget
+    # (fuel_ms × FUEL_PER_MS + boot allowance) instead of a raw fuel count.
+    # The epoch timeout remains the mandatory wall-clock backstop either way.
+    def effective_fuel
+      return fuel unless fuel_ms
+
+      fuel_ms * FUEL_PER_MS + BOOT_FUEL_ALLOWANCE
+    end
+
+    # Derives a copy with `changes` applied (never mutates the receiver).
+    # Passing both :fuel and a non-nil :fuel_ms is ambiguous and rejected;
+    # overriding :fuel on a configuration that uses :fuel_ms is rejected too
+    # (pass fuel_ms: nil first to switch to a raw fuel budget).
     def with(**changes)
+      if changes.key?(:fuel_ms)
+        if changes[:fuel_ms] && changes.key?(:fuel)
+          raise InvalidConfiguration,
+                "fuel and fuel_ms are mutually exclusive overrides"
+        end
+      elsif changes.key?(:fuel) && @fuel_ms
+        raise InvalidConfiguration,
+              "configuration uses fuel_ms (#{fuel_ms}); override fuel_ms or clear it with fuel_ms: nil instead of fuel"
+      end
+
       self.class.build(**to_h.merge(changes))
     end
 
@@ -49,12 +84,14 @@ module SecurityBox
       {
         image_path: @image_path,
         fuel: @fuel,
+        fuel_ms: @fuel_ms,
         timeout_ms: @timeout_ms,
         memory_size: @memory_size,
         stdout_limit: @stdout_limit,
         stderr_limit: @stderr_limit,
         epoch_interval_ms: @epoch_interval_ms,
-        env: @env
+        env: @env,
+        mounts: @mounts
       }
     end
 
@@ -87,9 +124,20 @@ module SecurityBox
       end
 
       def fuel(value)
+        raise InvalidConfiguration, "fuel and fuel_ms are mutually exclusive" if @changes.key?(:fuel_ms)
+
         @changes[:fuel] = value
       end
 
+      # Rate-based fuel ergonomics: sets fuel from an approximate millisecond
+      # budget (see Configuration#effective_fuel). Mutually exclusive with
+      # an explicit :fuel.
+      def fuel_ms(value)
+        raise InvalidConfiguration, "fuel and fuel_ms are mutually exclusive" if @changes.key?(:fuel)
+
+        @changes[:fuel_ms] = value
+      end
+
       def timeout_ms(value)
         @changes[:timeout_ms] = value
       end
@@ -114,6 +162,32 @@ module SecurityBox
       def env(value)
         @changes[:env] = value
       end
+
+      # Mounts a host directory into the guest, read-only by default:
+      #   c.mount "host/path" => "/data"
+      # Each call appends one mount; use #mount_rw for a writable mount.
+      def mount(mapping)
+        add_mount(mapping, :read_only)
+      end
+
+      # Opt-in writable mount — the only way to expose a writable host path
+      # besides the sandbox-private /work tmpdir:
+      #   c.mount_rw "host/path" => "/data"
+      def mount_rw(mapping)
+        add_mount(mapping, :read_write)
+      end
+
+      private
+
+      def add_mount(mapping, mode)
+        unless mapping.is_a?(Hash) && mapping.size == 1
+          raise InvalidConfiguration,
+                'mount expects exactly one pair: c.mount "host/path" => "/data"'
+        end
+
+        host, guest = mapping.first
+        @changes[:mounts] = Array(@changes[:mounts]) + [{ host: host, guest: guest, mode: mode }]
+      end
     end
 
     private
@@ -135,4 +209,117 @@ module SecurityBox
             "or pass image_path in the configuration."
     end
   end
+
+  # Validated collection of host-folder mounts (stage 5). A mount is a frozen
+  # {host:, guest:, mode:} hash; `mounts` in a Configuration is a frozen array
+  # of these, so the value survives #with, #fingerprint and Ractor ports.
+  #
+  # Validation (InvalidConfiguration on any violation):
+  #   - mode is :read_only or :read_write (wasmtime silently accepts unknown
+  #     symbols, so the mode is checked here, never trusted to the runtime)
+  #   - host: non-empty string; relative paths are expanded against Dir.pwd
+  #     (existence/directory checks are per-eval, in EvalRun — dirs can vanish)
+  #   - guest: absolute, normalized path (no "..", no trailing slash), not "/"
+  #   - guest paths must not overlap /work, /usr or /src (exact or nested):
+  #     a collision with the embedded VFS is silently shadowed (stage-5 spike:
+  #     the mount content is invisible), a mount inside /usr even breaks the
+  #     guest boot, and inside /work it would create a read-only subtree
+  #   - duplicate guest paths are rejected (wasmtime's last-mount-wins is
+  #     silently surprising)
+  #   - at most MAX_MOUNTS mounts
+  module Mounts
+    MODES = %i[read_only read_write].freeze
+    RESERVED_GUEST_PATHS = %w[/work /usr /src].freeze
+    MAX_MOUNTS = 16
+
+    class << self
+      # Validates + normalizes `raw` (an array of {host:, guest:, mode:} hashes
+      # or nil) and returns a frozen array of frozen, normalized hashes.
+      def normalize(raw)
+        return [].freeze if raw.nil?
+
+        raise InvalidConfiguration,
+              "mounts must be an Array of {host:, guest:, mode:} hashes, got #{raw.class}" unless raw.is_a?(Array)
+
+        mounts = raw.map { |entry| normalize_entry(entry) }
+        check_duplicates(mounts)
+        check_reserved(mounts)
+        check_count(mounts)
+        mounts.freeze
+      end
+
+      private
+
+      def normalize_entry(entry)
+        unless entry.is_a?(Hash) && entry.keys.sort == %i[guest host mode]
+          raise InvalidConfiguration,
+                "each mount must be a Hash with exactly :host, :guest and :mode keys, got #{entry.inspect}"
+        end
+
+        mode = entry[:mode]
+        unless MODES.include?(mode)
+          raise InvalidConfiguration,
+                "mount mode must be one of #{MODES.map(&:inspect).join(' or ')}, got #{mode.inspect}"
+        end
+
+        { host: normalize_host(entry[:host]),
+          guest: normalize_guest(entry[:guest]),
+          mode: mode }.freeze
+      end
+
+      def normalize_host(host)
+        unless host.is_a?(String) && !host.empty?
+          raise InvalidConfiguration, "mount host path must be a non-empty String, got #{host.inspect}"
+        end
+
+        File.expand_path(host).freeze
+      end
+
+      def normalize_guest(guest)
+        unless guest.is_a?(String) && !guest.empty?
+          raise InvalidConfiguration, "mount guest path must be a non-empty String, got #{guest.inspect}"
+        end
+        unless guest.start_with?("/")
+          raise InvalidConfiguration, "mount guest path must be absolute, got #{guest.inspect}"
+        end
+
+        guest = guest.chomp("/")
+        if guest.empty? || File.expand_path(guest, "/") != guest
+          raise InvalidConfiguration,
+                "mount guest path must be a normalized absolute path (no '..', '.' or trailing '/'), got #{guest.inspect}"
+        end
+        raise InvalidConfiguration, "mount guest path contains a NUL byte" if guest.include?("\0")
+
+        guest.freeze
+      end
+
+      def check_duplicates(mounts)
+        guests = mounts.map { |mount| mount[:guest] }
+        duplicate = guests.find { |guest| guests.count(guest) > 1 }
+        return unless duplicate
+
+        raise InvalidConfiguration, "duplicate guest mount path #{duplicate.inspect}"
+      end
+
+      def check_reserved(mounts)
+        mounts.each do |mount|
+          guest = mount[:guest]
+          conflict = RESERVED_GUEST_PATHS.find do |reserved|
+            guest == reserved || guest.start_with?("#{reserved}/") || reserved.start_with?("#{guest}/")
+          end
+          next unless conflict
+
+          raise InvalidConfiguration,
+                "mount guest path #{guest.inspect} overlaps the reserved path #{conflict.inspect}"
+        end
+      end
+
+      def check_count(mounts)
+        return if mounts.size <= MAX_MOUNTS
+
+        raise InvalidConfiguration,
+              "too many mounts (#{mounts.size}); the limit is #{MAX_MOUNTS}"
+      end
+    end
+  end
 end

data/lib/security_box/errors.rb

@@ -6,4 +6,6 @@ module SecurityBox
   class ImageMissing < Error; end
 
   class InvalidConfiguration < Error; end
+
+  class PoolClosed < Error; end
 end