vivarium 0.1.2 → 0.3.0

data/examples/execve_demo.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "tmpdir"
+require "vivarium"
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/execve_demo.rb
+
+TMP_PREFIX = "vivarium-exec-demo"
+
+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 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.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+require "vivarium"
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/file_operation_demo.rb
+
+TMP_PREFIX = "vivarium-file-demo"
+
+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 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("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/privilege_event_demo.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vivarium"
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/privilege_event_demo.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 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.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vivarium"
+
+def try_step(title)
+  puts "[priv-demo] #{title}"
+  yield
+rescue StandardError => e
+  puts "[priv-demo] #{title} failed: #{e.class}: #{e.message}"
+end
+
+Vivarium.observe 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

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vivarium"
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/signal_kill_demo.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 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/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,137 @@
+# 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:, dest: $stdout)
+      @pin_dir = pin_dir
+      @observer_pid = observer_pid
+      @main_tid = main_tid
+      @method_id_queue = method_id_queue
+      @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,
+        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