vivarium 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 332c9bfd2267f44bac72dea2cf344bd5c515613333f18a479f830d72c0133749
-  data.tar.gz: af42fd7731c9c211fd34b120125793214d485c0567310e4b3d70866eaafcbf3f
+  metadata.gz: 00bd1e28a68f907293bb6bd0d23ceb26443fe603e653a18a8a88a4a36575b540
+  data.tar.gz: 440caf222aa2003056ff827b8da3a211da1ea3fc25aae1c237b433d040331abb
 SHA512:
-  metadata.gz: f3543e2ee6a9b03a9916fb501957779b543782b8e247d66f084dddbd1372bfcc4de91082d7c875b25d7ff12fc9ad905c8675387df8eb049e40b2e57db121ff18
-  data.tar.gz: 604698d87ca591abdab4ead63bfd0053c43c9e5caaf86524eca626561a5e4e8bc47f267546ad4ac6882dd1f5f6692acf77eabf1e545aae0bba73b73daebf7033
+  metadata.gz: 7120d43057fa8f532c6fcffd512d33b5392bd7fe7cf174811afd3fc737c515230b6e82cad2ea26b776b129817a350467f4b5beb007dcf009c58c2b6cf656227c
+  data.tar.gz: 2502ea29816994a2a8dfa05c65c9302da57f74b29790692111e23c5afdd093ba7e2c992b84ab218234cd3e9701df08ea885549023264c6a92868fc882a72c18f

data/examples/dlopen_demo_otel.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fiddle"
+require "vivarium"
+
+FILTER = {
+  include_events: %w[dlopen mmap_exec]
+}.freeze
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+# 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_otel.rb
+#      or: VIVARIUM_OTEL_ENDPOINT=http://collector:4318/v1/traces bundle exec ruby examples/dlopen_demo_otel.rb
+#
+# 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, otel_endpoint: OTEL_ENDPOINT) do
+  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
+
+  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
+
+  Bundler.with_unbundled_env do
+    system("ruby -e 'require \"fiddle\"; Fiddle.dlopen(\"libm.so.6\").close'")
+  end
+end
+
+puts "[dlopen_demo] done"

data/examples/env_access_external_demo_otel.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rbconfig"
+require "vivarium"
+
+FILTER = {
+  include_events: %w[env_caccess proc_fork proc_exec]
+}.freeze
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/env_access_external_demo_otel.rb
+#      or: VIVARIUM_OTEL_ENDPOINT=http://collector:4318/v1/traces bundle exec ruby examples/env_access_external_demo_otel.rb
+#
+# This demo launches an external Ruby process and forces direct libc calls to
+# getenv/setenv/unsetenv/putenv/clearenv through Fiddle.
+
+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, otel_endpoint: OTEL_ENDPOINT) 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_otel.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vivarium"
+
+FILTER = {
+  include_events: %w[span_start span_stop env_caccess]
+}.freeze
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/env_access_ruby_demo_otel.rb
+#      or: VIVARIUM_OTEL_ENDPOINT=http://collector:4318/v1/traces bundle exec ruby examples/env_access_ruby_demo_otel.rb
+
+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, otel_endpoint: OTEL_ENDPOINT) 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/examples/execve_demo_otel.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "tmpdir"
+require "vivarium"
+
+TMP_PREFIX = "vivarium-exec-demo"
+FILTER = {
+  include_events: %w[proc_exec]
+}.freeze
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/execve_demo_otel.rb
+#      or: VIVARIUM_OTEL_ENDPOINT=http://collector:4318/v1/traces bundle exec ruby examples/execve_demo_otel.rb
+
+def try_step(title)
+  puts "[exec-demo] #{title}"
+  yield
+rescue StandardError => e
+  puts "[exec-demo] #{title} failed: #{e.class}: #{e.message}"
+end
+
+Dir.mktmpdir(TMP_PREFIX, "/tmp") do |dir|
+  output_path = File.join(dir, "execve-demo.out")
+
+  Vivarium.observe(filter: FILTER, otel_endpoint: OTEL_ENDPOINT) do
+    try_step("system echo with multiple args") do
+      system("/bin/echo", "hello", "from", "vivarium", out: File::NULL)
+    end
+
+    try_step("spawn env with explicit argv") do
+      pid = Process.spawn(
+        "/usr/bin/env",
+        "env",
+        "printf",
+        "execve-demo\n",
+        out: output_path,
+        err: File::NULL
+      )
+      Process.wait(pid)
+    end
+
+    try_step("spawn sleep with flag") do
+      pid = Process.spawn("/bin/sleep", "0")
+      Process.wait(pid)
+    end
+  end
+
+  puts "[exec-demo] output file: #{output_path}" if File.exist?(output_path)
+end
+
+puts "[exec-demo] done"

data/examples/file_operation_demo_otel.rb

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+require "vivarium"
+
+TMP_PREFIX = "vivarium-file-demo"
+FILTER = {
+  include_events: %w[path_open file_symlink file_hardlink file_rename file_chmod file_unlink file_getdents]
+}.freeze
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/file_operation_demo_otel.rb
+#      or: VIVARIUM_OTEL_ENDPOINT=http://collector:4318/v1/traces bundle exec ruby examples/file_operation_demo_otel.rb
+
+def try_step(title)
+  puts "[file-demo] #{title}"
+  yield
+rescue StandardError => e
+  puts "[file-demo] #{title} failed: #{e.class}: #{e.message}"
+end
+
+Dir.mktmpdir(TMP_PREFIX, "/tmp") do |dir|
+  source_path = File.join(dir, "source.txt")
+  renamed_path = File.join(dir, "renamed.txt")
+  hardlink_path = File.join(dir, "hardlink.txt")
+  symlink_path = File.join(dir, "symlink.txt")
+
+  Vivarium.observe(filter: FILTER, otel_endpoint: OTEL_ENDPOINT) do
+    try_step("create source file") do
+      File.write(source_path, "vivarium sample\n")
+      File.read(source_path)
+    end
+
+    try_step("directory listing") do
+      Dir.children(dir)
+    end
+
+    try_step("rename file") do
+      File.rename(source_path, renamed_path)
+      File.read(renamed_path)
+    end
+
+    try_step("create hardlink") do
+      File.link(renamed_path, hardlink_path)
+      File.read(hardlink_path)
+    end
+
+    try_step("create symlink") do
+      File.symlink(renamed_path, symlink_path)
+      File.read(symlink_path)
+    end
+
+    try_step("chmod file") do
+      File.chmod(0o640, renamed_path)
+      File.stat(renamed_path)
+    end
+
+    try_step("unlink hardlink") do
+      File.unlink(hardlink_path)
+    end
+
+    try_step("unlink symlink") do
+      File.unlink(symlink_path)
+    end
+
+    try_step("list directory again") do
+      Dir.children(dir)
+    end
+  end
+
+  FileUtils.rm_f(symlink_path)
+  FileUtils.rm_f(hardlink_path)
+  FileUtils.rm_f(renamed_path)
+  FileUtils.rm_f(source_path)
+end
+
+puts "[file-demo] done"

data/examples/network_client_demo_otel.rb

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "socket"
+require "vivarium"
+
+FILTER = {
+  include_events: %w[sock_connect dns_req odd_socket]
+}.freeze
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/network_client_demo_otel.rb
+#      or: VIVARIUM_OTEL_ENDPOINT=http://collector:4318/v1/traces bundle exec ruby examples/network_client_demo_otel.rb
+
+def try_step(title)
+  puts "[client] #{title}"
+  yield
+rescue StandardError => e
+  puts "[client] #{title} failed: #{e.class}: #{e.message}"
+end
+
+Vivarium.observe(filter: FILTER, otel_endpoint: OTEL_ENDPOINT) 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")
+    system("getent hosts unknown.example.com >/dev/null 2>&1 || true")
+  end
+
+  # Likely emits sock_connect through HTTPS connection attempts.
+  try_step("system: curl") do
+    system("curl -I https://example.com >/dev/null 2>&1 || true")
+  end
+
+  # ICMP example (may require CAP_NET_RAW / root depending on environment).
+  try_step("system: ping") do
+    system("ping -c 1 example.com >/dev/null 2>&1 || true")
+  end
+
+  # Explicit connect path.
+  try_step("Ruby TCP connect") do
+    sock = TCPSocket.new("example.com", 80)
+    sock.close
+  end
+
+  # Raw DNS query payload, useful for dns_req decode testing.
+  try_step("Ruby UDP DNS query") do
+    dns_query = "\x12\x34\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00" +
+                "\x09udp-query\x07example\x03com\x00" +
+                "\x00\x01\x00\x01"
+
+    udp = UDPSocket.new
+    begin
+      udp.connect("127.0.0.53", 53)
+    rescue StandardError
+      udp.connect("8.8.8.8", 53)
+    end
+    udp.send(dns_query, 0)
+    udp.close
+  end
+
+  # Explicit sendto path for DNS payload visibility.
+  try_step("Ruby UDP sendto DNS query") do
+    dns_query = "\x12\x34\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00" +
+                "\x06sendto\x07example\x03com\x00" +
+                "\x00\x01\x00\x01"
+
+    udp = UDPSocket.new
+    udp.send(dns_query, 0, "127.0.0.53", 53)
+    udp.close
+  end
+
+  # Intentionally unusual socket type to trigger odd_socket.
+  try_step("Ruby odd socket attempt") do
+    af_packet = Socket.const_defined?(:AF_PACKET) ? Socket::AF_PACKET : 17
+    raw = Socket.new(af_packet, Socket::SOCK_RAW, 0)
+    raw.close
+  end
+end
+
+puts "[client] done"

data/examples/network_client_demo_otel_out.rb

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "socket"
+require "vivarium"
+
+FILTER = {
+  include_events: %w[sock_connect dns_req odd_socket]
+}.freeze
+
+OTEL_OUT = ENV.fetch("VIVARIUM_OTEL_OUT", "network_client_demo_otel.json")
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/network_client_demo_otel_out.rb
+#      or: VIVARIUM_OTEL_OUT=/tmp/network_client_demo_otel.json bundle exec ruby examples/network_client_demo_otel_out.rb
+
+def try_step(title)
+  puts "[client] #{title}"
+  yield
+rescue StandardError => e
+  puts "[client] #{title} failed: #{e.class}: #{e.message}"
+end
+
+Vivarium.observe(filter: FILTER, otel_out: OTEL_OUT) 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")
+    system("getent hosts unknown.example.com >/dev/null 2>&1 || true")
+  end
+
+  # Likely emits sock_connect through HTTPS connection attempts.
+  try_step("system: curl") do
+    system("curl -I https://example.com >/dev/null 2>&1 || true")
+  end
+
+  # ICMP example (may require CAP_NET_RAW / root depending on environment).
+  try_step("system: ping") do
+    system("ping -c 1 example.com >/dev/null 2>&1 || true")
+  end
+
+  # Explicit connect path.
+  try_step("Ruby TCP connect") do
+    sock = TCPSocket.new("example.com", 80)
+    sock.close
+  end
+
+  # Raw DNS query payload, useful for dns_req decode testing.
+  try_step("Ruby UDP DNS query") do
+    dns_query = "\x12\x34\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00" +
+                "\x09udp-query\x07example\x03com\x00" +
+                "\x00\x01\x00\x01"
+
+    udp = UDPSocket.new
+    begin
+      udp.connect("127.0.0.53", 53)
+    rescue StandardError
+      udp.connect("8.8.8.8", 53)
+    end
+    udp.send(dns_query, 0)
+    udp.close
+  end
+
+  # Explicit sendto path for DNS payload visibility.
+  try_step("Ruby UDP sendto DNS query") do
+    dns_query = "\x12\x34\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00" +
+                "\x06sendto\x07example\x03com\x00" +
+                "\x00\x01\x00\x01"
+
+    udp = UDPSocket.new
+    udp.send(dns_query, 0, "127.0.0.53", 53)
+    udp.close
+  end
+
+  # Intentionally unusual socket type to trigger odd_socket.
+  try_step("Ruby odd socket attempt") do
+    af_packet = Socket.const_defined?(:AF_PACKET) ? Socket::AF_PACKET : 17
+    raw = Socket.new(af_packet, Socket::SOCK_RAW, 0)
+    raw.close
+  end
+end
+
+puts "[client] wrote OTLP JSON to #{OTEL_OUT}"
+puts "[client] done"

data/examples/privilege_event_demo_otel.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vivarium"
+
+FILTER = {
+  include_events: %w[setid_change capable_check bprm_creds]
+}.freeze
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/privilege_event_demo_otel.rb
+#      or: VIVARIUM_OTEL_ENDPOINT=http://collector:4318/v1/traces bundle exec ruby examples/privilege_event_demo_otel.rb
+
+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, otel_endpoint: OTEL_ENDPOINT) do
+  try_step("attempt setuid(0)") do
+    Process::UID.change_privilege(0)
+  end
+
+  try_step("attempt setgid(0)") do
+    Process::GID.change_privilege(0)
+  end
+
+  try_step("attempt opening /etc/shadow") do
+    File.read("/etc/shadow")
+  end
+
+  try_step("exec setuid-related binary") do
+    pid = Process.spawn("/usr/bin/sudo", "-n", "true", out: File::NULL, err: File::NULL)
+    Process.wait(pid)
+  rescue Errno::ENOENT
+    puts "[priv-demo] sudo not found; skipped"
+  end
+end
+
+puts "[priv-demo] done"

data/examples/raise_demo_otel.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vivarium"
+
+FILTER = {
+  include_events: %w[span_raise]
+}.freeze
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+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, otel_endpoint: OTEL_ENDPOINT) 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/save_raw_demo_otel.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "vivarium"
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/save_raw_demo_otel.rb
+#      or: VIVARIUM_OTEL_ENDPOINT=http://collector:4318/v1/traces bundle exec ruby examples/save_raw_demo_otel.rb
+#
+# Note: this is the OTLP streaming variant of save_raw_demo.rb, so no vivraw file is written.
+
+Vivarium.observe(otel_endpoint: OTEL_ENDPOINT) do
+  path = "/tmp/vivarium_save_raw_demo.txt"
+  File.write(path, "hello from save_raw demo\n")
+  File.chmod(0o600, path)
+  File.delete(path)
+
+  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 "[save_raw_demo] Net::HTTP failed: #{e.class}: #{e.message}"
+  end
+
+  system("true")
+end
+
+puts "[save_raw_demo] streamed OTLP events to #{OTEL_ENDPOINT}"

data/examples/signal_kill_demo_otel.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vivarium"
+
+FILTER = {
+  include_events: %w[task_kill]
+}.freeze
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/signal_kill_demo_otel.rb
+#      or: VIVARIUM_OTEL_ENDPOINT=http://collector:4318/v1/traces bundle exec ruby examples/signal_kill_demo_otel.rb
+
+def try_step(title)
+  puts "[signal-demo] #{title}"
+  yield
+rescue StandardError => e
+  puts "[signal-demo] #{title} failed: #{e.class}: #{e.message}"
+end
+
+child_pid = nil
+
+Vivarium.observe(filter: FILTER, otel_endpoint: OTEL_ENDPOINT) do
+  try_step("fork child process") do
+    child_pid = fork do
+      trap("TERM") { exit!(0) }
+      loop { sleep 1 }
+    end
+    puts "[signal-demo] child pid=#{child_pid}"
+  end
+
+  try_step("send TERM signal to child") do
+    sleep 0.1
+    Process.kill("TERM", child_pid)
+  end
+
+  try_step("wait child process") do
+    Process.wait(child_pid)
+  end
+end
+
+puts "[signal-demo] done"

data/examples/ssl_write_demo_otel.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "vivarium"
+
+FILTER = {
+  include_events: %w[ssl_write]
+}.freeze
+
+OTEL_ENDPOINT = ENV.fetch("VIVARIUM_OTEL_ENDPOINT", "http://localhost:4318/v1/traces")
+
+# 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_otel.rb
+#      or: VIVARIUM_OTEL_ENDPOINT=http://collector:4318/v1/traces bundle exec ruby examples/ssl_write_demo_otel.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, otel_endpoint: OTEL_ENDPOINT) do
+  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
+
+  system("curl -sS --http2 -o /dev/null https://nghttp2.org/ 2>/dev/null")
+end
+
+puts "[ssl_demo] done"