security_box 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdcc33a7689dd5d68b5e9ca6c8cd36a83d8da9aa5a44c9b29a5994bd991c5d9e
-  data.tar.gz: a2f4fbf283527b9fcf484a9dc06adb3a5d34d2a1c97f355412a880c5204c9283
+  metadata.gz: 9949a172b6bf1ddf1eddd9756c8dcbad273d8f2409669304227bb2f981c9fef6
+  data.tar.gz: 499c948e3fd57c221f8aef7f8ad6dd63757b36e9d5a4a62d8c8a70823908f86d
 SHA512:
-  metadata.gz: 86158b7097c7e53602f80949350d2f2aebaf9f672400f908127fb995fbf829dc5a16928873231d1c2b8539660a0f7c5a0c2f600f40a225558afaf39f83a9ee77
-  data.tar.gz: e08ee261ac36c91b3fe6761a01e655410d60c3023094e852c7e1fa9ddc8728efe646366bd840c6863264b1f41826874794b52e6a1125dddbca8f662ae3f76fe4
+  metadata.gz: 1cf51781bb108aa6849ae24bd1db5b812c7e0a7e94f0d1876eb1a860cabc4a6b00241fdc19b4b142b88da8bdf86ed6e9c5dc53009237f36706a4ff637fe96d5f
+  data.tar.gz: 39dfd3af95bc8bfd2e3bd79ac57b118ee706b2f7da3aee98854aea832094b29342e751b2a41bf630c593fd07289ecf7ac041b1d416682924f276a29be4a7259b

data/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.3.0] - 2026-09-14
+
+### Added
+
+- Named, reusable profiles: `SecurityBox.register(:name, from: :base) { |c| c.fuel 100 }`
+  and `SecurityBox.spawn(:name, **overrides)` (a `Configuration` or the defaults also
+  work). Profiles are immutable; duplicate/unknown names raise
+  `SecurityBox::InvalidConfiguration`.
+- `SecurityBox::Configuration#fingerprint`: a stable identity for equal settings
+  (SHA-256 of the canonical configuration), ready for artifact caches.
+- Guest error envelopes now carry a `backtrace`: user frames only, capped at 20,
+  sandbox-internal locations (no host paths). Surfaced via `Result#error["backtrace"]`;
+  malformed backtraces invalidate the envelope (`:sandbox_error`).
+- `Result#fuel_used` is now `nil` for `:timeout`: epoch traps restore fuel to the last
+  checkpoint, so the restored value understated consumption by orders of magnitude.
+  (Truthful on completion, fuel exhaustion and memory-limit traps.)
+
+### Changed
+
+- A guest `NoMemoryError` (interpreter OOM against the store limit) is reported as
+  `:memory_limit` instead of `:error`.
+- A `memory_size` below the image's declared minimum (1528 pages ≈ 95.5 MiB) now
+  returns a `:sandbox_error` Result with a `security_box:` note on stderr instead of
+  raising `Wasmtime::Error` out of `#eval`.
+- The sandbox image must be repacked (`rake security_box:build_image`) when
+  upgrading: the guest entrypoint protocol changed.
+
 ## [0.2.0] - 2026-09-14
 
 ### Added

data/README.md

@@ -144,13 +144,44 @@ SecurityBox.eval('1000.times { print "x" * 1000 }', stdout_limit: 4096).stdout.b
 Exceptions raised by guest code are a *result*, not a sandbox failure:
 
 ```ruby
-result = SecurityBox.eval('raise ArgumentError, "boom"')
+result = SecurityBox.eval("def boom; raise ArgumentError, 'boom'; end; boom")
 
-result.status           # => :error
-result.error["class"]   # => "ArgumentError"
-result.error["message"] # => "boom"
+result.status                    # => :error
+result.error["class"]            # => "ArgumentError"
+result.error["message"]          # => "boom"
+result.error["backtrace"]        # => ["sandbox:1:in 'Object#boom'", "sandbox:1:in '<main>'"]
 ```
 
+The backtrace contains guest frames only (sandbox-internal locations, capped at
+20 frames) — nothing from the host filesystem leaks.
+
+### Named profiles
+
+Reusable configurations registered once and spawned as often as needed:
+
+```ruby
+SecurityBox.register(:default) do |c|
+  c.fuel 10_000_000_000
+  c.timeout_ms 2_000
+end
+
+SecurityBox.register(:lean, from: :default) do |c|
+  c.fuel 2_000_000_000        # boot alone costs ~1e9; see the fuel notes below
+  c.timeout_ms 500
+end
+
+box = SecurityBox.spawn(:lean)               # Sandbox from the profile
+box.eval("40 + 2").value                     # => 42
+
+SecurityBox.spawn(:lean, timeout_ms: 100)    # per-call override (profile unchanged)
+SecurityBox.spawn                            # default configuration
+```
+
+Profiles are immutable: duplicate names and unknown names raise
+`SecurityBox::InvalidConfiguration`; overrides never mutate the profile.
+`SecurityBox::Configuration#fingerprint` gives every configuration a stable
+identity (equal settings → equal fingerprint), used to share runtime artifacts.
+
 ### Configuration
 
 `SecurityBox::Configuration` is immutable; use `.build` to create and `#with` to derive:
@@ -175,11 +206,11 @@ sandbox = SecurityBox::Sandbox.new(lean)
 | Status | Meaning |
 |---|---|
 | `:ok` | guest code ran and returned a value |
-| `:error` | guest code raised an exception (see `#error`) |
-| `:timeout` | interrupted by the epoch deadline (wall clock) |
+| `:error` | guest code raised an exception (see `#error`; includes `backtrace`) |
+| `:timeout` | interrupted by the epoch deadline (wall clock); `fuel_used` is `nil` (epoch traps restore fuel to the checkpoint) |
 | `:fuel_exhausted` | CPU budget exhausted |
-| `:memory_limit` | exceeded the store `memory_size` |
-| `:sandbox_error` | sandbox failure (unexpected trap, missing/invalid envelope) |
+| `:memory_limit` | exceeded the store `memory_size` (wasm trap or guest `NoMemoryError`) |
+| `:sandbox_error` | sandbox failure (unexpected trap, missing/invalid envelope, `memory_size` below the image's minimum) |
 
 Values are JSON-serialized; non-serializable objects are returned as their `inspect`
 string.
@@ -205,6 +236,17 @@ Notes:
 - 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`).
+- 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.
+- Fuel budgeting: compute workloads burn ~4–8e9 fuel/s (tight loops up to ~8.4e9/s)
+  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).
 
 ## Running the tests
 
@@ -240,3 +282,5 @@ bundle exec ruby bin/spike.rb
 - `docs/plan/stages/stage_1.md` — stage 1 findings and measured numbers
 - `docs/plan/stages/stage_2.md` — stage 2 findings (hardening prelude, result-channel
   integrity, compiled-module disk cache)
+- `docs/plan/stages/stage_3.md` — stage 3 findings (named profiles, Ractor
+  parallelism, memory floor, fuel calibration, backtrace)

data/lib/security_box/configuration.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "digest"
+require "json"
+
 module SecurityBox
   # Immutable sandbox configuration. Use .build to create and #with to derive.
   class Configuration
@@ -55,6 +58,64 @@ module SecurityBox
       }
     end
 
+    # Stable identity of the configuration values (SHA-256 of the normalized
+    # hash). Two configurations with equal settings — regardless of how they
+    # were built — share the same fingerprint; any #with change produces a
+    # different one. Used to key profiles and, later, cached artifacts.
+    def fingerprint
+      Digest::SHA256.hexdigest(JSON.generate(canonical))
+    end
+
+    def canonical
+      to_h.merge(env: @env.sort.to_h)
+    end
+
+    # Mutable collector for the register DSL. Setter names match the
+    # Configuration options (no `=`, e.g. `c.fuel 100`); only changed values
+    # are collected and merged over the base profile.
+    class Builder
+      def initialize
+        @changes = {}
+      end
+
+      def changes
+        @changes
+      end
+
+      def image_path(value)
+        @changes[:image_path] = value
+      end
+
+      def fuel(value)
+        @changes[:fuel] = value
+      end
+
+      def timeout_ms(value)
+        @changes[:timeout_ms] = value
+      end
+
+      def memory_size(value)
+        @changes[:memory_size] = value
+      end
+
+      def stdout_limit(value)
+        @changes[:stdout_limit] = value
+      end
+
+      def stderr_limit(value)
+        @changes[:stderr_limit] = value
+      end
+
+      def epoch_interval_ms(value)
+        @changes[:epoch_interval_ms] = value
+      end
+
+      # Replaces the guest environment (it is not merged with the base).
+      def env(value)
+        @changes[:env] = value
+      end
+    end
+
     private
 
     # Resolution order (first existing path wins):

data/lib/security_box/envelope.rb

@@ -55,11 +55,20 @@ module SecurityBox
           return false unless error.is_a?(Hash)
           return false unless error["class"].is_a?(String)
           return false unless error["message"].is_a?(String)
+          return false unless valid_backtrace?(error["backtrace"])
         end
 
         duration = envelope["duration_ms"]
         duration.nil? || duration.is_a?(Numeric)
       end
+
+      # Optional: an array of backtrace frame strings (guest-side errors).
+      def valid_backtrace?(backtrace)
+        return true if backtrace.nil?
+        return false unless backtrace.is_a?(Array)
+
+        backtrace.all?(String)
+      end
     end
   end
 end

data/lib/security_box/guest/main.rb

@@ -43,7 +43,26 @@ module SB
   def evaluate(code)
     { ok: true, value: jsonable(eval(code, TOPLEVEL_BINDING, "sandbox")) } # rubocop:disable Security/Eval,Style/EvalWithLocation
   rescue Exception => e # rubocop:disable Lint/RescueException
-    { ok: false, value: nil, error: { "class" => e.class.name, "message" => e.message.to_s } }
+    {
+      ok: false, value: nil,
+      error: {
+        "class" => e.class.name,
+        "message" => e.message.to_s,
+        "backtrace" => guest_backtrace(e)
+      }
+    }
+  end
+
+  # Frames of the user code only: guest protocol internals (main.rb /
+  # prelude.rb) are stripped and the list is capped so a deep recursion
+  # cannot flood the result channel.
+  def guest_backtrace(exception)
+    frames = (exception.backtrace || []).reject do |frame|
+      frame.include?("main.rb") || frame.include?("prelude.rb")
+    end
+    frames.first(20)
+  rescue StandardError
+    []
   end
 
   # Values must survive JSON; the round-trip normalizes what the host will read.
@@ -55,11 +74,22 @@ module SB
 
   # Preferred: /work/out.json. Fallback (no /work): sentinel on stdout.
   # Both carry the sandbox token so the host can reject forged results.
+  # The write is verified by reading it back — a silent truncation or
+  # partial write falls through to the sentinel instead of losing the
+  # result.
   def emit(out, token)
     json = JSON.generate(out.merge(token: token))
-    File.write(File.join(WORK_DIR, "out.json"), json)
+    unless write_verified(json)
+      $stdout.puts "#{SENTINEL}:#{token}:#{json}"
+    end
+  end
+
+  def write_verified(json)
+    path = File.join(WORK_DIR, "out.json")
+    File.write(path, json)
+    File.read(path) == json
   rescue StandardError, SystemCallError
-    $stdout.puts "#{SENTINEL}:#{token}:#{json}"
+    false
   end
 
   def fatal(message, token)

data/lib/security_box/registry.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SecurityBox
+  # Named, reusable profiles: `SecurityBox.register(:name, from: :base) { |c| ... }`
+  # stores an immutable Configuration built through the builder DSL; `spawn`
+  # resolves a profile and derives per-call overrides with `#with`.
+  #
+  # Profiles must be registered before they are referenced by `from:`, cannot
+  # be redefined (immutability avoids accidental shadowing) and live for the
+  # process lifetime; tests can reset the registry with `clear!`.
+  module Registry
+    MUTEX = Mutex.new
+
+    @profiles = {}
+
+    class << self
+      def register(name, from: nil, &block)
+        key = normalize(name)
+        MUTEX.synchronize do
+          raise InvalidConfiguration, "profile #{key.inspect} is already registered" if @profiles.key?(key)
+
+          builder = Configuration::Builder.new
+          block&.call(builder)
+          @profiles[key] = Configuration.build(**base_of(from), **builder.changes)
+        end
+      end
+
+      def resolve(name)
+        key = normalize(name)
+        MUTEX.synchronize do
+          @profiles.fetch(key) do
+            raise InvalidConfiguration, "unknown profile #{key.inspect}; register it first with SecurityBox.register"
+          end
+        end
+      end
+
+      def profiles
+        MUTEX.synchronize { @profiles.dup.freeze }
+      end
+
+      def clear!
+        MUTEX.synchronize { @profiles.clear }
+      end
+
+      private
+
+      def normalize(name)
+        unless name.is_a?(Symbol) || name.is_a?(String)
+          raise InvalidConfiguration, "profile name must be a Symbol or String, got #{name.class}"
+        end
+
+        name.to_sym
+      end
+
+      def base_of(from)
+        return {} if from.nil?
+
+        key = normalize(from)
+        @profiles.fetch(key) do
+          raise InvalidConfiguration, "unknown base profile #{key.inspect}; register it before deriving from it"
+        end.to_h
+      end
+    end
+  end
+end

data/lib/security_box/sandbox.rb

@@ -56,8 +56,13 @@ module SecurityBox
           instance = build_linker.instantiate(store, @module)
           store.set_epoch_deadline(epoch_ticks(config))
           status = invoke_guest(instance, store)
-          fuel_used = config.fuel - store.get_fuel
+          fuel_used = config.fuel - store.get_fuel unless status == :timeout
           envelope = read_envelope(workdir, stdout, token)
+        rescue Wasmtime::Error => e
+          # Instantiation can fail before the guest ever runs (e.g. a
+          # memory_size below the module's declared minimum pages).
+          status = :sandbox_error
+          stderr << "security_box: #{e.class}: #{e.message}\n"
         ensure
           store.close
         end
@@ -145,6 +150,15 @@ module SecurityBox
           fuel_used: fuel_used, duration_ms: duration_ms,
           guest_duration_ms: envelope["duration_ms"]
         )
+      elsif guest_memory_error?(guest_error)
+        # The guest hit the store memory limit through the Ruby interpreter
+        # (NoMemoryError instead of a wasm trap) — report it as a limit, not
+        # a user error.
+        Result.new(
+          status: :memory_limit, error: guest_error, stdout: stdout, stderr: stderr,
+          fuel_used: fuel_used, duration_ms: duration_ms,
+          guest_duration_ms: envelope["duration_ms"]
+        )
       else
         Result.new(
           status: :error, error: guest_error, stdout: stdout, stderr: stderr,
@@ -154,6 +168,10 @@ module SecurityBox
       end
     end
 
+    def guest_memory_error?(guest_error)
+      guest_error.is_a?(Hash) && guest_error["class"] == "NoMemoryError"
+    end
+
     def monotonic_ms
       Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000
     end

data/lib/security_box/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SecurityBox
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/security_box.rb

@@ -3,6 +3,7 @@
 require_relative "security_box/version"
 require_relative "security_box/errors"
 require_relative "security_box/configuration"
+require_relative "security_box/registry"
 require_relative "security_box/result"
 require_relative "security_box/module_cache"
 require_relative "security_box/runtime"
@@ -17,6 +18,33 @@ module SecurityBox
     Sandbox.new.eval(code, **overrides)
   end
 
+  # Registers a named, reusable profile (see Registry).
+  #   SecurityBox.register(:lean, from: :default) { |c| c.fuel 5_000_000 }
+  def self.register(name, from: nil, &block)
+    Registry.register(name, from: from, &block)
+  end
+
+  # Builds a Sandbox from a registered profile, a Configuration, or the
+  # defaults:
+  #   SecurityBox.spawn(:lean)                  # named profile
+  #   SecurityBox.spawn(:lean, fuel: 1_000)     # profile + per-call overrides
+  #   SecurityBox.spawn(my_config)              # explicit configuration
+  #   SecurityBox.spawn                         # default configuration
+  def self.spawn(profile = nil, **overrides)
+    config = case profile
+             when nil then Configuration.build(**overrides)
+             when Symbol, String
+               resolved = Registry.resolve(profile)
+               overrides.empty? ? resolved : resolved.with(**overrides)
+             when Configuration
+               overrides.empty? ? profile : profile.with(**overrides)
+             else
+               raise ArgumentError,
+                     "profile must be a registered name or a Configuration, got #{profile.class}"
+             end
+    Sandbox.new(config)
+  end
+
   # Prepares the shared runtime artifacts (Engine + compiled Module) ahead of
   # time so the first #eval skips the cold module compilation (~15s per
   # process). #eval warms these caches lazily on first use, so calling

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: security_box
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Marcelo Junior
@@ -44,6 +44,7 @@ files:
 - lib/security_box/guest/main.rb
 - lib/security_box/guest/prelude.rb
 - lib/security_box/module_cache.rb
+- lib/security_box/registry.rb
 - lib/security_box/result.rb
 - lib/security_box/runtime.rb
 - lib/security_box/sandbox.rb