vivarium 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7b939d2599fb7e7115ef398bcc83830be78d3b8576a05e5c6d7c1adec4003a1
+  data.tar.gz: 39a158bacb6b706a4b77144b47554f027822263662818a9175b1828109538406
+SHA512:
+  metadata.gz: 6b17e753a8ccaf72cb969e5fdb8b005d2e31fc2aa10f1d33984d93ba2b7c6a1e2d8e28560b39a4cb9f2860f453a498c3c9c974db9b4b316b4162b78b3e3841e6
+  data.tar.gz: 0bcd982884661f9e93ba27c3dc79cb1a952de8c68f715572022917cad708a771e4f4017af4bf12257f7f71ed38119535d14a5745d06666c580d6486c1d15b820

data/README.md

@@ -0,0 +1,114 @@
+# Vivarium
+
+Vivarium is an observation and sandbox helper for Ruby.
+
+It combines:
+
+- eBPF LSM monitoring via RbBCC (`vivariumd`)
+- Ruby-side method boundary observation via `TracePoint` (`Vivarium.observe`)
+
+The goal is to visualize which Ruby method context triggered low-level events.
+
+## Current Scope
+
+Implemented in this repository:
+
+- BPF LSM hook on `file_open`
+- Shared pinned maps on bpffs
+	- `config_targets` (PID -> 0/1)
+	- `event_invoked` (array length 64 with `event_t` records)
+	- `event_write_pos` (cursor for appending into `event_invoked`)
+- Ruby API `Vivarium.observe do ... end`
+	- Registers current PID to `config_targets`
+	- On each `:return` / `:c_return`, drains `event_invoked`
+	- Prints stack trace + events
+	- Clears event slots and cursor
+	- Unregisters PID on block exit
+
+`event_t` currently:
+
+```c
+struct event_t {
+	u32 pid;
+	char event_name[8];   // "path_open"
+	char payload[64];     // opened path (truncated)
+};
+```
+
+## Requirements
+
+- Linux kernel/environment supporting BPF LSM
+- `libbcc` installed
+- `bpftool` installed (used to resolve `struct file::f_path` offset from BTF)
+- root privileges for `vivariumd`
+- bpffs mounted (typically `/sys/fs/bpf`)
+
+## Installation
+
+Add to Gemfile:
+
+```ruby
+gem "vivarium"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Usage
+
+1) Start daemon (root):
+
+```bash
+sudo bundle exec vivariumd
+```
+
+2) Observe in Ruby process:
+
+```ruby
+require "vivarium"
+
+Vivarium.observe do
+	File.read("/etc/hosts")
+end
+```
+
+You can override pin directory via `VIVARIUM_BPF_PIN_DIR` on both sides:
+
+```bash
+VIVARIUM_BPF_PIN_DIR=/sys/fs/bpf/vivarium bundle exec vivariumd
+```
+
+```ruby
+ENV["VIVARIUM_BPF_PIN_DIR"] = "/sys/fs/bpf/vivarium"
+require "vivarium"
+```
+
+## Development
+
+Run tests:
+
+```bash
+bundle exec rake test
+```
+
+Daemon entrypoint:
+
+```bash
+bundle exec vivariumd --pin-dir /sys/fs/bpf/vivarium
+```
+
+## Notes
+
+- Thread/Ractor-awareness is not yet implemented.
+- `event_invoked` uses fixed 64 slots and wraps around when full.
+- Payload is truncated to 64 bytes in kernel space.
+- Current output format is textual and intended for iteration.
+- `vivariumd` resolves `struct file::f_path` offset from `/sys/kernel/btf/vmlinux` at startup.
+- You can override offset manually with `VIVARIUM_FILE_F_PATH_OFFSET` if auto-detection fails.
+
+## Contributing
+
+Issues and pull requests are welcome.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/exe/vivariumd

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

data/lib/vivarium/version.rb

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

data/lib/vivarium.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require "fiddle"
+require "fileutils"
+require "optparse"
+require "pathname"
+require "rbbcc"
+require_relative "vivarium/version"
+
+module Vivarium
+  class Error < StandardError; end
+
+  PIN_DIR = ENV.fetch("VIVARIUM_BPF_PIN_DIR", "/sys/fs/bpf/vivarium")
+  CONFIG_TARGETS_PIN = File.join(PIN_DIR, "config_targets")
+  EVENT_INVOKED_PIN = File.join(PIN_DIR, "event_invoked")
+  EVENT_WRITE_POS_PIN = File.join(PIN_DIR, "event_write_pos")
+
+  EVENT_NAME_SIZE = 16
+  EVENT_PAYLOAD_SIZE = 64
+  EVENT_STRUCT_SIZE = 4 + EVENT_NAME_SIZE + EVENT_PAYLOAD_SIZE
+  EVENT_CAPACITY = 64
+
+  Event = Struct.new(:pid, :event_name, :payload, keyword_init: true) do
+    def empty?
+      pid.to_i.zero? && event_name.to_s.empty? && payload.to_s.empty?
+    end
+
+    def self.from_binary(raw)
+      bytes = raw.to_s.b
+      bytes = bytes.ljust(EVENT_STRUCT_SIZE, "\x00")
+
+      pid = bytes[0, 4].unpack1("L<")
+      event_name = bytes[4, EVENT_NAME_SIZE].delete("\x00")
+      payload = bytes[4 + EVENT_NAME_SIZE, EVENT_PAYLOAD_SIZE].delete("\x00")
+
+      new(pid: pid, event_name: event_name, payload: payload)
+    end
+  end
+
+  class MapStore
+    def initialize(pin_dir: PIN_DIR)
+      @pin_dir = pin_dir
+      @config_targets = RbBCC::HashTable.from_pin(
+        File.join(@pin_dir, "config_targets"),
+        "unsigned int",
+        "unsigned char",
+        keysize: 4,
+        leafsize: 1
+      )
+      @event_invoked = RbBCC::ArrayTable.from_pin(
+        File.join(@pin_dir, "event_invoked"),
+        "unsigned int",
+        "char[#{EVENT_STRUCT_SIZE}]",
+        keysize: 4,
+        leafsize: EVENT_STRUCT_SIZE
+      )
+      @event_write_pos = RbBCC::ArrayTable.from_pin(
+        File.join(@pin_dir, "event_write_pos"),
+        "unsigned int",
+        "unsigned int",
+        keysize: 4,
+        leafsize: 4
+      )
+    rescue StandardError => e
+      raise Error, "failed to open pinned maps under #{@pin_dir}: #{e.class}: #{e.message}"
+    end
+
+    def register_pid(pid)
+      @config_targets[pid] = 1
+    end
+
+    def unregister_pid(pid)
+      @config_targets.delete(pid)
+    rescue KeyError
+      nil
+    end
+
+    def drain_events
+      events = []
+      EVENT_CAPACITY.times do |idx|
+        ptr = @event_invoked[idx]
+        next unless ptr
+
+        event = Event.from_binary(ptr[0, EVENT_STRUCT_SIZE])
+        next if event.empty?
+
+        events << event
+        @event_invoked[idx] = zeroed_event_ptr
+      end
+
+      @event_write_pos[0] = 0
+      events
+    end
+
+    private
+
+    def zeroed_event_ptr
+      ptr = Fiddle::Pointer.malloc(EVENT_STRUCT_SIZE)
+      ptr[0, EVENT_STRUCT_SIZE] = "\x00" * EVENT_STRUCT_SIZE
+      ptr
+    end
+  end
+
+  class Daemon
+    BPF_PROGRAM_TEMPLATE = <<~CLANG
+      struct path {
+        void *mnt;
+        void *dentry;
+      };
+      struct file {
+        char __off[__VIVARIUM_F_PATH_OFFSET__];
+        struct path f_path;
+      };
+
+      struct event_t {
+        u32 pid;
+        char event_name[16];
+        char payload[64];
+      };
+
+      BPF_HASH(config_targets, u32, u32, 1024);
+      BPF_ARRAY(event_invoked, struct event_t, 64);
+      BPF_ARRAY(event_write_pos, u32, 1);
+
+      static __always_inline int target_enabled(u32 pid)
+      {
+        u32 *enabled = config_targets.lookup(&pid);
+        if (!enabled) {
+          return 0;
+        }
+        return *enabled == 1;
+      }
+
+      LSM_PROBE(file_open, struct file *file)
+      {
+        u32 pid = bpf_get_current_pid_tgid() >> 32;
+        if (!target_enabled(pid)) {
+          return 0;
+        }
+
+        u32 zero = 0;
+        u32 *write_pos = event_write_pos.lookup(&zero);
+        if (!write_pos) {
+          return 0;
+        }
+
+        u32 idx = *write_pos & 63;
+        __sync_fetch_and_add(write_pos, 1);
+        struct event_t ev = {};
+        int path_ret;
+        ev.pid = pid;
+        __builtin_memcpy(ev.event_name, "path_open", 9);
+
+        path_ret = bpf_d_path(&file->f_path, ev.payload, sizeof(ev.payload));
+        if (path_ret < 0) {
+          __builtin_memcpy(ev.payload, "<path_error>", 13);
+        }
+
+        event_invoked.update(&idx, &ev);
+
+        return 0;
+      }
+    CLANG
+
+    def initialize(pin_dir: PIN_DIR)
+      @pin_dir = pin_dir
+    end
+
+    def run
+      ensure_root!
+      FileUtils.mkdir_p(@pin_dir)
+
+      f_path_offset = detect_f_path_offset
+      program = BPF_PROGRAM_TEMPLATE.gsub("__VIVARIUM_F_PATH_OFFSET__", f_path_offset.to_s)
+
+      bpf = RbBCC::BCC.new(text: program)
+
+      config_targets = bpf["config_targets"]
+      event_invoked = bpf["event_invoked"]
+      event_write_pos = bpf["event_write_pos"]
+
+      clear_event_slots(event_invoked)
+      event_write_pos[0] = 0
+
+      pin_map(config_targets, File.join(@pin_dir, "config_targets"))
+      pin_map(event_invoked, File.join(@pin_dir, "event_invoked"))
+      pin_map(event_write_pos, File.join(@pin_dir, "event_write_pos"))
+
+      puts "[vivariumd] started"
+      puts "[vivariumd] pinned maps in #{@pin_dir}"
+      puts "[vivariumd] watching LSM file_open (f_path offset=#{f_path_offset})"
+
+      loop do
+        sleep 1
+      end
+    rescue Interrupt
+      puts "\n[vivariumd] stopping"
+    end
+
+    private
+
+    def ensure_root!
+      return if Process.uid.zero?
+
+      raise Error, "vivariumd requires root privileges"
+    end
+
+    def pin_map(table, path)
+      File.unlink(path) if File.exist?(path)
+      RbBCC::BCC.pin!(table.map_fd, path)
+    end
+
+    def clear_event_slots(table)
+      ptr = Fiddle::Pointer.malloc(EVENT_STRUCT_SIZE)
+      ptr[0, EVENT_STRUCT_SIZE] = "\x00" * EVENT_STRUCT_SIZE
+      EVENT_CAPACITY.times do |idx|
+        table[idx] = ptr
+      end
+    end
+
+    def detect_f_path_offset
+      env_offset = ENV["VIVARIUM_FILE_F_PATH_OFFSET"]
+      return Integer(env_offset, 10) if env_offset
+
+      raw = IO.popen(
+        %w[bpftool btf dump file /sys/kernel/btf/vmlinux format raw],
+        err: IO::NULL,
+        &:read
+      )
+
+      in_file_struct = false
+      f_path_bits_offset = nil
+      anon_union_bits_offset = nil
+
+      raw.each_line do |line|
+        if line =~ /^\[\d+\] STRUCT 'file' /
+          in_file_struct = true
+          next
+        end
+
+        if in_file_struct && line.start_with?("[")
+          break
+        end
+
+        next unless in_file_struct
+
+        if (match = line.match(/'f_path'.*bits_offset=(\d+)/))
+          f_path_bits_offset = Integer(match[1], 10)
+          next
+        end
+
+        if (match = line.match(/'\(anon\)'.*bits_offset=(\d+)/))
+          anon_union_bits_offset = Integer(match[1], 10)
+        end
+      end
+
+      if f_path_bits_offset && anon_union_bits_offset && f_path_bits_offset != anon_union_bits_offset
+        warn "[vivariumd] BTF offset mismatch: f_path=#{f_path_bits_offset / 8}, (anon)=#{anon_union_bits_offset / 8}; preferring (anon)"
+      end
+
+      bits_offset = anon_union_bits_offset || f_path_bits_offset
+      if bits_offset
+        if (bits_offset % 8).positive?
+          raise Error, "unsupported f_path bits offset=#{bits_offset}"
+        end
+
+        if bits_offset >= 1024
+          warn "[vivariumd] suspicious f_path offset=#{bits_offset / 8}, fallback to offset=64"
+          return 64
+        end
+
+        return bits_offset / 8
+      end
+
+      warn "[vivariumd] could not find struct file::f_path in BTF, fallback to offset=64"
+      64
+    rescue Errno::ENOENT
+      raise Error, "bpftool is required to resolve struct file::f_path offset"
+    end
+  end
+
+  def self.observe(pin_dir: PIN_DIR, out: $stdout)
+    raise ArgumentError, "block is required" unless block_given?
+
+    store = MapStore.new(pin_dir: pin_dir)
+    pid = Process.pid
+    store.register_pid(pid)
+
+    tracer = TracePoint.new(:return, :c_return) do |tp|
+      events = store.drain_events
+      next if events.empty?
+
+      out.puts "[vivarium] #{events.size} event(s) at #{tp.defined_class}##{tp.method_id} (#{tp.event})"
+      events.each do |event|
+        out.puts "  pid=#{event.pid} #{event.event_name} payload=#{event.payload.inspect}"
+      end
+      out.puts "  stack:"
+      caller_locations(0, 12).each do |loc|
+        out.puts "    #{loc.path}:#{loc.lineno}:in #{loc.base_label}"
+      end
+    end
+
+    tracer.enable
+    yield
+  ensure
+    tracer&.disable
+    store&.unregister_pid(pid)
+  end
+
+  def self.run_daemon!(argv = ARGV)
+    options = { pin_dir: PIN_DIR }
+    OptionParser.new do |opts|
+      opts.banner = "Usage: vivariumd [--pin-dir PATH]"
+      opts.on("--pin-dir PATH", "Pinned map directory") { |v| options[:pin_dir] = v }
+    end.parse!(argv)
+
+    Daemon.new(pin_dir: options[:pin_dir]).run
+  end
+end

data/sig/vivarium.rbs

@@ -0,0 +1,41 @@
+module Vivarium
+  VERSION: String
+
+  class Error < ::StandardError
+  end
+
+  class Event < ::Struct
+    attr_accessor pid: Integer?
+    attr_accessor event_name: String?
+    attr_accessor payload: String?
+
+    def empty?: bool
+    def self.from_binary: (String raw) -> Event
+  end
+
+  class MapStore
+    def initialize: (?pin_dir: String pin_dir) -> void
+    def register_pid: (Integer pid) -> untyped
+    def unregister_pid: (Integer pid) -> untyped
+    def drain_events: () -> Array[Event]
+  end
+
+  class Daemon
+    BPF_PROGRAM: String
+    def initialize: (?pin_dir: String pin_dir) -> void
+    def run: () -> void
+  end
+
+  PIN_DIR: String
+  CONFIG_TARGETS_PIN: String
+  EVENT_INVOKED_PIN: String
+  EVENT_WRITE_POS_PIN: String
+
+  EVENT_NAME_SIZE: Integer
+  EVENT_PAYLOAD_SIZE: Integer
+  EVENT_STRUCT_SIZE: Integer
+  EVENT_CAPACITY: Integer
+
+  def self.observe: (?pin_dir: String pin_dir, ?out: untyped out) { () -> untyped } -> untyped
+  def self.run_daemon!: (?Array[String] argv) -> void
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: vivarium
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Uchio Kondo
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rbbcc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.2
+description: Vivarium visualizes low-level events such as file open paths and relates
+  them to Ruby method boundaries by combining RbBCC (eBPF LSM) and TracePoint.
+email:
+- udzura@udzura.jp
+executables:
+- vivariumd
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- exe/vivariumd
+- lib/vivarium.rb
+- lib/vivarium/version.rb
+- sig/vivarium.rbs
+homepage: https://github.com/udzura/vivarium
+licenses: []
+metadata:
+  homepage_uri: https://github.com/udzura/vivarium
+  source_code_uri: https://github.com/udzura/vivarium
+  changelog_uri: https://github.com/udzura/vivarium/blob/main/README.md
+  bug_tracker_uri: https://github.com/udzura/vivarium/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby observation and sandbox helper with RbBCC + TracePoint
+test_files: []