security_box 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22aa6209552c4b4a4fbc60fa98b71e6f70448fb308e3c8f133515ef663c32d7c
-  data.tar.gz: a33ce5bc7a235946efbd283eb3a8f5a718dc87a971eeb3eff799c5b6701ed172
+  metadata.gz: bdcc33a7689dd5d68b5e9ca6c8cd36a83d8da9aa5a44c9b29a5994bd991c5d9e
+  data.tar.gz: a2f4fbf283527b9fcf484a9dc06adb3a5d34d2a1c97f355412a880c5204c9283
 SHA512:
-  metadata.gz: aa260831067c04ed120b56d082b068ffd606a060999921e5e4f21f925eb4b721cd37c6e786a646cf024e02a5eba05f4e8e0354311045df76d3d9fb99838aa0fd
-  data.tar.gz: 1d0f95de215b37537d2ba3ca638120599d0461d50b783e1e5b52c5c56375d5729f4c1978e815082dc8c824a0389c1f765147cdf5d06f29981ad05e0f99c7ebc3
+  metadata.gz: 86158b7097c7e53602f80949350d2f2aebaf9f672400f908127fb995fbf829dc5a16928873231d1c2b8539660a0f7c5a0c2f600f40a225558afaf39f83a9ee77
+  data.tar.gz: e08ee261ac36c91b3fe6761a01e655410d60c3023094e852c7e1fa9ddc8728efe646366bd840c6863264b1f41826874794b52e6a1125dddbca8f662ae3f76fe4

data/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.2.0] - 2026-09-14
+
+### Added
+
+- Compiled-module disk cache (`~/.cache/security_box/modules`, override with
+  `SECURITY_BOX_CACHE_DIR`): new processes boot the runtime in ~0.5s instead
+  of ~15s by deserializing the compiled artifact instead of recompiling.
+  Best effort — misses, corruption or an unwritable directory fall back to a
+  normal compile.
+- Result-channel integrity: a per-eval random token is passed to the guest via
+  `SB_TOKEN`, captured and scrubbed by the hardening prelude, and embedded in
+  both the `/work/out.json` envelope and the stdout sentinel line. The host
+  validates the envelope schema and token; forged results (e.g. an `at_exit`
+  overwrite or a fake sentinel) become `:sandbox_error`.
+- Hardening prelude (`lib/security_box/guest/prelude.rb`): `system`, `exec`,
+  `Kernel#spawn`, backticks, `IO.popen`, `Process.spawn` and `Kernel#open` now
+  raise `SecurityError` inside the guest (they previously were misleading
+  WASI stubs); `ENV` is scrubbed before user code runs; `$stdout.sync = true`.
+
+### Changed
+
+- Guest result envelope carries a `token` field; `system(...)` inside guest
+  code raises `SecurityError` instead of returning a stub `true`.
+- The sandbox image must be repacked (`rake security_box:build_image`) when
+  upgrading: the guest entrypoint protocol changed.
+
 ## [0.1.0] - 2026-09-13
 
 ### Added

data/README.md

@@ -16,13 +16,16 @@ tries to escape.
 ## How it works
 
 1. A `ruby.wasm` image is packed with the Ruby runtime + stdlib + a small guest
-   entrypoint (`lib/security_box/guest/main.rb`).
+   entrypoint (`lib/security_box/guest/main.rb`) plus a hardening prelude
+   (`lib/security_box/guest/prelude.rb`).
 2. On every `#eval`, the host creates an exclusive tmpdir, writes the user code to it, and
-   mounts it read-write as `/work` inside the sandbox.
-3. A fresh wasm instance boots, evaluates the code and serializes a JSON envelope to
-   `/work/out.json`.
-4. The host reads the envelope, maps any wasmtime trap to a `Result` status, closes the
-   store and discards the tmpdir.
+   mounts it read-write as `/work` inside the sandbox. It also generates a per-eval
+   random token and passes it to the guest via `SB_TOKEN`.
+3. A fresh wasm instance boots; the prelude captures the token, scrubs `ENV` and
+   neutralizes process-spawn APIs, then the guest evaluates the code and serializes a
+   token-signed JSON envelope to `/work/out.json` (stdout sentinel fallback).
+4. The host validates the envelope (schema + token — forged results are rejected),
+   maps any wasmtime trap to a `Result` status, closes the store and discards the tmpdir.
 
 One wasm process per `#eval` means zero residual state between executions.
 
@@ -87,15 +90,18 @@ result.duration_ms # => 257.0 (approx; dominated by the ruby.wasm boot)
 
 ### Warming up
 
-The first `eval` in a process pays the cold WebAssembly compilation of the image
-(~15s) plus the engine setup. Call `SecurityBox.warmup` ahead of time (e.g., at
-boot) to pay that cost up front — every subsequent `eval` then only pays the
-~240ms guest boot:
+The first `eval` in a process pays either the cold WebAssembly compilation of the image
+(~15s) or a fast deserialize from the compiled-module disk cache (~0.5s) plus the engine
+setup. The cache lives in `~/.cache/security_box/modules` (override with
+`SECURITY_BOX_CACHE_DIR`), is keyed by the image content, and is fully best effort —
+on any miss or corruption the module is simply recompiled. Call `SecurityBox.warmup`
+ahead of time (e.g., at boot) to pay that cost up front — every subsequent `eval` then
+only pays the ~260ms guest boot:
 
 ```ruby
 SecurityBox.warmup
 
-SecurityBox.eval("40 + 2").value # => 42 (~250ms, no cold compile)
+SecurityBox.eval("40 + 2").value # => 42 (~260ms, no cold compile)
 ```
 
 `#eval` warms the same caches lazily on first use, so calling `warmup` is a pure
@@ -184,11 +190,13 @@ string.
 |---|---|
 | `File.write("/etc/passwd", ...)` | `Errno::ENOENT` (guest does not see the host FS) |
 | `Dir["/*"]` | `[]` (empty root) |
-| `system("ls")` / backticks / `IO.popen` | no-op stubs / `ArgumentError` (nothing executes) |
+| `system("ls")` / backticks / `IO.popen` / `Process.spawn` | `SecurityError` (hardening prelude) |
+| `Kernel#open(...)` | `SecurityError` (pipe form; use `File.open`) |
 | `fork` | `NotImplementedError` |
 | `Thread.new` | `NotImplementedError` (WASI p1 has no threads) |
 | `require "socket"` | `LoadError` (no network) |
-| `ENV` | `{}` (sanitized) |
+| `ENV` | `{}` (token read and scrubbed by the prelude) |
+| forge `out.json` via `at_exit` / fake sentinel | rejected (token mismatch → `:sandbox_error`) |
 | infinite loop | killed by epoch deadline or fuel budget |
 
 Notes:
@@ -230,3 +238,5 @@ bundle exec ruby bin/spike.rb
 
 - `docs/PLAN.md` — architecture, roadmap and threat model
 - `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)

data/lib/security_box/envelope.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SecurityBox
+  # Host-side validation of the guest result envelope.
+  #
+  # The guest reports its result either via /work/out.json or, when /work is
+  # unavailable, via a sentinel line on stdout (format:
+  # `__SECURITY_BOX_RESULT__:<token>:<json>`). Both embed the per-eval random
+  # token the host generated. An envelope is trusted only when it parses, the
+  # token matches and every field has the expected type; otherwise nil is
+  # returned and the execution is reported as a sandbox failure.
+  module Envelope
+    # Keep in sync with lib/security_box/guest/main.rb.
+    SENTINEL = "__SECURITY_BOX_RESULT__"
+
+    class << self
+      # Parses `raw` (JSON text) and validates it against `token`.
+      # Returns the envelope Hash or nil when invalid/untrusted.
+      def parse(raw, token)
+        return nil unless raw.is_a?(String) && token.is_a?(String) && !token.empty?
+
+        envelope = JSON.parse(raw)
+        return nil unless valid?(envelope, token)
+
+        envelope
+      rescue JSON::ParserError, TypeError, ArgumentError
+        nil
+      end
+
+      # Scans captured stdout for exactly one sentinel line carrying `token`.
+      # Zero or multiple sentinel lines (e.g. a guest forging an extra one)
+      # yield nil.
+      def from_stdout(stdout, token)
+        prefix = "#{SENTINEL}:"
+        lines = stdout.to_s.split("\n").select { |line| line.start_with?(prefix) }
+        return nil unless lines.size == 1
+
+        _sentinel, _embedded_token, json = lines.first.split(":", 3)
+        parse(json, token)
+      end
+
+      private
+
+      def valid?(envelope, token)
+        return false unless envelope.is_a?(Hash)
+        return false unless [true, false].include?(envelope["ok"])
+        return false unless envelope["token"] == token
+
+        if envelope["ok"]
+          return false unless envelope.key?("value")
+        else
+          error = envelope["error"]
+          return false unless error.is_a?(Hash)
+          return false unless error["class"].is_a?(String)
+          return false unless error["message"].is_a?(String)
+        end
+
+        duration = envelope["duration_ms"]
+        duration.nil? || duration.is_a?(Numeric)
+      end
+    end
+  end
+end

data/lib/security_box/guest/main.rb

@@ -3,11 +3,16 @@
 # Input: /work/code.rb (preferred) or ARGV[0].
 # Result: /work/out.json (JSON envelope); fallback: sentinel line on stdout.
 #
-# NOTE (stage 1): the result channel is reliable against accidents, not against
-# an active adversary (guest code can forge the envelope). Token mitigations and
-# schema validation land in Stage 2.
+# Integrity: the host generates a per-eval random token and passes it via ENV;
+# the prelude captures it and scrubs ENV before user code runs. Both the
+# envelope and the sentinel line embed the token, and the host rejects any
+# result that does not carry the expected token (see lib/security_box/envelope.rb).
+# This hardens the channel against forged results (e.g. an at_exit handler
+# overwriting out.json); it is defense in depth, not a cryptographic guarantee.
 require "json"
 
+require_relative "prelude"
+
 module SB
   SENTINEL = "__SECURITY_BOX_RESULT__"
   WORK_DIR = "/work"
@@ -15,13 +20,15 @@ module SB
   module_function
 
   def run
+    token = SBPrelude.apply!
+
     code = fetch_code
-    return fatal("no code provided") unless code
+    return fatal("no code provided", token) unless code
 
     t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     out = evaluate(code)
     out[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round(2)
-    emit(out)
+    emit(out, token)
   end
 
   def fetch_code
@@ -47,15 +54,16 @@ module SB
   end
 
   # Preferred: /work/out.json. Fallback (no /work): sentinel on stdout.
-  def emit(out)
-    json = JSON.generate(out)
+  # Both carry the sandbox token so the host can reject forged results.
+  def emit(out, token)
+    json = JSON.generate(out.merge(token: token))
     File.write(File.join(WORK_DIR, "out.json"), json)
   rescue StandardError, SystemCallError
-    $stdout.puts "#{SENTINEL}:#{json}"
+    $stdout.puts "#{SENTINEL}:#{token}:#{json}"
   end
 
-  def fatal(message)
-    emit({ ok: false, value: nil, error: { "class" => "SecurityBox::Guest", "message" => message } })
+  def fatal(message, token)
+    emit({ ok: false, value: nil, error: { "class" => "SecurityBox::Guest", "message" => message } }, token)
   end
 end
 

data/lib/security_box/guest/prelude.rb

@@ -0,0 +1,71 @@
+# Hardening prelude — loaded before user code (defense in depth; WASI is the
+# primary isolation boundary).
+#
+# Responsibilities (in order):
+#   1. capture the per-eval sandbox token from ENV and hand it to the guest
+#      protocol exactly once (main.rb), erasing every other reference;
+#   2. scrub ENV so user code sees an empty environment;
+#   3. neutralize the process-spawn APIs that WASI leaves as misleading stubs
+#      (e.g. `system` returns true without running anything) by raising
+#      SecurityError instead;
+#   4. disable Kernel#open entirely (its pipe form executes processes; user
+#      code must use File.open/IO.read for plain files);
+#   5. set $stdout.sync so captured output is not lost on a hard kill.
+module SBPrelude
+  DENIED_MESSAGE = "process execution is not allowed inside the sandbox"
+
+  class << self
+    # Applies all hardening and returns the sandbox token (or nil). The token
+    # is removed from the prelude state; afterwards it exists only in the
+    # caller's local scope.
+    def apply!
+      capture_token
+      scrub_env
+      neutralize_process_apis
+      sync_stdout
+      take_token
+    end
+
+    # Returns the token captured by apply! and erases the stored reference.
+    def take_token
+      token = @token
+      remove_instance_variable(:@token) if instance_variable_defined?(:@token)
+      token
+    end
+
+    private
+
+    def capture_token
+      @token = ENV["SB_TOKEN"]
+    end
+
+    def scrub_env
+      ENV.each_key { |key| ENV.delete(key) }
+    end
+
+    def neutralize_process_apis
+      %w[system exec spawn `].each do |name|
+        neutralize_instance_method(Kernel, name)
+      end
+      neutralize_instance_method(Kernel, "open")
+      neutralize_singleton_method(IO, :popen)
+      neutralize_singleton_method(Process, :spawn)
+    end
+
+    def neutralize_instance_method(owner, name)
+      owner.module_eval do
+        define_method(name) { |*args, **kwargs| raise SecurityError, DENIED_MESSAGE }
+      end
+    end
+
+    def neutralize_singleton_method(owner, name)
+      owner.define_singleton_method(name) do |*args, **kwargs|
+        raise SecurityError, DENIED_MESSAGE
+      end
+    end
+
+    def sync_stdout
+      $stdout.sync = true
+    end
+  end
+end

data/lib/security_box/module_cache.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "wasmtime"
+
+module SecurityBox
+  # Content-addressed disk cache for compiled wasm modules.
+  #
+  # Compiling the ruby.wasm image costs ~15s per process. This cache stores the
+  # compiled artifact (Module#serialize) so later processes pay only a fast
+  # deserialize. Files live at <cache_dir>/modules/<key>.cwasm, where the key
+  # combines the image content digest with the wasmtime precompile compatibility
+  # key — a stored module is only reused when the running engine can consume it.
+  #
+  # Everything here is best effort: on any I/O or deserialization failure the
+  # caller falls back to a regular compile and the cache self-heals on the next
+  # successful store. Set SECURITY_BOX_CACHE_DIR to relocate the cache; the
+  # default is ~/.cache/security_box.
+  module ModuleCache
+    CACHE_DIR_ENV_VAR = "SECURITY_BOX_CACHE_DIR"
+
+    class << self
+      # Returns the cached module for this engine+image, or nil on cache miss,
+      # corrupted cache file or any cache error.
+      def load_module(engine, image_path)
+        path = cache_path(engine, image_path)
+        return nil unless path && File.file?(path)
+
+        Wasmtime::Module.deserialize_file(engine, path)
+      rescue Wasmtime::Error, TypeError, SystemCallError
+        nil
+      end
+
+      # Compiles the image and stores the serialized artifact in the cache
+      # (best effort). Returns the compiled module in all cases.
+      def compile_and_store(engine, image_path)
+        module_ = Wasmtime::Module.from_file(engine, image_path)
+        store(engine, image_path, module_)
+        module_
+      end
+
+      def store(engine, image_path, module_)
+        path = cache_path(engine, image_path)
+        return if path.nil?
+
+        dir = File.dirname(path)
+        FileUtils.mkdir_p(dir)
+        tmp = File.join(dir, ".#{File.basename(path)}.#{Process.pid}.tmp")
+        File.binwrite(tmp, module_.serialize)
+        File.rename(tmp, path)
+      rescue Wasmtime::Error, SystemCallError
+        File.delete(tmp) if defined?(tmp) && tmp && File.exist?(tmp)
+        nil
+      end
+
+      # Nil when no usable cache directory exists (cache disabled).
+      def cache_path(engine, image_path)
+        dir = modules_dir
+        return nil unless dir
+
+        File.join(dir, "#{cache_key(engine, image_path)}.cwasm")
+      end
+
+      def modules_dir
+        base = ENV[CACHE_DIR_ENV_VAR] || default_base_dir
+        return nil unless base
+
+        File.expand_path("modules", base)
+      end
+
+      private
+
+      def default_base_dir
+        home = ENV["HOME"]
+        home && File.join(home, ".cache", "security_box")
+      end
+
+      # Digest cost scales with the image size (~0.7s for the 110MB ruby.wasm
+      # image); memoized per file identity so it is paid once per process
+      # (and recomputed only if the file changes on disk).
+      def cache_key(engine, image_path)
+        @keys ||= {}
+        stat = File.stat(image_path)
+        key = @keys[[image_path, stat.size, stat.mtime]]
+        return key if key
+
+        image_digest = Digest::SHA256.file(image_path).hexdigest
+        @keys[[image_path, stat.size, stat.mtime]] =
+          Digest::SHA256.hexdigest("#{image_digest}:#{engine.precompile_compatibility_key}")
+      end
+    end
+  end
+end

data/lib/security_box/runtime.rb

@@ -2,13 +2,16 @@
 
 require "wasmtime"
 
+require_relative "module_cache"
+
 module SecurityBox
   # Registry of heavyweight artifacts shared across sandboxes:
   # - Engine (one per runtime configuration; owns the epoch timer)
   # - Compiled Module (one per engine+image)
   #
-  # Module compilation is slow (~15s the first time per process); the disk cache
-  # (Module#serialize) lands in Stage 2.
+  # Module compilation is slow (~15s the first time per process); the compiled
+  # artifact is persisted via ModuleCache so later processes deserialize it
+  # from disk instead of recompiling.
   module Runtime
     MUTEX = Mutex.new
 
@@ -24,8 +27,10 @@ module SecurityBox
 
       def module_for(engine, image_path)
         MUTEX.synchronize do
-          @modules[[engine.object_id, image_path]] ||=
-            Wasmtime::Module.from_file(engine, image_path)
+          @modules[[engine.object_id, image_path]] ||= begin
+            ModuleCache.load_module(engine, image_path) ||
+              ModuleCache.compile_and_store(engine, image_path)
+          end
         end
       end
 

data/lib/security_box/sandbox.rb

@@ -10,12 +10,17 @@ module SecurityBox
   # Flow:
   #   1. exclusive tmpdir mounted as /work (read-write)
   #   2. user code written to /work/code.rb
-  #   3. guest (/src/main.rb) evaluates it and writes /work/out.json
-  #   4. host reads the envelope and returns a Result
+  #   3. a per-eval random token is passed via ENV (SB_TOKEN); the guest
+  #      prelude captures it and scrubs ENV before user code runs
+  #   4. guest (/src/main.rb) evaluates the code and writes /work/out.json,
+  #      embedding the token (stdout sentinel fallback does the same)
+  #   5. host reads the envelope, validates schema + token (untrusted results
+  #      become a sandbox failure) and returns a Result
   class Sandbox
     GUEST_ENTRYPOINT = "/src/main.rb"
     RESULT_FILE = "out.json"
     CODE_FILE = "code.rb"
+    TOKEN_ENV_VAR = "SB_TOKEN"
 
     def initialize(configuration = Configuration.build)
       @config = configuration
@@ -32,6 +37,7 @@ module SecurityBox
       config = overrides.empty? ? @config : @config.with(**overrides)
       stdout = +""
       stderr = +""
+      token = SecureRandom.hex(16)
       t0 = monotonic_ms
 
       Dir.mktmpdir("security_box") do |workdir|
@@ -42,7 +48,7 @@ module SecurityBox
 
         store = Wasmtime::Store.new(
           @engine,
-          wasi_p1_config: build_wasi(workdir, stdout, stderr, config),
+          wasi_p1_config: build_wasi(workdir, stdout, stderr, config, token),
           limits: { memory_size: config.memory_size }
         )
         begin
@@ -51,7 +57,7 @@ module SecurityBox
           store.set_epoch_deadline(epoch_ticks(config))
           status = invoke_guest(instance, store)
           fuel_used = config.fuel - store.get_fuel
-          envelope = read_envelope(workdir)
+          envelope = read_envelope(workdir, stdout, token)
         ensure
           store.close
         end
@@ -62,13 +68,13 @@ module SecurityBox
 
     private
 
-    def build_wasi(workdir, stdout, stderr, config)
+    def build_wasi(workdir, stdout, stderr, config, token)
       Wasmtime::WasiConfig.new
         .set_stdin_string("")
         .set_stdout_buffer(stdout, config.stdout_limit)
         .set_stderr_buffer(stderr, config.stderr_limit)
         .set_argv(["ruby", GUEST_ENTRYPOINT])
-        .set_env(config.env)
+        .set_env(config.env.merge(TOKEN_ENV_VAR => token))
         .set_mapped_directory(workdir, "/work", :read_write)
     end
 
@@ -110,12 +116,16 @@ module SecurityBox
       end
     end
 
-    def read_envelope(workdir)
-      path = File.join(workdir, RESULT_FILE)
-      return nil unless File.exist?(path)
+    def read_envelope(workdir, stdout, token)
+      # Preferred channel: /work/out.json. Fallback: sentinel line on stdout.
+      # Both go through the same strict validation (schema + token).
+      Envelope.parse(read_result_file(workdir), token) ||
+        Envelope.from_stdout(stdout, token)
+    end
 
-      JSON.parse(File.read(path))
-    rescue JSON::ParserError
+    def read_result_file(workdir)
+      File.read(File.join(workdir, RESULT_FILE))
+    rescue SystemCallError
       nil
     end
 

data/lib/security_box/version.rb

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

data/lib/security_box.rb

@@ -4,7 +4,9 @@ require_relative "security_box/version"
 require_relative "security_box/errors"
 require_relative "security_box/configuration"
 require_relative "security_box/result"
+require_relative "security_box/module_cache"
 require_relative "security_box/runtime"
+require_relative "security_box/envelope"
 require_relative "security_box/sandbox"
 
 module SecurityBox

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: security_box
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Marcelo Junior
@@ -39,8 +39,11 @@ files:
 - lib/security_box.rb
 - lib/security_box/assets/security_box.wasm
 - lib/security_box/configuration.rb
+- lib/security_box/envelope.rb
 - lib/security_box/errors.rb
 - lib/security_box/guest/main.rb
+- lib/security_box/guest/prelude.rb
+- lib/security_box/module_cache.rb
 - lib/security_box/result.rb
 - lib/security_box/runtime.rb
 - lib/security_box/sandbox.rb