vivarium 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6549be32807adc904ffe18fbefc055600cf14c85c68b106a3abfd7dce354e8b1
-  data.tar.gz: 1f9c961424d4712b2c43ad3df8d81ee679ea2190acaa8ea24e78a4f88b92f452
+  metadata.gz: be07034ab56d73e0aaa4fe9e124d67888ae2006cc5f6cb632cf4b93b20855422
+  data.tar.gz: 5f95cdaa111a56415f4fed08da0c638a87f5c08f01e51db2b5b818c04c256bc4
 SHA512:
-  metadata.gz: ebe88587a6328a37703899da2f0c8275f9321d7ea34e1af9806dccfaf929a6ee45bce68378356aeb2171708936b74ebb33545ada8a7eace2774aa60783b31b24
-  data.tar.gz: f707b190642345628ddf613038942a87cd95585877b45a264e13ffb1c243da0b7576712d6b5e5eb65e336dab06ff95a01f329b383bdb0007aec879629c30d2eb
+  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/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/version.rb

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

data/lib/vivarium.rb

@@ -95,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
@@ -407,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
@@ -494,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
@@ -726,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;
@@ -1519,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();
@@ -1551,11 +1675,12 @@ module Vivarium
     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
 
@@ -1580,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"]
@@ -1652,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)
@@ -1892,18 +2042,23 @@ module Vivarium
         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
-        Vivarium::Usdt.start(tp.defined_class.to_s, tp.method_id.to_s, file: file_arg, lineno: tp.lineno)
+        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: file_arg, lineno: tp.lineno)
+        Vivarium::Usdt.stop(span_class_name, tp.method_id.to_s, file: file_arg, lineno: tp.lineno)
       end
     end
   end
@@ -1935,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
@@ -1949,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
@@ -1959,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.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Uchio Kondo
@@ -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