vivarium 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8bbb6affa1c85f3c5af82f751021cc6d0230741545bcb090a3441ae6285ddae
-  data.tar.gz: 0a51c1fd7065cf030363679f8f1c2370937365b0d22115326948cabb6053ded4
+  metadata.gz: a0e7e80cef690342f163fde6c05fed6859c3ef81aa794fe532c87b00fbe11cd5
+  data.tar.gz: 4f2de93c9795fe93ecb0d8291f86a117ac0f595c8c12e2c7b41caabaae7c3273
 SHA512:
-  metadata.gz: 4efc19c34686b652e07213be2c6d865fa9b02fbe0a207b1f9e391cfd8591269f8dafbe6ad7c444091541bd1cb10e2c8a6ae07564caa5fe5deb2ed38226b3a38c
-  data.tar.gz: e0f15247ae4ed3ff159935686affd554626eb079bda7cf1db9e5f577df93db5ab57134c87ec926cab96da8302990c7524f187bbf120559b386cc40fe8399807f
+  metadata.gz: 9a116f2c50b978a368a05cca351411f9724686746820085b651038d060c8452a8546170cb6e6ac885ab8a721aa20bcf42c5746639d32cbfea0ba8a9452b9687e
+  data.tar.gz: fb5b4b5307682fa84b77dcfaa2165a71a5e16deef8d7b7d21d6b3267e82b5a12ce1f73dee946193605e039a247d59613a9c2dffca15ef96ddb502a17c9ce742d

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/dlopen_demo.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fiddle"
+require "vivarium"
+
+FILTER = {
+  include_events: %w[dlopen mmap_exec]
+}.freeze
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#      (dlopen uprobe is attached automatically when libc is found)
+#   2) Run this script: bundle exec ruby examples/dlopen_demo.rb
+#
+# Expected output: "DL dlopen" and "DL mmap_exec" events for each
+# library loaded via Fiddle.dlopen.
+#
+# You can disable the dlopen uprobe with `sudo vivariumd --no-dlopen-trace`
+# or point at a specific libc with `sudo vivariumd --libc /lib/x86_64-linux-gnu/libc.so.6`.
+
+Vivarium.observe(filter: FILTER) do
+  # libm: math functions — almost universally available
+  begin
+    libm = Fiddle.dlopen("libm.so.6")
+    sin_fn = Fiddle::Function.new(libm["sin"], [Fiddle::TYPE_DOUBLE], Fiddle::TYPE_DOUBLE)
+    puts "[dlopen_demo] sin(PI/4) = #{sin_fn.call(Math::PI / 4).round(6)}"
+    libm.close
+  rescue Fiddle::DLError => e
+    warn "[dlopen_demo] libm: #{e.message}"
+  end
+
+  # libsqlite3: a common library that may not be loaded at startup
+  begin
+    libsqlite3 = Fiddle.dlopen("libsqlite3.so.0")
+    puts "[dlopen_demo] libsqlite3 loaded: version = #{Fiddle::Function.new(libsqlite3["sqlite3_libversion"], [], Fiddle::TYPE_VOIDP).call}"
+    libsqlite3.close
+  rescue Fiddle::DLError => e
+    warn "[dlopen_demo] libsqlite3: #{e.message}"
+  end
+
+  # Spawn a child process that also calls dlopen — its events should
+  # appear under a PROC node in the tree (descendant PID tracking).
+  # Unbundle so Bundler does not spawn anything.
+  Bundler.with_unbundled_env do
+    system("ruby -e 'require \"fiddle\"; Fiddle.dlopen(\"libm.so.6\").close'")
+  end
+end
+
+puts "[dlopen_demo] done"

data/examples/drop_demo.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Standalone demo: shows what DROP warning nodes look like in the TreeRenderer
+# output. Does NOT require BPF or vivariumd — constructs RawEvent objects
+# directly and feeds them to TreeRenderer.
+#
+# Usage:
+#   ruby examples/drop_demo.rb
+
+$LOAD_PATH.unshift File.join(__dir__, "..", "lib")
+
+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
+
+# 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")
+
+events = [
+  Vivarium::Correlator::RawEvent.new(
+    ktime_ns: t0,
+    pid: pid, tid: tid,
+    event_name: "span_start",
+    payload: span_start_payload,
+    dropped_since_last: 0
+  ),
+  # This event carries drop info: 5 events were lost before it arrived
+  Vivarium::Correlator::RawEvent.new(
+    ktime_ns: t0 + 10_000_000,
+    pid: pid, tid: tid,
+    event_name: "path_open",
+    payload: "/etc/passwd\x00".b.ljust(Vivarium::EVENT_PAYLOAD_SIZE, "\x00"),
+    dropped_since_last: 5
+  ),
+  Vivarium::Correlator::RawEvent.new(
+    ktime_ns: t0 + 20_000_000,
+    pid: pid, tid: tid,
+    event_name: "dns_req",
+    payload: "\x06google\x03com\x00".b.ljust(Vivarium::EVENT_PAYLOAD_SIZE, "\x00"),
+    dropped_since_last: 0
+  ),
+  # Another burst: 12 events dropped just before this sock_connect
+  Vivarium::Correlator::RawEvent.new(
+    ktime_ns: t0 + 25_000_000,
+    pid: pid, tid: tid,
+    event_name: "sock_connect",
+    payload: [2, 443, 0x7f000001, 0].pack("S<nNN").ljust(Vivarium::EVENT_PAYLOAD_SIZE, "\x00"),
+    dropped_since_last: 12
+  ),
+  Vivarium::Correlator::RawEvent.new(
+    ktime_ns: t0 + 30_000_000,
+    pid: pid, tid: tid,
+    event_name: "span_stop",
+    payload: "\x00" * Vivarium::EVENT_PAYLOAD_SIZE,
+    dropped_since_last: 0
+  ),
+]
+
+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",
+  session_start_ktime: t0,
+  session_stop_iso: "2026-06-02T00:00:00.030Z",
+  session_stop_ktime: t0 + 30_000_000,
+  dest: $stdout
+).render

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

@@ -6,7 +6,7 @@ require "time"
 module Vivarium
   class Correlator
     RawEvent = Struct.new(
-      :ktime_ns, :pid, :tid, :event_name, :payload,
+      :ktime_ns, :pid, :tid, :event_name, :payload, :dropped_since_last,
       keyword_init: true
     )
 
@@ -17,16 +17,18 @@ module Vivarium
         u32 tid;
         char event_name[16];
         char payload[256];
+        u64 dropped_since_last;
       };
     C
 
     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 +81,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
@@ -102,11 +105,12 @@ module Vivarium
       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
+      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
+      dropped_since_last = bytes[Vivarium::EVENT_DROPPED_OFFSET, 8].unpack1("Q<")
 
       @events_mutex.synchronize do
         @events << RawEvent.new(
@@ -114,7 +118,8 @@ module Vivarium
           pid: pid,
           tid: tid,
           event_name: event_name,
-          payload: payload
+          payload: payload,
+          dropped_since_last: dropped_since_last
         )
       end
     rescue StandardError => e

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