Module: Vivarium

Defined in:

lib/vivarium.rb,
lib/vivarium/box.rb,
lib/vivarium/cli.rb,
lib/vivarium/version.rb,
lib/vivarium/raw_store.rb,
lib/vivarium/api_server.rb,
lib/vivarium/correlator.rb,
lib/vivarium/http_decoder.rb,
lib/vivarium/daemon_client.rb,
lib/vivarium/tree_renderer.rb,
lib/vivarium/display_filter.rb

Defined Under Namespace

Modules: CLI, RawStore Classes: ApiServer, Box, Correlator, Daemon, DaemonClient, DisplayFilter, Error, EventLog, HttpDecoder, ObservationSession, RawEvent, Registry, TreeRenderer

Constant Summary

PIN_DIR =

ENV.fetch("VIVARIUM_BPF_PIN_DIR", "/sys/fs/bpf/vivarium")

CONFIG_ROOT_TARGETS_PIN =

File.join(PIN_DIR, "config_root_targets")

CONFIG_SPAWNED_TARGETS_PIN =

File.join(PIN_DIR, "config_spawned_targets")

CONFIG_TARGETS_PIN =

CONFIG_ROOT_TARGETS_PIN

EVENTS_PIN =

File.join(PIN_DIR, "events")

SOCKET_PATH =

ENV.fetch("VIVARIUM_SOCKET_PATH", "/run/vivarium/vivariumd.sock")

EVENT_NAME_SIZE =

16

EVENT_PAYLOAD_SIZE =

256

EVENT_TS_SIZE =

8

PROC_EXEC_SLOT_SIZE =

64

PROC_EXEC_SLOT_COUNT =

4

EVENT_STRUCT_SIZE =

296

EVENT_TS_OFFSET =

0

EVENT_PID_OFFSET =

8

EVENT_TID_OFFSET =

12

EVENT_NAME_OFFSET =

16

EVENT_PAYLOAD_OFFSET =

32

EVENT_DROPPED_OFFSET =

288

EVENTS_RINGBUF_PAGES =

256

SPAN_METHOD_SIZE =

128

SPAN_FILE_SIZE =

120

SPAN_LINENO_OFFSET =

248

SPAN_METHOD_SIZE + SPAN_FILE_SIZE

SPAN_FILE_ARG_MAX =

SPAN_FILE_SIZE - 1

SPAN_RAISE_SLOT_SIZE =

80

SPAN_RAISE_LINENO_OFFSET =

240

SPAN_RAISE_SLOT_SIZE * 3

SPAN_RAISE_FILE_ARG_MAX =

SPAN_RAISE_SLOT_SIZE - 1

SSL_WRITE_PAYLOAD_DATA_LEN_OFFSET =

0

SSL_WRITE_PAYLOAD_CAP_LEN_OFFSET =

4

SSL_WRITE_PAYLOAD_DATA_OFFSET =

8

SSL_WRITE_PAYLOAD_DATA_MAX =

EVENT_PAYLOAD_SIZE - SSL_WRITE_PAYLOAD_DATA_OFFSET

LIBSSL_SEARCH_PATHS =

[
  "/lib/x86_64-linux-gnu/libssl.so.3",
  "/lib/x86_64-linux-gnu/libssl.so.1.1",
  "/lib/aarch64-linux-gnu/libssl.so.3",
  "/lib/aarch64-linux-gnu/libssl.so.1.1",
  "/usr/lib/x86_64-linux-gnu/libssl.so.3",
  "/usr/lib/x86_64-linux-gnu/libssl.so.1.1",
  "/usr/lib/aarch64-linux-gnu/libssl.so.3",
  "/usr/lib/aarch64-linux-gnu/libssl.so.1.1",
  "/usr/lib64/libssl.so.3",
  "/usr/lib64/libssl.so.1.1",
  "/usr/lib/libssl.so.3",
  "/usr/lib/libssl.so.1.1"
].freeze

LIBC_SEARCH_PATHS =

[
  "/lib/x86_64-linux-gnu/libc.so.6",
  "/lib/aarch64-linux-gnu/libc.so.6",
  "/usr/lib/x86_64-linux-gnu/libc.so.6",
  "/usr/lib/aarch64-linux-gnu/libc.so.6",
  "/lib64/libc.so.6",
  "/usr/lib64/libc.so.6",
  "/lib/libc.so.6",
].freeze

SPAN_ALLOWCLASSES =

[
  Socket,
  BasicSocket,
  IPSocket,
  TCPSocket,
  UDPSocket,
  UNIXSocket,
  Signal,
  Process,
  Process::UID,
  Process::GID,
  Net::HTTP,
]

SPAN_FILE_METHODS =

File/Dir are deliberately NOT in SPAN_ALLOWCLASSES: tracing every method is far too noisy and read/query methods (exist?, basename, read, stat, …) carry little security signal. Instead only the security-relevant methods below are turned into spans. Detection is done via tp.self (not tp.defined_class) so that e.g. File.open, whose method is owned by IO, is still matched. Kernel LSM events (path_open, file_chmod, file_rename, file_symlink, file_hardlink, file_getdents) already capture the underlying filesystem actions regardless of the Ruby method.

%i[
  open new write binwrite
  delete unlink rename truncate
  chmod lchmod chown lchown
  symlink link readlink
  realpath realdirpath
  mkfifo mknod utime
].to_set.freeze

SPAN_DIR_METHODS =

%i[
  mkdir rmdir delete unlink chdir chroot glob
].to_set.freeze

SPAN_ALLOWLIST =

[
  "Kernel#system",
  "Kernel#require",
  "Kernel#require_relative",
  "Kernel#load",
  "Kernel#eval",
  "Object#instance_eval",
  "Object#instance_exec",
  "ENV#[]",
  "ENV#fetch",
  "ENV#key?",
  "ENV#[]=",
  "ENV#store",
  "ENV#delete",
  "ENV#clear",
  "ENV#replace",
].freeze

ENV_PAYLOAD_OP_SIZE =

16

ENV_PAYLOAD_KEY_OFFSET =

ENV_PAYLOAD_OP_SIZE

ENV_PAYLOAD_KEY_SIZE =

EVENT_PAYLOAD_SIZE - ENV_PAYLOAD_KEY_OFFSET

EVENT_SEVERITY_HIGH =

%w[
  capable_check bprm_creds setid_change task_kill
  ptrace_check sb_mount kernel_read_file
  dlopen
].freeze

DEFAULT_FILTER =

Default display filter applied by both ‘vivarium load` (CLI) and Vivarium::Box. path_open fires on every file open and is far too noisy to show in full, so it is restricted to opens under /etc and /proc (config/state that matters for security review). render_event_payload renders the path via String#inspect, so the matched target text looks like “/etc/passwd” (leading quote included).

{
  include_events: %w[
    proc_fork proc_exec span_start span_stop
    path_open
    sock_connect dns_req odd_socket
    ssl_write
    dlopen mmap_exec
    task_kill
    setid_change capable_check bprm_creds
  ],
  payload: {
    "path_open" => %r{\A"?/(?:home|root|etc|proc)(?:/|"|\z)}
  }
}.freeze

CAPABILITY_NAMES =

{
  0 => "CAP_CHOWN",
  1 => "CAP_DAC_OVERRIDE",
  2 => "CAP_DAC_READ_SEARCH",
  3 => "CAP_FOWNER",
  4 => "CAP_FSETID",
  5 => "CAP_KILL",
  6 => "CAP_SETGID",
  7 => "CAP_SETUID",
  8 => "CAP_SETPCAP",
  9 => "CAP_LINUX_IMMUTABLE",
  10 => "CAP_NET_BIND_SERVICE",
  12 => "CAP_NET_ADMIN",
  13 => "CAP_NET_RAW",
  16 => "CAP_SYS_MODULE",
  17 => "CAP_SYS_RAWIO",
  18 => "CAP_SYS_CHROOT",
  19 => "CAP_SYS_PTRACE",
  21 => "CAP_SYS_ADMIN",
  22 => "CAP_SYS_BOOT",
  23 => "CAP_SYS_NICE",
  24 => "CAP_SYS_RESOURCE",
  25 => "CAP_SYS_TIME",
  27 => "CAP_MKNOD",
  29 => "CAP_AUDIT_WRITE",
  37 => "CAP_AUDIT_READ",
  38 => "CAP_PERFMON",
  39 => "CAP_BPF",
  40 => "CAP_CHECKPOINT_RESTORE"
}.freeze

SETID_FLAG_NAMES =

{
  0x01 => "LSM_SETID_ID",
  0x02 => "LSM_SETID_RE",
  0x04 => "LSM_SETID_RES",
  0x08 => "LSM_SETID_FS"
}.freeze

VERSION =

"0.5.2"

Class Attribute Summary

• .bpf_pin_dir ⇒ Object
• .socket_path ⇒ Object

Class Method Summary

• .build_observe_tracepoint ⇒ Object
• .c_string(bytes) ⇒ Object
• .decode_bad_socket_payload(raw_payload) ⇒ Object
• .decode_bprm_creds_payload(raw_payload) ⇒ Object
• .decode_capable_check_payload(raw_payload) ⇒ Object
• .decode_dns_qname(raw_payload) ⇒ Object
• .decode_env_payload(raw_payload) ⇒ Object
• .decode_file_chmod_payload(raw_payload) ⇒ Object
• .decode_file_getdents_payload(raw_payload) ⇒ Object
• .decode_file_hardlink_payload(raw_payload) ⇒ Object
• .decode_file_rename_payload(raw_payload) ⇒ Object
• .decode_file_symlink_payload(raw_payload) ⇒ Object
• .decode_file_unlink_payload(raw_payload) ⇒ Object
• .decode_kernel_read_file_payload(raw_payload) ⇒ Object
• .decode_odd_socket_payload(raw_payload) ⇒ Object
• .decode_proc_exec_payload(raw_payload) ⇒ Object
• .decode_proc_fork_payload(raw_payload) ⇒ Object
• .decode_ptrace_check_payload(raw_payload) ⇒ Object
• .decode_sb_mount_payload(raw_payload) ⇒ Object
• .decode_setid_change_payload(raw_payload) ⇒ Object
• .decode_sock_connect_payload(raw_payload) ⇒ Object
• .decode_span_payload(raw_payload) ⇒ Object
• .decode_span_raise_payload(raw_payload) ⇒ Object
• .decode_ssl_write_payload(raw_payload) ⇒ Object
• .decode_task_kill_payload(raw_payload) ⇒ Object
• .event_severity(event_name) ⇒ Object
• .gettid ⇒ Object
• .locate_vivarium_usdt_so ⇒ Object
• .monotonic_ktime_ns ⇒ Object
• .observe(socket_path: self.socket_path, dest: $stdout, filter: nil, save_raw: nil, &block) ⇒ Object
• .render_event_payload(event) ⇒ Object
• .run_daemon!(argv = ARGV) ⇒ Object
• .scoped_observe(socket_path: self.socket_path, dest:, filter: nil, save_raw: nil) ⇒ Object
• .socket_const_name(prefix, value) ⇒ Object
• .strip_to_first_null(bytes) ⇒ Object
• .tail_fit_string(value, max_bytes, marker: "...") ⇒ Object
• .top_observe(socket_path: self.socket_path, dest: $stdout, filter: nil, save_raw: nil) ⇒ Object

Class Attribute Details

.bpf_pin_dir ⇒ Object

# File 'lib/vivarium.rb', line 208

def bpf_pin_dir
  @bpf_pin_dir || PIN_DIR
end

.socket_path ⇒ Object

# File 'lib/vivarium.rb', line 212

def socket_path
  @socket_path || SOCKET_PATH
end

Class Method Details

.build_observe_tracepoint ⇒ Object

# File 'lib/vivarium.rb', line 2243

def self.build_observe_tracepoint
  allow_classes = SPAN_ALLOWCLASSES
  allowlist = SPAN_ALLOWLIST
  TracePoint.new(:call, :c_call, :return, :c_return, :raise) do |tp|
    if tp.event == :raise
      # FIXME: handle threaded events in the future
      next if tp.raised_exception.kind_of?(ThreadError)

      file_arg = tail_fit_string(tp.path, SPAN_RAISE_FILE_ARG_MAX)
      Vivarium::Usdt.raise(
        tp.raised_exception.class.to_s,
        tp.raised_exception.message.to_s,
        file: file_arg,
        lineno: tp.lineno
      )
      next
    end

    signature = if tp.self.equal?(ENV)
      "ENV##{tp.method_id}"
    else
      "#{tp.defined_class}##{tp.method_id}"
    end

    recv = tp.self
    mid = tp.method_id
    file_dir_name =
      if (recv.is_a?(Class) ? recv <= File : recv.is_a?(File)) && SPAN_FILE_METHODS.include?(mid)
        "File"
      elsif (recv.is_a?(Class) ? recv <= Dir : recv.is_a?(Dir)) && SPAN_DIR_METHODS.include?(mid)
        "Dir"
      end

    is_target = !file_dir_name.nil? || \
      allowlist.include?(signature) || \
      allow_classes.any? { |klass| tp.defined_class == klass } || \
      allow_classes.any? { |klass| tp.defined_class == klass.singleton_class }
    next unless is_target

    file_arg = tail_fit_string(tp.path, SPAN_FILE_ARG_MAX)
    span_class_name = tp.self.equal?(ENV) ? "ENV" : (file_dir_name || tp.defined_class.to_s)
    case tp.event
    when :call, :c_call
      Vivarium::Usdt.start(span_class_name, tp.method_id.to_s, file: file_arg, lineno: tp.lineno)
    when :return, :c_return
      Vivarium::Usdt.stop(span_class_name, tp.method_id.to_s, file: file_arg, lineno: tp.lineno)
    end
  end
end

.c_string(bytes) ⇒ Object

# File 'lib/vivarium.rb', line 217

def self.c_string(bytes)
  str = bytes.to_s.b
  nul = str.index("\x00")
  return str if nul.nil?

  str[0, nul]
end

.decode_bad_socket_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 308

def self.decode_bad_socket_payload(raw_payload)
  decode_odd_socket_payload(raw_payload)
end

.decode_bprm_creds_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 437

def self.decode_bprm_creds_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 2

  has_file = bytes.getbyte(0).to_i
  path = c_string(bytes[1, EVENT_PAYLOAD_SIZE - 1])
  "has_file=#{has_file} file=#{path.inspect}"
end

.decode_capable_check_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 427

def self.decode_capable_check_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 8

  cap = bytes[0, 4].unpack1("L<")
  opts = bytes[4, 4].unpack1("L<")
  cap_name = CAPABILITY_NAMES.fetch(cap, "UNKNOWN")
  "cap=#{cap}(#{cap_name}) opts=0x#{opts.to_s(16)}"
end

.decode_dns_qname(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 239

def self.decode_dns_qname(raw_payload)
  bytes = raw_payload.to_s.b.bytes
  labels = []
  idx = 0

  while idx < bytes.length
    length = bytes[idx]
    break if length.nil? || length.zero?
    break if length > 63

    idx += 1
    break if (idx + length) > bytes.length

    label = bytes[idx, length].pack("C*")
    labels << label
    idx += length
  end

  return "" if labels.empty?

  labels.join(".")
end

.decode_env_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 483

def self.decode_env_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < ENV_PAYLOAD_OP_SIZE

  op = c_string(bytes[0, ENV_PAYLOAD_OP_SIZE])
  key = c_string(bytes[ENV_PAYLOAD_KEY_OFFSET, ENV_PAYLOAD_KEY_SIZE])

  return "" if op.empty?
  return "op=#{op}" if key.empty?

  key = key.split("=", 2).first if op == "putenv"
  "op=#{op} key=#{key.inspect}"
end

.decode_file_chmod_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 342

def self.decode_file_chmod_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 2

  mode = bytes[0, 2].unpack1("S<")
  path = c_string(bytes[2, 254])
  "mode=#{format('0o%o', mode)} path=#{path.inspect}"
end

.decode_file_getdents_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 351

def self.decode_file_getdents_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 8

  fd = bytes[0, 4].unpack1("L<")
  count = bytes[4, 4].unpack1("L<")
  "fd=#{fd} count=#{count}"
end

.decode_file_hardlink_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 319

def self.decode_file_hardlink_payload(raw_payload)
  bytes = raw_payload.to_s.b
  old_path = c_string(bytes[0, 128])
  new_name = c_string(bytes[128, 128])
  "old_path=#{old_path.inspect} new_name=#{new_name.inspect}"
end

.decode_file_rename_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 326

def self.decode_file_rename_payload(raw_payload)
  bytes = raw_payload.to_s.b
  old_name = c_string(bytes[0, 128])
  new_name = c_string(bytes[128, 128])
  "old_name=#{old_name.inspect} new_name=#{new_name.inspect}"
end

.decode_file_symlink_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 312

def self.decode_file_symlink_payload(raw_payload)
  bytes = raw_payload.to_s.b
  target = c_string(bytes[0, 128])
  link_name = c_string(bytes[128, 128])
  "target=#{target.inspect} link_name=#{link_name.inspect}"
end

.decode_file_unlink_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 333

def self.decode_file_unlink_payload(raw_payload)
  bytes = raw_payload.to_s.b
   filename = c_string(bytes[0, 128])
   parent_dir = c_string(bytes[128, 128])
   result = "filename=#{filename.inspect}"
   result += " parent_dir=#{parent_dir.inspect}" if !parent_dir.empty?
   result
end

.decode_kernel_read_file_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 392

def self.decode_kernel_read_file_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 8

  id = bytes[0, 4].unpack1("L<")
  contents = bytes[4, 4].unpack1("L<")
  "id=#{id} contents=#{contents}"
end

.decode_odd_socket_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 283

def self.decode_odd_socket_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 6

  family = bytes[0, 2].unpack1("S<")
  type = bytes[2, 2].unpack1("S<")
  protocol = bytes[4, 2].unpack1("S<")
  family_name = socket_const_name("AF_", family)
  type_name = socket_const_name("SOCK_", type)
  protocol_name = socket_const_name("IPPROTO_", protocol)
  "family=#{family}(#{family_name}) type=#{type}(#{type_name}) protocol=#{protocol}(#{protocol_name})"
end

.decode_proc_exec_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 360

def self.decode_proc_exec_payload(raw_payload)
  bytes = raw_payload.to_s.b
  slots = PROC_EXEC_SLOT_COUNT.times.map do |index|
    offset = index * PROC_EXEC_SLOT_SIZE
    c_string(bytes[offset, PROC_EXEC_SLOT_SIZE])
  end
  slots.reject!(&:empty?)
  return "" if slots.empty?

  filename = slots.shift
  argv = slots
  "filename=#{filename.inspect} argv=[#{argv.map(&:inspect).join(', ')}]"
end

.decode_proc_fork_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 446

def self.decode_proc_fork_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 8

  child_pid = bytes[0, 4].unpack1("L<")
  child_tid = bytes[4, 4].unpack1("L<")
  "child_pid=#{child_pid} child_tid=#{child_tid}"
end

.decode_ptrace_check_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 374

def self.decode_ptrace_check_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 4

  mode = bytes[0, 4].unpack1("L<")
  "mode=0x#{mode.to_s(16)}"
end

.decode_sb_mount_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 382

def self.decode_sb_mount_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 248

  flags = bytes[0, 8].unpack1("Q<")
  dev_name = c_string(bytes[8, 120])
  fs_type = c_string(bytes[128, 120])
  "flags=0x#{flags.to_s(16)} dev_name=#{dev_name.inspect} fs_type=#{fs_type.inspect}"
end

.decode_setid_change_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 415

def self.decode_setid_change_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 4

  flags = bytes[0, 4].unpack1("L<")
  names = SETID_FLAG_NAMES.each_with_object([]) do |(bit, name), acc|
    acc << name if (flags & bit) != 0
  end
  names << "UNKNOWN" if names.empty?
  "flags=0x#{flags.to_s(16)} kinds=[#{names.join(', ')}]"
end

.decode_sock_connect_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 262

def self.decode_sock_connect_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 20

  family = bytes[0, 2].unpack1("S<")
  port = bytes[2, 2].unpack1("n")
  addr = bytes[4, 16]

  case family
  when 2 # AF_INET
    ipv4 = addr[0, 4].bytes.join(".")
    "#{ipv4}:#{port} (#{socket_const_name("AF_", family)})"
  when 10 # AF_INET6
    words = addr.unpack("n8")
    ipv6 = words.map { |w| format("%x", w) }.join(":")
    "[#{ipv6}]:#{port} (#{socket_const_name("AF_", family)})"
  else
    "family=#{family}(#{socket_const_name("AF_", family)}) port=#{port}"
  end
end

.decode_span_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 455

def self.decode_span_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 8

  method_id = bytes[0, 8].unpack1("q<")
  result = format("method_id=0x%016X", method_id & 0xFFFF_FFFF_FFFF_FFFF)

  if bytes.bytesize >= 24
    file_id = bytes[8, 8].unpack1("q<")
    lineno = bytes[16, 8].unpack1("q<")
    result += format(" file_id=0x%016X", file_id & 0xFFFF_FFFF_FFFF_FFFF) if file_id != -1
    result += " lineno=#{lineno}" if lineno > 0
  end

  result
end

.decode_span_raise_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 497

def self.decode_span_raise_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 8

  error_id = bytes[0, 8].unpack1("q<")
  result = format("error_id=0x%016X", error_id & 0xFFFF_FFFF_FFFF_FFFF)

  if bytes.bytesize >= 16
    message_id = bytes[8, 8].unpack1("q<")
    result += format(" message_id=0x%016X", message_id & 0xFFFF_FFFF_FFFF_FFFF)
  end

  if bytes.bytesize >= 24
    file_id = bytes[16, 8].unpack1("q<")
    result += format(" file_id=0x%016X", file_id & 0xFFFF_FFFF_FFFF_FFFF) if file_id != -1
  end

  if bytes.bytesize >= 32
    lineno = bytes[24, 8].unpack1("q<")
    result += " lineno=#{lineno}" if lineno > 0
  end

  result
end

.decode_ssl_write_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 472

def self.decode_ssl_write_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return { data_len: 0, cap_len: 0, data: "".b } if bytes.bytesize < SSL_WRITE_PAYLOAD_DATA_OFFSET

  data_len = bytes[SSL_WRITE_PAYLOAD_DATA_LEN_OFFSET, 4].unpack1("L<")
  cap_len = bytes[SSL_WRITE_PAYLOAD_CAP_LEN_OFFSET, 4].unpack1("L<")
  cap_len = SSL_WRITE_PAYLOAD_DATA_MAX if cap_len > SSL_WRITE_PAYLOAD_DATA_MAX
  data = bytes[SSL_WRITE_PAYLOAD_DATA_OFFSET, cap_len] || "".b
  { data_len: data_len, cap_len: cap_len, data: data }
end

.decode_task_kill_payload(raw_payload) ⇒ Object

# File 'lib/vivarium.rb', line 401

def self.decode_task_kill_payload(raw_payload)
  bytes = raw_payload.to_s.b
  return "" if bytes.bytesize < 4

  sig = bytes[0, 4].unpack1("l<")
  signame = begin
    Signal.signame(sig)
  rescue ArgumentError
    nil
  end

  signame ? "sig=#{sig} signame=#{signame}" : "sig=#{sig}"
end

.event_severity(event_name) ⇒ Object

# File 'lib/vivarium.rb', line 235

def self.event_severity(event_name)
  EVENT_SEVERITY_HIGH.include?(event_name.to_s) ? "high" : "medium"
end

.gettid ⇒ Object

# File 'lib/vivarium.rb', line 2293

def self.gettid
  @gettid_func ||= begin
    libc = Fiddle.dlopen("libc.so.6")
    Fiddle::Function.new(libc["gettid"], [], Fiddle::TYPE_INT)
  rescue Fiddle::DLError
    libc = Fiddle.dlopen(nil)
    Fiddle::Function.new(libc["gettid"], [], Fiddle::TYPE_INT)
  end
  @gettid_func.call
end

.locate_vivarium_usdt_so ⇒ Object

# File 'lib/vivarium.rb', line 2308

def self.locate_vivarium_usdt_so
  so = $LOADED_FEATURES.find { |p| p =~ %r{vivarium_usdt/vivarium_usdt\.(so|bundle|dylib)\z} }
  raise Error, "vivarium_usdt native extension not found in $LOADED_FEATURES" unless so

  File.realpath(so)
rescue LoadError => e
  raise Error, "failed to load vivarium_usdt: #{e.message}"
end

.monotonic_ktime_ns ⇒ Object

# File 'lib/vivarium.rb', line 2304

def self.monotonic_ktime_ns
  Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
end

.observe(socket_path: self.socket_path, dest: $stdout, filter: nil, save_raw: nil, &block) ⇒ Object

# File 'lib/vivarium.rb', line 2183

def self.observe(socket_path: self.socket_path, dest: $stdout, filter: nil, save_raw: nil, &block)
  if block_given?
    return scoped_observe(socket_path: socket_path, dest: dest, filter: filter, save_raw: save_raw, &block)
  end

  top_observe(socket_path: socket_path, dest: dest, filter: filter, save_raw: save_raw)
end

.render_event_payload(event) ⇒ Object

# File 'lib/vivarium.rb', line 522

def self.render_event_payload(event)
  case event.event_name
  when "dns_req"
    decoded = decode_dns_qname(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "sock_connect"
    decoded = decode_sock_connect_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "odd_socket"
    decoded = decode_odd_socket_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "proc_exec"
    decoded = decode_proc_exec_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "ptrace_check"
    decoded = decode_ptrace_check_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "sb_mount"
    decoded = decode_sb_mount_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "kernel_read_file"
    decoded = decode_kernel_read_file_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "task_kill"
    decoded = decode_task_kill_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "setid_change"
    decoded = decode_setid_change_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "capable_check"
    decoded = decode_capable_check_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "bprm_creds"
    decoded = decode_bprm_creds_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "proc_fork"
    decoded = decode_proc_fork_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "span_start", "span_stop"
    decoded = decode_span_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "span_raise"
    decoded = decode_span_raise_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "file_symlink"
    decoded = decode_file_symlink_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "file_hardlink"
    decoded = decode_file_hardlink_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "file_rename"
    decoded = decode_file_rename_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "file_unlink"
    decoded = decode_file_unlink_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "file_chmod"
    decoded = decode_file_chmod_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "file_getdents"
    decoded = decode_file_getdents_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "ssl_write"
    decoded = decode_ssl_write_payload(event.payload)
    "data_len=#{decoded[:data_len]} cap_len=#{decoded[:cap_len]}"
  when "env_caccess"
    decoded = decode_env_payload(event.payload)
    decoded.empty? ? event.payload.inspect : decoded
  when "dlopen", "mmap_exec"
    strip_to_first_null(event.payload).inspect
  else
    strip_to_first_null(event.payload).inspect
  end
end

.run_daemon!(argv = ARGV) ⇒ Object

# File 'lib/vivarium.rb', line 2317

def self.run_daemon!(argv = ARGV)
  options = { pin_dir: bpf_pin_dir, socket_path: socket_path, ssl_trace: true, libssl_path: nil,
              env_trace: true,
              dlopen_trace: true, libc_path: nil, usdt_so_paths: [] }
  OptionParser.new do |opts|
    opts.banner = "Usage: vivariumd [--pin-dir PATH] [--socket PATH] [--no-ssl-trace] [--libssl PATH] " \
                  "[--no-dlopen-trace] [--no-env-trace] [--libc PATH] [--usdt-so PATH ...]"
    opts.on("--usdt-so PATH", "USDT .so to attach (repeatable; " \
                              "overrides VIVARIUM_USDT_SO_PATH)") do |v|
      options[:usdt_so_paths] << v
    end
    opts.on("--pin-dir PATH", "Pinned map directory") { |v| options[:pin_dir] = v }
    opts.on("--socket PATH", "Unix domain socket path for the HTTP API") { |v| options[:socket_path] = v }
    opts.on("--[no-]ssl-trace", "Attach OpenSSL SSL_write uprobe (default: enabled)") do |v|
      options[:ssl_trace] = v
    end
    opts.on("--libssl PATH", "Path to libssl.so to attach SSL_write to") do |v|
      options[:libssl_path] = v
    end
    opts.on("--[no-]dlopen-trace", "Attach libc dlopen uprobe (default: enabled)") do |v|
      options[:dlopen_trace] = v
    end
    opts.on("--[no-]env-trace", "Attach libc getenv/setenv uprobes (default: enabled)") do |v|
      options[:env_trace] = v
    end
    opts.on("--libc PATH", "Path to libc.so for dlopen uprobe") do |v|
      options[:libc_path] = v
    end
  end.parse!(argv)

  Daemon.new(
    pin_dir: options[:pin_dir],
    socket_path: options[:socket_path],
    ssl_trace: options[:ssl_trace],
    libssl_path: options[:libssl_path],
    dlopen_trace: options[:dlopen_trace],
    env_trace: options[:env_trace],
    libc_path: options[:libc_path],
    usdt_so_paths: options[:usdt_so_paths]
  ).run
end

.scoped_observe(socket_path: self.socket_path, dest:, filter: nil, save_raw: nil) ⇒ Object

# File 'lib/vivarium.rb', line 2217

def self.scoped_observe(socket_path: self.socket_path, dest:, filter: nil, save_raw: nil)
  client = DaemonClient.new(socket_path: socket_path)
  pid = Process.pid
  main_tid = gettid

  correlator = Correlator.new(
    socket_path: socket_path,
    observer_pid: pid,
    main_tid: main_tid,
    filter: filter,
    dest: dest,
    save_raw: save_raw
  )
  correlator.start
  client.register(pid)

  tracer = build_observe_tracepoint
  tracer.enable

  yield
ensure
  tracer&.disable
  client&.unregister(pid)
  correlator&.stop
end

.socket_const_name(prefix, value) ⇒ Object

# File 'lib/vivarium.rb', line 296

def self.socket_const_name(prefix, value)
  return "UNKNOWN" unless defined?(Socket)

  key = Socket.constants.find do |name|
    name.to_s.start_with?(prefix) && Socket.const_get(name) == value
  rescue NameError
    false
  end

  key ? key.to_s : "UNKNOWN"
end

.strip_to_first_null(bytes) ⇒ Object

# File 'lib/vivarium.rb', line 597

def self.strip_to_first_null(bytes)
  nul = bytes.index("\x00")
  return bytes if nul.nil?

  bytes[0, nul]
end

.tail_fit_string(value, max_bytes, marker: "...") ⇒ Object

# File 'lib/vivarium.rb', line 225

def self.tail_fit_string(value, max_bytes, marker: "...")
  str = value.to_s.b
  return str if str.bytesize <= max_bytes
  return str.byteslice(-max_bytes, max_bytes) || "" if max_bytes <= marker.bytesize

  tail_size = max_bytes - marker.bytesize
  tail = str.byteslice(-tail_size, tail_size) || ""
  "#{marker}#{tail}"
end

.top_observe(socket_path: self.socket_path, dest: $stdout, filter: nil, save_raw: nil) ⇒ Object

# File 'lib/vivarium.rb', line 2191

def self.top_observe(socket_path: self.socket_path, dest: $stdout, filter: nil, save_raw: nil)
  client = DaemonClient.new(socket_path: socket_path)
  pid = Process.pid
  main_tid = gettid

  correlator = Correlator.new(
    socket_path: socket_path,
    observer_pid: pid,
    main_tid: main_tid,
    filter: filter,
    dest: dest,
    save_raw: save_raw
  )
  correlator.start
  client.register(pid)

  tracer = build_observe_tracepoint
  tracer.enable

  session = ObservationSession.new(
    client: client, pid: pid, tracer: tracer, correlator: correlator
  )
  at_exit { session.stop }
  session
end