robot_lab-sandbox 0.2.8

data/docs/getting_started.md

@@ -0,0 +1,121 @@
+# Getting Started
+
+## Prerequisites
+
+- Ruby 3.2+ (per the gemspec's `required_ruby_version`)
+- `robot_lab` — `robot_lab/sandbox` requires `RobotLab::ScriptTool` to already
+  be defined, so `robot_lab` must be `require`d first.
+- macOS, if you want real OS-level confinement. On other platforms the gem
+  still loads and wires itself in, but every script runs through
+  `Sandbox::Null` (a passthrough) with a one-time warning logged.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "robot_lab"
+gem "robot_lab-sandbox"
+```
+
+Then:
+
+```sh
+bundle install
+```
+
+Or install directly:
+
+```sh
+gem install robot_lab-sandbox
+```
+
+## Enabling
+
+Requiring the gem and turning on confinement are two separate steps —
+matching how `robot_lab` core's `sandbox:` config section already worked
+before this gem existed.
+
+**1. Require it**, after `robot_lab`:
+
+```ruby
+require "robot_lab"
+require "robot_lab/sandbox"
+```
+
+This installs `RobotLab::Sandbox::Executor` as `RobotLab::ScriptTool.executor`
+and registers the gem via `RobotLab.register_extension(:sandbox, ...)`. On its
+own this changes nothing yet — see [How It Works](how_it_works.md#scripttoolexecute-with-no-executor-installed)
+for why: `ScriptTool.execute` only delegates to the executor when one is
+installed, and the executor itself checks `Sandbox.enabled?` before doing
+anything.
+
+**2. Turn on confinement** in config:
+
+```yaml
+# config/robot_lab.yml
+sandbox:
+  enabled: true
+  fs_read: ["."]
+  fs_write: []
+  network: false
+  timeout: 60
+```
+
+or via environment variables:
+
+```sh
+export ROBOT_LAB_SANDBOX__ENABLED=true
+```
+
+If `robot_lab` has not been loaded yet, `require "robot_lab/sandbox"` raises
+`RobotLab::Sandbox::Error` ("robot_lab must be loaded before robot_lab/sandbox").
+
+## Minimal Example
+
+```ruby
+require "robot_lab"
+require "robot_lab/sandbox"
+
+RobotLab.config.sandbox.enabled = true
+RobotLab.config.sandbox.fs_write = ["./tmp"]
+
+# A skill's SKILL.md declares what it wants; robot_lab core builds the
+# Capabilities object from that front matter automatically when the skill
+# is discovered. Here we build one directly to call ScriptTool ourselves:
+capabilities = RobotLab::Capabilities.new(fs_write: ["./tmp"], timeout: 10)
+
+tool = RobotLab::ScriptTool.from_path(
+  "./skills/cleanup/scripts/purge_tmp.sh",
+  capabilities: capabilities,
+  skill_dir: "./skills/cleanup"
+)
+
+puts tool.call({}) # runs confined on macOS, unconfined (with a warning) elsewhere
+```
+
+In practice you won't call `ScriptTool.from_path` directly — a discovered
+`AgentSkill` builds its own `script_tools` from its `SKILL.md` front matter
+and capabilities automatically. This example exists to show the pieces in
+isolation; see [robot_lab's Skill Scripts and Sandboxing guide](https://github.com/MadBomber/robot_lab/blob/main/docs/guides/using-tools.md#skill-scripts-and-sandboxing)
+for the end-to-end skill-bundle path.
+
+## Checking What's Installed
+
+```ruby
+RobotLab.extension_loaded?(:sandbox)   # => true, once required
+RobotLab::ScriptTool.executor          # => RobotLab::Sandbox::Executor, or nil
+RobotLab::Sandbox.enabled?             # => reads config.sandbox.enabled
+RobotLab::Sandbox.macos?               # => RUBY_PLATFORM.include?("darwin")
+```
+
+## Key Constraints
+
+- `robot_lab` must be `require`d before `robot_lab/sandbox` — see Prerequisites above.
+- Confinement is opt-in via `config.sandbox.enabled` (default `false`).
+  Requiring this gem does **not** turn confinement on by itself.
+- Real OS-level confinement is macOS-only. Off macOS, or for any skill
+  declaring `trust: core`, every script runs through the `Sandbox::Null`
+  passthrough regardless of `sandbox.enabled`.
+- The declared `timeout:` (per-skill or the config ceiling) only takes effect
+  once this gem is loaded — core alone runs scripts with no timeout at all.

data/docs/how_it_works.md

@@ -0,0 +1,236 @@
+# How It Works
+
+## The Extension Point: `ScriptTool.executor`
+
+`robot_lab` core's `RobotLab::ScriptTool` exposes a single seam for
+confinement:
+
+```ruby
+module RobotLab
+  module ScriptTool
+    class << self
+      attr_accessor :executor
+    end
+  end
+end
+```
+
+`executor` is `nil` by default. `ScriptTool.execute(cmd, capabilities:, skill_dir:)`
+checks it on every call:
+
+```ruby
+def self.execute(cmd, capabilities:, skill_dir:)
+  return executor.call(cmd, capabilities: capabilities, skill_dir: skill_dir) if executor
+
+  output, status = Open3.capture2e(*cmd)
+  format_result(output, status)
+end
+```
+
+### `ScriptTool.execute` with no executor installed
+
+Without `robot_lab-sandbox` (or any other gem setting `executor`), every call
+takes the second branch: a plain `Open3.capture2e`, unconfined, with no
+timeout. This is exactly how core alone always behaved — the extension point
+was added specifically so this default stays true with zero code in core
+that knows anything about sandboxing.
+
+### What loading this gem does
+
+`lib/robot_lab/sandbox.rb` runs this at load time:
+
+```ruby
+unless defined?(RobotLab::ScriptTool)
+  raise RobotLab::Sandbox::Error, "robot_lab must be loaded before robot_lab/sandbox"
+end
+
+RobotLab::ScriptTool.executor = RobotLab::Sandbox::Executor
+
+if RobotLab.respond_to?(:register_extension)
+  RobotLab.register_extension(:sandbox, RobotLab::Sandbox)
+end
+```
+
+From that point on, every `ScriptTool.execute` call delegates entirely to
+`RobotLab::Sandbox::Executor.call`. Core no longer knows or cares what the
+executor does with `capabilities` or how — or whether — it bounds execution
+time; that's this gem's job from here down.
+
+## `Sandbox::Executor` — What Actually Runs
+
+```ruby
+def self.call(cmd, capabilities:, skill_dir:)
+  unless Sandbox.enabled?
+    output, status = Open3.capture2e(*cmd)
+    return RobotLab::ScriptTool.format_result(output, status)
+  end
+
+  grant   = capabilities.intersect(Capabilities.ceiling)
+  sandbox = Sandbox.for(grant, skill_dir: skill_dir)
+  begin
+    output, status = run_with_timeout(sandbox.wrap(cmd), grant.timeout)
+    RobotLab::ScriptTool.format_result(output, status)
+  ensure
+    sandbox.cleanup
+  end
+end
+```
+
+Two paths, gated by `Sandbox.enabled?` (which reads `config.sandbox.enabled`,
+default `false`):
+
+1. **Disabled** — identical to core's own unconfined path. Loading this gem
+   with `sandbox.enabled: false` changes nothing observable.
+2. **Enabled** — computes the effective grant (skill's declared `Capabilities`
+   ∩ the config ceiling, see [Configuration](configuration.md#the-intersection)),
+   picks a strategy via `Sandbox.for`, wraps the command, runs it under a
+   timeout, and always calls `sandbox.cleanup` in an `ensure` — even if the
+   run raised or timed out.
+
+## Strategy Selection: `Sandbox.for`
+
+```ruby
+def self.for(grant, skill_dir:, macos: macos?)
+  return Null.new if grant.core?
+  return Seatbelt.new(grant, skill_dir: skill_dir) if macos
+
+  warn_once_non_macos
+  Null.new
+end
+```
+
+Selection order:
+
+1. `trust: core` (`grant.core?`) → always `Sandbox::Null`, on every platform.
+2. macOS → `Sandbox::Seatbelt`.
+3. Anything else → `Sandbox::Null`, plus a one-time `warn`-level log message
+   (`Sandbox.warn_once_non_macos`, idempotent — a run with many scripts
+   doesn't flood the log).
+
+`macos:` is injectable (defaults to the real `RUBY_PLATFORM` check) so both
+branches are testable on any host without stubbing.
+
+## `Sandbox::Null` — the Passthrough
+
+```ruby
+class Null
+  def wrap(cmd) = cmd
+  def cleanup; end
+end
+```
+
+`wrap` is the identity function; `cleanup` is a no-op. Used off-macOS and for
+`trust: core` skills — the command runs exactly as it would with no executor
+installed at all, except still bounded by `Executor`'s timeout.
+
+## `Sandbox::Seatbelt` — Real Confinement on macOS
+
+`wrap(cmd)` generates a Seatbelt profile to a `Tempfile` and returns:
+
+```ruby
+["sandbox-exec", "-f", profile_path, *cmd]
+```
+
+### The generated profile
+
+```
+(version 1)
+(import "bsd.sb")
+(deny default)
+(allow process-fork)
+(allow process-exec)
+(allow sysctl-read)
+(allow mach-lookup)
+(allow file-read-metadata)
+(allow file-read* (subpath "/usr") (subpath "/bin") ... (subpath <skill_dir>) (subpath <granted fs_read>) ...)
+(allow file-write* (literal "/dev/null") ... (subpath <granted fs_write>))
+(allow network*)   ; only present when the grant allows network
+```
+
+Built from three pieces:
+
+| Piece | Source |
+|-------|--------|
+| **Deny by default** | `(deny default)` — nothing is allowed unless an explicit `(allow ...)` clause says so. |
+| **Boot allowances** | `(import "bsd.sb")` (the base rules a process needs to start — dyld, mach bootstrap, etc.; without it a deny-default profile aborts the binary before it runs), plus `process-fork`, `process-exec`, `sysctl-read`, `mach-lookup`, and `file-read-metadata` on any path (so the interpreter can `stat`/traverse to reach granted files — reading file *contents* stays restricted separately). |
+| **The grant** | `file-read*` on `Seatbelt::SYSTEM_READ` (`/usr /bin /sbin /System /Library /opt /private/etc /dev /var/select`) plus the skill directory plus the grant's `fs_read`; `file-write*` on `Seatbelt::DEV_WRITE` (`/dev/null /dev/stdout /dev/stderr /dev/dtracehelper /dev/tty`) plus the grant's `fs_write`; `network*` only when `grant.network` is true. |
+
+`$HOME` is never in any of these lists — it is never implicitly readable.
+See [Troubleshooting](troubleshooting.md#interpreter-installed-under-home-is-invisible)
+for the direct consequence of that.
+
+### Path canonicalization
+
+Every path is resolved to its symlink-free real path before being written
+into the profile:
+
+```ruby
+def canonicalize(paths)
+  Array(paths).map { |p| real_path(File.expand_path(p.to_s)) }.compact.uniq
+end
+```
+
+This matters because macOS symlinks `/tmp` → `/private/tmp`, `/var` →
+`/private/var`, etc. — the kernel matches Seatbelt rules against the *real*
+path, so a rule written against the logical `/tmp/...` path would silently
+never match. For a write target that doesn't exist yet, `real_path` walks up
+to the nearest existing ancestor, resolves *that*, and re-appends the
+non-existent remainder.
+
+### Lifecycle
+
+`wrap` writes the profile via `Tempfile.create`; `cleanup` unlinks it and
+swallows any error (an already-removed file is fine). `Executor.call` always
+calls `sandbox.cleanup` in an `ensure`, so a profile file is never leaked
+even when the script raises or times out.
+
+## Timeout Enforcement
+
+`Executor.run_with_timeout(cmd, timeout)` runs the (possibly Seatbelt-wrapped)
+command in its own process group and reads combined stdout+stderr until
+`timeout` seconds elapse:
+
+```ruby
+def self.run_with_timeout(cmd, timeout)
+  Open3.popen2e(*cmd, pgroup: true) do |stdin, out, wait|
+    stdin.close
+    output = +""
+    begin
+      Timeout.timeout(timeout) { output << out.read }
+    rescue Timeout::Error
+      terminate(wait.pid)
+      return ["#{output}\n[killed: exceeded #{timeout}s]", nil]
+    end
+    [output, wait.value]
+  end
+end
+```
+
+On expiry, `terminate` sends `SIGTERM` to the whole process **group**
+(`Process.kill('-TERM', ...)` against `Process.getpgid(pid)`), so a script
+that spawned children takes them down with it, and swallows any error — a
+process that already exited by the time `terminate` runs is not an error. A
+`nil` status return value is `ScriptTool.format_result`'s signal for
+`"Error (timed out):\n<output>"`, which is what the LLM sees; a `nil`
+status is never confused with a real (even nonzero) exit code.
+
+The timeout used is `grant.timeout` — the smaller of the skill's declared
+`timeout:` and the config ceiling's `sandbox.timeout` (see
+[Configuration](configuration.md#the-intersection)). This bound applies only
+because this gem is loaded; core alone never times a script out.
+
+## Extension Registration
+
+`RobotLab.register_extension(:sandbox, RobotLab::Sandbox)` lets other code
+detect this gem is loaded without depending on it directly:
+
+```ruby
+RobotLab.extension_loaded?(:sandbox)  # => true, once required
+RobotLab.extension(:sandbox)          # => RobotLab::Sandbox, or nil
+```
+
+This follows the same pattern every other RobotLab extension gem
+(`robot_lab-audit`, `robot_lab-durable`, etc.) uses — `register_extension` is
+a no-op-safe check (`RobotLab.respond_to?(:register_extension)`), so
+`robot_lab/sandbox` never raises on this line even against an unusually old
+`robot_lab` core.

data/docs/index.md

@@ -0,0 +1,58 @@
+# robot_lab-sandbox
+
+OS-level confinement for [RobotLab](https://github.com/MadBomber/robot_lab) skill scripts.
+
+`robot_lab` core has **no sandboxing and no execution limitations of its own** —
+every [AgentSkill](https://github.com/MadBomber/robot_lab/blob/main/docs/api/skills.md)
+script runs as a plain, unconfined OS process. `robot_lab-sandbox` plugs into
+core's one extension point for this (`RobotLab::ScriptTool.executor`) and, once
+turned on in config, confines each script to a declared, ceiling-clamped set of
+capabilities: which paths it may read and write, whether it may reach the
+network, and how long it may run.
+
+```ruby
+require "robot_lab"
+require "robot_lab/sandbox"
+# RobotLab::ScriptTool.executor is now RobotLab::Sandbox::Executor.
+```
+
+```yaml
+# config/robot_lab.yml
+sandbox:
+  enabled: true
+  fs_read: ["."]
+  fs_write: ["./tmp"]
+  network: false
+  timeout: 60
+```
+
+On macOS, `enabled: true` wraps every skill script in a generated
+deny-by-default `sandbox-exec` (Seatbelt) profile. Elsewhere it's a passthrough
+with a one-time warning — confinement is currently macOS-only. Requiring the
+gem never changes behavior on its own; nothing is confined until
+`sandbox.enabled` is set.
+
+## Navigation
+
+- [Getting Started](getting_started.md) — installation, enabling, a minimal example, checking what's installed
+- [Configuration](configuration.md) — the `sandbox:` ceiling, `SKILL.md` capability declarations, and how the two intersect
+- [How It Works](how_it_works.md) — the `ScriptTool.executor` extension point, `Sandbox.for` strategy selection, the generated Seatbelt profile, timeout enforcement, extension registration
+- [Troubleshooting](troubleshooting.md) — the interpreter-under-`$HOME` problem, non-macOS behavior, diagnosing a denied path
+
+## At a Glance
+
+| | |
+|---|---|
+| **Confines** | `RobotLab::ScriptTool` executions — i.e. AgentSkill `scripts/` shelled out as tools |
+| **Strategies** | `Sandbox::Seatbelt` (macOS, `sandbox-exec`), `Sandbox::Null` (passthrough) |
+| **Opt-in via** | `config.sandbox.enabled` (default `false`) — requiring this gem does not turn it on |
+| **Grant model** | effective grant = skill's declared `Capabilities` ∩ config `sandbox:` ceiling |
+| **Always unconfined** | `trust: core` skills, regardless of platform or config |
+| **Extension point** | `RobotLab::ScriptTool.executor = RobotLab::Sandbox::Executor` |
+| **Timeout enforcement** | only when this gem is loaded and sandboxing is enabled |
+
+## Links
+
+- [RobotLab Core](https://github.com/MadBomber/robot_lab)
+- [RubyGems](https://rubygems.org/gems/robot_lab-sandbox)
+- [GitHub](https://github.com/MadBomber/robot_lab-sandbox)

data/docs/troubleshooting.md

@@ -0,0 +1,108 @@
+# Troubleshooting
+
+## Interpreter installed under `$HOME` is invisible
+
+**Symptom:** a script fails immediately with something like
+`env: ruby: No such file or directory` or `bad interpreter`, but the same
+script runs fine with `sandbox.enabled: false`.
+
+**Cause:** the generated Seatbelt profile never grants read access to
+`$HOME`, on purpose — that's what keeps SSH keys and cloud credentials out of
+reach of a confined script. But it also means any interpreter installed
+under `$HOME` (rbenv, asdf, mise, a Homebrew prefix under `~`, `~/.gem`, a
+project-local `bundle` path under `~/.bundle`) is invisible to the sandboxed
+process, and the script can't even start.
+
+**Fix:** either
+
+- Grant the interpreter's install path explicitly in the skill's `fs_read`:
+  ```yaml
+  fs_read: ["~/.rbenv"]
+  ```
+  (this still goes through the config `sandbox.fs_read` ceiling — the
+  ceiling must permit it too, see [Configuration](configuration.md#the-intersection)), or
+- Mark the skill `trust: core` if you wrote and audited it yourself — this
+  bypasses confinement entirely, see [Configuration — trust: core](configuration.md#trust-core-bypassing-confinement).
+
+## A path I granted is still denied
+
+**Symptom:** a script writes to (or reads from) a path you declared in
+`fs_write`/`fs_read`, but the write silently fails or the read comes back
+empty, even though `sandbox.enabled: true` and the skill's front matter
+looks right.
+
+**Checklist:**
+
+1. **Is the path inside the config ceiling?** The effective grant is the
+   *intersection* of what the skill declares and `config.sandbox.fs_read`/
+   `fs_write` — a path outside every ceiling root is dropped silently, even
+   if the skill asks for it. Check `RobotLab::Capabilities.ceiling.fs_read`
+   / `.fs_write` in a console.
+2. **Is it a symlinked path?** macOS symlinks `/tmp` → `/private/tmp`,
+   `/var` → `/private/var`. The profile is generated against the resolved
+   real path — if you're comparing against the logical path elsewhere (e.g.
+   in a test assertion), resolve it with `File.realpath` first. See
+   [How It Works — Path canonicalization](how_it_works.md#path-canonicalization).
+3. **Does the path exist yet, for a write target?** Canonicalization walks up
+   to the nearest existing ancestor to resolve symlinks, then re-appends the
+   rest — if an intermediate directory in the path doesn't exist and is
+   *itself* a symlink once created, the grant can end up pointing at the
+   wrong real path. Prefer granting an existing parent directory over a
+   not-yet-created nested path.
+4. **Is `trust: core` set?** A `core` skill bypasses the sandbox entirely —
+   if you're debugging a *denial* and the skill is `trust: core`, the
+   sandbox isn't involved at all; look elsewhere (permissions, the script
+   itself).
+
+You can inspect the exact profile a grant produces without running anything:
+
+```ruby
+grant = RobotLab::Capabilities.new(fs_read: ["./data"], fs_write: ["./out"])
+puts RobotLab::Sandbox::Seatbelt.new(grant, skill_dir: "./skills/example").profile_text
+```
+
+## Nothing is confined, even with `sandbox.enabled: true`
+
+**Symptom:** scripts still behave as if sandboxing were off — no denials,
+no warnings, everything just works as before.
+
+**Checklist:**
+
+1. **Is `robot_lab/sandbox` actually required?** `require "robot_lab/sandbox"`
+   must run *after* `require "robot_lab"`. Check:
+   ```ruby
+   RobotLab::ScriptTool.executor  # nil means this gem was never loaded
+   ```
+2. **Is the skill `trust: core`?** Always bypasses confinement — see above.
+3. **Are you off macOS?** Confinement is macOS-only; elsewhere every script
+   runs through `Sandbox::Null` (a passthrough) with a one-time warning
+   logged (`Sandbox: OS-level confinement is only available on macOS; ...`).
+   Check `RobotLab::Sandbox.macos?`.
+
+## A script that used to finish now gets killed with `[killed: exceeded Ns]`
+
+**Cause:** once this gem is loaded and sandboxing is enabled, every script
+run is bounded by the effective grant's `timeout` — the smaller of the
+skill's declared `timeout:` and `config.sandbox.timeout` (default `60`).
+Core alone never enforced a timeout at all, so a slow script that worked
+fine before can now hit this for the first time.
+
+**Fix:** raise the skill's declared `timeout:` in its `SKILL.md` front
+matter, and/or raise the config ceiling's `sandbox.timeout` — whichever is
+currently the smaller (and therefore binding) value.
+
+## `robot_lab/sandbox` raises on require
+
+```
+RobotLab::Sandbox::Error: robot_lab must be loaded before robot_lab/sandbox
+```
+
+**Cause:** `require "robot_lab/sandbox"` ran before `require "robot_lab"` (or
+`robot_lab` failed to load for some other reason first). `robot_lab/sandbox`
+checks `defined?(RobotLab::ScriptTool)` at load time and raises immediately
+rather than silently no-op-ing, since a sandbox gem that failed to install
+itself and said nothing would be far more dangerous than one that's loud
+about it.
+
+**Fix:** reorder your `require`s (or Gemfile-driven autoload order) so
+`robot_lab` loads first.

data/lib/robot_lab/sandbox/executor.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module RobotLab
+  module Sandbox
+    # Installed as RobotLab::ScriptTool.executor when this gem loads. Runs a
+    # skill script unconfined when sandboxing is disabled (config.sandbox.enabled
+    # is false, the default), or confined and timeout-bounded when it is enabled.
+    module Executor
+      module_function
+
+      # @param cmd [Array<String>] command to run
+      # @param capabilities [Capabilities] declared capabilities (from SKILL.md)
+      # @param skill_dir [String] skill bundle root
+      # @return [String] combined stdout+stderr, or an error string on failure
+      def call(cmd, capabilities:, skill_dir:)
+        unless Sandbox.enabled?
+          output, status = Open3.capture2e(*cmd)
+          return RobotLab::ScriptTool.format_result(output, status)
+        end
+
+        grant   = capabilities.intersect(Capabilities.ceiling)
+        sandbox = Sandbox.for(grant, skill_dir: skill_dir)
+        begin
+          output, status = run_with_timeout(sandbox.wrap(cmd), grant.timeout)
+          RobotLab::ScriptTool.format_result(output, status)
+        ensure
+          sandbox.cleanup
+        end
+      end
+
+      # @return [Array(String, Process::Status|nil)] output and status (nil = timed out)
+      def run_with_timeout(cmd, timeout)
+        Open3.popen2e(*cmd, pgroup: true) do |stdin, out, wait|
+          stdin.close
+          output = +""
+          begin
+            Timeout.timeout(timeout) { output << out.read }
+          rescue Timeout::Error
+            terminate(wait.pid)
+            return ["#{output}\n[killed: exceeded #{timeout}s]", nil]
+          end
+          [output, wait.value]
+        end
+      end
+
+      def terminate(pid)
+        Process.kill("-TERM", Process.getpgid(pid))
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/robot_lab/sandbox/null.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Sandbox
+    # Passthrough strategy: runs the command with no confinement. Used when
+    # sandboxing is unavailable (non-macOS) or unnecessary (trust: core).
+    class Null
+      def wrap(cmd) = cmd
+
+      def cleanup; end
+    end
+  end
+end