vivarium 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8bbb6affa1c85f3c5af82f751021cc6d0230741545bcb090a3441ae6285ddae
-  data.tar.gz: 0a51c1fd7065cf030363679f8f1c2370937365b0d22115326948cabb6053ded4
+  metadata.gz: 150b5b98d7555e1954b0002ca2224b1e445b799fa5d163ab4bbcbc8cac42ea74
+  data.tar.gz: 5984b875d3fab3600c86f9e1d961a0c1ab84945f1c1ea76e78e72248ec2fd9f7
 SHA512:
-  metadata.gz: 4efc19c34686b652e07213be2c6d865fa9b02fbe0a207b1f9e391cfd8591269f8dafbe6ad7c444091541bd1cb10e2c8a6ae07564caa5fe5deb2ed38226b3a38c
-  data.tar.gz: e0f15247ae4ed3ff159935686affd554626eb079bda7cf1db9e5f577df93db5ab57134c87ec926cab96da8302990c7524f187bbf120559b386cc40fe8399807f
+  metadata.gz: 17847e5f3852628e8bc58f4a31fc4e934b0b06d35d7961ac811d27d34ffcb4a8f17fd9e9c7f61253b9e7d37db09ee9d06354be637f8953c4bd1827baf8d3e0e7
+  data.tar.gz: 1980ac521ccd83eadb68bbbb5b6cb6a6053f3737c2b8c7aaeded5b9ace3563b34666da472bfe133204caf5889a4e77febea2c9069900e4f040a728a6f609b75a

data/README.md

@@ -21,6 +21,7 @@ Implemented in this repository:
 - BPF LSM hooks on `inode_symlink`, `inode_link`, `inode_rename`, `path_chmod`
 - BPF tracepoint on `sys_enter_getdents64`
 - BPF tracepoint on `sys_enter_execve` (captures executable path and first few argv entries as `proc_exec`)
+- BPF tracepoint on `sched_process_fork` (tracks descendants and emits `proc_fork`)
 - BPF LSM hooks for suspicious behavior checks:
 	- `ptrace_access_check` (emits `ptrace_check`)
 	- `sb_mount` (emits `sb_mount`)
@@ -32,17 +33,18 @@ Implemented in this repository:
 - BPF LSM hook on `socket_create` (flags unusual socket creation as `odd_socket`)
 - BPF LSM hook on `socket_connect` (captures destination family/address/port as `sock_connect`)
 - BPF tracepoints on `sys_enter_sendmsg`, `sys_enter_sendto`, `sys_enter_sendmmsg` (capture UDP/53 DNS QNAME raw bytes as `dns_req`)
+- USDT probes for method span boundaries and exceptions (`span_start`, `span_stop`, `span_raise`)
+- OpenSSL `SSL_write` uprobe event (`ssl_write`)
 - Shared pinned maps on bpffs
 	- `config_root_targets` (root PID -> 0/1)
 	- `config_spawned_targets` (spawned TID -> 0/1)
-	- `event_invoked` (array length 1024 with `event_t` records)
-	- `event_write_pos` (cursor for appending into `event_invoked`)
+	- `events` (`BPF_RINGBUF_OUTPUT`, shared by system events and span events)
 - Ruby API `Vivarium.observe do ... end`
 	- Registers current PID to `config_root_targets`
 	- eBPF tracks spawned descendants into `config_spawned_targets` via `sched_process_fork`
-	- On each `:return` / `:c_return`, drains `event_invoked`
-	- Prints stack trace + events
-	- Clears event slots and cursor
+	- `TracePoint` emits span probes on allowlisted call/return and emits `span_raise` on Ruby `:raise`
+	- Correlator thread consumes ringbuf events and joins them to spans by `tid`/time window
+	- Renders a process tree once at session end
 	- Unregisters PID on block exit
 
 `event_t` currently:
@@ -51,6 +53,7 @@ Implemented in this repository:
 struct event_t {
 	u64 ktime_ns;
 	u32 pid;
+	u32 tid;
 	char event_name[16];
 	char payload[256];
 };
@@ -147,7 +150,7 @@ observer = Vivarium.top_observe
 observer.stop
 ```
 
-By default, Vivarium excludes its own internal frames from stack output. Set `VIVARIUM_FILTER_INTERNAL_FRAMES=0` to disable this filter.
+`Vivarium.observe` / `Vivarium.top_observe` produce one process-tree report at session end (block exit, `observer.stop`, or process exit).
 
 You can override pin directory via `VIVARIUM_BPF_PIN_DIR` on both sides:
 
@@ -179,17 +182,18 @@ bundle exec vivariumd --pin-dir /sys/fs/bpf/vivarium
 ## Notes
 
 - Thread/Ractor-awareness is not yet implemented.
-- `event_invoked` uses fixed 1024 slots and wraps around when full.
+- Current transport is ring buffer (`events`) pinned under bpffs.
+- Ring buffer is single-consumer by nature; v1 supports a single observer per host.
 - `payload` is 256 bytes in `event_t`; some event types intentionally use smaller structured slices inside that buffer.
 - `proc_exec` currently stores the executable path plus up to 3 argv entries in 4 fixed 64-byte slots to keep the BPF verifier happy.
+- `span_raise` is emitted on Ruby `:raise` and rendered as `EXCP` lines within the enclosing span.
+- Events that do not match any real span are grouped into synthetic `<no-span>` spans.
 - Each event is tagged with severity metadata: `high` for `setid_change`, `capable_check`, `bprm_creds`, `task_kill`, `ptrace_check`, `sb_mount`, and `kernel_read_file`; others are `medium` by default.
-- In `human` format output, `high` severity events are rendered in red.
 - `capable_check` is intentionally filtered to high-risk capabilities to reduce noise from extremely frequent `capable` hook calls.
-- Current output format is textual and intended for iteration.
+- Output format is textual process tree with a session header and per-span relative timing.
 - `vivariumd` resolves `struct file::f_path` offset from `/sys/kernel/btf/vmlinux` at startup.
 - `vivariumd` also resolves `struct dentry::d_name` offset from `/sys/kernel/btf/vmlinux` at startup.
 - You can override offsets manually with `VIVARIUM_FILE_F_PATH_OFFSET` and `VIVARIUM_DENTRY_D_NAME_OFFSET` if auto-detection fails.
-- `vivariumd` also prints `bpf_trace_printk` lines (`vivarium: pid=... path=...`) to its own logs.
 
 ## Contributing
 

data/examples/execve_demo.rb

@@ -9,6 +9,9 @@ require "vivarium"
 #   2) Run this script: bundle exec ruby examples/execve_demo.rb
 
 TMP_PREFIX = "vivarium-exec-demo"
+FILTER = {
+  include_events: %w[proc_exec]
+}.freeze
 
 def try_step(title)
   puts "[exec-demo] #{title}"
@@ -20,7 +23,7 @@ end
 Dir.mktmpdir(TMP_PREFIX, "/tmp") do |dir|
   output_path = File.join(dir, "execve-demo.out")
 
-  Vivarium.observe do
+  Vivarium.observe(filter: FILTER) do
     try_step("system echo with multiple args") do
       system("/bin/echo", "hello", "from", "vivarium", out: File::NULL)
     end

data/examples/file_operation_demo.rb

@@ -10,6 +10,9 @@ require "vivarium"
 #   2) Run this script: bundle exec ruby examples/file_operation_demo.rb
 
 TMP_PREFIX = "vivarium-file-demo"
+FILTER = {
+  include_events: %w[path_open file_symlink file_hardlink file_rename file_chmod file_getdents]
+}.freeze
 
 def try_step(title)
   puts "[file-demo] #{title}"
@@ -24,7 +27,7 @@ Dir.mktmpdir(TMP_PREFIX, "/tmp") do |dir|
   hardlink_path = File.join(dir, "hardlink.txt")
   symlink_path = File.join(dir, "symlink.txt")
 
-  Vivarium.observe do
+  Vivarium.observe(filter: FILTER) do
     try_step("create source file") do
       File.write(source_path, "vivarium sample\n")
       File.read(source_path)

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

@@ -3,6 +3,10 @@
 
 require "vivarium"
 
+FILTER = {
+  include_events: %w[span_raise]
+}.freeze
+
 def try_step(title)
   puts "[priv-demo] #{title}"
   yield
@@ -10,7 +14,7 @@ rescue StandardError => e
   puts "[priv-demo] #{title} failed: #{e.class}: #{e.message}"
 end
 
-Vivarium.observe do
+Vivarium.observe(filter: FILTER) do
   try_step("raise in main") do
     raise "error in main"
   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/lib/vivarium/correlator.rb

@@ -22,11 +22,12 @@ module Vivarium
 
     POLL_TIMEOUT_MS = 200
 
-    def initialize(pin_dir:, observer_pid:, main_tid:, method_id_queue:, dest: $stdout)
+    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 = []
@@ -79,6 +80,7 @@ module Vivarium
         session_start_ktime: @session_start_ktime,
         session_stop_iso: @session_stop_iso,
         session_stop_ktime: @session_stop_ktime,
+        filter: @filter,
         dest: @dest
       ).render
     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

data/lib/vivarium/http_decoder.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+begin
+  require "http/2"
+rescue LoadError
+  # http/2 gem is optional; without it we can still parse frame headers but not HPACK-decompress HEADERS.
+end
+
+module Vivarium
+  # Decodes payloads captured from OpenSSL `SSL_write` into a human-readable
+  # one-liner. Auto-detects HTTP/1.x request/response lines and HTTP/2 binary
+  # frames; HPACK-decompresses HEADERS / CONTINUATION when the `http-2` gem
+  # is available, otherwise reports frame types only.
+  #
+  # HPACK decompressor state is kept per pid. This is sufficient for the
+  # common "one HTTPS connection per process" case; with multiple concurrent
+  # TLS connections per pid the HPACK table can diverge and decoding may
+  # fail — in that case the decompressor for that pid is reset on the next
+  # decode error.
+  class HttpDecoder
+    HTTP1_METHODS = %w[GET POST PUT PATCH DELETE HEAD OPTIONS TRACE CONNECT].freeze
+    HTTP2_PREFACE = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n".b
+    H2_FRAME_HEADER_SIZE = 9
+    H2_FLAG_END_HEADERS = 0x04
+    H2_FLAG_PADDED = 0x08
+    H2_FLAG_PRIORITY = 0x20
+    FRAME_TYPE_NAMES = {
+      0x0 => "DATA",
+      0x1 => "HEADERS",
+      0x2 => "PRIORITY",
+      0x3 => "RST_STREAM",
+      0x4 => "SETTINGS",
+      0x5 => "PUSH_PROMISE",
+      0x6 => "PING",
+      0x7 => "GOAWAY",
+      0x8 => "WINDOW_UPDATE",
+      0x9 => "CONTINUATION"
+    }.freeze
+
+    def initialize
+      @hpack_available = load_http2_gem
+      @decompressors = {}
+      @continuation = {}
+    end
+
+    def hpack_available?
+      @hpack_available
+    end
+
+    def render(pid:, data:, data_len:)
+      data = data.to_s.b
+      data_len = data_len.to_i
+
+      return "data_len=0" if data_len <= 0
+      return "len=#{data_len} <no-capture>" if data.empty?
+
+      if (summary = http1_summary(data))
+        kind, line = summary
+        return "http/1.x #{kind}: #{line}#{truncation_note(data, data_len)}"
+      end
+
+      rest = data
+      preface_note = ""
+      if rest.start_with?(HTTP2_PREFACE)
+        preface_note = "preface "
+        rest = rest.byteslice(HTTP2_PREFACE.bytesize..) || "".b
+      end
+
+      frames = parse_h2_frames(rest)
+      if frames.empty?
+        if !preface_note.empty?
+          return "h2 preface only#{truncation_note(data, data_len)}"
+        end
+        return "binary len=#{data_len}#{truncation_note(data, data_len)}"
+      end
+
+      rendered = frames.map { |f| render_h2_frame(pid, f) }.join(" | ")
+      "h2 #{preface_note}#{rendered}#{truncation_note(data, data_len)}"
+    end
+
+    private
+
+    def truncation_note(data, data_len)
+      return "" if data.bytesize >= data_len
+
+      " (captured #{data.bytesize}/#{data_len}B)"
+    end
+
+    def load_http2_gem
+      require "http/2"
+      true
+    rescue LoadError
+      false
+    end
+
+    def http1_summary(data)
+      head = data.byteslice(0, 512).to_s
+      first_line = head.split("\r\n", 2).first
+      return nil if first_line.nil? || first_line.empty?
+
+      first_line = first_line.dup.force_encoding(Encoding::UTF_8)
+      return nil unless first_line.valid_encoding?
+
+      if HTTP1_METHODS.any? { |m| first_line.start_with?("#{m} ") }
+        return ["request", first_line]
+      end
+
+      if first_line.start_with?("HTTP/1.1 ") || first_line.start_with?("HTTP/1.0 ")
+        return ["response", first_line]
+      end
+
+      nil
+    end
+
+    # @return [Array<Array(Integer, Integer, Integer, String, Boolean)>]
+    #   each entry: [frame_type, flags, stream_id, frame_payload, truncated?]
+    def parse_h2_frames(payload)
+      frames = []
+      i = 0
+      total = payload.bytesize
+
+      while i + H2_FRAME_HEADER_SIZE <= total
+        length = (payload.getbyte(i) << 16) |
+                 (payload.getbyte(i + 1) << 8) |
+                 payload.getbyte(i + 2)
+        frame_type = payload.getbyte(i + 3)
+        flags = payload.getbyte(i + 4)
+        stream_id = payload.byteslice(i + 5, 4).unpack1("N") & 0x7fff_ffff
+        i += H2_FRAME_HEADER_SIZE
+
+        if i + length > total
+          remaining = payload.byteslice(i, total - i) || "".b
+          frames << [frame_type, flags, stream_id, remaining, true]
+          break
+        end
+
+        frame_payload = payload.byteslice(i, length) || "".b
+        i += length
+        frames << [frame_type, flags, stream_id, frame_payload, false]
+      end
+
+      # Heuristic: if the very first "frame" doesn't look like a valid HTTP/2
+      # frame, refuse the whole parse so we fall back to "binary".
+      first_type = frames.first && frames.first[0]
+      return [] if first_type && !FRAME_TYPE_NAMES.key?(first_type)
+
+      frames
+    end
+
+    def render_h2_frame(pid, frame)
+      frame_type, flags, stream_id, frame_payload, truncated = frame
+      frame_name = FRAME_TYPE_NAMES.fetch(frame_type, "TYPE0x#{format('%02x', frame_type)}")
+      header = "#{frame_name} stream=#{stream_id} flags=0x#{format('%02x', flags)} len=#{frame_payload.bytesize}#{truncated ? '*' : ''}"
+
+      case frame_type
+      when 0x1 # HEADERS
+        fragment = headers_fragment(flags, frame_payload)
+        return "#{header} <bad_payload>" if fragment.nil?
+
+        if (flags & H2_FLAG_END_HEADERS) != 0
+          pseudo = decode_hpack(pid, fragment)
+          "#{header}#{format_pseudo(pseudo)}"
+        else
+          @continuation[[pid, stream_id]] = fragment.dup
+          "#{header} <collecting>"
+        end
+      when 0x9 # CONTINUATION
+        key = [pid, stream_id]
+        unless @continuation.key?(key)
+          return "#{header} <orphan>"
+        end
+
+        @continuation[key] << frame_payload
+        if (flags & H2_FLAG_END_HEADERS) == 0
+          "#{header} <collecting>"
+        else
+          buf = @continuation.delete(key)
+          pseudo = decode_hpack(pid, buf)
+          "#{header}#{format_pseudo(pseudo)}"
+        end
+      else
+        header
+      end
+    end
+
+    def headers_fragment(flags, frame_payload)
+      start_idx = 0
+      end_idx = frame_payload.bytesize
+
+      if (flags & H2_FLAG_PADDED) != 0
+        return nil if end_idx.zero?
+
+        pad_len = frame_payload.getbyte(0)
+        start_idx += 1
+        end_idx = [start_idx, end_idx - pad_len].max
+      end
+
+      if (flags & H2_FLAG_PRIORITY) != 0
+        return nil if start_idx + 5 > end_idx
+
+        start_idx += 5
+      end
+
+      frame_payload.byteslice(start_idx, end_idx - start_idx) || "".b
+    end
+
+    def decompressor_for(pid)
+      return nil unless @hpack_available
+
+      @decompressors[pid] ||= HTTP2::Header::Decompressor.new
+    end
+
+    def decode_hpack(pid, header_block)
+      dec = decompressor_for(pid)
+      return { ":error" => "hpack-unavailable" } unless dec
+
+      pairs = dec.decode(header_block.b)
+      pairs.each_with_object({}) { |(k, v), h| h[k] = v }
+    rescue StandardError => e
+      @decompressors.delete(pid)
+      { ":error" => "#{e.class}: #{e.message}" }
+    end
+
+    def format_pseudo(pseudo)
+      return " <error: #{pseudo[':error']}>" if pseudo.key?(":error")
+
+      parts = []
+      parts << ":method=#{pseudo[':method']}" if pseudo[':method']
+      parts << ":path=#{pseudo[':path']}" if pseudo[':path']
+      parts << ":authority=#{pseudo[':authority']}" if pseudo[':authority']
+      parts << ":status=#{pseudo[':status']}" if pseudo[':status']
+      return "" if parts.empty?
+
+      " #{parts.join(' ')}"
+    end
+  end
+end

data/lib/vivarium/tree_renderer.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 require "set"
+require_relative "http_decoder"
 
 module Vivarium
   class TreeRenderer
     SPAN_EVENT_NAMES = %w[span_start span_stop].to_set.freeze
     FORK_EVENT_NAME = "proc_fork"
     EXEC_EVENT_NAME = "proc_exec"
+    SSL_WRITE_EVENT_NAME = "ssl_write"
 
     LSM_EVENT_NAMES = %w[
       path_open sock_connect odd_socket
@@ -19,6 +21,8 @@ module Vivarium
       dns_req proc_exec file_getdents proc_fork
     ].to_set.freeze
 
+    UPROBE_EVENT_NAMES = %w[ssl_write].to_set.freeze
+
     SYNTHETIC_SPAN_NAME = "<no-span>"
     UNRESOLVED_METHOD_PREFIX = "<method_id="
 
@@ -49,7 +53,7 @@ module Vivarium
 
     def initialize(events:, method_table:, observer_pid:, main_tid:,
                    session_start_iso:, session_start_ktime:,
-                   session_stop_iso:, session_stop_ktime:, dest:)
+                   session_stop_iso:, session_stop_ktime:, filter: nil, dest:)
       @events = events
       @method_table = method_table
       @observer_pid = observer_pid
@@ -58,6 +62,7 @@ module Vivarium
       @session_start_ktime = session_start_ktime
       @session_stop_iso = session_stop_iso
       @session_stop_ktime = session_stop_ktime
+      @display_filter = Vivarium::DisplayFilter.compile(filter)
       @dest = dest
 
       @pid_comm = { observer_pid => "ruby" }
@@ -265,6 +270,7 @@ module Vivarium
       @dest.puts "[PROC pid=#{@observer_pid} comm=#{@pid_comm[@observer_pid] || 'ruby'}]"
       children = spans.reject { |s| s.synthetic && s.events.empty? }
                       .reject { |s| @child_span_set.include?(s) }
+                      .select { |s| span_visible?(s) }
       children.each_with_index do |span, idx|
         print_span(span, prefix: "", is_last: idx == children.size - 1)
       end
@@ -320,6 +326,14 @@ module Vivarium
       root_children = []
 
       span.events.each do |ev|
+        target_text = nil
+        if @display_filter.needs_payload?
+          target_text = render_target(ev)
+          next unless event_visible?(ev, span, target_text)
+        else
+          next unless event_visible?(ev, span)
+        end
+
         if ev.event_name == FORK_EVENT_NAME
           child_pid = read_proc_fork_child_pid(ev.payload)
           child_node = ProcNode.new(
@@ -333,7 +347,7 @@ module Vivarium
           ev_node = EventNode.new(
             kind: kind_for(ev),
             name: ev.event_name,
-            target: render_target(ev),
+            target: target_text || render_target(ev),
             offset_ns: ev.ktime_ns - span.start_ktime,
             child_proc: child_node
           )
@@ -344,7 +358,7 @@ module Vivarium
           ev_node = EventNode.new(
             kind: kind_for(ev),
             name: ev.event_name,
-            target: render_target(ev),
+            target: target_text || render_target(ev),
             offset_ns: ev.ktime_ns - span.start_ktime,
             child_proc: nil
           )
@@ -416,8 +430,12 @@ module Vivarium
     end
 
     def print_nodes(nodes, prefix)
-      nodes.each_with_index do |node, idx|
-        is_last = idx == nodes.size - 1
+      visible_nodes = nodes.select do |node|
+        !node.is_a?(Span) || span_visible?(node)
+      end
+
+      visible_nodes.each_with_index do |node, idx|
+        is_last = idx == visible_nodes.size - 1
         case node
         when EventNode
           print_event_node(node, prefix: prefix, is_last: is_last)
@@ -429,6 +447,21 @@ module Vivarium
       end
     end
 
+    def span_visible?(span)
+      @display_filter.allow_span_name?(span_display_name(span))
+    end
+
+    def event_visible?(ev, span, target_text = nil)
+      @display_filter.allow_event?(
+        event_name: ev.event_name,
+        severity: Vivarium.event_severity(ev.event_name),
+        span_name: span_display_name(span),
+        payload: target_text,
+        pid: ev.pid,
+        tid: ev.tid
+      )
+    end
+
     def print_event_node(node, prefix:, is_last:)
       marker = is_last && node.child_proc.nil? ? "└─ " : "├─ "
       marker = "└─ " if is_last && node.child_proc.nil?
@@ -457,6 +490,7 @@ module Vivarium
     def kind_for(ev)
       return "EXCP" if ev.event_name == "span_raise"
       return "USDT" if SPAN_EVENT_NAMES.include?(ev.event_name)
+      return "SSL" if ev.event_name == SSL_WRITE_EVENT_NAME
       return "LSM" if LSM_EVENT_NAMES.include?(ev.event_name)
       return "TP" if TP_EVENT_NAMES.include?(ev.event_name)
 
@@ -465,12 +499,28 @@ module Vivarium
 
     def render_target(ev)
       return render_raise_target(ev) if ev.event_name == "span_raise"
+      return render_ssl_write_target(ev) if ev.event_name == SSL_WRITE_EVENT_NAME
 
       text = Vivarium.render_event_payload(ev).to_s
       text = text.gsub(/\s+/, " ").strip
       text.empty? ? "-" : text
     end
 
+    def render_ssl_write_target(ev)
+      decoded = Vivarium.decode_ssl_write_payload(ev.payload)
+      http_decoder.render(
+        pid: ev.pid,
+        data: decoded[:data],
+        data_len: decoded[:data_len]
+      )
+    rescue StandardError => e
+      "ssl_write <decode-error: #{e.class}: #{e.message}>"
+    end
+
+    def http_decoder
+      @http_decoder ||= Vivarium::HttpDecoder.new
+    end
+
     def render_raise_target(ev)
       bytes = ev.payload.to_s.b
       return "-" if bytes.bytesize < 8

data/lib/vivarium/version.rb

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

data/lib/vivarium.rb

@@ -2,6 +2,7 @@
 
 require "fiddle"
 require "fileutils"
+require "net/http"
 require "optparse"
 require "pathname"
 require "rbbcc"
@@ -30,6 +31,27 @@ module Vivarium
   EVENT_NAME_OFFSET = 16
   EVENT_PAYLOAD_OFFSET = 32
   EVENTS_RINGBUF_PAGES = 256
+
+  SSL_WRITE_PAYLOAD_DATA_LEN_OFFSET = 0
+  SSL_WRITE_PAYLOAD_CAP_LEN_OFFSET = 4
+  SSL_WRITE_PAYLOAD_DATA_OFFSET = 8
+  SSL_WRITE_PAYLOAD_DATA_MAX = EVENT_PAYLOAD_SIZE - SSL_WRITE_PAYLOAD_DATA_OFFSET
+
+  LIBSSL_SEARCH_PATHS = [
+    "/lib/x86_64-linux-gnu/libssl.so.3",
+    "/lib/x86_64-linux-gnu/libssl.so.1.1",
+    "/lib/aarch64-linux-gnu/libssl.so.3",
+    "/lib/aarch64-linux-gnu/libssl.so.1.1",
+    "/usr/lib/x86_64-linux-gnu/libssl.so.3",
+    "/usr/lib/x86_64-linux-gnu/libssl.so.1.1",
+    "/usr/lib/aarch64-linux-gnu/libssl.so.3",
+    "/usr/lib/aarch64-linux-gnu/libssl.so.1.1",
+    "/usr/lib64/libssl.so.3",
+    "/usr/lib64/libssl.so.1.1",
+    "/usr/lib/libssl.so.3",
+    "/usr/lib/libssl.so.1.1"
+  ].freeze
+
   SPAN_ALLOWCLASSES = [
     Socket,
     BasicSocket,
@@ -43,6 +65,7 @@ module Vivarium
     Process,
     Process::UID,
     Process::GID,
+    Net::HTTP,
   ]
   SPAN_ALLOWLIST = [
     "Kernel#system",
@@ -342,6 +365,17 @@ module Vivarium
     result
   end
 
+  def self.decode_ssl_write_payload(raw_payload)
+    bytes = raw_payload.to_s.b
+    return { data_len: 0, cap_len: 0, data: "".b } if bytes.bytesize < SSL_WRITE_PAYLOAD_DATA_OFFSET
+
+    data_len = bytes[SSL_WRITE_PAYLOAD_DATA_LEN_OFFSET, 4].unpack1("L<")
+    cap_len = bytes[SSL_WRITE_PAYLOAD_CAP_LEN_OFFSET, 4].unpack1("L<")
+    cap_len = SSL_WRITE_PAYLOAD_DATA_MAX if cap_len > SSL_WRITE_PAYLOAD_DATA_MAX
+    data = bytes[SSL_WRITE_PAYLOAD_DATA_OFFSET, cap_len] || "".b
+    { data_len: data_len, cap_len: cap_len, data: data }
+  end
+
   def self.decode_span_raise_payload(raw_payload)
     bytes = raw_payload.to_s.b
     return "" if bytes.bytesize < 8
@@ -426,6 +460,9 @@ module Vivarium
     when "file_getdents"
       decoded = decode_file_getdents_payload(event.payload)
       decoded.empty? ? event.payload.inspect : decoded
+    when "ssl_write"
+      decoded = decode_ssl_write_payload(event.payload)
+      "data_len=#{decoded[:data_len]} cap_len=#{decoded[:cap_len]}"
     else
       strip_to_first_null(event.payload).inspect
     end
@@ -1339,6 +1376,42 @@ module Vivarium
         return 0;
       }
 
+      int on_ssl_write(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;
+        }
+
+        const char *buf = (const char *)PT_REGS_PARM2(ctx);
+        int num = (int)PT_REGS_PARM3(ctx);
+        if (!buf || num <= 0) {
+          return 0;
+        }
+
+        struct event_t ev = {};
+        ev.pid = pid;
+        __builtin_memcpy(ev.event_name, "ssl_write", 10);
+
+        u32 data_len = (u32)num;
+        u32 cap = data_len;
+        if (cap > #{SSL_WRITE_PAYLOAD_DATA_MAX}) {
+          cap = #{SSL_WRITE_PAYLOAD_DATA_MAX};
+        }
+        __builtin_memcpy(&ev.payload[#{SSL_WRITE_PAYLOAD_DATA_LEN_OFFSET}], &data_len, sizeof(data_len));
+        __builtin_memcpy(&ev.payload[#{SSL_WRITE_PAYLOAD_CAP_LEN_OFFSET}], &cap, sizeof(cap));
+        if (bpf_probe_read_user(&ev.payload[#{SSL_WRITE_PAYLOAD_DATA_OFFSET}], cap, buf) < 0) {
+          u32 zero = 0;
+          __builtin_memcpy(&ev.payload[#{SSL_WRITE_PAYLOAD_CAP_LEN_OFFSET}], &zero, sizeof(zero));
+        }
+
+        submit_event(&ev);
+        return 0;
+      }
+
       int on_span_raise(struct pt_regs *ctx)
       {
         u64 pid_tgid = bpf_get_current_pid_tgid();
@@ -1370,8 +1443,10 @@ module Vivarium
       }
     CLANG
 
-    def initialize(pin_dir: Vivarium.bpf_pin_dir)
+    def initialize(pin_dir: Vivarium.bpf_pin_dir, ssl_trace: true, libssl_path: nil)
       @pin_dir = pin_dir
+      @ssl_trace = ssl_trace
+      @libssl_path = libssl_path
     end
 
     def run
@@ -1392,6 +1467,8 @@ module Vivarium
 
       bpf = RbBCC::BCC.new(text: program, usdt_contexts: [usdt])
 
+      attach_ssl_write_uprobe(bpf) if @ssl_trace
+
       config_root_targets = bpf["config_root_targets"]
       config_spawned_targets = bpf["config_spawned_targets"]
       events_ringbuf = bpf["events"]
@@ -1416,6 +1493,39 @@ module Vivarium
 
     private
 
+    def attach_ssl_write_uprobe(bpf)
+      path = resolve_libssl_path
+      unless path
+        warn "[vivariumd] libssl not found; SSL_write uprobe disabled " \
+             "(set --libssl PATH or VIVARIUM_LIBSSL_PATH to override)"
+        return
+      end
+
+      bpf.attach_uprobe(name: path, sym: "SSL_write", fn_name: "on_ssl_write")
+      puts "[vivariumd] SSL_write uprobe attached via #{path}"
+    rescue StandardError => e
+      warn "[vivariumd] SSL_write uprobe attach failed: #{e.class}: #{e.message}"
+    end
+
+    def resolve_libssl_path
+      if @libssl_path
+        return @libssl_path if File.exist?(@libssl_path)
+
+        warn "[vivariumd] --libssl path does not exist: #{@libssl_path}"
+        return nil
+      end
+
+      env_path = ENV["VIVARIUM_LIBSSL_PATH"]
+      if env_path && !env_path.empty?
+        return env_path if File.exist?(env_path)
+
+        warn "[vivariumd] VIVARIUM_LIBSSL_PATH does not exist: #{env_path}"
+        return nil
+      end
+
+      LIBSSL_SEARCH_PATHS.find { |p| File.exist?(p) }
+    end
+
     def ensure_root!
       return if Process.uid.zero?
 
@@ -1557,13 +1667,13 @@ module Vivarium
     end
   end
 
-  def self.observe(pin_dir: bpf_pin_dir, dest: $stdout, &block)
-    return scoped_observe(pin_dir: pin_dir, dest: dest, &block) if block_given?
+  def self.observe(pin_dir: bpf_pin_dir, dest: $stdout, filter: nil, &block)
+    return scoped_observe(pin_dir: pin_dir, dest: dest, filter: filter, &block) if block_given?
 
-    top_observe(pin_dir: pin_dir, dest: dest)
+    top_observe(pin_dir: pin_dir, dest: dest, filter: filter)
   end
 
-  def self.top_observe(pin_dir: bpf_pin_dir, dest: $stdout)
+  def self.top_observe(pin_dir: bpf_pin_dir, dest: $stdout, filter: nil)
     require "vivarium_usdt"
 
     store = MapStore.new(pin_dir: pin_dir)
@@ -1578,6 +1688,7 @@ module Vivarium
       observer_pid: pid,
       main_tid: main_tid,
       method_id_queue: method_id_queue,
+      filter: filter,
       dest: dest
     )
     correlator.start
@@ -1592,7 +1703,7 @@ module Vivarium
     session
   end
 
-  def self.scoped_observe(pin_dir:, dest:)
+  def self.scoped_observe(pin_dir:, dest:, filter: nil)
     require "vivarium_usdt"
 
     store = MapStore.new(pin_dir: pin_dir)
@@ -1607,6 +1718,7 @@ module Vivarium
       observer_pid: pid,
       main_tid: main_tid,
       method_id_queue: method_id_queue,
+      filter: filter,
       dest: dest
     )
     correlator.start
@@ -1626,6 +1738,11 @@ module Vivarium
     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
+
         Vivarium::Usdt.raise(
           tp.raised_exception.class.to_s,
           tp.raised_exception.message.to_s,
@@ -1677,15 +1794,26 @@ module Vivarium
   end
 
   def self.run_daemon!(argv = ARGV)
-    options = { pin_dir: bpf_pin_dir }
+    options = { pin_dir: bpf_pin_dir, ssl_trace: true, libssl_path: nil }
     OptionParser.new do |opts|
-      opts.banner = "Usage: vivariumd [--pin-dir PATH]"
+      opts.banner = "Usage: vivariumd [--pin-dir PATH] [--no-ssl-trace] [--libssl 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
+      end
+      opts.on("--libssl PATH", "Path to libssl.so to attach SSL_write to") do |v|
+        options[:libssl_path] = v
+      end
     end.parse!(argv)
 
-    Daemon.new(pin_dir: options[:pin_dir]).run
+    Daemon.new(
+      pin_dir: options[:pin_dir],
+      ssl_trace: options[:ssl_trace],
+      libssl_path: options[:libssl_path]
+    ).run
   end
 end
 
 require_relative "vivarium/correlator"
+require_relative "vivarium/display_filter"
 require_relative "vivarium/tree_renderer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vivarium
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Uchio Kondo
@@ -70,6 +70,7 @@ files:
 - examples/privilege_event_demo.rb
 - examples/raise_demo.rb
 - examples/signal_kill_demo.rb
+- examples/ssl_write_demo.rb
 - examples/sudo_attempt_demo.rb
 - exe/vivarium
 - exe/vivariumd
@@ -77,6 +78,8 @@ files:
 - lib/vivarium.rb
 - lib/vivarium/cli.rb
 - lib/vivarium/correlator.rb
+- lib/vivarium/display_filter.rb
+- lib/vivarium/http_decoder.rb
 - lib/vivarium/tree_renderer.rb
 - lib/vivarium/version.rb
 - logo-simple.png