vivarium 0.2.0 → 0.3.1

data/examples/network_client_demo.rb

@@ -4,6 +4,10 @@
 require "socket"
 require "vivarium"
 
+FILTER = {
+  include_events: %w[sock_connect dns_req odd_socket]
+}.freeze
+
 # Usage:
 #   1) In another shell (root): sudo bundle exec vivariumd
 #   2) Run this script: bundle exec ruby examples/network_client_demo.rb
@@ -15,7 +19,7 @@ rescue StandardError => e
   puts "[client] #{title} failed: #{e.class}: #{e.message}"
 end
 
-Vivarium.observe do
+Vivarium.observe(filter: FILTER) do
   # Likely emits sock_connect and dns_req via resolver traffic.
   try_step("system: DNS lookup") do
     system("getent hosts example.com >/dev/null 2>&1 || true")

data/examples/privilege_event_demo.rb

@@ -3,6 +3,10 @@
 
 require "vivarium"
 
+FILTER = {
+  include_events: %w[setid_change capable_check bprm_creds]
+}.freeze
+
 # Usage:
 #   1) In another shell (root): sudo bundle exec vivariumd
 #   2) Run this script: bundle exec ruby examples/privilege_event_demo.rb
@@ -14,7 +18,7 @@ rescue StandardError => e
   puts "[priv-demo] #{title} failed: #{e.class}: #{e.message}"
 end
 
-Vivarium.observe do
+Vivarium.observe(filter: FILTER) do
   try_step("attempt setuid(0)") do
     Process::UID.change_privilege(0)
   end

data/examples/raise_demo.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vivarium"
+
+FILTER = {
+  include_events: %w[span_raise]
+}.freeze
+
+def try_step(title)
+  puts "[priv-demo] #{title}"
+  yield
+rescue StandardError => e
+  puts "[priv-demo] #{title} failed: #{e.class}: #{e.message}"
+end
+
+Vivarium.observe(filter: FILTER) do
+  try_step("raise in main") do
+    raise "error in main"
+  end
+
+  try_step("raise in eval") do
+    eval("raise 'error in eval'")
+  end
+
+  try_step("raise in nested eval") do
+    eval(<<~RUBY)
+      eval(<<~INNER_RUBY)
+        begin
+          eval(<<~INNER_INNER_RUBY)
+            puts "Hi"
+            raise "error in nested nested eval"
+          INNER_INNER_RUBY
+        rescue StandardError => _
+          puts "Rescued in nested eval"
+        end
+        File.open("/etc/hosts")
+      INNER_RUBY
+    RUBY
+  end
+
+
+  try_step("raise in method") do
+    File.open("notfound")
+  end
+end

data/examples/signal_kill_demo.rb

@@ -3,6 +3,10 @@
 
 require "vivarium"
 
+FILTER = {
+  include_events: %w[task_kill]
+}.freeze
+
 # Usage:
 #   1) In another shell (root): sudo bundle exec vivariumd
 #   2) Run this script: bundle exec ruby examples/signal_kill_demo.rb
@@ -16,7 +20,7 @@ end
 
 child_pid = nil
 
-Vivarium.observe do
+Vivarium.observe(filter: FILTER) do
   try_step("fork child process") do
     child_pid = fork do
       trap("TERM") { exit!(0) }

data/examples/ssl_write_demo.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "vivarium"
+
+FILTER = {
+  include_events: %w[ssl_write]
+}.freeze
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#      (SSL_write uprobe is attached automatically when libssl is found)
+#   2) Run this script: bundle exec ruby examples/ssl_write_demo.rb
+#
+# You can disable the SSL_write uprobe with `sudo vivariumd --no-ssl-trace`
+# or point at a specific library with `sudo vivariumd --libssl /path/to/libssl.so.3`.
+
+Vivarium.observe(filter: FILTER) do
+  # Net::HTTP uses libssl's SSL_write under the hood. With HTTP/1.1 the
+  # request line should appear verbatim in the SSL event payload.
+  begin
+    uri = URI("https://udzura.jp/")
+    Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+      http.get(uri.request_uri)
+    end
+  rescue StandardError => e
+    warn "[ssl_demo] Net::HTTP failed: #{e.class}: #{e.message}"
+  end
+
+  # `curl --http2` should produce HTTP/2 traffic; HEADERS frames will be
+  # HPACK-decoded if the `http-2` gem is installed on the observer side.
+  system("curl -sS --http2 -o /dev/null https://nghttp2.org/ 2>/dev/null")
+end
+
+puts "[ssl_demo] done"

data/examples/sudo_attempt_demo.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+def debug_output(msg)
+  $stderr.puts("[DEBUG] #{msg}") if ENV["VIVARIUM_DEBUG"]
+end
+
+debug_output "=== sudo attempt demo ==="
+
+debug_output "[1] Attempting: sudo id"
+system("sudo", "-n", "id")
+
+debug_output "[2] Attempting: sudo cat /etc/shadow"
+system("sudo", "-n", "cat", "/etc/shadow")
+
+debug_output "[3] Attempting: sudo cat /proc/1/environ"
+system("sudo", "-n", "cat", "/proc/1/environ")
+
+debug_output "=== done ==="

data/exe/vivarium

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vivarium"
+
+Vivarium::CLI.run!

data/lib/vivarium/cli.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Vivarium
+  module CLI
+    def self.run!(argv = ARGV)
+      options = { pin_dir: Vivarium.bpf_pin_dir, dest: $stdout }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: vivarium [options] <command> [args]"
+        opts.separator ""
+        opts.separator "Commands:"
+        opts.separator "  load <script>    Load and observe a Ruby script"
+        opts.separator ""
+        opts.separator "Options:"
+        opts.on("--pin-dir PATH", "Pinned map directory") { |v| options[:pin_dir] = v }
+        opts.on("-o", "--output PATH", "Log output file (default: stdout)") { |v| options[:dest] = File.open(v, "a") }
+      end
+      parser.order!(argv)
+
+      command = argv.shift
+      case command
+      when "load"
+        run_load!(argv, options)
+      else
+        abort parser.help
+      end
+    end
+
+    def self.run_load!(argv, options)
+      script = argv.shift
+      abort "Usage: vivarium load <script>" unless script
+      abort "File not found: #{script}" unless File.exist?(script)
+
+      Vivarium.observe(pin_dir: options[:pin_dir], dest: options[:dest]) do
+        Kernel.load(File.expand_path(script))
+      end
+    end
+  end
+end

data/lib/vivarium/correlator.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "rbbcc"
+require "time"
+
+module Vivarium
+  class Correlator
+    RawEvent = Struct.new(
+      :ktime_ns, :pid, :tid, :event_name, :payload,
+      keyword_init: true
+    )
+
+    EVENT_C_TYPE = <<~C
+      struct event_t {
+        u64 ktime_ns;
+        u32 pid;
+        u32 tid;
+        char event_name[16];
+        char payload[256];
+      };
+    C
+
+    POLL_TIMEOUT_MS = 200
+
+    def initialize(pin_dir:, observer_pid:, main_tid:, method_id_queue:, 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
+
+      @ringbuf = RbBCC::RingBuf.from_pin(
+        File.join(@pin_dir, "events"),
+        EVENT_C_TYPE,
+        Vivarium::EVENTS_RINGBUF_PAGES
+      )
+      @ringbuf.open_ring_buffer do |_ctx, data, size|
+        capture_event(data, size)
+      end
+    end
+
+    def start
+      return if @started
+
+      @session_start_iso = Time.now.utc.iso8601(3)
+      @session_start_ktime = Vivarium.monotonic_ktime_ns
+      @thread = Thread.new { run }
+      @started = true
+    end
+
+    def stop
+      return unless @started
+      return if @stopped
+
+      @stop_flag = true
+      @thread&.join(POLL_TIMEOUT_MS * 4 / 1000.0 + 1)
+      @session_stop_iso = Time.now.utc.iso8601(3)
+      @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,
+        session_start_ktime: @session_start_ktime,
+        session_stop_iso: @session_stop_iso,
+        session_stop_ktime: @session_stop_ktime,
+        filter: @filter,
+        dest: @dest
+      ).render
+    end
+
+    private
+
+    def run
+      until @stop_flag
+        safe_poll(POLL_TIMEOUT_MS)
+        drain_method_id_queue
+      end
+    end
+
+    def safe_poll(timeout_ms)
+      @ringbuf.ring_buffer_poll(timeout_ms)
+    rescue StandardError => e
+      warn "[vivarium correlator] poll error: #{e.class}: #{e.message}"
+    end
+
+    def capture_event(data, size)
+      bytes = data[0, size].to_s.b
+      bytes = bytes.ljust(Vivarium::EVENT_STRUCT_SIZE, "\x00") if bytes.bytesize < Vivarium::EVENT_STRUCT_SIZE
+
+      ktime_ns = bytes[Vivarium::EVENT_TS_OFFSET, Vivarium::EVENT_TS_SIZE].unpack1("Q<")
+      pid = bytes[Vivarium::EVENT_PID_OFFSET, 4].unpack1("L<")
+      tid = bytes[Vivarium::EVENT_TID_OFFSET, 4].unpack1("L<")
+      event_name = Vivarium.c_string(bytes[Vivarium::EVENT_NAME_OFFSET, Vivarium::EVENT_NAME_SIZE])
+      payload = bytes[Vivarium::EVENT_PAYLOAD_OFFSET, Vivarium::EVENT_PAYLOAD_SIZE].to_s.b
+
+      @events_mutex.synchronize do
+        @events << RawEvent.new(
+          ktime_ns: ktime_ns,
+          pid: pid,
+          tid: tid,
+          event_name: event_name,
+          payload: payload
+        )
+      end
+    rescue StandardError => e
+      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/display_filter.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Vivarium
+  class DisplayFilter
+    attr_reader :include_events, :exclude_events, :include_severities, :include_pids, :include_tids
+
+    def self.compile(raw)
+      return new if raw.nil?
+      return raw if raw.is_a?(self)
+
+      unless raw.respond_to?(:to_h)
+        raise ArgumentError, "filter must be a Hash-compatible object"
+      end
+
+      new(raw.to_h)
+    end
+
+    def initialize(raw = {})
+      @raw = symbolize_keys(raw || {})
+
+      @include_events = normalize_string_set(fetch_key(:include_events, :event_names, :events))
+      @exclude_events = normalize_string_set(fetch_key(:exclude_events))
+      @include_severities = normalize_string_set(fetch_key(:include_severities, :severities, :severity))
+      @include_pids = normalize_integer_set(fetch_key(:include_pids, :pids, :pid))
+      @include_tids = normalize_integer_set(fetch_key(:include_tids, :tids, :tid))
+
+      @include_span_names = normalize_string_set(fetch_key(:include_span_names, :span_names))
+      @span_pattern = normalize_pattern(fetch_key(:span, :span_pattern))
+
+      payload_value = fetch_key(:payload)
+      @payload_pattern = normalize_pattern(fetch_key(:payload_pattern))
+      @payload_patterns_by_event = {}
+      if payload_value.is_a?(Hash)
+        @payload_patterns_by_event = normalize_payload_map(payload_value)
+      else
+        @payload_pattern ||= normalize_pattern(payload_value)
+      end
+    end
+
+    def enabled?
+      !@raw.empty?
+    end
+
+    def needs_payload?
+      !@payload_pattern.nil? || !@payload_patterns_by_event.empty?
+    end
+
+    def allow_span_name?(span_name)
+      return true if @include_span_names.empty? && @span_pattern.nil?
+
+      name = span_name.to_s
+      return true if @include_span_names.include?(name)
+      return true if @span_pattern && @span_pattern.match?(name)
+
+      false
+    end
+
+    def allow_event?(event_name:, severity:, span_name:, payload: nil, pid: nil, tid: nil)
+      return false unless allow_span_name?(span_name)
+
+      name = event_name.to_s
+      sev = severity.to_s
+
+      return false if @exclude_events.include?(name)
+      return false if !@include_events.empty? && !@include_events.include?(name)
+      return false if !@include_severities.empty? && !@include_severities.include?(sev)
+      return false if !@include_pids.empty? && !@include_pids.include?(pid.to_i)
+      return false if !@include_tids.empty? && !@include_tids.include?(tid.to_i)
+
+      payload_pattern = @payload_patterns_by_event[name] || @payload_pattern
+      if payload_pattern
+        return false if payload.nil?
+        return false unless payload_pattern.match?(payload.to_s)
+      end
+
+      true
+    end
+
+    private
+
+    def fetch_key(*keys)
+      keys.each do |key|
+        return @raw[key] if @raw.key?(key)
+      end
+      nil
+    end
+
+    def symbolize_keys(hash)
+      hash.each_with_object({}) do |(k, v), out|
+        out[k.respond_to?(:to_sym) ? k.to_sym : k] = v
+      end
+    end
+
+    def normalize_string_set(value)
+      arr = case value
+            when nil
+              []
+            when Array
+              value
+            else
+              [value]
+            end
+
+      arr.each_with_object(Set.new) do |item, set|
+        str = item.to_s.strip
+        set << str unless str.empty?
+      end
+    end
+
+    def normalize_integer_set(value)
+      arr = case value
+            when nil
+              []
+            when Array
+              value
+            else
+              [value]
+            end
+
+      arr.each_with_object(Set.new) do |item, set|
+        begin
+          set << Integer(item)
+        rescue ArgumentError, TypeError
+          nil
+        end
+      end
+    end
+
+    def normalize_pattern(value)
+      case value
+      when nil
+        nil
+      when Regexp
+        value
+      when String
+        return nil if value.empty?
+
+        Regexp.new(Regexp.escape(value))
+      else
+        nil
+      end
+    end
+
+    def normalize_payload_map(raw_map)
+      raw_map.each_with_object({}) do |(event_name, pattern), out|
+        key = event_name.to_s.strip
+        next if key.empty?
+
+        normalized = normalize_pattern(pattern)
+        next unless normalized
+
+        out[key] = normalized
+      end
+    end
+  end
+end