vivarium 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0e7e80cef690342f163fde6c05fed6859c3ef81aa794fe532c87b00fbe11cd5
-  data.tar.gz: 4f2de93c9795fe93ecb0d8291f86a117ac0f595c8c12e2c7b41caabaae7c3273
+  metadata.gz: be07034ab56d73e0aaa4fe9e124d67888ae2006cc5f6cb632cf4b93b20855422
+  data.tar.gz: 5f95cdaa111a56415f4fed08da0c638a87f5c08f01e51db2b5b818c04c256bc4
 SHA512:
-  metadata.gz: 9a116f2c50b978a368a05cca351411f9724686746820085b651038d060c8452a8546170cb6e6ac885ab8a721aa20bcf42c5746639d32cbfea0ba8a9452b9687e
-  data.tar.gz: fb5b4b5307682fa84b77dcfaa2165a71a5e16deef8d7b7d21d6b3267e82b5a12ce1f73dee946193605e039a247d59613a9c2dffca15ef96ddb502a17c9ce742d
+  metadata.gz: 49e166adbaca6231263d10255779ce4ff16a98ba9905a4afc48da012382d21fe1635b4f3bfff3990125bcb9718f7e1e5f3c5168a3a7f39b7fd8981be312bc3a4
+  data.tar.gz: a85783ba20a6eb866bd8215f55a4edb6890bef1b0b3e3e7af6d11bfcc0fda77adbfa2e7ea465e201c424d6fc9f883bcb20d7846e3c051c294560151ac0078d30

data/README.md

@@ -139,6 +139,22 @@ bundle exec ruby examples/privilege_event_demo.rb
 
 This demo attempts setuid/setgid changes, sensitive file access, and `sudo` exec to trigger privilege-related events such as `setid_change`, `capable_check`, and `bprm_creds`.
 
+8) Ruby internal ENV access demo client:
+
+```bash
+bundle exec ruby examples/env_access_ruby_demo.rb
+```
+
+This demo triggers Ruby-side ENV methods (`[]`, `fetch`, `key?`, `[]=`, `store`, `delete`, `clear`, `replace`) and is intended to produce SPAN events.
+
+9) External command ENV libc access demo client:
+
+```bash
+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.
+
 You can also start top-level observation without a block (it keeps observing until process exit):
 
 ```ruby

data/examples/drop_demo.rb

@@ -14,16 +14,15 @@ require "vivarium"
 require "vivarium/correlator"
 require "vivarium/tree_renderer"
 require "vivarium/display_filter"
-require "vivarium_usdt"
 
-t0        = 1_000_000_000  # base ktime_ns
-pid       = Process.pid
-tid       = Process.pid
-method_id = 0x0001_0001
+t0  = 1_000_000_000  # base ktime_ns
+pid = Process.pid
+tid = Process.pid
 
-# span_start payload: method_id (8B) + file_id (8B) + lineno (8B)
-span_start_payload = [method_id, 0, 10].pack("q<q<q<")
-                                        .ljust(Vivarium::EVENT_PAYLOAD_SIZE, "\x00")
+# span_start payload: method_name (128B) + file_name (120B) + lineno (8B)
+span_start_payload = "MyClass#my_method".ljust(Vivarium::SPAN_METHOD_SIZE, "\x00") +
+                     "drop_demo.rb".ljust(Vivarium::SPAN_FILE_SIZE, "\x00") +
+                     [10].pack("q<")
 
 events = [
   Vivarium::Correlator::RawEvent.new(
@@ -67,7 +66,6 @@ events = [
 
 Vivarium::TreeRenderer.new(
   events: events,
-  method_table: { method_id => "MyClass#my_method" },
   observer_pid: pid,
   main_tid: tid,
   session_start_iso: "2026-06-02T00:00:00.000Z",

data/examples/env_access_external_demo.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rbconfig"
+require "vivarium"
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/env_access_external_demo.rb
+#
+# This demo launches an external Ruby process and forces direct libc calls to
+# getenv/setenv/unsetenv/putenv/clearenv through Fiddle.
+# These should appear as eBPF events with event_name=env_caccess.
+
+FILTER = {
+  include_events: %w[env_caccess proc_fork proc_exec]
+}.freeze
+
+CHILD_CODE = <<~RUBY
+  require "fiddle"
+
+  libc = begin
+    Fiddle.dlopen("libc.so.6")
+  rescue Fiddle::DLError
+    Fiddle.dlopen(nil)
+  end
+
+  getenv = Fiddle::Function.new(libc["getenv"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_VOIDP)
+  setenv = Fiddle::Function.new(libc["setenv"], [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT], Fiddle::TYPE_INT)
+  unsetenv = Fiddle::Function.new(libc["unsetenv"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_INT)
+  putenv = Fiddle::Function.new(libc["putenv"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_INT)
+  clearenv = Fiddle::Function.new(libc["clearenv"], [], Fiddle::TYPE_INT)
+
+  key = "VIVARIUM_ENV_EXT_DEMO"
+  putenv_buf = "VIVARIUM_ENV_EXT_PUT=from_putenv"
+
+  getenv.call("HOME")
+  setenv.call(key, "from_setenv", 1)
+  getenv.call(key)
+  putenv.call(putenv_buf)
+  unsetenv.call(key)
+  clearenv.call
+RUBY
+
+Vivarium.observe(filter: FILTER) do
+  puts "[env-external-demo] spawning external child"
+  pid = Process.spawn(RbConfig.ruby, "-e", CHILD_CODE)
+  Process.wait(pid)
+  puts "[env-external-demo] child exit status=#{Process.last_status.exitstatus}"
+end
+
+puts "[env-external-demo] done"

data/examples/env_access_ruby_demo.rb

@@ -0,0 +1,52 @@
+#!/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/env_access_ruby_demo.rb
+#
+# This demo intentionally triggers Ruby-side ENV access methods so they are
+# observed through TracePoint -> SPAN (USDT) path.
+
+FILTER = {
+  include_events: %w[span_start span_stop env_caccess]
+}.freeze
+
+def safe_fetch(key)
+  ENV.fetch(key)
+rescue KeyError
+  nil
+end
+
+def demo_env_reads
+  ENV["HOME"]
+  safe_fetch("PATH")
+  ENV.key?("SHELL")
+end
+
+def demo_env_writes
+  ENV["VIVARIUM_ENV_DEMO_A"] = "1"
+  ENV.store("VIVARIUM_ENV_DEMO_B", "2")
+  ENV.delete("VIVARIUM_ENV_DEMO_A")
+  ENV.replace(ENV.to_h.merge("VIVARIUM_ENV_DEMO_C" => "3"))
+  ENV.delete("VIVARIUM_ENV_DEMO_B")
+  ENV.delete("VIVARIUM_ENV_DEMO_C")
+end
+
+Vivarium.observe(filter: FILTER) do
+  original_env = ENV.to_h
+
+  puts "[env-ruby-demo] read methods"
+  demo_env_reads
+
+  puts "[env-ruby-demo] write methods"
+  demo_env_writes
+
+  puts "[env-ruby-demo] clear"
+  ENV.clear
+  ENV.replace(original_env)
+end
+
+puts "[env-ruby-demo] done"

data/lib/vivarium/correlator.rb

@@ -23,17 +23,15 @@ module Vivarium
 
     POLL_TIMEOUT_MS = 200
 
-    def initialize(pin_dir:, observer_pid:, main_tid:, method_id_queue:, filter: nil, dest: $stdout)
+    def initialize(pin_dir:, observer_pid:, main_tid:, filter: nil, dest: $stdout)
       @pin_dir = pin_dir
       @observer_pid = observer_pid
       @main_tid = main_tid
-      @method_id_queue = method_id_queue
       @filter = filter
       @dest = dest
 
       @events = []
       @events_mutex = Mutex.new
-      @method_table = {}
       @stop_flag = false
       @started = false
 
@@ -66,15 +64,12 @@ module Vivarium
       @session_stop_ktime = Vivarium.monotonic_ktime_ns
 
       3.times { safe_poll(50) }
-      drain_method_id_queue
 
       events_snapshot = @events_mutex.synchronize { @events.dup }
-      method_table_snapshot = @method_table.dup
       @stopped = true
 
       TreeRenderer.new(
         events: events_snapshot,
-        method_table: method_table_snapshot,
         observer_pid: @observer_pid,
         main_tid: @main_tid,
         session_start_iso: @session_start_iso,
@@ -91,7 +86,6 @@ module Vivarium
     def run
       until @stop_flag
         safe_poll(POLL_TIMEOUT_MS)
-        drain_method_id_queue
       end
     end
 
@@ -126,17 +120,5 @@ module Vivarium
       warn "[vivarium correlator] capture error: #{e.class}: #{e.message}"
     end
 
-    def drain_method_id_queue
-      loop do
-        msg = begin
-          @method_id_queue.pop(true)
-        rescue ThreadError
-          return
-        end
-
-        method_id, signature = msg
-        @method_table[method_id] = signature
-      end
-    end
   end
 end

data/lib/vivarium/tree_renderer.rb

@@ -28,7 +28,7 @@ module Vivarium
     UNRESOLVED_METHOD_PREFIX = "<method_id="
 
     Span = Struct.new(
-      :tid, :method_id, :file_id, :lineno, :start_ktime, :stop_ktime, :exit_kind,
+      :tid, :method_name, :file_name, :lineno, :start_ktime, :stop_ktime, :exit_kind,
       :events, :descendant_pids, :synthetic, :raised,
       keyword_init: true
     ) do
@@ -52,11 +52,10 @@ module Vivarium
     EventNode = Struct.new(:kind, :name, :target, :offset_ns, :child_proc, keyword_init: true)
     ProcNode = Struct.new(:pid, :comm, :parent_pid, :children, keyword_init: true)
 
-    def initialize(events:, method_table:, observer_pid:, main_tid:,
+    def initialize(events:, observer_pid:, main_tid:,
                    session_start_iso:, session_start_ktime:,
                    session_stop_iso:, session_stop_ktime:, filter: nil, dest:)
       @events = events
-      @method_table = method_table
       @observer_pid = observer_pid
       @main_tid = main_tid
       @session_start_iso = session_start_iso
@@ -68,7 +67,6 @@ module Vivarium
 
       @pid_comm = { observer_pid => "ruby" }
       @pid_parent = {}
-      @unresolved_method_ids = []
     end
 
     def render
@@ -101,11 +99,11 @@ module Vivarium
       events.each do |ev|
         case ev.event_name
         when "span_start"
-          mid, fid, lno = read_span_payload(ev.payload)
+          method_name, file_name, lno = read_span_payload(ev.payload)
           span = Span.new(
             tid: ev.tid,
-            method_id: mid,
-            file_id: fid,
+            method_name: method_name,
+            file_name: file_name,
             lineno: lno,
             start_ktime: ev.ktime_ns,
             stop_ktime: nil,
@@ -195,8 +193,8 @@ module Vivarium
     def synthetic_span(start_ktime, stop_ktime)
       Span.new(
         tid: @main_tid,
-        method_id: nil,
-        file_id: nil,
+        method_name: nil,
+        file_name: nil,
         lineno: nil,
         start_ktime: start_ktime,
         stop_ktime: stop_ktime,
@@ -262,9 +260,6 @@ module Vivarium
     end
 
     def print_warnings
-      @unresolved_method_ids.uniq.each do |mid|
-        @dest.puts format("# warning method_id=0x%016X unresolved at render time", mid & 0xFFFF_FFFF_FFFF_FFFF)
-      end
     end
 
     def print_observer_proc(spans)
@@ -301,25 +296,17 @@ module Vivarium
 
     def span_file_info(span)
       return "" if span.synthetic
-      return "" unless span.file_id && span.file_id != -1
-
-      file_name = Vivarium::Usdt.get_file_name(span.file_id)
-      return "" unless file_name
+      return "" if span.file_name.nil? || span.file_name.empty?
 
       lno = span.lineno && span.lineno > 0 ? ":#{span.lineno}" : ""
-      "  at=#{File.basename(file_name)}#{lno}"
+      "  at=#{File.basename(span.file_name)}#{lno}"
     end
 
     def span_display_name(span)
       return SYNTHETIC_SPAN_NAME if span.synthetic
-      return SYNTHETIC_SPAN_NAME if span.method_id.nil?
-
-      name = @method_table[span.method_id]
-      name ||= Vivarium::Usdt.get_method_name(span.method_id)
-      return name if name
+      return SYNTHETIC_SPAN_NAME if span.method_name.nil? || span.method_name.empty?
 
-      @unresolved_method_ids << span.method_id
-      format("#{UNRESOLVED_METHOD_PREFIX}0x%016X>", span.method_id & 0xFFFF_FFFF_FFFF_FFFF)
+      span.method_name
     end
 
     def build_span_children(span)
@@ -548,28 +535,20 @@ module Vivarium
 
     def render_raise_target(ev)
       bytes = ev.payload.to_s.b
-      return "-" if bytes.bytesize < 8
-
-      error_id = bytes[0, 8].unpack1("q<")
-      message_id = bytes.bytesize >= 16 ? bytes[8, 8].unpack1("q<") : -1
-      file_id = bytes.bytesize >= 24 ? bytes[16, 8].unpack1("q<") : -1
-      lineno = bytes.bytesize >= 32 ? bytes[24, 8].unpack1("q<") : -1
-
-      error_name = Vivarium::Usdt.get_error_name(error_id) ||
-                   format("0x%016X", error_id & 0xFFFF_FFFF_FFFF_FFFF)
-
-      parts = ["error=#{error_name}"]
-
-      if message_id != -1
-        msg = Vivarium::Usdt.get_message_name(message_id)
-        parts << "message=#{msg.inspect}" if msg
-      end
-
-      if file_id != -1 && (file_name = Vivarium::Usdt.get_file_name(file_id))
-        lno = lineno && lineno > 0 ? ":#{lineno}" : ""
+      return "-" if bytes.empty?
+
+      slot = Vivarium::SPAN_RAISE_SLOT_SIZE
+      error_name = Vivarium.c_string(bytes[0, slot])
+      message    = Vivarium.c_string(bytes[slot, slot])
+      file_name  = Vivarium.c_string(bytes[slot * 2, slot])
+      lineno     = bytes.bytesize > Vivarium::SPAN_RAISE_LINENO_OFFSET ? bytes[Vivarium::SPAN_RAISE_LINENO_OFFSET, 8].unpack1("q<") : -1
+
+      parts = ["error=#{error_name.empty? ? '?' : error_name}"]
+      parts << "message=#{message.inspect}" unless message.empty?
+      unless file_name.empty?
+        lno = lineno > 0 ? ":#{lineno}" : ""
         parts << "at=#{File.basename(file_name)}#{lno}"
       end
-
       parts.join(" ")
     end
 
@@ -589,12 +568,12 @@ module Vivarium
 
     def read_span_payload(payload)
       bytes = payload.to_s.b
-      return [0, -1, -1] if bytes.bytesize < 8
+      return [nil, nil, -1] if bytes.empty?
 
-      method_id = bytes[0, 8].unpack1("q<")
-      file_id = bytes.bytesize >= 16 ? bytes[8, 8].unpack1("q<") : -1
-      lineno = bytes.bytesize >= 24 ? bytes[16, 8].unpack1("q<") : -1
-      [method_id, file_id, lineno]
+      method_name = Vivarium.c_string(bytes[0, Vivarium::SPAN_METHOD_SIZE])
+      file_name   = Vivarium.c_string(bytes[Vivarium::SPAN_METHOD_SIZE, Vivarium::SPAN_FILE_SIZE])
+      lineno      = bytes.bytesize > Vivarium::SPAN_LINENO_OFFSET ? bytes[Vivarium::SPAN_LINENO_OFFSET, 8].unpack1("q<") : -1
+      [method_name, file_name, lineno]
     end
 
     def read_proc_fork_child_pid(payload)

data/lib/vivarium/version.rb

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

data/lib/vivarium.rb

@@ -33,6 +33,15 @@ module Vivarium
   EVENT_DROPPED_OFFSET = 288
   EVENTS_RINGBUF_PAGES = 256
 
+  SPAN_METHOD_SIZE     = 128
+  SPAN_FILE_SIZE       = 120
+  SPAN_LINENO_OFFSET   = SPAN_METHOD_SIZE + SPAN_FILE_SIZE  # 248
+  SPAN_FILE_ARG_MAX    = SPAN_FILE_SIZE - 1
+
+  SPAN_RAISE_SLOT_SIZE     = 80
+  SPAN_RAISE_LINENO_OFFSET = SPAN_RAISE_SLOT_SIZE * 3        # 240
+  SPAN_RAISE_FILE_ARG_MAX  = SPAN_RAISE_SLOT_SIZE - 1
+
   SSL_WRITE_PAYLOAD_DATA_LEN_OFFSET = 0
   SSL_WRITE_PAYLOAD_CAP_LEN_OFFSET = 4
   SSL_WRITE_PAYLOAD_DATA_OFFSET = 8
@@ -86,7 +95,20 @@ module Vivarium
     "Kernel#eval",
     "Object#instance_eval",
     "Object#instance_exec",
+    "ENV#[]",
+    "ENV#fetch",
+    "ENV#key?",
+    "ENV#[]=",
+    "ENV#store",
+    "ENV#delete",
+    "ENV#clear",
+    "ENV#replace",
   ].freeze
+
+  ENV_PAYLOAD_OP_SIZE = 16
+  ENV_PAYLOAD_KEY_OFFSET = ENV_PAYLOAD_OP_SIZE
+  ENV_PAYLOAD_KEY_SIZE = EVENT_PAYLOAD_SIZE - ENV_PAYLOAD_KEY_OFFSET
+
   EVENT_SEVERITY_HIGH = %w[
     capable_check bprm_creds setid_change task_kill
     ptrace_check sb_mount kernel_read_file
@@ -149,6 +171,16 @@ module Vivarium
     str[0, nul]
   end
 
+  def self.tail_fit_string(value, max_bytes, marker: "...")
+    str = value.to_s.b
+    return str if str.bytesize <= max_bytes
+    return str.byteslice(-max_bytes, max_bytes) || "" if max_bytes <= marker.bytesize
+
+    tail_size = max_bytes - marker.bytesize
+    tail = str.byteslice(-tail_size, tail_size) || ""
+    "#{marker}#{tail}"
+  end
+
   def self.event_severity(event_name)
     EVENT_SEVERITY_HIGH.include?(event_name.to_s) ? "high" : "medium"
   end
@@ -388,6 +420,20 @@ module Vivarium
     { data_len: data_len, cap_len: cap_len, data: data }
   end
 
+  def self.decode_env_payload(raw_payload)
+    bytes = raw_payload.to_s.b
+    return "" if bytes.bytesize < ENV_PAYLOAD_OP_SIZE
+
+    op = c_string(bytes[0, ENV_PAYLOAD_OP_SIZE])
+    key = c_string(bytes[ENV_PAYLOAD_KEY_OFFSET, ENV_PAYLOAD_KEY_SIZE])
+
+    return "" if op.empty?
+    return "op=#{op}" if key.empty?
+
+    key = key.split("=", 2).first if op == "putenv"
+    "op=#{op} key=#{key.inspect}"
+  end
+
   def self.decode_span_raise_payload(raw_payload)
     bytes = raw_payload.to_s.b
     return "" if bytes.bytesize < 8
@@ -475,6 +521,9 @@ module Vivarium
     when "ssl_write"
       decoded = decode_ssl_write_payload(event.payload)
       "data_len=#{decoded[:data_len]} cap_len=#{decoded[:cap_len]}"
+    when "env_caccess"
+      decoded = decode_env_payload(event.payload)
+      decoded.empty? ? event.payload.inspect : decoded
     when "dlopen", "mmap_exec"
       strip_to_first_null(event.payload).inspect
     else
@@ -707,6 +756,26 @@ module Vivarium
         events.ringbuf_submit(ev, 0);
       }
 
+      static __always_inline void submit_env_event(u32 pid, const char *op, u32 op_len, const char *name_ptr)
+      {
+        struct event_t ev = {};
+        ev.pid = pid;
+        __builtin_memcpy(ev.event_name, "env_caccess", 12);
+
+        if (op && op_len > 0) {
+          if (op_len > #{ENV_PAYLOAD_OP_SIZE} - 1) {
+            op_len = #{ENV_PAYLOAD_OP_SIZE} - 1;
+          }
+          __builtin_memcpy(&ev.payload[0], op, op_len);
+        }
+
+        if (name_ptr) {
+          bpf_probe_read_user_str(&ev.payload[#{ENV_PAYLOAD_KEY_OFFSET}], #{ENV_PAYLOAD_KEY_SIZE}, name_ptr);
+        }
+
+        submit_event(&ev);
+      }
+
       static __always_inline int is_dns_destination(void *addr)
       {
         u16 family = 0;
@@ -1394,19 +1463,19 @@ module Vivarium
           return 0;
         }
 
-        u64 method_id = 0;
-        u64 file_id = 0;
-        u64 lineno = 0;
-        bpf_usdt_readarg(1, ctx, &method_id);
-        bpf_usdt_readarg(2, ctx, &file_id);
+        u64 method_str_ptr = 0;
+        u64 file_str_ptr = 0;
+        s64 lineno = 0;
+        bpf_usdt_readarg(1, ctx, &method_str_ptr);
+        bpf_usdt_readarg(2, ctx, &file_str_ptr);
         bpf_usdt_readarg(3, ctx, &lineno);
 
         struct event_t ev = {};
         ev.pid = pid;
         __builtin_memcpy(ev.event_name, "span_start", 11);
-        __builtin_memcpy(&ev.payload[0], &method_id, sizeof(method_id));
-        __builtin_memcpy(&ev.payload[8], &file_id, sizeof(file_id));
-        __builtin_memcpy(&ev.payload[16], &lineno, sizeof(lineno));
+        bpf_probe_read_user_str(&ev.payload[0], #{SPAN_METHOD_SIZE}, (void*)method_str_ptr);
+        bpf_probe_read_user_str(&ev.payload[#{SPAN_METHOD_SIZE}], #{SPAN_FILE_SIZE}, (void*)file_str_ptr);
+        __builtin_memcpy(&ev.payload[#{SPAN_LINENO_OFFSET}], &lineno, sizeof(lineno));
         submit_event(&ev);
         return 0;
       }
@@ -1421,19 +1490,19 @@ module Vivarium
           return 0;
         }
 
-        u64 method_id = 0;
-        u64 file_id = 0;
-        u64 lineno = 0;
-        bpf_usdt_readarg(1, ctx, &method_id);
-        bpf_usdt_readarg(2, ctx, &file_id);
+        u64 method_str_ptr = 0;
+        u64 file_str_ptr = 0;
+        s64 lineno = 0;
+        bpf_usdt_readarg(1, ctx, &method_str_ptr);
+        bpf_usdt_readarg(2, ctx, &file_str_ptr);
         bpf_usdt_readarg(3, ctx, &lineno);
 
         struct event_t ev = {};
         ev.pid = pid;
         __builtin_memcpy(ev.event_name, "span_stop", 10);
-        __builtin_memcpy(&ev.payload[0], &method_id, sizeof(method_id));
-        __builtin_memcpy(&ev.payload[8], &file_id, sizeof(file_id));
-        __builtin_memcpy(&ev.payload[16], &lineno, sizeof(lineno));
+        bpf_probe_read_user_str(&ev.payload[0], #{SPAN_METHOD_SIZE}, (void*)method_str_ptr);
+        bpf_probe_read_user_str(&ev.payload[#{SPAN_METHOD_SIZE}], #{SPAN_FILE_SIZE}, (void*)file_str_ptr);
+        __builtin_memcpy(&ev.payload[#{SPAN_LINENO_OFFSET}], &lineno, sizeof(lineno));
         submit_event(&ev);
         return 0;
       }
@@ -1500,6 +1569,80 @@ module Vivarium
         return 0;
       }
 
+      int on_getenv(struct pt_regs *ctx)
+      {
+        u64 pid_tgid = bpf_get_current_pid_tgid();
+        u32 pid = pid_tgid >> 32;
+        u32 tid = (u32)pid_tgid;
+        const char *name = (const char *)PT_REGS_PARM1(ctx);
+
+        if (!target_enabled(pid, tid) || !name) {
+          return 0;
+        }
+
+        submit_env_event(pid, "getenv", 6, name);
+        return 0;
+      }
+
+      int on_setenv(struct pt_regs *ctx)
+      {
+        u64 pid_tgid = bpf_get_current_pid_tgid();
+        u32 pid = pid_tgid >> 32;
+        u32 tid = (u32)pid_tgid;
+        const char *name = (const char *)PT_REGS_PARM1(ctx);
+
+        if (!target_enabled(pid, tid) || !name) {
+          return 0;
+        }
+
+        submit_env_event(pid, "setenv", 6, name);
+        return 0;
+      }
+
+      int on_unsetenv(struct pt_regs *ctx)
+      {
+        u64 pid_tgid = bpf_get_current_pid_tgid();
+        u32 pid = pid_tgid >> 32;
+        u32 tid = (u32)pid_tgid;
+        const char *name = (const char *)PT_REGS_PARM1(ctx);
+
+        if (!target_enabled(pid, tid) || !name) {
+          return 0;
+        }
+
+        submit_env_event(pid, "unsetenv", 8, name);
+        return 0;
+      }
+
+      int on_putenv(struct pt_regs *ctx)
+      {
+        u64 pid_tgid = bpf_get_current_pid_tgid();
+        u32 pid = pid_tgid >> 32;
+        u32 tid = (u32)pid_tgid;
+        const char *string = (const char *)PT_REGS_PARM1(ctx);
+
+        if (!target_enabled(pid, tid) || !string) {
+          return 0;
+        }
+
+        submit_env_event(pid, "putenv", 6, string);
+        return 0;
+      }
+
+      int on_clearenv(struct pt_regs *ctx)
+      {
+        u64 pid_tgid = bpf_get_current_pid_tgid();
+        u32 pid = pid_tgid >> 32;
+        u32 tid = (u32)pid_tgid;
+
+        if (!target_enabled(pid, tid)) {
+          return 0;
+        }
+
+        submit_env_event(pid, "clearenv", 8, 0);
+        return 0;
+      }
+
       int on_span_raise(struct pt_regs *ctx)
       {
         u64 pid_tgid = bpf_get_current_pid_tgid();
@@ -1510,33 +1653,34 @@ module Vivarium
           return 0;
         }
 
-        u64 error_id = 0;
-        u64 message_id = 0;
-        u64 file_id = 0;
-        u64 lineno = 0;
-        bpf_usdt_readarg(1, ctx, &error_id);
-        bpf_usdt_readarg(2, ctx, &message_id);
-        bpf_usdt_readarg(3, ctx, &file_id);
+        u64 error_str_ptr = 0;
+        u64 message_str_ptr = 0;
+        u64 file_str_ptr = 0;
+        s64 lineno = 0;
+        bpf_usdt_readarg(1, ctx, &error_str_ptr);
+        bpf_usdt_readarg(2, ctx, &message_str_ptr);
+        bpf_usdt_readarg(3, ctx, &file_str_ptr);
         bpf_usdt_readarg(4, ctx, &lineno);
 
         struct event_t ev = {};
         ev.pid = pid;
         __builtin_memcpy(ev.event_name, "span_raise", 11);
-        __builtin_memcpy(&ev.payload[0], &error_id, sizeof(error_id));
-        __builtin_memcpy(&ev.payload[8], &message_id, sizeof(message_id));
-        __builtin_memcpy(&ev.payload[16], &file_id, sizeof(file_id));
-        __builtin_memcpy(&ev.payload[24], &lineno, sizeof(lineno));
+        bpf_probe_read_user_str(&ev.payload[0], #{SPAN_RAISE_SLOT_SIZE}, (void*)error_str_ptr);
+        bpf_probe_read_user_str(&ev.payload[#{SPAN_RAISE_SLOT_SIZE}], #{SPAN_RAISE_SLOT_SIZE}, (void*)message_str_ptr);
+        bpf_probe_read_user_str(&ev.payload[#{SPAN_RAISE_SLOT_SIZE * 2}], #{SPAN_RAISE_SLOT_SIZE}, (void*)file_str_ptr);
+        __builtin_memcpy(&ev.payload[#{SPAN_RAISE_LINENO_OFFSET}], &lineno, sizeof(lineno));
         submit_event(&ev);
         return 0;
       }
     CLANG
 
     def initialize(pin_dir: Vivarium.bpf_pin_dir, ssl_trace: true, libssl_path: nil,
-                   dlopen_trace: true, libc_path: nil)
+                   dlopen_trace: true, env_trace: true, libc_path: nil)
       @pin_dir      = pin_dir
       @ssl_trace    = ssl_trace
       @libssl_path  = libssl_path
       @dlopen_trace = dlopen_trace
+      @env_trace    = env_trace
       @libc_path    = libc_path
     end
 
@@ -1561,6 +1705,7 @@ module Vivarium
 
       attach_ssl_write_uprobe(bpf) if @ssl_trace
       attach_dlopen_uprobe(bpf) if @dlopen_trace
+      attach_env_uprobes(bpf) if @env_trace
 
       config_root_targets = bpf["config_root_targets"]
       config_spawned_targets = bpf["config_spawned_targets"]
@@ -1633,6 +1778,30 @@ module Vivarium
       warn "[vivariumd] dlopen uprobe attach failed: #{e.class}: #{e.message}"
     end
 
+    def attach_env_uprobes(bpf)
+      path = resolve_libc_path
+      unless path
+        warn "[vivariumd] libc not found; ENV uprobes disabled " \
+             "(set --libc PATH or VIVARIUM_LIBC_PATH to override)"
+        return
+      end
+
+      {
+        "getenv" => "on_getenv",
+        "setenv" => "on_setenv",
+        "unsetenv" => "on_unsetenv",
+        "putenv" => "on_putenv",
+        "clearenv" => "on_clearenv"
+      }.each do |sym, fn_name|
+        begin
+          bpf.attach_uprobe(name: path, sym: sym, fn_name: fn_name)
+          puts "[vivariumd] #{sym} uprobe attached via #{path}"
+        rescue StandardError => e
+          warn "[vivariumd] #{sym} uprobe attach failed: #{e.class}: #{e.message}"
+        end
+      end
+    end
+
     def resolve_libc_path
       if @libc_path
         return @libc_path if File.exist?(@libc_path)
@@ -1806,20 +1975,18 @@ module Vivarium
     pid = Process.pid
     store.register_pid(pid)
 
-    method_id_queue = Thread::Queue.new
     main_tid = gettid
 
     correlator = Correlator.new(
       pin_dir: pin_dir,
       observer_pid: pid,
       main_tid: main_tid,
-      method_id_queue: method_id_queue,
       filter: filter,
       dest: dest
     )
     correlator.start
 
-    tracer = build_observe_tracepoint(method_id_queue)
+    tracer = build_observe_tracepoint
     tracer.enable
 
     session = ObservationSession.new(
@@ -1836,20 +2003,18 @@ module Vivarium
     pid = Process.pid
     store.register_pid(pid)
 
-    method_id_queue = Thread::Queue.new
     main_tid = gettid
 
     correlator = Correlator.new(
       pin_dir: pin_dir,
       observer_pid: pid,
       main_tid: main_tid,
-      method_id_queue: method_id_queue,
       filter: filter,
       dest: dest
     )
     correlator.start
 
-    tracer = build_observe_tracepoint(method_id_queue)
+    tracer = build_observe_tracepoint
     tracer.enable
 
     yield
@@ -1859,37 +2024,41 @@ module Vivarium
     correlator&.stop
   end
 
-  def self.build_observe_tracepoint(method_id_queue)
+  def self.build_observe_tracepoint
     allow_classes = SPAN_ALLOWCLASSES
     allowlist = SPAN_ALLOWLIST
     TracePoint.new(:call, :c_call, :return, :c_return, :raise) do |tp|
       if tp.event == :raise
         # FIXME: handle threaded events in the future
-        if tp.raised_exception.kind_of?(ThreadError)
-          next
-        end
+        next if tp.raised_exception.kind_of?(ThreadError)
 
+        file_arg = tail_fit_string(tp.path, SPAN_RAISE_FILE_ARG_MAX)
         Vivarium::Usdt.raise(
           tp.raised_exception.class.to_s,
           tp.raised_exception.message.to_s,
-          file: tp.path,
+          file: file_arg,
           lineno: tp.lineno
         )
         next
       end
 
-      signature = "#{tp.defined_class}##{tp.method_id}"
+      signature = if tp.self.equal?(ENV)
+        "ENV##{tp.method_id}"
+      else
+        "#{tp.defined_class}##{tp.method_id}"
+      end
       is_target = allowlist.include?(signature) || \
         allow_classes.any? { |klass| tp.defined_class == klass } || \
         allow_classes.any? { |klass| tp.defined_class == klass.singleton_class }
       next unless is_target
 
+      file_arg = tail_fit_string(tp.path, SPAN_FILE_ARG_MAX)
+      span_class_name = tp.self.equal?(ENV) ? "ENV" : tp.defined_class.to_s
       case tp.event
       when :call, :c_call
-        method_id = Vivarium::Usdt.start(tp.defined_class.to_s, tp.method_id.to_s, file: tp.path, lineno: tp.lineno)
-        method_id_queue << [method_id, signature]
+        Vivarium::Usdt.start(span_class_name, tp.method_id.to_s, file: file_arg, lineno: tp.lineno)
       when :return, :c_return
-        Vivarium::Usdt.stop(tp.defined_class.to_s, tp.method_id.to_s, file: tp.path, lineno: tp.lineno)
+        Vivarium::Usdt.stop(span_class_name, tp.method_id.to_s, file: file_arg, lineno: tp.lineno)
       end
     end
   end
@@ -1921,10 +2090,11 @@ module Vivarium
 
   def self.run_daemon!(argv = ARGV)
     options = { pin_dir: bpf_pin_dir, ssl_trace: true, libssl_path: nil,
+                env_trace: true,
                 dlopen_trace: true, libc_path: nil }
     OptionParser.new do |opts|
       opts.banner = "Usage: vivariumd [--pin-dir PATH] [--no-ssl-trace] [--libssl PATH] " \
-                    "[--no-dlopen-trace] [--libc PATH]"
+                    "[--no-dlopen-trace] [--no-env-trace] [--libc PATH]"
       opts.on("--pin-dir PATH", "Pinned map directory") { |v| options[:pin_dir] = v }
       opts.on("--[no-]ssl-trace", "Attach OpenSSL SSL_write uprobe (default: enabled)") do |v|
         options[:ssl_trace] = v
@@ -1935,6 +2105,9 @@ module Vivarium
       opts.on("--[no-]dlopen-trace", "Attach libc dlopen uprobe (default: enabled)") do |v|
         options[:dlopen_trace] = v
       end
+      opts.on("--[no-]env-trace", "Attach libc getenv/setenv uprobes (default: enabled)") do |v|
+        options[:env_trace] = v
+      end
       opts.on("--libc PATH", "Path to libc.so for dlopen uprobe") do |v|
         options[:libc_path] = v
       end
@@ -1945,6 +2118,7 @@ module Vivarium
       ssl_trace: options[:ssl_trace],
       libssl_path: options[:libssl_path],
       dlopen_trace: options[:dlopen_trace],
+      env_trace: options[:env_trace],
       libc_path: options[:libc_path]
     ).run
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vivarium
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.1
 platform: ruby
 authors:
 - Uchio Kondo
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: ostruct
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +66,8 @@ files:
 - Rakefile
 - examples/dlopen_demo.rb
 - examples/drop_demo.rb
+- examples/env_access_external_demo.rb
+- examples/env_access_ruby_demo.rb
 - examples/execve_demo.rb
 - examples/file_operation_demo.rb
 - examples/network_client_demo.rb