hermetic 0.1.0

data/lib/hermetic/transport/subprocess.rb

@@ -0,0 +1,64 @@
+require "open3"
+
+module Hermetic
+  module Transport
+    # Host-side process runner: spawns an argv, pipes stdin, and enforces the
+    # wall clock with a reaper (never trusts the guest to exit — the pattern
+    # ported from Silas's Docker adapter). Returns
+    # [stdout, stderr, exit_status, timed_out]; a timeout maps to exit 124
+    # (coreutils convention, matches Silas TIMEOUT_EXIT). The low-level
+    # capture is injectable so the tuple/timeout contract is unit-testable
+    # with no real processes.
+    class Subprocess
+      TIMEOUT_EXIT = 124
+
+      def initialize(capture: nil)
+        @capture = capture || method(:popen_capture)
+      end
+
+      def call(argv, stdin: nil, timeout: 30)
+        unless argv.is_a?(Array) && !argv.empty? && argv.all?(String)
+          raise ConfigError, "argv must be a non-empty Array of Strings, got #{argv.inspect}"
+        end
+
+        out, err, status, timed_out = @capture.call(argv, stdin: stdin, timeout: timeout)
+        return [ out, err, status, false ] unless timed_out
+
+        [ "", "hermetic: command timed out after #{timeout}s", TIMEOUT_EXIT, true ]
+      end
+
+      private
+
+      def popen_capture(argv, stdin:, timeout:)
+        Open3.popen3(*argv) do |in_io, out_io, err_io, wait|
+          timed_out = false
+          reaper = Thread.new do
+            unless wait.join(timeout)
+              timed_out = true
+              begin
+                Process.kill("KILL", wait.pid)
+              rescue Errno::ESRCH
+                nil # exited on the deadline itself; wall clock was still blown
+              end
+            end
+          end
+
+          out_reader = Thread.new { out_io.read }
+          err_reader = Thread.new { err_io.read }
+          begin
+            in_io.write(stdin) if stdin
+          rescue Errno::EPIPE
+            nil # guest exited without reading stdin; its exit status tells the story
+          end
+          in_io.close
+
+          status = wait.value
+          reaper.join
+          [ out_reader.value, err_reader.value, status.exitstatus || (128 + status.termsig.to_i), timed_out ]
+        end
+      rescue Errno::ENOENT => e
+        raise TransportError, "#{argv.first.inspect} not found on PATH (#{e.message})"
+      end
+    end
+  end
+end

data/lib/hermetic/version.rb

@@ -0,0 +1,3 @@
+module Hermetic
+  VERSION = "0.1.0"
+end

data/lib/hermetic.rb

@@ -0,0 +1,67 @@
+require "hermetic/version"
+require "hermetic/errors"
+require "hermetic/result"
+require "hermetic/limits"
+require "hermetic/network_policy"
+require "hermetic/credentials"
+require "hermetic/request"
+require "hermetic/transport/subprocess"
+require "hermetic/transport/http"
+require "hermetic/backends/base"
+require "hermetic/backends/null"
+
+# hermetic — the missing Ruby sandbox. One `run` interface, swappable
+# isolation backends, designed to run off the app host so a guest escape
+# can't reach your secrets. Every constructor returns a plain object
+# implementing run/enabled?, so `config.sandbox = Hermetic.gvisor(...)`
+# drops into Silas unchanged.
+#
+# Backends beyond Null are required lazily — constructing one you haven't
+# shipped/installed fails at the constructor, not at boot.
+module Hermetic
+  # Options that shape the client-side Request (or the wire itself) and so
+  # stay on the Remote client when `executor:` reroutes a local constructor;
+  # everything else is the executor's to construct with (spec §3).
+  CLIENT_OPTS = %i[limits credentials credential_mode env_allowlist transport].freeze
+
+  class << self
+    def null = Backends::Null.new
+
+    def docker(**opts) = backend(:docker, :Docker, "hermetic/backends/docker", **opts)
+
+    def gvisor(**opts) = backend(:gvisor, :Gvisor, "hermetic/backends/gvisor", **opts)
+
+    def firecracker(**opts) = backend(:firecracker, :Firecracker, "hermetic/backends/firecracker", **opts)
+
+    def hosted(provider, **opts)
+      require "hermetic/backends/hosted"
+      Backends::Hosted.build(provider, **opts)
+    end
+
+    # Off-host executor client (trust :remote): the isolation runs on a
+    # dedicated sandbox host; this process holds only the URL + token.
+    def wrap(executor:, **opts)
+      require "hermetic/remote"
+      Remote.new(executor: executor, **opts)
+    end
+
+    private
+
+    # Any local constructor takes `executor:` (+ `token:`) and becomes a
+    # Remote client for that isolation kind — same backend, off the app host:
+    #   Hermetic.gvisor(image: "ruby:3.3-slim", executor: "https://sbx:8443", token: ...)
+    # Request-shaping options stay client-side; the rest ship as
+    # backend_options for the executor to construct with.
+    def backend(kind, const, path, **opts)
+      if opts.key?(:executor)
+        return wrap(backend: kind,
+                    executor: opts[:executor], token: opts[:token],
+                    backend_options: opts.except(:executor, :token, *CLIENT_OPTS),
+                    **opts.slice(*CLIENT_OPTS))
+      end
+
+      require path
+      Backends.const_get(const).new(**opts)
+    end
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: hermetic
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel St Paul
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Pick your isolation strength (gVisor, a Firecracker microVM, a hosted
+  sandbox, or hardened Docker) behind one `run` call, and run it off your app host
+  so an escape can't reach your database or secrets. Zero runtime dependencies — stdlib
+  only.
+email:
+- daniel@zerogravity.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- EXECUTOR.md
+- LICENSE
+- README.md
+- lib/hermetic.rb
+- lib/hermetic/backends/base.rb
+- lib/hermetic/backends/docker.rb
+- lib/hermetic/backends/firecracker.rb
+- lib/hermetic/backends/gvisor.rb
+- lib/hermetic/backends/hosted.rb
+- lib/hermetic/backends/hosted/e2b.rb
+- lib/hermetic/backends/null.rb
+- lib/hermetic/credentials.rb
+- lib/hermetic/errors.rb
+- lib/hermetic/limits.rb
+- lib/hermetic/network_policy.rb
+- lib/hermetic/remote.rb
+- lib/hermetic/request.rb
+- lib/hermetic/result.rb
+- lib/hermetic/silas.rb
+- lib/hermetic/transport/http.rb
+- lib/hermetic/transport/subprocess.rb
+- lib/hermetic/version.rb
+homepage: https://github.com/danielstpaul/hermetic
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/danielstpaul/hermetic
+  source_code_uri: https://github.com/danielstpaul/hermetic
+  changelog_uri: https://github.com/danielstpaul/hermetic/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'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: The missing Ruby sandbox — real isolation for untrusted / model-generated
+  code.
+test_files: []