vivarium 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be07034ab56d73e0aaa4fe9e124d67888ae2006cc5f6cb632cf4b93b20855422
-  data.tar.gz: 5f95cdaa111a56415f4fed08da0c638a87f5c08f01e51db2b5b818c04c256bc4
+  metadata.gz: 0a0f8b6dfc29af71d39ff5fe1ebceca9040cf62a2c6147dba5c2a074b392cdc1
+  data.tar.gz: c9f10129e5b42fd51653dcda0a02ed0e7be8b4c2ad7daef4f48a9fa5c03dcf41
 SHA512:
-  metadata.gz: 49e166adbaca6231263d10255779ce4ff16a98ba9905a4afc48da012382d21fe1635b4f3bfff3990125bcb9718f7e1e5f3c5168a3a7f39b7fd8981be312bc3a4
-  data.tar.gz: a85783ba20a6eb866bd8215f55a4edb6890bef1b0b3e3e7af6d11bfcc0fda77adbfa2e7ea465e201c424d6fc9f883bcb20d7846e3c051c294560151ac0078d30
+  metadata.gz: 9530187d826e63976bd7e1c86872345f5cad281608b2ee06f0dbe20e6211455d8d050a18013822f6baecf4c0af18e9e01b58fec7fe13174d9631181df8660569
+  data.tar.gz: c3ee802cf168d5ca917c6d9de5cce25c9441ba46a35995bc5e5f78ce6c78055c1a4d8141bff7dd4e7763205d65c1a41344a789185dbea8fc65f4589ef8e90586

data/README.md

@@ -155,6 +155,14 @@ bundle exec ruby examples/env_access_external_demo.rb
 
 This demo spawns an external process that directly calls libc `getenv`, `setenv`, `unsetenv`, `putenv`, and `clearenv`, intended to trigger `env_caccess` eBPF events.
 
+10) Box context demo:
+
+```bash
+bundle exec ruby examples/box_demo.rb
+```
+
+This demo shows how to use `Vivarium::Box` to isolate Ruby code evaluation and trace method calls within that isolated context.
+
 You can also start top-level observation without a block (it keeps observing until process exit):
 
 ```ruby

data/examples/box_demo.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vivarium"
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/box_demo.rb
+#
+# This demo demonstrates Vivarium::Box usage for automatically tracing
+# method calls within an isolated eval context.
+
+FILTER = {
+  include_events: %w[span_start span_stop]
+}.freeze
+
+# Create a box and define a class within it
+box = Vivarium::Box.new
+
+box.eval(<<~RUBY)
+  require "net/http"
+  class Calculator
+    def add(a, b)
+      a + b
+    end
+
+    def multiply(a, b)
+      a * b
+    end
+  end
+
+  class Greeter
+    def greet(name)
+      system "echo Hello \#{name}!"
+    end
+  end
+
+  system "ping -c 1 example.com"
+RUBY
+
+box.done_load!
+
+# Enable observation - all Box method calls will be automatically traced
+puts "[box-demo] calling box methods with automatic tracing"
+
+# Access classes defined in the box through const_missing
+calc = box::Calculator.new
+result1 = calc.add(10, 20)
+puts "[box-demo] calc.add(10, 20) = #{result1}"
+
+result2 = calc.multiply(3, 4)
+puts "[box-demo] calc.multiply(3, 4) = #{result2}"
+
+greeter = box::Greeter.new
+greeting = greeter.greet("World")
+puts "[box-demo] greeter.greet('World') = #{greeting}"
+
+puts "[box-demo] done"
+

data/lib/vivarium/box.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Vivarium
+  # Box provides an isolated execution context where method calls are automatically traced
+  # through Vivarium's observation system.
+  #
+  # Usage:
+  #   box = Vivarium::Box.new
+  #   box.eval('class MyClass; def foo; "result"; end; end')
+  #   result = box::MyClass.new.foo  # automatically traced if Vivarium.observe is active
+  #
+  class Box < Module
+    DEFAULT_FILTER = {
+      include_events: %w[
+        proc_fork proc_exec span_start span_stop
+        sock_connect dns_req odd_socket
+        ssl_write
+        dlopen mmap_exec
+        task_kill
+        setid_change capable_check bprm_creds
+      ]
+    }
+
+    def initialize(pin_dir: Vivarium.bpf_pin_dir, dest: $stdout, filter: DEFAULT_FILTER)
+      super()
+      @inner_box = Ruby::Box.new
+      @pin_dir = pin_dir
+      @dest = dest
+      @filter = filter
+      @session = nil
+
+      @tracing_level = [0]
+      # Set up TracePoint to automatically trace method calls within this box
+      @tracer = TracePoint.new(:call, :return) do |tp|
+        handle_trace_event(tp, @tracing_level, @inner_box)
+      end
+    end
+    attr_reader :inner_box, :tracer
+
+    # Evaluate code within the box context
+    def eval(code)
+      result = nil
+      Vivarium.observe(filter: @filter) do
+        result = @inner_box.eval(code)
+      end
+      result
+    end
+
+    # Require a file within the box context
+    # Automatically traced if Vivarium.observe is active
+    def require(path)
+      result = nil
+      Vivarium.observe(filter: @filter) do
+        result = @inner_box.require(path)
+      end
+      result
+    end
+
+    # Require a file relative to the current file within the box context
+    # Automatically traced if Vivarium.observe is active
+    def require_relative(path)
+      result = nil
+      Vivarium.observe(filter: @filter) do
+        result = @inner_box.require_relative(path)
+      end
+      result
+    end
+
+    # Load a file within the box context (executed every time, unlike require)
+    # Automatically traced if Vivarium.observe is active
+    def load(path, wrap = false)
+      result = nil
+      Vivarium.observe(filter: @filter) do
+        result = @inner_box.load(path, wrap)
+      end
+      result
+    end
+
+    # Intercept constant access to resolve from the box's evaluated context
+    def const_missing(name)
+      @inner_box.const_get(name)
+    rescue NameError => e
+      raise NameError, "#{name} not found in box: #{e.message}"
+    end
+
+    def done_load!
+      @tracer.enable
+    end
+
+    private
+
+    def handle_trace_event(tp, tracing_level, target_box)
+      begin
+        if should_trace_call?(tp, target_box)
+          case tp.event
+          when :call
+            if tracing_level[0].zero?
+              start_vivarium_observation
+            end
+            tracing_level[0] += 1
+            file_arg = Vivarium.tail_fit_string(tp.path, Vivarium::SPAN_FILE_ARG_MAX)
+            root = Ruby::Box.root
+            root::Vivarium::Usdt.start("#{tp.defined_class}", tp.method_id.to_s, file: file_arg, lineno: tp.lineno)
+          when :return
+            tracing_level[0] -= 1
+            file_arg = Vivarium.tail_fit_string(tp.path, Vivarium::SPAN_FILE_ARG_MAX)
+            root = Ruby::Box.root
+            root::Vivarium::Usdt.stop("#{tp.defined_class}", tp.method_id.to_s, file: file_arg, lineno: tp.lineno)
+            if tracing_level[0].zero?
+              stop_vivarium_observation
+            end
+          end
+        end
+      rescue StandardError
+        # Silently ignore tracing errors to avoid breaking user code
+      end
+    end
+
+    def should_trace_call?(tp, target_box)
+      tp.binding.eval("Ruby::Box.current") == target_box
+    end
+
+    def start_vivarium_observation
+      puts "[debug] Starting Vivarium observation for Box method calls"
+      @session = Vivarium.top_observe(pin_dir: @pin_dir, dest: @dest, filter: @filter)
+    end
+
+    def stop_vivarium_observation
+      puts "[debug] Stopping Vivarium observation for Box method calls"
+      @session&.stop
+      @session = nil
+    end
+  end
+end

data/lib/vivarium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vivarium
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

data/lib/vivarium.rb

@@ -7,6 +7,12 @@ require "optparse"
 require "pathname"
 require "rbbcc"
 require "socket"
+if defined?(Ruby) && defined?(Ruby::Box) && Ruby::Box.enabled?
+  Ruby::Box.root.require "vivarium_usdt"
+else
+  require "vivarium_usdt"
+end
+
 require_relative "vivarium/version"
 require_relative "vivarium/cli"
 
@@ -1694,7 +1700,6 @@ module Vivarium
         .gsub("__VIVARIUM_F_PATH_OFFSET__", f_path_offset.to_s)
         .gsub("__VIVARIUM_DENTRY_D_NAME_OFFSET__", d_name_offset.to_s)
 
-      require "vivarium_usdt"
       usdt_so_path = ENV.fetch("VIVARIUM_USDT_SO_PATH") { Vivarium.locate_vivarium_usdt_so }
       usdt = RbBCC::USDT.new(path: usdt_so_path)
       usdt.enable_probe(probe: "start_probe", fn_name: "on_span_start")
@@ -1969,8 +1974,6 @@ module Vivarium
   end
 
   def self.top_observe(pin_dir: bpf_pin_dir, dest: $stdout, filter: nil)
-    require "vivarium_usdt"
-
     store = MapStore.new(pin_dir: pin_dir)
     pid = Process.pid
     store.register_pid(pid)
@@ -1997,8 +2000,6 @@ module Vivarium
   end
 
   def self.scoped_observe(pin_dir:, dest:, filter: nil)
-    require "vivarium_usdt"
-
     store = MapStore.new(pin_dir: pin_dir)
     pid = Process.pid
     store.register_pid(pid)
@@ -2079,7 +2080,6 @@ module Vivarium
   end
 
   def self.locate_vivarium_usdt_so
-    require "vivarium_usdt/vivarium_usdt"
     so = $LOADED_FEATURES.find { |p| p =~ %r{vivarium_usdt/vivarium_usdt\.(so|bundle|dylib)\z} }
     raise Error, "vivarium_usdt native extension not found in $LOADED_FEATURES" unless so
 
@@ -2127,3 +2127,6 @@ end
 require_relative "vivarium/correlator"
 require_relative "vivarium/display_filter"
 require_relative "vivarium/tree_renderer"
+if defined?(Ruby) && defined?(Ruby::Box) && Ruby::Box.enabled?
+  require_relative "vivarium/box"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vivarium
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Uchio Kondo
@@ -64,6 +64,7 @@ files:
 - CONTEXT.md
 - README.md
 - Rakefile
+- examples/box_demo.rb
 - examples/dlopen_demo.rb
 - examples/drop_demo.rb
 - examples/env_access_external_demo.rb
@@ -80,6 +81,7 @@ files:
 - exe/vivariumd
 - image.png
 - lib/vivarium.rb
+- lib/vivarium/box.rb
 - lib/vivarium/cli.rb
 - lib/vivarium/correlator.rb
 - lib/vivarium/display_filter.rb