little_ghost 0.3.0 → 0.5.0

data/lib/little_ghost/sandbox/mount.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module LittleGhost
+  class Sandbox
+    # Maps one trusted host directory into the sandbox's virtual filesystem.
+    # Process and Filesystem Tool visibility are separate: +tools: false+ keeps the
+    # mount available to child processes while denying it to the filesystem
+    # broker. +protect_aliases+ preserves restrictive access when the same host
+    # files are reachable through a broader mount.
+    class Mount # :nodoc:
+      ACCESS_MODES = %i[read_only read_write].freeze # :nodoc:
+
+      # Returns +value+ unchanged or builds a mount from a Hash.
+      def self.coerce(value, root: nil)
+        return value if value.is_a?(self)
+        raise PolicyError, "mount must be a Hash or Sandbox::Mount" unless value.is_a?(Hash)
+
+        new(**value.transform_keys(&:to_sym), root:)
+      end
+
+      # Maps +source+ at the absolute virtual +target+ with the selected access.
+      # +source+ is trusted host configuration, not model input.
+      def initialize(source:, target:, access: :read_only, protect_aliases: false, tools: true, root: nil)
+        source = File.expand_path(String(source), root)
+        target = normalize_target(target)
+        access = access.to_sym
+        raise PolicyError, "mount access must be :read_only or :read_write" unless ACCESS_MODES.include?(access)
+
+        @source = source.freeze
+        @target = target.freeze
+        @access = access
+        @protect_aliases = !!protect_aliases
+        @tools = !!tools
+        freeze
+      end
+
+      # Absolute host directory exposed by this mount.
+      attr_reader :source
+      # Absolute path presented inside the sandbox.
+      attr_reader :target
+      # Either +:read_only+ or +:read_write+.
+      attr_reader :access
+      # Indicates whether the mount's access applies through physical aliases.
+      attr_reader :protect_aliases
+      # Indicates whether direct filesystem tools may traverse this mount.
+      attr_reader :tools
+
+      # Indicates that the mount does not permit writes.
+      def read_only? = access == :read_only
+      # Indicates that the mount permits writes.
+      def writable? = access == :read_write
+      # Indicates that physical aliases retain this mount's access.
+      def protect_aliases? = protect_aliases
+      # Indicates that direct filesystem tools may traverse this mount.
+      def tool_visible? = tools
+
+      # Indicates whether +path+ is this mount target or one of its descendants.
+      def covers?(path)
+        path = self.class.send(:normalize_virtual_path, path)
+        path == target || path.start_with?("#{target}/")
+      end
+
+      # Returns a copy narrowed to +target+ and +access+. Widening raises
+      # CapabilityError.
+      def narrow(target: self.target, access: self.access)
+        target = self.class.send(:normalize_virtual_path, target)
+        raise CapabilityError, "sandbox scope cannot expose a path outside its parent mount" unless covers?(target)
+        if read_only? && access.to_sym == :read_write
+          raise CapabilityError, "sandbox scope cannot make a read-only mount writable"
+        end
+
+        relative = target.delete_prefix(self.target).delete_prefix("/")
+        parent_root = File.realpath(source)
+        child_root = relative.empty? ? parent_root : File.realpath(File.join(parent_root, relative))
+        unless child_root == parent_root || child_root.start_with?("#{parent_root}#{File::SEPARATOR}")
+          raise CapabilityError, "sandbox scope mount source escapes its parent"
+        end
+        self.class.new(
+          source: child_root,
+          target:,
+          access:,
+          protect_aliases: protect_aliases?,
+          tools: tool_visible?
+        )
+      rescue Errno::ENOENT, Errno::EACCES
+        raise CapabilityError, "sandbox scope mount source is unavailable"
+      end
+
+      # Mounts compare by their normalized mapping and access semantics.
+      def ==(other)
+        other.is_a?(self.class) &&
+          [comparison_source, target, access, protect_aliases?, tool_visible?] ==
+            [other.send(:comparison_source), other.target, other.access, other.protect_aliases?, other.tool_visible?]
+      end
+
+      alias_method :eql?, :==
+
+      # Hashes the normalized mapping and access semantics.
+      def hash = [comparison_source, target, access, protect_aliases?, tool_visible?].hash
+
+      def self.normalize_virtual_path(path)
+        value = String(path)
+        raise PolicyError, "mount target contains a null byte" if value.include?("\0")
+        raise PolicyError, "mount target must be absolute" unless value.start_with?(File::SEPARATOR)
+        raise PolicyError, "mount target cannot contain traversal" if value.split(File::SEPARATOR).include?("..")
+
+        Pathname.new(value).cleanpath.to_s
+      end
+
+      class << self
+        private :normalize_virtual_path
+      end
+
+      private
+
+      def comparison_source
+        File.realpath(source)
+      rescue Errno::ENOENT, Errno::EACCES
+        source
+      end
+
+      def normalize_target(path)
+        self.class.send(:normalize_virtual_path, path)
+      end
+    end
+  end
+end

data/lib/little_ghost/sandbox/network_policy.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  class Sandbox
+    # Declares outbound connectivity for sandbox-launched processes. A network
+    # policy does not apply to providers or arbitrary Ruby tools in the host.
+    class NetworkPolicy
+      MODES = %i[inherit none allowlist].freeze # :nodoc:
+      INSPECTION_MODES = %i[connect http].freeze # :nodoc:
+
+      # Returns +value+ unchanged or converts a mode or Hash to a policy.
+      def self.coerce(value)
+        return nil if value.nil?
+        return value if value.is_a?(self)
+        return new(mode: value) if value.is_a?(Symbol) || value.is_a?(String)
+        raise PolicyError, "network policy must be a mode, Hash, or Sandbox::NetworkPolicy" unless value.is_a?(Hash)
+
+        new(**value.transform_keys(&:to_sym))
+      end
+
+      # Builds an outbound policy. Enforcement remains the configured gateway's
+      # responsibility.
+      def initialize(mode:, allow: [], inspection: :connect, gateway: nil, authorizer: nil, forward_headers: [], mutation_headers: [])
+        mode = mode.to_sym
+        inspection = inspection.to_sym
+        raise PolicyError, "network mode must be :inherit, :none, or :allowlist" unless MODES.include?(mode)
+        unless INSPECTION_MODES.include?(inspection)
+          raise PolicyError, "network inspection must be :connect or :http"
+        end
+        if mode != :allowlist && (!Array(allow).empty? || gateway || authorizer || !Array(forward_headers).empty? || !Array(mutation_headers).empty?)
+          raise PolicyError, "network allow, gateway, authorizer, and header policy require mode :allowlist"
+        end
+        if inspection == :http && mode != :allowlist
+          raise PolicyError, "HTTP inspection requires mode :allowlist"
+        end
+        if inspection == :http && !authorizer
+          raise PolicyError, "HTTP inspection requires an authorizer"
+        end
+        if mode == :allowlist && Array(allow).empty?
+          raise PolicyError, "network mode :allowlist requires at least one exact destination"
+        end
+
+        @mode = mode
+        @allow = Array(allow).map { |endpoint| normalize_endpoint(endpoint) }.uniq.freeze
+        @inspection = inspection
+        @gateway = gateway
+        @authorizer = authorizer
+        @forward_headers = Array(forward_headers).map { |name| normalize_header_name(name) }.uniq.freeze
+        @mutation_headers = Array(mutation_headers).map { |name| normalize_header_name(name) }.uniq.freeze
+        freeze
+      end
+
+      # Connectivity mode: +:inherit+, +:none+, or +:allowlist+.
+      attr_reader :mode
+      # Normalized endpoints accepted by an allowlist gateway.
+      attr_reader :allow
+      # Inspection level requested from the gateway.
+      attr_reader :inspection
+      # Explicit gateway declaration, when supplied.
+      attr_reader :gateway
+      # Trusted request authorizer used by HTTP inspection, when supplied.
+      attr_reader :authorizer
+      # Header names the gateway may pass to an HTTP authorizer.
+      attr_reader :forward_headers
+      # Header names an HTTP authorizer may set on an upstream request.
+      attr_reader :mutation_headers
+
+      # Indicates unrestricted backend-provided connectivity.
+      def inherit? = mode == :inherit
+      # Indicates that outbound connectivity must be disabled.
+      def none? = mode == :none
+      # Indicates that outbound traffic must pass an allowlist gateway.
+      def allowlist? = mode == :allowlist
+
+      # Policies compare by their normalized enforcement declaration.
+      def ==(other)
+        other.is_a?(self.class) &&
+          [mode, allow, inspection, gateway, authorizer, forward_headers, mutation_headers] ==
+            [other.mode, other.allow, other.inspection, other.gateway, other.authorizer,
+              other.forward_headers, other.mutation_headers]
+      end
+
+      alias_method :eql?, :==
+
+      # Hashes the normalized enforcement declaration.
+      def hash = [mode, allow, inspection, gateway, authorizer, forward_headers, mutation_headers].hash
+
+      private
+
+      def normalize_endpoint(endpoint)
+        value = String(endpoint).strip.downcase
+        raise PolicyError, "network allowlist entries cannot be empty" if value.empty?
+        raise PolicyError, "network allowlist entries cannot contain whitespace" if value.match?(/\s/)
+
+        value.freeze
+      end
+
+      def normalize_header_name(name)
+        value = String(name).downcase
+        unless value.match?(/\A[a-z0-9][a-z0-9-]*\z/)
+          raise PolicyError, "forwarded network header names must be lowercase HTTP tokens"
+        end
+
+        value.freeze
+      end
+    end
+  end
+end

data/lib/little_ghost/sandbox/policy.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  class Sandbox
+    # Normalizes requested filesystem, process, environment, and child-network
+    # controls into one immutable policy. Policy is a declaration, not proof of
+    # isolation; the selected backend exposes #effective_policy and rejects
+    # controls it cannot enforce.
+    class Policy
+      COMMON_KEYS = %i[
+        files runtime_paths root_filesystem environment network
+      ].freeze # :nodoc:
+      ACCESS_MODES = %i[read_only read_write].freeze # :nodoc:
+      ROOT_FILESYSTEM_MODES = %i[isolated read_only read_write].freeze # :nodoc:
+      # Returns an existing policy or builds one from a Hash and keyword options.
+      def self.coerce(value = nil, **options)
+        return value if value.is_a?(self) && options.empty?
+        values = value.nil? ? {} : value
+        raise PolicyError, "sandbox policy must be a Hash or Sandbox::Policy" unless values.is_a?(Hash)
+
+        new(**values.transform_keys(&:to_sym).merge(options))
+      end
+
+      # Builds a backend-independent policy from named Workspace paths.
+      def initialize(
+        files: {root: :read_only},
+        runtime_paths: {},
+        root_filesystem: :isolated,
+        environment: {},
+        network: nil
+      )
+        @files = normalize_paths(files, "files")
+        @runtime_paths = normalize_paths(runtime_paths, "runtime_paths")
+        @root_filesystem = enum!(root_filesystem, ROOT_FILESYSTEM_MODES, "root filesystem")
+        @environment = EnvironmentPolicy.coerce(environment)
+        @network = NetworkPolicy.coerce(network)
+        freeze
+      end
+
+      # Named Workspace paths visible to tools and child processes.
+      attr_reader :files
+      # Named workspace paths visible only to sandboxed processes.
+      attr_reader :runtime_paths
+      # Requested host-root access: +:isolated+, +:read_only+, or +:read_write+.
+      attr_reader :root_filesystem
+      # Environment inheritance and explicit values.
+      attr_reader :environment
+      # Network policy, or +nil+ for a backend-specific secure default.
+      attr_reader :network
+      # Whether the +:root+ entry in +files+ requests +:read_write+ access.
+      def workspace_writable? = files.fetch(:root, :read_only) == :read_write
+
+      # Builds internal identity grants for a concrete Workspace.
+      def process_grants(workspace) # :nodoc:
+        file_mounts = files.map do |name, access|
+          source = workspace_directory(workspace, name)
+          Mount.new(source:, target: source, access:, protect_aliases: true)
+        end
+        process_mounts = runtime_paths.map do |name, access|
+          source = workspace_directory(workspace, name)
+          Mount.new(source:, target: source, access:, protect_aliases: true, tools: false)
+        end
+        (file_mounts + process_mounts).sort_by { |mount| -mount.target.length }.freeze
+      end
+
+      private
+
+      def enum!(value, choices, label)
+        value = value.to_sym
+        raise PolicyError, "#{label} must be one of #{choices.map { |choice| ":#{choice}" }.join(", ")}" unless choices.include?(value)
+
+        value
+      end
+
+      def normalize_paths(value, label)
+        raise PolicyError, "sandbox #{label} must be a Hash" unless value.respond_to?(:each_pair)
+
+        value.each_pair.to_h do |name, access|
+          [name.to_sym, enum!(access, ACCESS_MODES, "#{label} access")]
+        end.freeze
+      end
+
+      def workspace_directory(workspace, name)
+        (name.to_sym == :root) ? workspace.root : workspace.path(name)
+      end
+    end
+  end
+end

data/lib/little_ghost/sandbox/process_runner.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module LittleGhost
+  class Sandbox
+    # Runs one bounded child process and terminates its entire process group when
+    # the Run is cancelled or the command exceeds its timeout.
+    class ProcessRunner # :nodoc:
+      POLL_INTERVAL = 0.01
+      TERMINATION_GRACE = 0.5
+
+      def self.run(...) = new(...).run
+
+      def initialize(command:, timeout:, context: nil, max_output_bytes: 1_000_000,
+        environment: {}, inherit_environment: false, chdir: nil)
+        @command = Array(command).map(&:to_s)
+        @timeout = Float(timeout)
+        @context = context
+        @max_output_bytes = Integer(max_output_bytes)
+        @environment = environment.transform_keys(&:to_s).transform_values(&:to_s)
+        @inherit_environment = inherit_environment
+        @chdir = chdir
+
+        raise ToolError, "Command must contain an executable" if @command.empty? || @command.first.empty?
+        raise ArgumentError, "timeout must be positive" unless @timeout.positive? && @timeout.finite?
+        raise ArgumentError, "max_output_bytes must be positive" unless @max_output_bytes.positive?
+      end
+
+      def run
+        result = nil
+        options = {pgroup: true, unsetenv_others: !@inherit_environment}
+        options[:chdir] = @chdir if @chdir
+        Open3.popen3(@environment, *@command, **options) do |stdin, stdout, stderr, wait_thread|
+          stdin.close
+          stdout_reader = Thread.new { drain(stdout) }
+          stderr_reader = Thread.new { drain(stderr) }
+          wait_for(wait_thread, [stdout_reader, stderr_reader])
+          result = Execution.new(
+            stdout: stdout_reader.value,
+            stderr: stderr_reader.value,
+            exit_code: wait_thread.value.exitstatus
+          )
+        ensure
+          stdout_reader&.kill
+          stderr_reader&.kill
+        end
+        result
+      rescue Errno::ENOENT
+        Execution.new(stdout: "", stderr: "#{@command.first}: command not found\n", exit_code: 127)
+      end
+
+      private
+
+      def wait_for(wait_thread, readers)
+        deadline = monotonic_time + @timeout
+        until !wait_thread.alive? && readers.none?(&:alive?)
+          @context&.check!
+          raise ToolError, "Command timed out after #{@timeout} seconds" if monotonic_time >= deadline
+
+          wait_thread.join(POLL_INTERVAL)
+        end
+      rescue
+        terminate(wait_thread.pid)
+        raise
+      end
+
+      def terminate(pid)
+        Process.kill("TERM", -pid)
+        deadline = monotonic_time + TERMINATION_GRACE
+        Thread.pass while monotonic_time < deadline && process_group_alive?(pid)
+        Process.kill("KILL", -pid) if process_group_alive?(pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      end
+
+      def process_group_alive?(pid)
+        Process.kill(0, -pid)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      end
+
+      def drain(io)
+        captured = String.new(encoding: Encoding::BINARY)
+        truncated = false
+        while (chunk = io.read(16_384))
+          remaining = @max_output_bytes - captured.bytesize
+          captured << chunk.byteslice(0, remaining) if remaining.positive?
+          truncated ||= chunk.bytesize > remaining
+        end
+        captured = captured.force_encoding(Encoding::UTF_8).scrub
+        truncated ? "#{captured}\n[output truncated]" : captured
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end