robot_lab-sandbox 0.2.8

data/lib/robot_lab/sandbox/seatbelt.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module RobotLab
+  module Sandbox
+    # macOS strategy: generates a deny-by-default sandbox-exec profile from the
+    # effective grant and wraps the command as
+    #   sandbox-exec -f <profile> <cmd...>
+    #
+    # The profile allows process exec plus reads of system locations (so the
+    # interpreter can load), reads of the skill bundle and granted paths, writes
+    # only to granted paths (and the standard /dev sinks), and network only when
+    # granted. Everything else -- notably $HOME, so SSH/cloud credentials --
+    # is denied. Interpreters installed under $HOME (e.g. rbenv) are not visible;
+    # declare them in fs_read or mark the skill trust: core.
+    class Seatbelt
+      # System locations a typical interpreter needs to read to start up.
+      SYSTEM_READ = %w[/usr /bin /sbin /System /Library /opt /private/etc /dev /var/select].freeze
+      DEV_WRITE   = %w[/dev/null /dev/stdout /dev/stderr /dev/dtracehelper /dev/tty].freeze
+
+      def initialize(grant, skill_dir:)
+        @grant     = grant
+        @skill_dir = File.expand_path(skill_dir.to_s)
+        @profile   = nil
+      end
+
+      def wrap(cmd)
+        @profile = write_profile
+        ["sandbox-exec", "-f", @profile, *cmd]
+      end
+
+      def cleanup
+        File.unlink(@profile) if @profile && File.exist?(@profile)
+      rescue StandardError
+        nil
+      end
+
+      # The generated Seatbelt profile text (public for testing).
+      def profile_text
+        reads  = canonicalize(SYSTEM_READ + [@skill_dir] + @grant.fs_read)
+        writes = canonicalize(@grant.fs_write)
+        lines = [
+          "(version 1)",
+          # bsd.sb supplies the base rules a process needs to start (dyld, mach
+          # bootstrap, etc.); without it a deny-default profile aborts the binary.
+          '(import "bsd.sb")',
+          "(deny default)",
+          "(allow process-fork)",
+          "(allow process-exec)",
+          "(allow sysctl-read)",
+          "(allow mach-lookup)",
+          # Metadata (stat/lookup) on any path so the interpreter can traverse to
+          # granted files; reading file *contents* stays restricted below.
+          "(allow file-read-metadata)",
+          read_rule(reads),
+          write_rule(DEV_WRITE.map { |p| [:literal, p] } + writes.map { |p| [:subpath, p] })
+        ]
+        lines << "(allow network*)" if @grant.network
+        "#{lines.compact.join("\n")}\n"
+      end
+
+      private
+
+      # :reek:FeatureEnvy -- building and returning a Tempfile inherently
+      # calls several methods on it; that's not envy of another object's data.
+      def write_profile
+        file = Tempfile.create(["robot_lab-sandbox-", ".sb"])
+        file.write(profile_text)
+        file.close
+        file.path
+      end
+
+      # Resolve to the real (symlink-free) path the kernel matches against. macOS
+      # symlinks /tmp -> /private/tmp, /var -> /private/var, etc., so logical
+      # paths would never match. For not-yet-existing write targets, resolve the
+      # nearest existing ancestor and re-append the remainder.
+      def canonicalize(paths)
+        Array(paths).map { |p| real_path(File.expand_path(p.to_s)) }.compact.uniq
+      end
+
+      def real_path(expanded)
+        existing = expanded
+        rest     = []
+        until File.exist?(existing) || existing == "/"
+          rest.unshift(File.basename(existing))
+          existing = File.dirname(existing)
+        end
+        real = File.realpath(existing)
+        rest.empty? ? real : File.join(real, *rest)
+      rescue StandardError
+        expanded
+      end
+
+      def read_rule(paths)
+        subpaths = paths.map { |p| "(subpath #{p.inspect})" }.join(" ")
+        "(allow file-read* #{subpaths})"
+      end
+
+      def write_rule(entries)
+        clauses = entries.map { |kind, p| "(#{kind} #{p.inspect})" }.join(" ")
+        "(allow file-write* #{clauses})"
+      end
+    end
+  end
+end

data/lib/robot_lab/sandbox/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Sandbox
+    VERSION = "0.2.8"
+  end
+end

data/lib/robot_lab/sandbox.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "sandbox/version"
+
+module RobotLab
+  # Confines skill-script execution to a granted set of capabilities.
+  #
+  # Sandboxing is opt-in (config.sandbox.enabled). When off, every script runs
+  # unconfined exactly as robot_lab core alone would run it. When on, each
+  # script runs under a strategy:
+  #
+  # - {Sandbox::Seatbelt} on macOS — a generated deny-by-default sandbox-exec
+  #   profile derived from the effective {Capabilities} grant.
+  # - {Sandbox::Null} elsewhere (or for +trust: core+ skills) — a passthrough.
+  #
+  # OS-level confinement is therefore best-effort and platform-specific; it is
+  # never a hard dependency. robot_lab core has no notion of sandboxing at
+  # all -- requiring this gem is what installs confinement into
+  # RobotLab::ScriptTool via {Executor}.
+  module Sandbox
+    class Error < StandardError; end
+
+    module_function
+
+    # @return [Boolean] whether sandboxing is turned on in config
+    def enabled?(config = RobotLab.config)
+      config.respond_to?(:sandbox) && config.sandbox && config.sandbox.enabled == true
+    end
+
+    def macos?
+      RUBY_PLATFORM.include?("darwin")
+    end
+
+    # Pick a strategy for the given (already-intersected) grant.
+    #
+    # @param grant [Capabilities] effective grant
+    # @param skill_dir [String] skill bundle root, always granted read access
+    # @param macos [Boolean] whether to use the macOS strategy; defaults to the
+    #   real platform check and is injectable so both branches are testable on
+    #   any host without stubbing.
+    # @return [#wrap, #cleanup]
+    # :reek:ControlParameter -- macos: is an intentional test seam (see above).
+    def 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
+
+    def warn_once_non_macos
+      return if @warned_non_macos
+
+      @warned_non_macos = true
+      RobotLab.config.logger.warn(
+        "Sandbox: OS-level confinement is only available on macOS; scripts run unconfined here"
+      )
+    end
+  end
+end
+
+require_relative "sandbox/seatbelt"
+require_relative "sandbox/null"
+require_relative "sandbox/executor"
+
+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

data/mkdocs.yml

@@ -0,0 +1,118 @@
+site_name: robot_lab-sandbox
+site_description: OS-level confinement for RobotLab skill scripts
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/robot_lab-sandbox
+copyright: Copyright © 2026 Dewayne VanHoozer
+
+repo_name: MadBomber/robot_lab-sandbox
+repo_url: https://github.com/MadBomber/robot_lab-sandbox
+edit_uri: edit/main/docs/
+docs_dir: docs
+
+theme:
+  name: material
+
+  palette:
+    - scheme: default
+      primary: teal
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: teal
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  icon:
+    repo: fontawesome/brands/github
+    logo: material/shield-lock-outline
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: MadBomber
+      repo: robot_lab-sandbox
+      normalize_issue_symbols: true
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/MadBomber/robot_lab-sandbox
+      name: robot_lab-sandbox on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/robot_lab-sandbox
+      name: robot_lab-sandbox on RubyGems
+
+nav:
+  - Home: index.md
+  - Getting Started: getting_started.md
+  - Configuration: configuration.md
+  - How It Works: how_it_works.md
+  - Troubleshooting: troubleshooting.md

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: robot_lab-sandbox
+version: !ruby/object:Gem::Version
+  version: 0.2.8
+platform: ruby
+authors:
+- Dewayne VanHoozer
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: robot_lab
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: Deny-by-default, capability-scoped execution for AgentSkills scripts.
+  On macOS, wraps scripts in a generated sandbox-exec (Seatbelt) profile derived from
+  the skill's declared capabilities intersected with a configured ceiling; robot_lab
+  core runs unconfined until this gem is required.
+email:
+- dvanhoozer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- ".github/workflows/deploy-github-pages.yml"
+- ".loki"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- COMMITS.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/configuration.md
+- docs/getting_started.md
+- docs/how_it_works.md
+- docs/index.md
+- docs/troubleshooting.md
+- lib/robot_lab/sandbox.rb
+- lib/robot_lab/sandbox/executor.rb
+- lib/robot_lab/sandbox/null.rb
+- lib/robot_lab/sandbox/seatbelt.rb
+- lib/robot_lab/sandbox/version.rb
+- mkdocs.yml
+homepage: https://github.com/MadBomber/robot_lab-sandbox
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MadBomber/robot_lab-sandbox
+  source_code_uri: https://github.com/MadBomber/robot_lab-sandbox
+  changelog_uri: https://github.com/MadBomber/robot_lab-sandbox/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: OS-level confinement for RobotLab skill scripts.
+test_files: []