ruby_llm-toolbox 0.1.0

data/lib/ruby_llm/toolbox/ruby_outline.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "ripper"
+
+module RubyLLM
+  module Toolbox
+    # Extracts a structural outline (classes, modules, methods, constants) from
+    # Ruby source, with line numbers and nesting depth. Parsing only — the code
+    # is never executed.
+    #
+    # Two backends sit behind one dispatcher and produce identical Entry lists:
+    #
+    #   * PrismBackend  — used automatically when `require "prism"` succeeds.
+    #     Prism is bundled with Ruby 3.3+, so on a modern Ruby this needs no gem
+    #     install. It is the same parser the VM itself uses, so its line numbers
+    #     and structure are authoritative.
+    #   * RipperBackend — the stdlib fallback for runtimes that don't bundle
+    #     Prism (e.g. non-MRI). Dependency-free, always present.
+    #
+    # Parity between the two is enforced by spec/ruby_outline_parity_spec.rb and
+    # by bin/verify_prism_parity, which can be run under any Ruby (e.g. a
+    # sandboxed ruby:3.4) to confirm the backends agree.
+    module RubyOutline
+      class ParseError < StandardError; end
+
+      Entry = Struct.new(:kind, :name, :line, :depth, keyword_init: true)
+
+      module_function
+
+      # True when the Prism backend can be loaded on this Ruby. Memoized.
+      def prism_available?
+        return @prism_available if defined?(@prism_available)
+
+        @prism_available = begin
+          require "prism"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      def active_backend
+        prism_available? ? PrismBackend : RipperBackend
+      end
+
+      # Returns an Array<Entry> in source order. Raises ParseError on a syntax
+      # error. Pass backend: to force a specific one (used by the parity tests).
+      def extract(source, backend: active_backend)
+        backend.extract(source.to_s)
+      end
+
+      # --- Prism backend ----------------------------------------------------
+      module PrismBackend
+        module_function
+
+        def extract(source)
+          require "prism"
+          result = Prism.parse(source)
+          raise ParseError, "source is not valid Ruby (syntax error)" unless result.success?
+
+          acc = []
+          visit(result.value, 0, acc)
+          acc
+        end
+
+        def visit(node, depth, acc)
+          return if node.nil?
+
+          case node
+          when Prism::ClassNode
+            acc << Entry.new(kind: :class, name: node.constant_path.slice,
+                             line: node.constant_path.location.start_line, depth: depth)
+            visit(node.body, depth + 1, acc)
+          when Prism::ModuleNode
+            acc << Entry.new(kind: :module, name: node.constant_path.slice,
+                             line: node.constant_path.location.start_line, depth: depth)
+            visit(node.body, depth + 1, acc)
+          when Prism::SingletonClassNode
+            acc << Entry.new(kind: :singleton_class, name: "<< #{node.expression.slice}",
+                             line: node.location.start_line, depth: depth)
+            visit(node.body, depth + 1, acc)
+          when Prism::DefNode
+            name = node.receiver ? "#{node.receiver.slice}.#{node.name}" : node.name.to_s
+            acc << Entry.new(kind: :method, name: name, line: node.name_loc.start_line, depth: depth)
+            # method bodies are not descended into
+          when Prism::ConstantWriteNode
+            acc << Entry.new(kind: :constant, name: node.name.to_s,
+                             line: node.name_loc.start_line, depth: depth)
+          else
+            node.compact_child_nodes.each { |child| visit(child, depth, acc) }
+          end
+        end
+      end
+
+      # --- Ripper backend (stdlib) ------------------------------------------
+      module RipperBackend
+        module_function
+
+        def extract(source)
+          sexp = Ripper.sexp(source.to_s)
+          raise ParseError, "source is not valid Ruby (syntax error)" if sexp.nil?
+
+          acc = []
+          walk(sexp, 0, acc)
+          acc
+        end
+
+        def walk(node, depth, acc)
+          return unless node.is_a?(Array)
+
+          if node[0].is_a?(Symbol)
+            dispatch(node, depth, acc)
+          else
+            node.each { |child| walk(child, depth, acc) }
+          end
+        end
+
+        def dispatch(node, depth, acc)
+          case node[0]
+          when :program
+            walk(node[1], depth, acc)
+          when :class
+            acc << Entry.new(kind: :class, name: const_name(node[1]), line: line_of(node[1]), depth: depth)
+            walk(node[3], depth + 1, acc) # bodystmt
+          when :module
+            acc << Entry.new(kind: :module, name: const_name(node[1]), line: line_of(node[1]), depth: depth)
+            walk(node[2], depth + 1, acc)
+          when :sclass # class << self
+            acc << Entry.new(kind: :singleton_class, name: "<< #{simple_name(node[1])}", line: line_of(node), depth: depth)
+            walk(node[2], depth + 1, acc)
+          when :def
+            acc << Entry.new(kind: :method, name: ident_name(node[1]), line: line_of(node[1]), depth: depth)
+          when :defs # def self.x / def Recv.x
+            name = "#{simple_name(node[1])}.#{ident_name(node[3])}"
+            acc << Entry.new(kind: :method, name: name, line: line_of(node[3]), depth: depth)
+          when :bodystmt
+            walk(node[1], depth, acc)
+          when :assign
+            handle_assign(node, depth, acc)
+          else
+            node[1..].each { |child| walk(child, depth, acc) }
+          end
+        end
+
+        def handle_assign(node, depth, acc)
+          target = node[1]
+          return unless target.is_a?(Array) && target[0] == :var_field
+
+          field = target[1]
+          return unless field.is_a?(Array) && field[0] == :@const
+
+          acc << Entry.new(kind: :constant, name: field[1], line: field[2]&.first, depth: depth)
+        end
+
+        def const_name(node)
+          case node && node[0]
+          when :const_ref, :top_const_ref, :var_ref
+            simple_name(node[1])
+          when :const_path_ref # Foo::Bar
+            "#{const_name(node[1])}::#{simple_name(node[2])}"
+          else
+            simple_name(node)
+          end
+        end
+
+        def simple_name(node)
+          return node.to_s unless node.is_a?(Array)
+
+          case node[0]
+          when :@const, :@ident, :@ivar, :@gvar, :@kw then node[1].to_s
+          when :const_ref, :var_ref, :var_field then simple_name(node[1])
+          when :const_path_ref then "#{simple_name(node[1])}::#{simple_name(node[2])}"
+          else
+            leaf = find_name_leaf(node)
+            leaf ? leaf[1].to_s : "?"
+          end
+        end
+
+        def ident_name(node)
+          return node.to_s unless node.is_a?(Array)
+
+          node[0] == :@ident || node[0] == :@const || node[0] == :@kw ? node[1].to_s : simple_name(node)
+        end
+
+        def line_of(node)
+          return nil unless node.is_a?(Array)
+
+          if node.size == 3 && node[2].is_a?(Array) && node[2].size == 2 &&
+             node[2][0].is_a?(Integer) && node[0].is_a?(Symbol)
+            return node[2][0]
+          end
+
+          node.each do |child|
+            line = line_of(child)
+            return line if line
+          end
+          nil
+        end
+
+        def find_name_leaf(node)
+          return nil unless node.is_a?(Array)
+          return node if %i[@const @ident @kw].include?(node[0])
+
+          node.each do |child|
+            found = find_name_leaf(child)
+            return found if found
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/safe_math.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Toolbox
+    # A safe arithmetic evaluator. Parses and evaluates a math expression with a
+    # hand-written recursive-descent parser — it never calls eval, so a
+    # malicious expression can't execute Ruby. Supports + - * / % **, unary
+    # minus, parentheses, a small set of functions, and the constants pi and e.
+    module SafeMath
+      class Error < StandardError; end
+
+      FUNCTIONS = {
+        "sqrt" => ->(x) { Math.sqrt(x) },
+        "abs" => ->(x) { x.abs },
+        "sin" => ->(x) { Math.sin(x) },
+        "cos" => ->(x) { Math.cos(x) },
+        "tan" => ->(x) { Math.tan(x) },
+        "ln" => ->(x) { Math.log(x) },
+        "log10" => ->(x) { Math.log10(x) },
+        "exp" => ->(x) { Math.exp(x) },
+        "floor" => ->(x) { x.floor },
+        "ceil" => ->(x) { x.ceil },
+        "round" => ->(x) { x.round }
+      }.freeze
+
+      CONSTANTS = { "pi" => Math::PI, "e" => Math::E }.freeze
+
+      module_function
+
+      def evaluate(expression)
+        tokens = tokenize(expression.to_s)
+        parser = Parser.new(tokens)
+        value = parser.expression
+        raise Error, "unexpected token: #{parser.current.inspect}" unless parser.done?
+
+        value
+      end
+
+      def tokenize(str)
+        tokens = []
+        scanner = str.dup
+        until scanner.empty?
+          case scanner
+          when /\A\s+/ then scanner = scanner[Regexp.last_match(0).length..]
+          when /\A(\d+\.\d+|\.\d+|\d+)([eE][+-]?\d+)?/
+            tokens << [:num, Regexp.last_match(0).to_f]
+            scanner = scanner[Regexp.last_match(0).length..]
+          when /\A[A-Za-z_]\w*/
+            tokens << [:ident, Regexp.last_match(0)]
+            scanner = scanner[Regexp.last_match(0).length..]
+          when /\A\*\*/ then tokens << [:op, "**"]; scanner = scanner[2..]
+          when %r{\A[-+*/%(),]} then tokens << [:op, Regexp.last_match(0)]; scanner = scanner[1..]
+          else raise Error, "unexpected character: #{scanner[0].inspect}"
+          end
+        end
+        tokens
+      end
+
+      # Recursive-descent parser with standard precedence.
+      class Parser
+        def initialize(tokens)
+          @tokens = tokens
+          @pos = 0
+        end
+
+        def current
+          @tokens[@pos]
+        end
+
+        def done?
+          @pos >= @tokens.length
+        end
+
+        def expression
+          value = term
+          while op?(%w[+ -])
+            operator = take[1]
+            rhs = term
+            value = operator == "+" ? value + rhs : value - rhs
+          end
+          value
+        end
+
+        private
+
+        def term
+          value = power
+          while op?(%w[* / %])
+            operator = take[1]
+            rhs = power
+            value = apply(operator, value, rhs)
+          end
+          value
+        end
+
+        def power
+          base = unary
+          if op?(["**"])
+            take
+            base**power # right-associative
+          else
+            base
+          end
+        end
+
+        def unary
+          if op?(%w[- +])
+            operator = take[1]
+            value = unary
+            operator == "-" ? -value : value
+          else
+            primary
+          end
+        end
+
+        def primary
+          token = current
+          raise Error, "unexpected end of expression" if token.nil?
+
+          case token[0]
+          when :num
+            take[1]
+          when :ident
+            identifier(take[1])
+          when :op
+            raise Error, "expected '(' " unless token[1] == "("
+
+            take
+            value = expression
+            expect(")")
+            value
+          else
+            raise Error, "unexpected token: #{token.inspect}"
+          end
+        end
+
+        def identifier(name)
+          key = name.downcase
+          return CONSTANTS[key] if CONSTANTS.key?(key)
+
+          func = FUNCTIONS[key]
+          raise Error, "unknown name: #{name}" unless func
+
+          expect("(")
+          arg = expression
+          expect(")")
+          func.call(arg)
+        end
+
+        def apply(operator, lhs, rhs)
+          case operator
+          when "*" then lhs * rhs
+          when "/"
+            raise Error, "division by zero" if rhs.zero?
+
+            lhs / rhs
+          when "%"
+            raise Error, "modulo by zero" if rhs.zero?
+
+            lhs % rhs
+          end
+        end
+
+        def op?(values)
+          token = current
+          token && token[0] == :op && values.include?(token[1])
+        end
+
+        def take
+          token = current
+          @pos += 1
+          token
+        end
+
+        def expect(symbol)
+          token = take
+          raise Error, "expected #{symbol.inspect}" unless token && token[1] == symbol
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/safety/command_guard.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Toolbox
+    module Safety
+      # Validates the executable name for BashTool. The actual execution path
+      # uses array-form spawning (no shell), so this guard only has to ensure
+      # the program itself is on the allowlist and isn't smuggling a path or
+      # shell metacharacters. Arguments are passed verbatim as argv and are
+      # therefore inert — there is no shell to interpret them.
+      class CommandGuard
+        class Blocked < StandardError; end
+
+        SHELL_META = /[;&|<>`$(){}\[\]*?!#~\n\r]/
+        PATH_SEP   = %r{[/\\]}
+
+        def initialize(allowed)
+          @allowed = Array(allowed).map(&:to_s)
+        end
+
+        # Returns the validated executable name, or raises Blocked.
+        def check!(command)
+          cmd = command.to_s
+          raise Blocked, "no command given" if cmd.empty?
+
+          if cmd.match?(PATH_SEP)
+            raise Blocked, "executable name may not contain a path: #{cmd.inspect}"
+          end
+          if cmd.match?(SHELL_META)
+            raise Blocked, "executable name may not contain shell metacharacters: #{cmd.inspect}"
+          end
+          unless @allowed.include?(cmd)
+            raise Blocked, "command not allowed: #{cmd.inspect} " \
+                           "(allowed: #{@allowed.empty? ? '(none)' : @allowed.join(', ')})"
+          end
+
+          cmd
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/safety/path_jail.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Toolbox
+    module Safety
+      # Confines a user-supplied path to a root directory. Resolves symlinks so
+      # a link inside the root can't point outside it, and tolerates
+      # not-yet-existing files (for write/edit tools) by resolving the parent
+      # directory instead.
+      class PathJail
+        class Jailbreak < StandardError; end
+
+        def initialize(root, enforce: true)
+          @root = File.realpath(File.expand_path(root.to_s))
+          @enforce = enforce
+        rescue Errno::ENOENT
+          raise Jailbreak, "fs_root does not exist: #{root}"
+        end
+
+        attr_reader :root
+
+        # Returns the absolute, symlink-resolved path if it lies within root;
+        # raises Jailbreak otherwise. When enforce is false (an operator-granted
+        # unsafe override), the path is resolved anywhere on the host.
+        def resolve(path)
+          raise Jailbreak, "path must be provided" if path.nil? || path.to_s.empty?
+
+          candidate = File.expand_path(path.to_s, @root)
+          real = existing_realpath(candidate)
+          return real unless @enforce
+
+          unless real == @root || real.start_with?(@root + File::SEPARATOR)
+            raise Jailbreak, "path escapes fs_root: #{path}"
+          end
+
+          real
+        end
+
+        private
+
+        # realpath only works on paths that exist. For a target that doesn't
+        # exist yet, resolve the nearest existing ancestor (so symlinked parents
+        # are still caught) and re-append the remaining components.
+        def existing_realpath(candidate)
+          return File.realpath(candidate) if File.exist?(candidate)
+
+          parent = File.dirname(candidate)
+          base   = File.basename(candidate)
+          parent = File.realpath(parent) if File.exist?(parent)
+          File.join(parent, base)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/safety/url_guard.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "uri"
+require "ipaddr"
+require "resolv"
+
+module RubyLLM
+  module Toolbox
+    module Safety
+      # SSRF defense for tools that fetch arbitrary URLs. It:
+      #   - allows only http/https,
+      #   - rejects embedded credentials,
+      #   - enforces optional domain allow/deny lists,
+      #   - resolves the host and blocks the request if ANY resolved address is
+      #     private, loopback, link-local (incl. the cloud metadata IP), CGNAT,
+      #     unique-local IPv6, or otherwise reserved.
+      #
+      # resolve! also returns a vetted IP so the caller can pin the socket to it
+      # (Net::HTTP#ipaddr=), closing the DNS-rebinding window: the address that
+      # was vetted is exactly the one connected to, while TLS/SNI/cert checks
+      # still use the hostname. Re-run resolve! on every redirect hop (the fetch
+      # helpers do).
+      class UrlGuard
+        class Blocked < StandardError; end
+
+        # A vetted result: the parsed URI plus a concrete IP that every
+        # connection should be pinned to, so a second DNS lookup at connect time
+        # can't swap in a private address (DNS rebinding).
+        Resolution = Struct.new(:uri, :address, keyword_init: true)
+
+        ALLOWED_SCHEMES = %w[http https].freeze
+
+        BLOCKED_RANGES = %w[
+          0.0.0.0/8 10.0.0.0/8 100.64.0.0/10 127.0.0.0/8 169.254.0.0/16
+          172.16.0.0/12 192.0.0.0/24 192.0.2.0/24 192.168.0.0/16 198.18.0.0/15
+          198.51.100.0/24 203.0.113.0/24 224.0.0.0/4 240.0.0.0/4 255.255.255.255/32
+          ::1/128 ::/128 fc00::/7 fe80::/10
+        ].map { |cidr| IPAddr.new(cidr) }.freeze
+
+        def initialize(allowlist: [], denylist: [])
+          @allowlist = Array(allowlist).map { |d| d.to_s.downcase }
+          @denylist  = Array(denylist).map { |d| d.to_s.downcase }
+        end
+
+        # Returns a parsed URI if the URL is safe to fetch; raises Blocked
+        # otherwise.
+        def check!(url)
+          resolve!(url).uri
+        end
+
+        # Like check!, but also returns a vetted IP address to pin the connection
+        # to (see Resolution). Raises Blocked otherwise.
+        def resolve!(url)
+          uri = parse(url)
+          raise Blocked, "only http/https URLs are allowed" unless ALLOWED_SCHEMES.include?(uri.scheme)
+          raise Blocked, "URL must include a host" if uri.host.nil? || uri.host.empty?
+          raise Blocked, "URLs with embedded credentials are not allowed" if uri.userinfo
+
+          host = uri.host.downcase
+          enforce_domain_lists(host)
+          address = vetted_address(host)
+          Resolution.new(uri: uri, address: address)
+        end
+
+        private
+
+        def parse(url)
+          URI.parse(url.to_s)
+        rescue URI::InvalidURIError => e
+          raise Blocked, "invalid URL: #{e.message}"
+        end
+
+        def enforce_domain_lists(host)
+          if @denylist.any? { |d| host == d || host.end_with?(".#{d}") }
+            raise Blocked, "host is denylisted: #{host}"
+          end
+          return if @allowlist.empty?
+
+          allowed = @allowlist.any? { |d| host == d || host.end_with?(".#{d}") }
+          raise Blocked, "host is not on the allowlist: #{host}" unless allowed
+        end
+
+        # Resolve the host, block the request if ANY resolved address is in a
+        # blocked range, and return the first address for the caller to pin to.
+        def vetted_address(host)
+          addresses = resolve(host)
+          raise Blocked, "could not resolve host: #{host}" if addresses.empty?
+
+          addresses.each do |addr|
+            raise Blocked, "host resolves to a blocked address (#{addr})" if blocked_ip?(addr)
+          end
+          addresses.first
+        end
+
+        def resolve(host)
+          Resolv.getaddresses(host)
+        rescue StandardError
+          []
+        end
+
+        def blocked_ip?(addr)
+          ip = IPAddr.new(addr.to_s)
+          ip = ip.native if ip.respond_to?(:ipv4_mapped?) && ip.ipv4_mapped?
+          BLOCKED_RANGES.any? { |range| range.include?(ip) }
+        rescue IPAddr::Error
+          true # if we can't parse it, don't fetch it
+        end
+      end
+    end
+  end
+end