vivarium 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bc495e3c2b8f9d99a2b1c84706b5e00913cc08831b3103b0460db0d4027c77b
-  data.tar.gz: 1ee086243fdc153da5bac6a2bec8d0afe8e644ceac2fef2308b7723b89533338
+  metadata.gz: 973df86f00b8e2ca9d5e963958562e2f58822e13c0e4d33af53e85a8d38f12be
+  data.tar.gz: a5651655ef69c10e6b6eab89baf9f98e5d99a158a8e89a6fc940fe2d844ab636
 SHA512:
-  metadata.gz: a203dd1cbaeff9fe0f4bf464a01ff49f131a104ca9e1eb14b6c08dd4371f49acf31c493119eee70114cafacbc6aa8a42976a9e6c230b1d828fe442e738c57c54
-  data.tar.gz: a31a64e20f2f7d0956626658b5d6f91e0cd5333f97854ad3388c41cc0d3b0b8d233850c3bdaaf60663c9152d6cf35e4034355e37c50fc913687ad05295dffaba
+  metadata.gz: 3606b1f6df38a813e2b0cdf48aef48312be1a7c0bd3f20f88ca8a4c527c724733184c1c0d52f39fc9242282ab6d41ca18f6bcc977f4cafad0c5d4faa17a27d78
+  data.tar.gz: 4171eefdd7052d8634cd5a49267c8fe4f925e87f5b18691cb0721dd3f014efac68475196762e9ecc800627bcc529d9077e088b7d0366d91a6252867d3a0fc5f1

data/README.md

@@ -18,10 +18,24 @@ The goal is to visualize which Ruby method context triggered low-level events.
 Implemented in this repository:
 
 - BPF LSM hook on `file_open`
+- 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 LSM hooks for suspicious behavior checks:
+	- `ptrace_access_check` (emits `ptrace_check`)
+	- `sb_mount` (emits `sb_mount`)
+	- `kernel_read_file` (emits `kernel_read_file`)
+	- `task_kill` (emits `task_kill`)
+	- `task_fix_setuid` (emits `setid_change`)
+	- `capable` for high-risk capabilities only (emits `capable_check`)
+	- `bprm_creds_from_file` (emits `bprm_creds`)
+- 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`)
 - Shared pinned maps on bpffs
 	- `config_root_targets` (root PID -> 0/1)
 	- `config_spawned_targets` (spawned TID -> 0/1)
-	- `event_invoked` (array length 64 with `event_t` records)
+	- `event_invoked` (array length 1024 with `event_t` records)
 	- `event_write_pos` (cursor for appending into `event_invoked`)
 - Ruby API `Vivarium.observe do ... end`
 	- Registers current PID to `config_root_targets`
@@ -35,9 +49,10 @@ Implemented in this repository:
 
 ```c
 struct event_t {
+	u64 ktime_ns;
 	u32 pid;
-	char event_name[8];   // "path_open"
-	char payload[64];     // opened path (truncated)
+	char event_name[16];
+	char payload[256];
 };
 ```
 
@@ -45,7 +60,7 @@ struct event_t {
 
 - Linux kernel/environment supporting BPF LSM
 - `libbcc` installed
-- `bpftool` installed (used to resolve `struct file::f_path` offset from BTF)
+- `bpftool` installed (used to resolve `struct file::f_path` and `struct dentry::d_name` offsets from BTF)
 - root privileges for `vivariumd`
 - bpffs mounted (typically `/sys/fs/bpf`)
 
@@ -81,6 +96,46 @@ Vivarium.observe do
 end
 ```
 
+3) Network monitoring demo client:
+
+```bash
+bundle exec ruby examples/network_client_demo.rb
+```
+
+This demo intentionally triggers `sock_connect`, `dns_req`, and `odd_socket` events.
+
+4) File operation demo client (only touches `/tmp`):
+
+```bash
+bundle exec ruby examples/file_operation_demo.rb
+```
+
+This demo intentionally triggers `path_open`, `file_symlink`, `file_hardlink`, `file_rename`, `file_chmod`, and `file_getdents` events under `/tmp`.
+
+5) Execve demo client:
+
+```bash
+bundle exec ruby examples/execve_demo.rb
+```
+
+This demo intentionally triggers `proc_exec` with several argument patterns using direct `execve`-style process launches.
+
+6) Signal demo client:
+
+```bash
+bundle exec ruby examples/signal_kill_demo.rb
+```
+
+This demo forks a child process and sends `TERM` with `Process.kill`, which is useful for triggering `task_kill`.
+
+7) Privilege-related event demo client:
+
+```bash
+bundle exec ruby examples/privilege_event_demo.rb
+```
+
+This demo attempts setuid/setgid changes, sensitive file access, and `sudo` exec to trigger privilege-related events such as `setid_change`, `capable_check`, and `bprm_creds`.
+
 You can also start top-level observation without a block (it keeps observing until process exit):
 
 ```ruby
@@ -124,11 +179,16 @@ 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.
+- `event_invoked` uses fixed 1024 slots and wraps around when full.
+- `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.
+- 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.
 - `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.
+- `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

@@ -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/network_client_demo.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "socket"
+require "vivarium"
+
+# Usage:
+#   1) In another shell (root): sudo bundle exec vivariumd
+#   2) Run this script: bundle exec ruby examples/network_client_demo.rb
+
+def try_step(title)
+  puts "[client] #{title}"
+  yield
+rescue StandardError => e
+  puts "[client] #{title} failed: #{e.class}: #{e.message}"
+end
+
+Vivarium.observe 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/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/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/lib/vivarium/logger.rb

@@ -5,6 +5,8 @@ require "json"
 module Vivarium
   class Logger
     FORMATS = %i[human json].freeze
+    ANSI_RED = "\e[31m"
+    ANSI_RESET = "\e[0m"
 
     # dest: IO object or file path string
     # format: :human or :json
@@ -45,7 +47,9 @@ module Vivarium
       @io.puts "[vivarium] #{events.size} event(s) at #{tp.defined_class}##{tp.method_id} (#{tp.event})"
       @io.puts "  location: #{tp.path}:#{tp.lineno}"
       events.each do |event|
-        @io.puts "  pid=#{event.pid} #{event.event_name} payload=#{event.payload.inspect}"
+        severity = event.respond_to?(:severity) ? event.severity : Vivarium.event_severity(event.event_name)
+        line = "  ktime_ns=#{event.ktime_ns} pid=#{event.pid} severity=#{severity} #{event.event_name} payload=#{Vivarium.render_event_payload(event)}"
+        @io.puts(severity == "high" ? "#{ANSI_RED}#{line}#{ANSI_RESET}" : line)
       end
       @io.puts "  stack:"
       stack.each do |loc|
@@ -59,7 +63,15 @@ module Vivarium
         event:  tp.event.to_s,
         path:   tp.path,
         lineno: tp.lineno,
-        events: events.map { |e| { pid: e.pid, event_name: e.event_name, payload: e.payload } },
+        events: events.map do |e|
+          {
+            ktime_ns: e.ktime_ns,
+            pid: e.pid,
+            severity: (e.respond_to?(:severity) ? e.severity : Vivarium.event_severity(e.event_name)),
+            event_name: e.event_name,
+            payload: Vivarium.render_event_payload(e)
+          }
+        end,
         stack:  stack.map { |loc| "#{loc.path}:#{loc.lineno}:in #{loc.base_label}" }
       }
       @io.puts JSON.generate(entry)

data/lib/vivarium/version.rb

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