Module: Vivarium

Defined in:
lib/vivarium.rb,
lib/vivarium/cli.rb,
lib/vivarium/version.rb,
lib/vivarium/correlator.rb,
lib/vivarium/http_decoder.rb,
lib/vivarium/tree_renderer.rb,
lib/vivarium/display_filter.rb

Defined Under Namespace

Modules: CLI Classes: Correlator, Daemon, DisplayFilter, Error, HttpDecoder, MapStore, ObservationSession, TreeRenderer

Constant Summary collapse

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")
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,
  File,
  Dir,
  Signal,
  Process,
  Process::UID,
  Process::GID,
  Net::HTTP,
]
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
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.4.1"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.bpf_pin_dir ⇒ Object 



161
162
163
 
# File 'lib/vivarium.rb', line 161

def bpf_pin_dir
  @bpf_pin_dir || PIN_DIR
end

Class Method Details

.build_observe_tracepoint ⇒ Object 



2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
 
# File 'lib/vivarium.rb', line 2027

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
    is_target = 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" : 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 



166
167
168
169
170
171
172
 
# File 'lib/vivarium.rb', line 166

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 



257
258
259
 
# File 'lib/vivarium.rb', line 257

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

.decode_bprm_creds_payload(raw_payload) ⇒ Object 



377
378
379
380
381
382
383
384
 
# File 'lib/vivarium.rb', line 377

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 



367
368
369
370
371
372
373
374
375
 
# File 'lib/vivarium.rb', line 367

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 



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/vivarium.rb', line 188

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 



423
424
425
426
427
428
429
430
431
432
433
434
435
 
# File 'lib/vivarium.rb', line 423

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 



282
283
284
285
286
287
288
289
 
# File 'lib/vivarium.rb', line 282

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 



291
292
293
294
295
296
297
298
 
# File 'lib/vivarium.rb', line 291

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 



268
269
270
271
272
273
 
# File 'lib/vivarium.rb', line 268

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 



275
276
277
278
279
280
 
# File 'lib/vivarium.rb', line 275

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 



261
262
263
264
265
266
 
# File 'lib/vivarium.rb', line 261

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_kernel_read_file_payload(raw_payload) ⇒ Object 



332
333
334
335
336
337
338
339
 
# File 'lib/vivarium.rb', line 332

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 



232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/vivarium.rb', line 232

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 



300
301
302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/vivarium.rb', line 300

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 



386
387
388
389
390
391
392
393
 
# File 'lib/vivarium.rb', line 386

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 



314
315
316
317
318
319
320
 
# File 'lib/vivarium.rb', line 314

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 



322
323
324
325
326
327
328
329
330
 
# File 'lib/vivarium.rb', line 322

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 



355
356
357
358
359
360
361
362
363
364
365
 
# File 'lib/vivarium.rb', line 355

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 



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/vivarium.rb', line 211

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 



395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
 
# File 'lib/vivarium.rb', line 395

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 



437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
 
# File 'lib/vivarium.rb', line 437

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 



412
413
414
415
416
417
418
419
420
421
 
# File 'lib/vivarium.rb', line 412

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 



341
342
343
344
345
346
347
348
349
350
351
352
353
 
# File 'lib/vivarium.rb', line 341

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 



184
185
186
 
# File 'lib/vivarium.rb', line 184

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

.gettid ⇒ Object 



2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
 
# File 'lib/vivarium.rb', line 2066

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 



2081
2082
2083
2084
2085
2086
2087
2088
2089
 
# File 'lib/vivarium.rb', line 2081

def self.locate_vivarium_usdt_so
  require "vivarium_usdt/vivarium_usdt"
  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 



2077
2078
2079
 
# File 'lib/vivarium.rb', line 2077

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

.observe(pin_dir: bpf_pin_dir, dest: $stdout, filter: nil, &block) ⇒ Object 



1965
1966
1967
1968
1969
 
# File 'lib/vivarium.rb', line 1965

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

  top_observe(pin_dir: pin_dir, dest: dest, filter: filter)
end

.render_event_payload(event) ⇒ Object 



462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
 
# File 'lib/vivarium.rb', line 462

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_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 



2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
 
# File 'lib/vivarium.rb', line 2091

def self.run_daemon!(argv = ARGV)
  options = { pin_dir: bpf_pin_dir, ssl_trace: true, libssl_path: nil,
              env_trace: true,
              dlopen_trace: true, libc_path: nil }
  OptionParser.new do |opts|
    opts.banner = "Usage: vivariumd [--pin-dir PATH] [--no-ssl-trace] [--libssl PATH] " \
                  "[--no-dlopen-trace] [--no-env-trace] [--libc PATH]"
    opts.on("--pin-dir PATH", "Pinned map directory") { |v| options[:pin_dir] = 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],
    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]
  ).run
end

.scoped_observe(pin_dir:, dest:, filter: nil) ⇒ Object 



1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 
# File 'lib/vivarium.rb', line 1999

def self.scoped_observe(pin_dir:, dest:, filter: nil)
  require "vivarium_usdt"

  store = MapStore.new(pin_dir: pin_dir)
  pid = Process.pid
  store.register_pid(pid)

  main_tid = gettid

  correlator = Correlator.new(
    pin_dir: pin_dir,
    observer_pid: pid,
    main_tid: main_tid,
    filter: filter,
    dest: dest
  )
  correlator.start

  tracer = build_observe_tracepoint
  tracer.enable

  yield
ensure
  tracer&.disable
  store&.unregister_pid(pid)
  correlator&.stop
end

.socket_const_name(prefix, value) ⇒ Object 



245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/vivarium.rb', line 245

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 



534
535
536
537
538
539
 
# File 'lib/vivarium.rb', line 534

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 



174
175
176
177
178
179
180
181
182
 
# File 'lib/vivarium.rb', line 174

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(pin_dir: bpf_pin_dir, dest: $stdout, filter: nil) ⇒ Object 



1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
 
# File 'lib/vivarium.rb', line 1971

def self.top_observe(pin_dir: bpf_pin_dir, dest: $stdout, filter: nil)
  require "vivarium_usdt"

  store = MapStore.new(pin_dir: pin_dir)
  pid = Process.pid
  store.register_pid(pid)

  main_tid = gettid

  correlator = Correlator.new(
    pin_dir: pin_dir,
    observer_pid: pid,
    main_tid: main_tid,
    filter: filter,
    dest: dest
  )
  correlator.start

  tracer = build_observe_tracepoint
  tracer.enable

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