security_box 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 999342421a33fdaba7863952bafad78dc8e87bac98a1ec02269fb2903be9d414
-  data.tar.gz: b119d9d14854ba07b2f99bd1c5d8c8e2e25db4f5f50370d1ecea41491ee8b673
+  metadata.gz: b5972e4ef120906a25c58bd1783e11091948929bd3fbdbd8aa4f738cd57a8819
+  data.tar.gz: b50d68cb20da70bcae520b0c5828391d11cf34c3f81839c7e9d458dde82d4f86
 SHA512:
-  metadata.gz: 20c96a86adc927a31e1abbe16a6a6cae1b49b015f7078917a0cd1fccfab61e3f5afbc7e2b0a1f71bf546aa21bd40db7d063fb138f542f3c1d2c14f968cd93e05
-  data.tar.gz: 8eddad9955d7801ce2ce93531ba92d581f1686f07288012501bc933d47034502dc3a7a4089f992340a2173ed2230e3698c1b5fdbb1b1e575465ccda0c53f3004
+  metadata.gz: 0221d3c37d4d5cb19c985b51088724ddd213d99ae52a9e3af305e1ed924e527c842e05bdebd0b5cfa330564bffea4571a6d28dc95f2fbed3ad8deb6a403f7bef
+  data.tar.gz: f5a71c1643e9543424e6b2767960d6cbb6d836ae8fa979dd653fcffe4bc14498c92352658a0de5c49f9263f45c5c6e37959f64ac8f6ed64268fe38424ced054f

data/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.7.0] - 2026-11-02
+
+### Added
+
+- RSpec is bundled into the sandbox image (`lib/security_box/guest_ext`), so
+  guest code can run spec suites from mounted projects. `SB.run_rspec` loads
+  RSpec lazily, runs it with `HOME`/cwd set to a writable directory and
+  returns the exit status instead of exiting the guest. The image grows by
+  ~2MB (about 52MB total); boot time is unchanged because RSpec is only
+  required on first use.
+- `samples/rspec_sandbox`: a runnable sample that mounts a `ruby_src/` folder
+  read-only, runs its existing spec with `/work` as cwd through
+  `SB.run_rspec`, and includes a deliberately failing example to show how
+  failures reach the caller (`Result#value` + `Result#stdout`).
+
+### Changed
+
+- `Rakefile`: the guest image freshness check now includes
+  `lib/security_box/guest_ext/Gemfile.lock`.
+
 ## [0.6.0] - 2026-09-21
 
 ### Added

data/README.md

@@ -20,7 +20,8 @@ tries to escape.
    then packed with the guest entrypoint (`lib/security_box/guest/main.rb`)
    plus a hardening prelude (`lib/security_box/guest/prelude.rb`). The
    `sb_rpc` gem declares the `sb`/`call` wasm import used by the host RPC
-   channel (see "Host RPC (code mode)" below).
+   channel (see "Host RPC (code mode)" below), and RSpec is bundled so guest
+   code can run spec suites (see "Running RSpec inside the sandbox").
 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. It also generates a per-eval
    random token and passes it to the guest via `SB_TOKEN`.
@@ -53,7 +54,7 @@ gem "security_box"
 ```
 
 The gem ships a prebuilt sandbox image (`lib/security_box/assets/security_box.wasm`,
-about 50MB), so no network access or build tools are needed at install or at
+about 52MB), so no network access or build tools are needed at install or at
 runtime.
 
 ### Rebuilding the image (development only)
@@ -269,6 +270,50 @@ Security notes:
 - 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.
 
+### Running RSpec inside the sandbox
+
+The image bundles RSpec (`~> 3.13`), so guest code can run a spec suite from a
+mounted project. `SB.run_rspec` loads RSpec lazily, runs it with `HOME` and cwd
+set to a writable directory, and returns the exit status (`0` = all examples
+passed) instead of exiting the guest:
+
+```ruby
+box = SecurityBox.spawn(
+  timeout_ms: 30_000,
+  fuel_ms: 20_000,
+  mounts: [{ host: "./project", guest: "/project", mode: :read_only }]
+)
+
+result = box.eval(<<~RUBY)
+  SB.run_rspec("--no-color", "-I", "/project/lib", "/project/spec",
+               chdir: "/project")
+RUBY
+
+result.value   # => 0
+result.stdout  # => RSpec output
+```
+
+`chdir:` defaults to `/work` (the sandbox tmpdir). Use it when the suite needs
+`.rspec`, relative paths or status files from the mounted project; mount the
+project read-write if RSpec must persist them.
+
+You can also call RSpec directly:
+
+```ruby
+require "/bundle/setup.rb"
+require "rspec/core"
+RSpec::Core::Runner.run(["--no-color", "/work/spec"], $stderr, $stdout)
+```
+
+Notes:
+
+- Specs need a larger `timeout_ms`/`fuel_ms` than trivial evals; size them for
+  the whole suite, not for a single expression.
+- The guest has no process APIs, so RSpec features that spawn processes
+  (external formatters, `--bisect`-style workflows) are unavailable.
+- `/work` is the sandbox's own writable tmpdir and cannot be used as a mount
+  target; mount projects at another path (for example `/project`).
+
 ### Configuration
 
 `SecurityBox::Configuration` is immutable; use `.build` to create and `#with` to derive:
@@ -433,6 +478,17 @@ bundle exec ruby bin/spike.rb
   LLM agent built with [RubyLLM](https://github.com/crmne/ruby_llm) whose code-execution
   tool runs model-generated Ruby inside the sandbox, demonstrating folder mounts
   (read-only vs read-write) end to end.
+- [`samples/ruby_llm/context7_code_mode`](samples/ruby_llm/context7_code_mode/README.md) —
+  a RubyLLM code-mode agent whose sandbox code reaches the hosted
+  [Context7](https://context7.com) MCP server through `SB.call`: host RPC
+  handlers proxy the MCP tools (streamable HTTP + bearer auth), so the API
+  key never crosses the sandbox boundary. Includes a no-LLM smoke script
+  that exercises the RPC↔MCP wiring.
+- [`samples/rspec_sandbox`](samples/rspec_sandbox/README.md) — runs an existing
+  RSpec suite inside the sandbox: the library and its spec live in `ruby_src/`,
+  are mounted read-only and run with `/work` as cwd via `SB.run_rspec`. The
+  suite includes one deliberately failing example, showing how failures reach
+  the caller through `Result#value` and `Result#stdout`.
 
 ## Documentation
 

data/lib/security_box/assets/security_box.wasm

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/security_box/assets/security_box.wasm
-size: 52249212 bytes
-sha256: 6a6b265e2c1e79f871ccee925a8ea63310cdf433fcffb061369c72f64fd5301c
+size: 53871847 bytes
+sha256: a866ea3c387155f5bce26a4a3f109b54c778297a1ad45680bbf63d38001fc636

data/lib/security_box/guest/main.rb

@@ -100,4 +100,8 @@ end
 # above; must load after it.
 require_relative "rpc"
 
+# Guest RSpec runner (SB.run_rspec) — also reopens SB; RSpec itself is
+# required lazily on the first call.
+require_relative "rspec"
+
 SB.run

data/lib/security_box/guest/rspec.rb

@@ -0,0 +1,59 @@
+# Guest-side RSpec runner (loaded by main.rb before user code).
+#
+# The image bundles RSpec (see lib/security_box/guest_ext/Gemfile), so guest
+# code can run a spec suite written to /work or mounted at another path:
+#
+#   SB.run_rspec("--no-color", "/work/spec")
+#   SB.run_rspec("-I", "/project/lib", "/project/spec", chdir: "/project")
+#
+# RSpec is required lazily on the first call, so ordinary evals do not pay
+# the load cost. The runner returns RSpec's exit status (0 = all examples
+# passed) instead of exiting the process, keeping the envelope channel intact.
+module SB
+  module_function
+
+  # Runs RSpec with `args` (an argv-style list) and returns its exit status.
+  # The suite runs with cwd and HOME set to `chdir` (default /work) so
+  # relative paths, `.rspec` discovery and RSpec's status/cache files stay
+  # inside a writable directory.
+  def run_rspec(*args, chdir: "/work")
+    previous_home = ENV["HOME"]
+    previous_pwd = Dir.pwd
+    load_rspec!
+
+    work = if File.directory?(chdir)
+             chdir
+           elsif File.directory?("/work")
+             "/work"
+           else
+             previous_pwd
+           end
+    ENV["HOME"] = work
+    Dir.chdir(work)
+
+    RSpec::Core::Runner.run(args.flatten, $stderr, $stdout)
+  ensure
+    Dir.chdir(previous_pwd) if previous_pwd && File.directory?(previous_pwd)
+    if previous_home.nil?
+      ENV.delete("HOME")
+    else
+      ENV["HOME"] = previous_home
+    end
+  end
+
+  def load_rspec!
+    require "/bundle/setup.rb"
+    require "rspec/core"
+    # Hide the embedded guest protocol frames (/src/main.rb, /src/rspec.rb,
+    # ...) from RSpec's printed failure backtraces; the sandbox reserves /src,
+    # so this cannot hide user files.
+    RSpec.configure do |config|
+      config.backtrace_exclusion_patterns << %r{\A/src/}
+    end
+  rescue LoadError => e
+    raise LoadError,
+          "rspec is not available in this image (#{e.message}); " \
+          "rebuild it with `bundle exec rake security_box:build_image`"
+  end
+  private_class_method :load_rspec!
+end

data/lib/security_box/guest_ext/Gemfile

@@ -8,3 +8,8 @@ gem "ruby_wasm", "~> 2.10.1"
 # Rakefile). Only guest-safe dependencies belong here — host-only gems
 # (wasmtime) must stay in the project Gemfile.
 gem "sb_rpc", path: "sb_rpc"
+
+# Bundled so guest code can run spec suites mounted at /work (see
+# lib/security_box/guest/rspec.rb and SB.run_rspec). RSpec is pure Ruby and
+# adds no native extensions, so it does not change the Ruby build cache key.
+gem "rspec", "~> 3.13"

data/lib/security_box/guest_ext/Gemfile.lock

@@ -6,7 +6,21 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    diff-lcs (1.6.2)
     logger (1.7.0)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
     ruby_wasm (2.10.1)
       logger
     ruby_wasm (2.10.1-x86_64-linux)
@@ -17,12 +31,19 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  rspec (~> 3.13)
   ruby_wasm (~> 2.10.1)
   sb_rpc!
 
 CHECKSUMS
   bundler (4.0.20) sha256=7978a8ac648767f5e635bc522445b79e80a52b907a39a36c2d8085ed6bc762ae
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
   ruby_wasm (2.10.1) sha256=874e0acb783a8326bfb0db892004816c26963a4276a9f719791a8828e53a05f1
   ruby_wasm (2.10.1-x86_64-linux) sha256=728e29dc688246572b56dcef1c7b131431d07865320c9b8434dd1ccdfd63db2b
   sb_rpc (0.1.0)

data/lib/security_box/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: security_box
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Marcelo Junior
@@ -45,6 +45,7 @@ files:
 - lib/security_box/guest/main.rb
 - lib/security_box/guest/prelude.rb
 - lib/security_box/guest/rpc.rb
+- lib/security_box/guest/rspec.rb
 - lib/security_box/guest_ext/Gemfile
 - lib/security_box/guest_ext/Gemfile.lock
 - lib/security_box/guest_ext/sb_rpc/ext/sb_rpc/extconf.rb