mxc 0.1.0-x86_64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d92d20b908054c2e9efaa875a2ed37fdfcbf47c2cb5126e658c1ad348074239
+  data.tar.gz: b46625d02e842e6cb75711583e5876dde8393408c60f477b523a7c241869569d
+SHA512:
+  metadata.gz: e950f61d89ff775076ce1923f8801deeecd5f8a655d3470989e6fa1f0b8a0ea96dd83e668f8181915235118eb23731f5793abcb3983ccbffbe267ab7909774e1
+  data.tar.gz: 7f6a86cfadd3a2b97e041407a9d0342276b3a246bf48d6699a42eba037974f814f08eadeee1ee80a7682ebb5fa6d04ecf5c0281e95c5b1f3b20e9463b1bd5454

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carmine Paolino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/NOTICE

@@ -0,0 +1,34 @@
+MXC for Ruby
+Copyright (c) 2026 Carmine Paolino
+
+This gem is an unofficial Ruby binding to MXC. It is not affiliated with or
+endorsed by Microsoft.
+
+The native extension compiles and links the mxc-sdk crate
+(https://github.com/microsoft/mxc, https://crates.io/crates/mxc-sdk),
+which is distributed under the MIT License:
+
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The native extension also links other open source Rust crates, listed with
+their versions in Cargo.lock. Their licenses are available from crates.io.

data/README.md

@@ -0,0 +1,140 @@
+<div align="center">
+
+# MXC for Ruby
+
+<strong>Run untrusted commands in an OS sandbox, from Ruby</strong>
+
+[Documentation](https://crmne.github.io/mxc/) · [Getting Started](https://crmne.github.io/mxc/getting-started/) · [Running in Docker](https://crmne.github.io/mxc/running-in-docker/)
+
+[![Gem Version](https://badge.fury.io/rb/mxc.svg)](https://badge.fury.io/rb/mxc)
+[![CI](https://github.com/crmne/mxc/actions/workflows/ci.yml/badge.svg)](https://github.com/crmne/mxc/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+</div>
+
+---
+
+Your app runs code it did not write: scripts a model generated, skills users uploaded, build steps from someone else. MXC for Ruby runs them in a sandbox that decides what they can read, write, and reach, and how long they get.
+
+```ruby
+result = MXC.run("python3 build.py", readable: "app/skills", writable: "tmp/out", timeout: 30)
+result.stdout
+result.success?
+```
+
+It is an unofficial Ruby binding to [Microsoft's MXC](https://github.com/microsoft/mxc), the MIT-licensed sandbox library. Not affiliated with or endorsed by Microsoft.
+
+## Installation
+
+```sh
+bundle add mxc
+```
+
+Precompiled gems cover Linux (x86_64 and ARM64, glibc and musl), macOS (Intel and Apple Silicon), and Windows (x64 and ARM64). On Linux, install Bubblewrap:
+
+```sh
+sudo apt-get install bubblewrap
+```
+
+Commands that use the network also need `slirp4netns`, `iptables`, util-linux, and `/dev/net/tun`. macOS and Windows need nothing extra.
+
+## Usage
+
+Run a command. It sees the system's programs read-only, nothing of your home directory or project, and no network:
+
+```ruby
+MXC.run("python3 -c 'print(6 * 7)'").stdout # => "42\n"
+```
+
+One String runs through the shell, like `Kernel#system`. Pass the program and its arguments separately when part of the command comes from users, so each one reaches the program unchanged:
+
+```ruby
+MXC.run("python3", "convert.py", params[:filename])
+```
+
+Build a policy with chainable setters:
+
+```ruby
+sandbox = MXC.sandbox
+  .with_readable("app/skills")
+  .with_writable(Rails.root.join("tmp/skills"))
+  .with_denied("app/skills/secrets")
+  .with_network(allow: ["pypi.org", "*.pythonhosted.org"])
+  .with_env("LANG" => "C.UTF-8")
+  .with_directory("app/skills")
+  .with_timeout(30)
+
+result = sandbox.run("pip download --no-deps -d /tmp/wheels requests")
+result.blocked # => hosts the allow-list refused
+```
+
+Stream output as it arrives:
+
+```ruby
+sandbox.run("python3 train.py") { |chunk| print chunk.content }
+```
+
+Drive an interactive process:
+
+```ruby
+process = sandbox.spawn("python3 -i -q")
+process.write("print(6 * 7)\n")
+process.close_write
+process.each { |chunk| print chunk.content }
+process.wait # => #<MXC::Result exit_code=0 timed_out=false backend=:bubblewrap>
+```
+
+Name a policy you use in several places:
+
+```ruby
+class SkillSandbox < MXC::Sandbox
+  readable "app/skills"
+  writable "tmp/skills"
+  network false
+  timeout 30
+end
+
+SkillSandbox.new.run("python3 app/skills/build.py")
+```
+
+Check the machine before you rely on it:
+
+```ruby
+MXC.supported?                 # starts a real sandbox once and caches the answer
+MXC.availability.remediation   # what to change when it cannot
+MXC.supports?(:network_policy) # host allow-lists work here
+MXC.backends                   # => [#<MXC::Backend name=:bubblewrap ...>]
+```
+
+## Platforms
+
+| Platform | Backend | 0.1.0 |
+| --- | --- | --- |
+| Linux | Bubblewrap | Supported and tested |
+| macOS | Seatbelt | Supported and tested |
+| Windows 11 24H2 and later | ProcessContainer | Supported and tested, without host allow-lists |
+
+On Windows, a single String runs through `cmd.exe` instead of `sh`. See [Running Commands](https://crmne.github.io/mxc/running-commands/#windows) and [Policies](https://crmne.github.io/mxc/policies/#windows) for what else differs.
+
+Docker blocks the namespaces Bubblewrap needs by default. [Running in Docker](https://crmne.github.io/mxc/running-in-docker/) shows the smallest set of changes that makes it work, with a seccomp profile and a Kamal configuration for a job role.
+
+## Documentation
+
+* [Getting Started](https://crmne.github.io/mxc/getting-started/)
+* [Running Commands](https://crmne.github.io/mxc/running-commands/)
+* [Policies](https://crmne.github.io/mxc/policies/)
+* [Checking the Host](https://crmne.github.io/mxc/checking-the-host/)
+* [Running in Docker](https://crmne.github.io/mxc/running-in-docker/)
+
+## Development
+
+```sh
+bin/setup                    # bundle install and compile the extension
+bundle exec rake             # compile, tests, Rust unit tests, RuboCop
+```
+
+Tests that start sandboxes skip on machines that cannot. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. The native extension bundles Microsoft's MXC, also MIT; see [NOTICE](NOTICE).

data/lib/mxc/availability.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module MXC
+  # Whether this host can start a sandbox, and why not, as returned by MXC.availability.
+  #
+  #   availability = MXC.availability
+  #   availability.supported?  # => false
+  #   availability.remediation # => "Unprivileged user namespaces are blocked. ..."
+  class Availability
+    # Returns the backend that was checked.
+    attr_reader :backend
+
+    # Returns why a sandbox cannot start, or nil when it can.
+    attr_reader :reason
+
+    # Returns a suggestion for making the host supported, or nil.
+    attr_reader :remediation
+
+    def self.probe(backend) # :nodoc:
+      result = Sandbox.new(backend:, timeout: 10).run('exit 0')
+      return new(backend:, supported: true) if result.success?
+
+      outcome = result.timed_out? ? 'timed out' : "exited with #{result.exit_code}"
+      new(backend:, supported: false, reason: "A sandboxed `exit 0` #{outcome}: #{result.stderr.strip}")
+    rescue Error => e
+      new(backend:, supported: false, reason: e.message, remediation: e.remediation)
+    end
+
+    def initialize(backend:, supported:, reason: nil, remediation: nil) # :nodoc:
+      @backend = backend
+      @supported = supported
+      @reason = reason
+      @remediation = remediation
+    end
+
+    # Returns true when a sandbox can start.
+    def supported?
+      @supported
+    end
+
+    def inspect # :nodoc:
+      "#<MXC::Availability backend=#{backend.inspect} supported=#{supported?} reason=#{reason.inspect}>"
+    end
+  end
+end

data/lib/mxc/backend.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module MXC
+  # A sandbox backend MXC found on this host, as returned by MXC.backends.
+  #
+  #   MXC.backends.first.name # => :bubblewrap
+  class Backend
+    # Returns the backend's name, such as <tt>:bubblewrap</tt> or <tt>:seatbelt</tt>.
+    attr_reader :name
+
+    # Returns the isolation tier MXC reports for the backend, or nil when it has none.
+    attr_reader :tier
+
+    # Returns the optional capabilities MXC reports for the backend, as Symbols.
+    attr_reader :capabilities
+
+    # Returns MXC's explanations for capabilities the backend lacks on this host.
+    attr_reader :warnings
+
+    def initialize(name:, tier: nil, capabilities: [], warnings: []) # :nodoc:
+      @name = name
+      @tier = tier
+      @capabilities = capabilities.freeze
+      @warnings = warnings.freeze
+    end
+
+    # Returns true when the backend reports +capability+, such as <tt>:proxy_enforcement</tt>.
+    def supports?(capability)
+      capabilities.include?(capability)
+    end
+
+    def inspect # :nodoc:
+      "#<MXC::Backend name=#{name.inspect} tier=#{tier.inspect} capabilities=#{capabilities.inspect}>"
+    end
+  end
+end

data/lib/mxc/chunk.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MXC
+  # A piece of output from a running sandbox, as passed to the block of Sandbox#run and Process#each.
+  #
+  #   sandbox.run("python3 build.py") { |chunk| print chunk.content }
+  class Chunk
+    # Returns the stream the output came from: <tt>:stdout</tt> or <tt>:stderr</tt>.
+    attr_reader :stream
+
+    # Returns the output as a String.
+    attr_reader :content
+
+    def initialize(stream:, content:) # :nodoc:
+      @stream = stream
+      @content = content
+    end
+
+    # Returns true when the chunk came from standard output.
+    def stdout?
+      stream == :stdout
+    end
+
+    # Returns true when the chunk came from standard error.
+    def stderr?
+      stream == :stderr
+    end
+
+    def inspect # :nodoc:
+      "#<MXC::Chunk stream=#{stream.inspect} content=#{content.inspect}>"
+    end
+  end
+end

data/lib/mxc/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module MXC
+  # Global defaults for every sandbox. Change them with MXC.configure.
+  class Configuration
+    # Returns the default backend, <tt>:auto</tt> unless changed.
+    attr_reader :backend
+
+    # Returns the default timeout in seconds, or nil for none.
+    attr_reader :timeout
+
+    # Returns a Configuration with the built-in defaults.
+    def initialize
+      @backend = :auto
+      @timeout = nil
+    end
+
+    # Sets the default backend: <tt>:auto</tt>, <tt>:bubblewrap</tt>, or <tt>:seatbelt</tt>.
+    def backend=(name)
+      @backend = Sandbox.backend_name(name)
+    end
+
+    # Sets the default timeout in seconds. Accepts anything that responds to +to_f+, or nil for none.
+    def timeout=(seconds)
+      @timeout = Sandbox.duration(seconds)
+    end
+  end
+end

data/lib/mxc/error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module MXC
+  # Raised when MXC cannot start or finish a sandbox.
+  #
+  #   rescue MXC::Error => e
+  #     e.code        # => :backend_error
+  #     e.remediation # => "Install bubblewrap"
+  class Error < StandardError
+    # Returns MXC's error code as a Symbol, such as <tt>:backend_unavailable</tt>.
+    attr_reader :code
+
+    # Returns a suggestion for fixing the problem, or nil.
+    attr_reader :remediation
+
+    # Returns the operation that failed, as MXC names it, or nil.
+    attr_reader :operation
+
+    # Returns the operating system's own error code, or nil.
+    attr_reader :native_code
+
+    # Returns a new Error with +message+ and optional details.
+    def initialize(message = nil, code: nil, remediation: nil, operation: nil, native_code: nil)
+      super(message)
+      @code = code
+      @remediation = remediation
+      @operation = operation
+      @native_code = native_code
+    end
+  end
+
+  # Raised when this host cannot run the sandbox as configured, such as when Bubblewrap is
+  # missing, user namespaces are blocked, or a network policy needs tools that are not installed.
+  # Its +remediation+ says what to change.
+  class UnsupportedError < Error; end
+end

data/lib/mxc/native.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+begin
+  require "mxc/#{RUBY_VERSION[/\d+\.\d+/]}/mxc"
+rescue LoadError
+  require 'mxc/mxc'
+end
+
+module MXC
+  module Native # :nodoc:
+    UNSUPPORTED_CODES = %i[backend_unavailable unsupported_containment].freeze
+    BACKEND_NAMES = { processcontainer: :process_container }.freeze
+    MISSING_BUBBLEWRAP = /bwrap\) is not installed/
+    INSTALL_BUBBLEWRAP = 'Install Bubblewrap 0.5.0 or newer (Debian/Ubuntu: apt-get install bubblewrap; ' \
+                         'Fedora: dnf install bubblewrap; Arch: pacman -S bubblewrap)'
+
+    def self.backend_attributes
+      backends.map { |attributes| attributes.merge(name: BACKEND_NAMES.fetch(attributes[:name], attributes[:name])) }
+    end
+
+    def self.error(message, code: nil, remediation: nil, **)
+      if message.match?(MISSING_BUBBLEWRAP)
+        UnsupportedError.new(message, code: :backend_unavailable, remediation: remediation || INSTALL_BUBBLEWRAP, **)
+      else
+        (UNSUPPORTED_CODES.include?(code) ? UnsupportedError : Error).new(message, code:, remediation:, **)
+      end
+    end
+  end
+end

data/lib/mxc/preflight.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module MXC
+  module Preflight # :nodoc:
+    NETWORK_TOOLS = %w[slirp4netns iptables ip6tables iptables-restore ip6tables-restore nsenter unshare].freeze
+    TUN = '/dev/net/tun'
+    INSTALL = 'Install slirp4netns, iptables and util-linux ' \
+              '(Debian/Ubuntu: apt-get install slirp4netns iptables util-linux; ' \
+              'Fedora: dnf install slirp4netns iptables-nft util-linux; ' \
+              'Arch: pacman -S slirp4netns iptables util-linux)'
+    WINDOWS_ALLOW_LIST = 'Use network: false, or network: true for unrestricted access. On Windows, MXC confines ' \
+                         'a sandbox to a proxy only by also accepting inbound connections to it'
+    WINDOWS_DENIED = 'Leave the paths out of readable and writable instead, or run on a Windows build where ' \
+                     'MXC.supports?(:filesystem_denied_paths) is true'
+
+    module_function
+
+    def check!(network:, denied: [])
+      error = problem(network:, denied:)
+      raise error if error
+    end
+
+    def problem(network:, denied: [], path: ENV.fetch('PATH', ''), tun: TUN)
+      return windows_problem(network, denied) if windows?
+      return unless network && linux?
+
+      missing = NETWORK_TOOLS.reject { |tool| executable?(tool, path) }
+      if missing.any?
+        return UnsupportedError.new("Network access from a sandbox needs #{missing.join(', ')} on PATH",
+                                    code: :backend_unavailable, remediation: INSTALL)
+      end
+      return if tun_usable?(tun)
+
+      UnsupportedError.new("Network access from a sandbox needs a usable #{tun}",
+                           code: :backend_unavailable, remediation: tun_remediation)
+    end
+
+    def linux?
+      RUBY_PLATFORM.include?('linux')
+    end
+
+    def windows?
+      Gem.win_platform?
+    end
+
+    def windows_problem(network, denied)
+      if network.is_a?(Hash)
+        UnsupportedError.new('Host allow-lists are not supported on Windows',
+                             code: :backend_unavailable, remediation: WINDOWS_ALLOW_LIST)
+      elsif denied.any? && !denied_paths_enforced?
+        UnsupportedError.new("MXC's AppContainer sandbox on this Windows build does not enforce denied paths",
+                             code: :backend_unavailable, remediation: WINDOWS_DENIED)
+      end
+    end
+
+    def denied_paths_enforced?
+      MXC.backends.any? { |backend| backend.supports?(:filesystem_denied_paths) }
+    end
+
+    def executable?(tool, path)
+      path.split(File::PATH_SEPARATOR).any? do |dir|
+        file = File.join(dir, tool)
+        File.file?(file) && File.executable?(file)
+      end
+    end
+
+    def tun_usable?(tun)
+      File.open(tun, File::RDWR) { true }
+    rescue SystemCallError
+      false
+    end
+
+    def tun_remediation
+      if File.exist?('/.dockerenv') || File.exist?('/run/.containerenv')
+        'Pass the TUN device to the container: docker run --device /dev/net/tun ' \
+          '(Kamal: options: { device: /dev/net/tun } on the role)'
+      else
+        'Load the tun kernel module: sudo modprobe tun'
+      end
+    end
+  end
+end

data/lib/mxc/process.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module MXC
+  # A command running in a sandbox, as returned by Sandbox#spawn.
+  #
+  #   process = MXC.sandbox.spawn("python3 -i")
+  #   process.write("print(6 * 7)\n")
+  #   process.close_write
+  #   process.each { |chunk| print chunk.content }
+  #   process.wait # => #<MXC::Result exit_code=0 ...>
+  #
+  # Output is read in the background from the start, so the command never blocks on a full pipe,
+  # and the timeout applies whether or not anything waits.
+  class Process
+    READ_SIZE = 16 * 1024 # :nodoc:
+    STREAMS = %i[stdout stderr].freeze # :nodoc:
+
+    def initialize(native, backend:) # :nodoc:
+      @native = native
+      @backend = backend
+      @chunks = Thread::Queue.new
+      @output = STREAMS.to_h { |stream| [stream, String.new(encoding: Encoding::BINARY)] }
+      @lock = Mutex.new
+      @streams_lock = Mutex.new
+      @open_streams = STREAMS.size
+      @readers = STREAMS.map { |stream| background { read(stream) } }
+      @waiter = background { @native.wait }
+    end
+
+    # Returns the operating system process id of the sandbox.
+    def pid
+      @native.pid
+    end
+
+    # Writes +data+ to the command's standard input and returns the number of bytes written.
+    def write(data)
+      @native.write(data.to_s)
+    end
+
+    # Closes the command's standard input, so it reads end of file.
+    def close_write
+      @native.close_stdin
+      nil
+    end
+
+    # Yields each Chunk of output as it arrives, until the command closes both output streams.
+    # Returns an Enumerator without a block.
+    def each
+      return enum_for(:each) unless block_given?
+
+      while (chunk = @chunks.pop)
+        yield chunk
+      end
+      self
+    end
+
+    # Stops the command and everything it started.
+    def kill
+      @native.kill
+      nil
+    end
+
+    # Closes standard input, waits for the command to finish, and returns its Result.
+    #
+    # Raises Error, or UnsupportedError for a host problem, when the sandbox itself could not start.
+    def wait
+      @lock.synchronize { @result || (@result = finish) }
+    end
+
+    def inspect # :nodoc:
+      "#<MXC::Process pid=#{pid} backend=#{@backend.inspect}>"
+    end
+
+    private
+
+    def background(&)
+      Thread.new(&).tap { |thread| thread.report_on_exception = false }
+    end
+
+    def read(stream)
+      reader = :"read_#{stream}"
+      while (data = @native.public_send(reader, READ_SIZE))
+        @output[stream] << data
+        @chunks << Chunk.new(stream:, content: data.dup.force_encoding(Encoding.default_external).freeze)
+      end
+    rescue IOError
+      nil
+    ensure
+      @streams_lock.synchronize { @chunks.close if (@open_streams -= 1).zero? }
+    end
+
+    def finish
+      close_write
+      outcome = @waiter.value
+      @readers.each(&:join)
+      outcome = outcome.merge(stdout: @output[:stdout], stderr: @output[:stderr])
+      Result.new(**StartupFailure.check!(outcome), backend: @backend)
+    end
+  end
+end

data/lib/mxc/result.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module MXC
+  # The outcome of a command that ran in a sandbox.
+  #
+  #   result = MXC.run("python3 build.py")
+  #   result.success? # => true
+  #   result.stdout   # => "built 3 files\n"
+  class Result
+    # Returns everything the command wrote to standard output.
+    attr_reader :stdout
+
+    # Returns everything the command wrote to standard error.
+    attr_reader :stderr
+
+    # Returns the exit code, or nil when the command timed out.
+    attr_reader :exit_code
+
+    # Returns MXC's warnings about the sandbox, as Strings.
+    attr_reader :warnings
+
+    # Returns the <tt>host:port</tt> destinations the network allow-list refused.
+    attr_reader :blocked
+
+    # Returns the backend that ran the command, such as <tt>:bubblewrap</tt>.
+    attr_reader :backend
+
+    def initialize(stdout:, stderr:, exit_code:, timed_out:, warnings:, blocked:, backend:) # :nodoc:
+      @stdout = text(stdout)
+      @stderr = text(stderr)
+      @exit_code = exit_code
+      @timed_out = timed_out
+      @warnings = warnings.freeze
+      @blocked = blocked.freeze
+      @backend = backend
+    end
+
+    # Returns true when the command exited with status 0 before its timeout.
+    def success?
+      !timed_out? && exit_code.zero?
+    end
+
+    # Returns true when the command ran out of time and was stopped.
+    def timed_out?
+      @timed_out
+    end
+
+    # Returns the result as a Hash.
+    def to_h
+      { stdout:, stderr:, exit_code:, timed_out: timed_out?, warnings:, blocked:, backend: }
+    end
+
+    def inspect # :nodoc:
+      "#<MXC::Result exit_code=#{exit_code.inspect} timed_out=#{timed_out?} backend=#{backend.inspect}>"
+    end
+
+    private
+
+    def text(bytes)
+      bytes.dup.force_encoding(Encoding.default_external).freeze
+    end
+  end
+end

data/lib/mxc/sandbox.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module MXC
+  # A sandbox policy: what a command may read, write and reach, and how long it may run.
+  #
+  # Setters return the sandbox, so they chain, and +nil+ resets a setting to its default:
+  #
+  #   sandbox = MXC.sandbox
+  #     .with_readable("app/skills")
+  #     .with_writable(Rails.root.join("tmp"))
+  #     .with_network(allow: ["pypi.org", "*.pythonhosted.org"])
+  #     .with_timeout(30)
+  #   sandbox.run("python3 app/skills/build.py")
+  #   sandbox.run("python3", "app/skills/convert.py", params[:filename])
+  #
+  # Subclasses declare the same settings with class macros:
+  #
+  #   class SkillSandbox < MXC::Sandbox
+  #     readable "app/skills"
+  #     writable "tmp/skills"
+  #     network false
+  #     timeout 30
+  #   end
+  #
+  #   SkillSandbox.new.run("python3 app/skills/build.py")
+  class Sandbox
+    BACKENDS = %i[auto bubblewrap seatbelt process_container].freeze # :nodoc:
+    OPTIONS = %i[readable writable denied network env directory timeout backend].freeze # :nodoc:
+    HOST_RESOLVER_SOCKETS = %w[/run/systemd/resolve].freeze # :nodoc:
+    WINDOWS_ENV = %w[SYSTEMROOT WINDIR SYSTEMDRIVE COMSPEC PATHEXT PATH LOCALAPPDATA TEMP TMP
+                     PROCESSOR_ARCHITECTURE NUMBER_OF_PROCESSORS OS].freeze # :nodoc:
+    BATCH_FILE = /\.(bat|cmd)\z/i # :nodoc:
+    MAX_TIMEOUT_MS = (2**32) - 1 # :nodoc:
+    DEFAULTS = {
+      readable: [], writable: [], denied: [], env: {}, network: false, directory: nil, timeout: nil, backend: nil
+    }.freeze # :nodoc:
+
+    class << self
+      # Adds paths every instance can read.
+      def readable(*paths) = configure { |sandbox| sandbox.with_readable(*paths) }
+
+      # Adds paths every instance can read and write.
+      def writable(*paths) = configure { |sandbox| sandbox.with_writable(*paths) }
+
+      # Adds paths every instance hides, even inside readable or writable paths.
+      def denied(*paths) = configure { |sandbox| sandbox.with_denied(*paths) }
+
+      # Sets every instance's network access. Takes the same arguments as #with_network.
+      def network(...) = configure { |sandbox| sandbox.with_network(...) }
+
+      # Adds environment variables for every instance.
+      def env(variables) = configure { |sandbox| sandbox.with_env(variables) }
+
+      # Sets every instance's working directory.
+      def directory(path) = configure { |sandbox| sandbox.with_directory(path) }
+
+      # Sets every instance's timeout in seconds.
+      def timeout(seconds) = configure { |sandbox| sandbox.with_timeout(seconds) }
+
+      # Sets every instance's backend.
+      def backend(name) = configure { |sandbox| sandbox.with_backend(name) }
+
+      def defaults # :nodoc:
+        @defaults ||= allocate.tap { |sandbox| sandbox.send(:inherit, self == Sandbox ? nil : superclass.defaults) }
+      end
+
+      def backend_name(name) # :nodoc:
+        name = name.to_sym
+        return name if BACKENDS.include?(name)
+
+        raise ArgumentError, "unknown backend #{name.inspect}, expected one of #{BACKENDS.map(&:inspect).join(', ')}"
+      end
+
+      def duration(seconds) # :nodoc:
+        return if seconds.nil?
+
+        value = seconds.to_f
+        unless value.positive?
+          raise ArgumentError,
+                "timeout must be a positive number of seconds, got #{seconds.inspect}"
+        end
+
+        seconds
+      end
+
+      private
+
+      def configure
+        yield defaults
+        nil
+      end
+    end
+
+    # Returns a new sandbox with the class's defaults, then applies +options+ through
+    # the matching setters: <tt>readable:</tt>, <tt>writable:</tt>, <tt>denied:</tt>,
+    # <tt>network:</tt>, <tt>env:</tt>, <tt>directory:</tt>, <tt>timeout:</tt> and <tt>backend:</tt>.
+    #
+    #   MXC::Sandbox.new(readable: "app/skills", network: { allow: ["pypi.org"] }, timeout: 30)
+    def initialize(**options)
+      unknown = options.keys - OPTIONS
+      raise ArgumentError, "unknown option#{'s' if unknown.size > 1}: #{unknown.join(', ')}" if unknown.any?
+
+      inherit(self.class.defaults)
+      options.each { |name, value| apply(name, value) }
+    end
+
+    def initialize_copy(source) # :nodoc:
+      super
+      @settings = @settings.transform_values(&:dup)
+    end
+
+    # Returns the paths the command can read, as given.
+    def readable = @settings[:readable].dup.freeze
+
+    # Returns the paths the command can read and write, as given.
+    def writable = @settings[:writable].dup.freeze
+
+    # Returns the paths hidden from the command, as given.
+    def denied = @settings[:denied].dup.freeze
+
+    # Returns the environment variables set for the command.
+    def env = @settings[:env].dup.freeze
+
+    # Returns the network access: +false+, +true+, or <tt>{ allow: [...] }</tt> for an allow-list.
+    def network = @settings[:network]
+
+    # Returns the working directory, or nil for the default.
+    def directory = @settings[:directory]
+
+    # Returns the timeout in seconds, falling back to MXC.config.timeout.
+    def timeout = @settings[:timeout] || MXC.config.timeout
+
+    # Returns the backend, falling back to MXC.config.backend.
+    def backend = @settings[:backend] || MXC.config.backend
+
+    # Adds paths the command can read. Accepts Strings and Pathnames; relative paths
+    # are expanded from the current directory when the command runs.
+    def with_readable(*paths)
+      add_paths(:readable, paths)
+    end
+
+    # Adds paths the command can read and write.
+    def with_writable(*paths)
+      add_paths(:writable, paths)
+    end
+
+    # Adds paths hidden from the command, even inside readable or writable paths.
+    def with_denied(*paths)
+      add_paths(:denied, paths)
+    end
+
+    # Sets network access. The default, +false+, gives the command no network at all.
+    # +true+ allows any destination. <tt>allow:</tt> takes a list of hosts the command
+    # may reach over HTTP and HTTPS: <tt>"pypi.org"</tt>, <tt>"*.pythonhosted.org"</tt>
+    # (subdomains only), or <tt>"example.com:8443"</tt> for another port.
+    #
+    #   sandbox.with_network(allow: ["pypi.org", "*.pythonhosted.org"])
+    def with_network(enabled = true, allow: nil)
+      if allow
+        raise ArgumentError, 'pass allow: or true/false, not both' unless enabled == true
+
+        @settings[:network] = { allow: Array(allow).map(&:to_s).freeze }.freeze
+      else
+        raise ArgumentError, "network must be true, false or nil, got #{enabled.inspect}" unless [true, false,
+                                                                                                  nil].include?(enabled)
+
+        @settings[:network] = enabled || false
+      end
+      self
+    end
+
+    # Adds environment variables for the command. The sandbox starts from a minimal
+    # environment, not the parent's. On Windows, that environment keeps the system
+    # variables programs need to start, such as +SYSTEMROOT+ and +PATH+.
+    #
+    #   sandbox.with_env("LANG" => "C.UTF-8")
+    def with_env(variables)
+      env = @settings[:env]
+      variables.nil? ? env.clear : variables.each { |name, value| env[name.to_s] = value.to_s }
+      self
+    end
+
+    # Sets the directory the command starts in. The sandbox must be able to read it.
+    # Without one, the command starts in <tt>/</tt>, or <tt>%SystemRoot%</tt> on Windows.
+    def with_directory(path)
+      @settings[:directory] = path && File.path(path)
+      self
+    end
+
+    # Sets the timeout in seconds. Accepts anything that responds to +to_f+, such as
+    # <tt>30</tt>, <tt>2.5</tt> or <tt>1.minute</tt>.
+    def with_timeout(seconds)
+      @settings[:timeout] = self.class.duration(seconds)
+      self
+    end
+
+    # Sets the backend: <tt>:auto</tt> (Bubblewrap on Linux, Seatbelt on macOS,
+    # ProcessContainer on Windows), <tt>:bubblewrap</tt>, <tt>:seatbelt</tt>, or
+    # <tt>:process_container</tt>.
+    def with_backend(name)
+      @settings[:backend] = name && self.class.backend_name(name)
+      self
+    end
+
+    # Runs +command+ and returns its Result once it finishes. Like Kernel#system, one
+    # String runs through the platform shell: <tt>sh -c</tt>, or <tt>cmd.exe /d /s /c</tt>
+    # on Windows. Two or more Strings are a program and its arguments, and each argument
+    # reaches the program unchanged, without a shell.
+    #
+    # With a block, yields each Chunk of output as it arrives.
+    #
+    #   sandbox.run("python3 build.py && ls dist")
+    #   sandbox.run("python3", "convert.py", params[:filename])
+    #   sandbox.run("python3", "build.py") { |chunk| print chunk.content }
+    #
+    # Raises ArgumentError without a command or when given an Array. On Windows, it also
+    # raises ArgumentError for a program and arguments that start a +.bat+ or +.cmd+ file,
+    # because Windows runs those through +cmd.exe+, which splits the arguments again.
+    def run(*command, &)
+      return stream(*command, &) if block_given?
+
+      outcome = StartupFailure.check!(Native.run(command_line(command), request))
+      Result.new(**outcome, backend: resolved_backend)
+    end
+
+    # Starts +command+ and returns its Process without waiting for it. Takes the command
+    # the same way as #run.
+    #
+    #   sandbox.spawn("python3", "-i", "-q")
+    def spawn(*command)
+      Process.new(Native.spawn(command_line(command), request), backend: resolved_backend)
+    end
+
+    # Returns true when this host can run this sandbox, including its network policy.
+    def supported?
+      availability.supported?
+    end
+
+    # Returns the Availability of this sandbox on this host, with the reason and
+    # remediation when it cannot run.
+    def availability
+      problem = Preflight.problem(network:, denied:)
+      return MXC.availability(backend:) unless problem
+
+      Availability.new(backend:, supported: false, reason: problem.message, remediation: problem.remediation)
+    end
+
+    def inspect # :nodoc:
+      "#<#{self.class.name || 'MXC::Sandbox'} backend=#{backend.inspect} network=#{network.inspect} " \
+        "readable=#{readable.inspect} writable=#{writable.inspect} timeout=#{timeout.inspect}>"
+    end
+
+    protected
+
+    attr_reader :settings # :nodoc:
+
+    private
+
+    def inherit(source)
+      @settings = source ? source.settings.transform_values(&:dup) : DEFAULTS.transform_values(&:dup)
+    end
+
+    def apply(name, value)
+      case name
+      when :readable, :writable, :denied then public_send(:"with_#{name}", *Array(value))
+      when :network then value.is_a?(Hash) ? with_network(**value) : with_network(value)
+      else public_send(:"with_#{name}", value)
+      end
+    end
+
+    def add_paths(name, paths)
+      list = @settings[name]
+      paths == [nil] ? list.clear : list.concat(paths.flatten.map { |path| File.path(path) })
+      self
+    end
+
+    def stream(*command, &)
+      process = spawn(*command)
+      finished = false
+      process.each(&)
+      finished = true
+      process.wait
+    ensure
+      process&.kill unless finished
+    end
+
+    def command_line(command)
+      arguments = command_arguments(command)
+      return command_line_for_windows(arguments) if Preflight.windows?
+
+      arguments.one? ? arguments.first : Shellwords.join(arguments)
+    end
+
+    def command_arguments(command)
+      raise ArgumentError, 'no command given' if command.empty?
+      if command.any?(Array)
+        raise ArgumentError, 'pass the program and its arguments as separate Strings, ' \
+                             'as in run("python3", "build.py"), not as an Array'
+      end
+
+      command.map { |argument| String.try_convert(argument) || File.path(argument) }
+    end
+
+    def command_line_for_windows(arguments)
+      return %(cmd.exe /d /s /c "#{arguments.first}") if arguments.one?
+
+      if arguments.first.match?(BATCH_FILE)
+        raise ArgumentError, 'Windows runs batch files through cmd.exe, which does not keep arguments apart. ' \
+                             'Run them with one String and quote untrusted input yourself'
+      end
+
+      arguments.map { |argument| WindowsArguments.quote(argument) }.join(' ')
+    end
+
+    def resolved_backend
+      return backend unless backend == :auto
+      return :process_container if Preflight.windows?
+
+      Preflight.linux? ? :bubblewrap : :seatbelt
+    end
+
+    def request
+      Preflight.check!(network:, denied:)
+      {
+        readonly: expand(readable),
+        readwrite: expand(writable),
+        denied: expand(denied) | hidden_resolver_sockets,
+        environment:,
+        working_directory:,
+        timeout_ms: timeout && [(timeout.to_f * 1000).ceil, MAX_TIMEOUT_MS].min,
+        backend:,
+        network: network == true,
+        allow: network.is_a?(Hash) ? network[:allow] : nil
+      }
+    end
+
+    def expand(paths)
+      paths.map { |path| native_path(File.expand_path(path)) }
+    end
+
+    def native_path(path)
+      Preflight.windows? ? path.tr('/', '\\') : path
+    end
+
+    def working_directory
+      return native_path(File.expand_path(directory)) if directory
+
+      ENV.fetch('SystemRoot', nil) if Preflight.windows?
+    end
+
+    def environment
+      return env unless Preflight.windows?
+
+      system = ENV.to_h.select { |name, _| WINDOWS_ENV.include?(name.upcase) }
+      system.reject { |name, _| env.keys.any? { |own| own.casecmp?(name) } }.merge(env)
+    end
+
+    def hidden_resolver_sockets
+      return [] if network == true
+
+      HOST_RESOLVER_SOCKETS.select { |path| File.exist?(path) }
+    end
+  end
+end

data/lib/mxc/startup_failure.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MXC
+  module StartupFailure # :nodoc:
+    DOCKER_GUIDE = 'https://crmne.github.io/mxc/running-in-docker/'
+    NAMESPACES = Regexp.union(/No permissions to create a?\s*new namespace/i, /Creating new namespace failed/i,
+                              /setting up uid map/i, /unshare.*Operation not permitted/i)
+    PROC = /Can't mount proc|mount proc on/i
+    HOST_PROBLEMS = {
+      NAMESPACES => 'Unprivileged user namespaces are blocked. On a host, enable kernel.unprivileged_userns_clone=1 ' \
+                    'and, on Ubuntu 23.10 and later, allow bwrap in AppArmor ' \
+                    '(kernel.apparmor_restrict_unprivileged_userns). ' \
+                    "In Docker, run with a seccomp profile that allows namespaces: #{DOCKER_GUIDE}",
+      PROC => 'bwrap cannot mount a fresh /proc because the container masks /proc paths. ' \
+              "In Docker, see #{DOCKER_GUIDE}"
+    }.freeze
+    CHDIR = /Can't chdir/i
+
+    module_function
+
+    def detect(outcome)
+      return unless outcome[:exit_code] == 1 && outcome[:stdout].to_s.empty?
+
+      stderr = outcome[:stderr].to_s
+      return unless stderr.match?(/\Abwrap: [^\n]*\n?\z/)
+
+      message = "Bubblewrap could not start the sandbox: #{stderr.strip}"
+      _, hint = HOST_PROBLEMS.find { |pattern, _| stderr.match?(pattern) }
+      return UnsupportedError.new(message, code: :backend_unavailable, remediation: hint, operation: 'bwrap') if hint
+
+      remediation = 'Make the directory readable or writable in the sandbox' if stderr.match?(CHDIR)
+      Error.new(message, code: :backend_error, remediation:, operation: 'bwrap')
+    end
+
+    def check!(outcome)
+      error = detect(outcome)
+      raise error if error
+
+      outcome
+    end
+  end
+end

data/lib/mxc/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MXC
+  # The gem version.
+  VERSION = '0.1.0'
+end

data/lib/mxc/windows_arguments.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MXC
+  module WindowsArguments # :nodoc:
+    SPECIAL = /[\s"]/
+
+    module_function
+
+    # Quotes +argument+ so CommandLineToArgvW and the C runtime read it back unchanged.
+    def quote(argument)
+      return '""' if argument.empty?
+      return argument unless argument.match?(SPECIAL)
+
+      quoted = argument.gsub(/(\\*)"/) { "#{Regexp.last_match(1) * 2}\\\"" }
+      "\"#{quoted.sub(/(\\+)\z/) { Regexp.last_match(1) * 2 }}\""
+    end
+  end
+end

data/lib/mxc.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'mxc/version'
+require 'mxc/error'
+require 'mxc/configuration'
+require 'mxc/native'
+require 'mxc/preflight'
+require 'mxc/startup_failure'
+require 'mxc/chunk'
+require 'mxc/result'
+require 'mxc/backend'
+require 'mxc/availability'
+require 'mxc/process'
+require 'mxc/windows_arguments'
+require 'mxc/sandbox'
+
+# Runs commands in sandboxes through Microsoft's MXC.
+#
+#   result = MXC.run("python3 build.py", readable: "app/skills", writable: "tmp/out", timeout: 30)
+#   result.stdout
+module MXC
+  @availability = {}
+  @availability_lock = Mutex.new
+
+  class << self
+    # Returns the global Configuration.
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Yields the global Configuration to change the defaults every sandbox starts from.
+    #
+    #   MXC.configure do |config|
+    #     config.timeout = 60
+    #   end
+    def configure
+      yield config
+    end
+
+    # Returns a new Sandbox, optionally configured with the same keywords as Sandbox.new.
+    def sandbox(**)
+      Sandbox.new(**)
+    end
+
+    # Runs +command+ in a new sandbox and returns its Result. Takes the command the same
+    # way as Sandbox#run, one String for the shell or a program and its arguments, and the
+    # same keywords as Sandbox.new. A block receives each Chunk of output as it arrives.
+    #
+    #   MXC.run("python3 build.py", readable: "app/skills", timeout: 30)
+    #   MXC.run("python3", "convert.py", params[:filename], readable: "app/skills")
+    def run(*command, **, &)
+      sandbox(**).run(*command, &)
+    end
+
+    # Starts +command+ in a new sandbox and returns its Process. Takes the command the
+    # same way as Sandbox#run, and the same keywords as Sandbox.new.
+    #
+    #   MXC.spawn("python3", "-i", "-q", timeout: 60)
+    def spawn(*command, **)
+      sandbox(**).spawn(*command)
+    end
+
+    # Returns true when this host can start a sandbox with +backend+.
+    #
+    # The answer comes from starting one real sandbox, once per backend and process.
+    def supported?(backend: config.backend)
+      availability(backend:).supported?
+    end
+
+    # Returns the Availability of +backend+ on this host, with the reason and remediation
+    # when it is unsupported. Pass <tt>refresh: true</tt> to probe the host again.
+    def availability(backend: config.backend, refresh: false)
+      backend = Sandbox.backend_name(backend)
+      @availability_lock.synchronize do
+        @availability.delete(backend) if refresh
+        @availability[backend] ||= Availability.probe(backend)
+      end
+    end
+
+    # Returns the sandbox backends MXC finds on this host, as Backend objects.
+    def backends
+      Native.backend_attributes.map { |attributes| Backend.new(**attributes) }
+    end
+
+    # Returns true when this host supports +capability+ with the configured backend.
+    #
+    # +capability+ is <tt>:network</tt> for unrestricted network access,
+    # <tt>:network_policy</tt> for host allow-lists, or any capability a Backend reports.
+    def supports?(capability)
+      return false unless supported?
+
+      case capability
+      when :network then Preflight.problem(network: true).nil?
+      when :network_policy then Preflight.problem(network: { allow: [] }).nil? && proxy_enforcement?
+      else configured_backends.any? { |backend| backend.supports?(capability) }
+      end
+    end
+
+    private
+
+    def proxy_enforcement?
+      !Preflight.linux? || configured_backends.any? { |backend| backend.supports?(:proxy_enforcement) }
+    end
+
+    def configured_backends
+      backends.select { |backend| config.backend == :auto || backend.name == config.backend }
+    end
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: mxc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-linux-musl
+authors:
+- Carmine Paolino
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-14 00:00:00.000000000 Z
+dependencies: []
+description: An unofficial Ruby binding to Microsoft's MXC. Run commands in Bubblewrap,
+  Seatbelt or Windows ProcessContainer sandboxes with filesystem, network, environment
+  and timeout policies.
+email:
+- carmine@paolino.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- NOTICE
+- README.md
+- lib/mxc.rb
+- lib/mxc/3.2/mxc.so
+- lib/mxc/3.3/mxc.so
+- lib/mxc/3.4/mxc.so
+- lib/mxc/4.0/mxc.so
+- lib/mxc/availability.rb
+- lib/mxc/backend.rb
+- lib/mxc/chunk.rb
+- lib/mxc/configuration.rb
+- lib/mxc/error.rb
+- lib/mxc/native.rb
+- lib/mxc/preflight.rb
+- lib/mxc/process.rb
+- lib/mxc/result.rb
+- lib/mxc/sandbox.rb
+- lib/mxc/startup_failure.rb
+- lib/mxc/version.rb
+- lib/mxc/windows_arguments.rb
+homepage: https://crmne.github.io/mxc/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://crmne.github.io/mxc/
+  source_code_uri: https://github.com/crmne/mxc
+  bug_tracker_uri: https://github.com/crmne/mxc/issues
+  changelog_uri: https://github.com/crmne/mxc/releases
+  funding_uri: https://github.com/sponsors/crmne
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.22
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Run untrusted commands in OS sandboxes from Ruby, through Microsoft's MXC.
+test_files: []