vanken 0.1.0

data/lib/vanken/capture/launcher.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "json"
+require "rbconfig"
+
+module Vanken
+  module Capture
+    class Launcher
+      class Unavailable < StandardError; end
+      WRAPPER = "/usr/local/libexec/vanken/vanken-capture"
+      SAFE_ENV = %w[DISPLAY WAYLAND_DISPLAY XDG_RUNTIME_DIR DBUS_SESSION_BUS_ADDRESS XAUTHORITY LANG LC_ALL TERM].freeze
+
+      class Handle
+        attr_reader :pid, :stdin, :stdout, :stderr, :status
+
+        def initialize(pid, stdin, stdout, stderr)
+          @pid, @stdin, @stdout, @stderr = pid, stdin, stdout, stderr
+          @reap_lock = Mutex.new
+        end
+
+        def wait(timeout: nil)
+          deadline = timeout && (monotonic + timeout)
+          loop do
+            @reap_lock.synchronize do
+              return @status if @reaped
+              result = Process.waitpid2(@pid, Process::WNOHANG)
+              @reaped, @status = true, result.last if result
+              return @status if @reaped
+            rescue Errno::ECHILD
+              @reaped = true
+              return @status
+            end
+            return if deadline && monotonic >= deadline
+
+            sleep 0.01
+          end
+        end
+
+        def stop(timeout: 3)
+          @stdin.close unless @stdin.closed?
+          signal("TERM") unless @reaped
+          return @status if wait(timeout: timeout)
+
+          signal("KILL") unless @reaped
+          wait
+        end
+
+        def close
+          stop
+          [@stdout, @stderr].each { |io| io.close unless io.closed? }
+        end
+
+        private
+
+        def signal(signal)
+          @reap_lock.synchronize do
+            return if @reaped
+
+            result = Process.waitpid2(@pid, Process::WNOHANG)
+            if result
+              @reaped, @status = true, result.last
+            else
+              Process.kill(signal, -@pid)
+            end
+          end
+        rescue Errno::ECHILD
+          @reaped = true
+        rescue Errno::ESRCH
+          nil
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def initialize(strategy: :auto, wrapper: WRAPPER, direct_command: nil, askpass: nil, env: ENV)
+        @strategy, @wrapper, @askpass, @env = strategy.to_sym, wrapper, askpass, env
+        lib = File.expand_path("../..", __dir__)
+        helper = File.expand_path("../../../exe/vanken-capture", __dir__)
+        dependency_paths = Gem.loaded_specs.fetch("redhound", nil)&.full_require_paths || []
+        @direct_command = direct_command || [RbConfig.ruby, "-I", ([lib] + dependency_paths).join(File::PATH_SEPARATOR), helper]
+      end
+
+      def launch(options = [], strategy: @strategy)
+        args = options.is_a?(Array) ? options : capture_argv(options.respond_to?(:capture) ? options.capture : options)
+        strategy = strategy.to_sym
+        strategy = automatic_strategy(args) if strategy == :auto
+        command, extra_env = command_for(strategy, args)
+        spawn(command, extra_env)
+      rescue SystemCallError => e
+        raise Unavailable, "cannot launch capture helper: #{e.message}"
+      end
+
+      def command_for(strategy, args)
+        return [@direct_command + args, {}] if strategy == :direct
+        raise Unavailable, "use direct capture or install the root-owned capture helper; developer sudo is disabled" unless %i[pkexec sudo].include?(strategy)
+
+        trusted_path!(@wrapper)
+        raise Unavailable, "capture must be launched by an unprivileged user" if Process.uid.zero? || Process.gid.zero?
+
+        args = args + ["--drop-to", "#{Process.uid}:#{Process.gid}"]
+        if strategy == :pkexec
+          executable = executable("pkexec") || raise(Unavailable, "pkexec is unavailable")
+          [[executable, @wrapper] + args, {}]
+        else
+          executable = executable("sudo") || raise(Unavailable, "sudo is unavailable")
+          trusted_path!(@askpass) if @askpass
+          [[executable, @askpass ? "-A" : "-n", "--", @wrapper] + args,
+           @askpass ? {"SUDO_ASKPASS" => @askpass} : {}]
+        end
+      end
+
+      def self.trusted_path?(path)
+        return false unless path && path.start_with?("/") && File.realpath(path) == path && File.file?(path) && File.executable?(path)
+
+        current = path
+        loop do
+          stat = File.stat(current)
+          return false unless stat.uid.zero? && (stat.mode & 0o022).zero?
+          return true if current == "/"
+
+          current = File.dirname(current)
+        end
+      rescue SystemCallError
+        false
+      end
+
+      private
+
+      def spawn(command, extra_env = {})
+        input_read, input_write = IO.pipe
+        output_read, output_write = IO.pipe
+        error_read, error_write = IO.pipe
+        env = @env.to_h.slice(*SAFE_ENV).merge("PATH" => "/usr/bin:/bin:/usr/sbin:/sbin").merge(extra_env)
+        pid = Process.spawn(env, [command.first, command.first], *command.drop(1),
+                            in: input_read, out: output_write, err: error_write, unsetenv_others: true, close_others: true, pgroup: true)
+        handle = Handle.new(pid, input_write, output_read, error_read)
+      ensure
+        [input_write, output_read, error_read].compact.each { |io| io.close unless io.closed? } unless handle
+        [input_read, output_write, error_write].compact.each { |io| io.close unless io.closed? }
+      end
+
+      def automatic_strategy(args)
+        interface_index = args.index("--interface") || args.index("-i")
+        check_args = ["--check"]
+        check_args += ["--interface", args.fetch(interface_index + 1)] if interface_index
+        handle = spawn(@direct_command + check_args)
+        if handle.wait(timeout: 3)
+          diagnostic = JSON.parse(handle.stdout.read(65_537)) rescue {}
+          return :direct if diagnostic["direct"] == true
+        end
+        trusted_path!(@wrapper)
+        if RUBY_PLATFORM.include?("linux") && (@env["DISPLAY"] || @env["WAYLAND_DISPLAY"]) && executable("pkexec")
+          :pkexec
+        elsif executable("sudo")
+          :sudo
+        else
+          raise Unavailable, "capture permission is unavailable; install the root-owned capture helper"
+        end
+      ensure
+        handle&.close
+      end
+
+      def trusted_path!(path)
+        raise Unavailable, "capture helper must be executable in a root-owned directory without group or other write access" unless self.class.trusted_path?(path)
+      end
+
+      def executable(name)
+        %w[/usr/bin /bin].map { |directory| File.join(directory, name) }.find { |path| File.executable?(path) }
+      end
+
+      def capture_argv(options)
+        options.flat_map do |key, value|
+          next [] if value.nil?
+          next value ? [] : ["--no-promiscuous"] if key.to_sym == :promiscuous
+
+          ["--#{key.to_s.tr('_', '-')}", value.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/vanken/capture/privileges.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Vanken
+  module Capture
+    module Privileges
+      class Error < StandardError; end
+
+      def self.drop!(uid, gid)
+        raise Error, "refusing a root identity" unless uid.is_a?(Integer) && gid.is_a?(Integer) && uid.positive? && gid.positive?
+
+        Process.groups = []
+        Process::GID.change_privilege(gid)
+        Process::UID.change_privilege(uid)
+        unless Process.uid == uid && Process.euid == uid && Process.gid == gid && Process.egid == gid && Process.groups.empty?
+          raise Error, "could not verify dropped privileges"
+        end
+
+        true
+      rescue SystemCallError => e
+        raise Error, "could not drop privileges: #{e.message}"
+      end
+    end
+  end
+end

data/lib/vanken/capture/receiver.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Vanken
+  module Capture
+    class Receiver
+      def initialize(document, source) = (@document, @source = document, source)
+      def run
+        flushed_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        each_frame do |frame|
+          break if @document.cancelled?
+          number = @document.store.append(frame) if frame
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if (number && (number % 256 == 0 || number == 50)) || now - flushed_at >= 0.05
+            @document.store.flush
+            @document.signal
+            flushed_at = now
+            Thread.pass
+          end
+        end
+      rescue StandardError => error
+        @document.fail(error)
+      ensure
+        @document.store.flush
+        @document.receiving_done
+        @source.close if @source.respond_to?(:close)
+      end
+      private
+      def each_frame
+        return @source.each { |frame| yield frame } unless @source.respond_to?(:next_frame)
+
+        until @document.cancelled?
+          yield @source.next_frame(timeout: 0.05)
+          break if @source.eof?
+        end
+      end
+    end
+  end
+end

data/lib/vanken/cli.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Vanken
+  module CLI
+    def self.start(argv, out: $stdout, err: $stderr)
+      options = {}
+      parser = OptionParser.new do |flags|
+        flags.banner = "Usage: vanken [options] [capture.pcapng]"
+        flags.on("--version", "Show version") { out.puts(VERSION); return 0 }
+        flags.on("-h", "--help", "Show help") { out.puts(flags); return 0 }
+        flags.on("-r PATH", "--read PATH", "Open a pcap or pcapng capture") { |value| options[:path] = value }
+        flags.on("--headless", "Run without a native window") { options[:headless] = true }
+        flags.on("--print-columns", "Print tab-separated packet columns") { options[:print_columns] = true }
+        flags.on("--filter EXPR", "Apply a Vanken display filter") { |value| options[:filter] = value }
+        flags.on("--tui", "Run in a terminal") { options[:tui] = true }
+        flags.on("--smoke", "Draw three frames and exit") { options[:smoke] = true }
+        flags.on("--allow-root", "Allow privileged UI with a warning") { options[:allow_root] = true }
+        flags.on("--no-yjit", "Do not enable YJIT") { options[:no_yjit] = true }
+        flags.on("--debug", "Enable debug logging") { options[:debug] = true }
+      end
+      remaining = parser.parse(argv.dup)
+      raise OptionParser::InvalidArgument, "only one capture path is accepted" if remaining.size > 1 || (options[:path] && !remaining.empty?)
+      options[:path] ||= remaining.first
+      raise OptionParser::InvalidArgument, "--tui and --headless cannot be combined" if options[:tui] && options[:headless]
+      RubyVM::YJIT.enable if defined?(RubyVM::YJIT.enable) && !options[:no_yjit]
+      if options[:print_columns]
+        raise OptionParser::InvalidArgument, "--print-columns needs --read or a capture path" unless options[:path]
+        return print_columns(options, out)
+      end
+      if Process.euid.zero? && !options[:allow_root]
+        err.puts("Vanken refuses to run its UI as root. Run the capture helper with capture privileges instead.")
+        return 3
+      end
+      err.puts("Warning: running the packet analysis UI as root.") if Process.euid.zero?
+      require_relative "ui/application"
+      application = UI::Application.new(backend: options[:headless] ? :headless : options[:tui] ? :tui : nil, debug: options[:debug])
+      application.open_file(options[:path]) if options[:path]
+      application.initial_filter(options[:filter]) if options[:filter]
+      options[:smoke] ? application.smoke : application.run
+      0
+    rescue OptionParser::ParseError => error
+      err.puts(error.message)
+      2
+    rescue Vanken::Error, Core::DisplayFilter::SyntaxError, IOError, SystemCallError => error
+      err.puts(error.message)
+      1
+    ensure
+      application&.close
+    end
+
+    def self.print_columns(options, out)
+      document = App::Document.new.open(options[:path]).wait
+      raise document.error if document.error
+      document.apply_filter(options[:filter]).wait if options[:filter]
+      raise document.error if document.error
+      out.puts("No.\tTime\tSource\tDestination\tProtocol\tLength\tInfo")
+      document.display_numbers.each do |number|
+        row = document.row(number)
+        out.puts([number, format("%.6f", document.time_value(number)), row[:source], row[:destination], row[:protocol], row[:length], row[:info]].join("\t"))
+      end
+      0
+    ensure
+      document&.close
+    end
+  end
+end

data/lib/vanken/config/log.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "logger"
+require "fileutils"
+
+module Vanken
+  module Config
+    module Log
+      def self.open(debug: false, directory: Paths.state)
+        FileUtils.mkdir_p(directory, mode: 0o700)
+        File.chmod(0o700, directory)
+        path = File.join(directory, "vanken.log")
+        File.open(path, File::WRONLY | File::CREAT | File::APPEND, 0o600, &:close)
+        File.chmod(0o600, path)
+        Logger.new(path, 5, 1 << 20, level: debug ? Logger::DEBUG : Logger::INFO)
+      end
+    end
+  end
+end

data/lib/vanken/config/preferences.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "yaml"
+require "fileutils"
+require "logger"
+require "tempfile"
+
+module Vanken
+  module Config
+    module Paths
+      def self.config
+        case RUBY_PLATFORM
+        when /darwin/ then File.join(Dir.home, "Library", "Application Support", "Vanken")
+        when /mingw|mswin/ then File.join(ENV.fetch("APPDATA", Dir.home), "Vanken")
+        else File.join(ENV.fetch("XDG_CONFIG_HOME", File.join(Dir.home, ".config")), "vanken")
+        end
+      end
+      def self.state
+        return File.join(config, "state") unless RUBY_PLATFORM.include?("linux")
+        File.join(ENV.fetch("XDG_STATE_HOME", File.join(Dir.home, ".local", "state")), "vanken")
+      end
+    end
+
+    class Preferences
+      DEFAULTS = {
+        "schema_version" => 1,
+        "appearance" => {"theme" => "system", "font_size" => 13, "language" => "ja"},
+        "packet_list" => {"time_format" => "relative", "time_precision" => "micro", "autoscroll" => true, "row_cache_rows" => 20_000},
+        "capture" => {"snaplen" => 262_144, "promiscuous" => true, "buffer_size" => 4 << 20, "backend" => "auto", "launcher" => "auto", "direction" => "inout"},
+        "analysis" => {"verify_checksums" => false, "max_state_mib" => 256, "max_flows" => 100_000, "workers" => 4},
+        "history" => [], "recent_files" => [], "bookmarks" => {}, "layout" => {"ratios" => [0.55, 0.6], "width" => 1280, "height" => 800, "columns" => []}
+      }.freeze
+      attr_reader :warning, :directory
+
+      def initialize(directory: Paths.config)
+        @directory = directory
+        @values = Marshal.load(Marshal.dump(DEFAULTS))
+        path = File.join(directory, "preferences.yml")
+        return unless File.file?(path)
+        saved = YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
+        raise Vanken::ConfigError, "unsupported preferences schema" unless saved.is_a?(Hash) && saved["schema_version"] == 1
+        merge(@values, saved)
+        validate
+      rescue Psych::Exception, Vanken::ConfigError, SystemCallError, TypeError => error
+        @values = Marshal.load(Marshal.dump(DEFAULTS))
+        @warning = error.message
+      end
+
+      def get(path) = path.split(".").reduce(@values) { |value, key| value.fetch(key) }
+      def set(path, value)
+        keys = path.split(".")
+        target = keys[0...-1].reduce(@values) { |hash, key| hash.fetch(key) }
+        previous = target.fetch(keys.last)
+        target[keys.last] = value
+        validate
+        save
+        value
+      rescue Vanken::ConfigError
+        target[keys.last] = previous
+        raise
+      end
+      def history = @values["history"].dup
+      def recent_files = @values["recent_files"].dup
+      def bookmarks = @values["bookmarks"].dup
+      def remember_filter(expression) = remember("history", expression, 50)
+      def remember_file(path) = remember("recent_files", File.expand_path(path), 10)
+      def bookmark(name, expression)
+        @values["bookmarks"][name] = expression
+        save
+      end
+      def save
+        FileUtils.mkdir_p(@directory, mode: 0o700)
+        File.chmod(0o700, @directory)
+        temporary = Tempfile.create(["preferences-", ".tmp"], @directory)
+        temporary.write(YAML.dump(@values))
+        temporary.flush
+        temporary.fsync
+        temporary.close
+        File.rename(temporary.path, File.join(@directory, "preferences.yml"))
+      ensure
+        temporary&.close unless temporary&.closed?
+        File.unlink(temporary.path) if temporary && File.exist?(temporary.path)
+      end
+
+      private
+
+      def remember(key, value, limit)
+        @values[key] = ([value] + @values[key].reject { |entry| entry == value }).first(limit)
+        save
+      end
+      def merge(base, saved)
+        saved.each do |key, value|
+          next unless base.key?(key)
+          key == "bookmarks" || !base[key].is_a?(Hash) || !value.is_a?(Hash) ? base[key] = value : merge(base[key], value)
+        end
+      end
+      def validate
+        validate_shape(DEFAULTS, @values)
+        raise Vanken::ConfigError, "invalid theme" unless %w[system dark light high_contrast].include?(get("appearance.theme"))
+        raise Vanken::ConfigError, "invalid font size" unless get("appearance.font_size").is_a?(Integer) && get("appearance.font_size").between?(8, 32)
+        raise Vanken::ConfigError, "invalid time format" unless %w[relative absolute delta delta_displayed epoch].include?(get("packet_list.time_format"))
+        raise Vanken::ConfigError, "invalid time precision" unless %w[milli micro nano].include?(get("packet_list.time_precision"))
+        raise Vanken::ConfigError, "invalid history" unless history.all? { |item| item.is_a?(String) } && recent_files.all? { |item| item.is_a?(String) } && bookmarks.all? { |name, expression| name.is_a?(String) && expression.is_a?(String) }
+        {"analysis.workers" => 1..32, "analysis.max_state_mib" => 1..65_536, "analysis.max_flows" => 1..10_000_000,
+          "capture.snaplen" => 1..16_777_216, "capture.buffer_size" => 65_536..268_435_456,
+          "packet_list.row_cache_rows" => 1..100_000, "layout.width" => 320..65_536, "layout.height" => 240..65_536}.each do |path, range|
+          raise Vanken::ConfigError, "invalid #{path}" unless range.cover?(get(path))
+        end
+        raise Vanken::ConfigError, "invalid split ratios" unless get("layout.ratios").size == 2 && get("layout.ratios").all? { |ratio| ratio.is_a?(Numeric) && ratio.finite? && ratio.between?(0.1, 0.9) }
+        columns = get("layout.columns")
+        raise Vanken::ConfigError, "invalid columns" unless columns.all? { |column| column.is_a?(Hash) && %w[no time source destination protocol length info].include?(column["key"]) && column["width"].is_a?(Numeric) && column["width"].finite? && column["width"].between?(40, 4096) && [true, false].include?(column["visible"]) } && columns.map { |column| column["key"] }.uniq.size == columns.size
+        raise Vanken::ConfigError, "invalid capture settings" unless %w[auto direct sudo pkexec].include?(get("capture.launcher")) && %w[auto ring socket bpf].include?(get("capture.backend")) && %w[in out inout].include?(get("capture.direction"))
+      rescue NoMethodError, KeyError
+        raise Vanken::ConfigError, "invalid preferences shape"
+      end
+      def validate_shape(default, value)
+        valid = [true, false].include?(default) ? [true, false].include?(value) : value.is_a?(default.class)
+        raise Vanken::ConfigError, "invalid preferences shape" unless valid
+        if default.is_a?(Hash)
+          default.each { |key, expected| validate_shape(expected, value.fetch(key)) }
+        end
+      end
+    end
+  end
+end

data/lib/vanken/core/display_filter/compiler.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+require_relative "field_resolver"
+require_relative "types"
+
+module Vanken
+  module Core
+    module DisplayFilter
+      class Program
+        attr_reader :expression #: String
+        attr_reader :fields #: Array[String]
+        attr_reader :sources #: Array[Symbol]
+        attr_reader :warnings #: Array[String]
+
+        # @rbs (expression: String, fields: Array[String], sources: Array[Symbol], warnings: Array[String], evaluator: ^(untyped) -> bool) -> void
+        def initialize(expression:, fields:, sources:, warnings:, evaluator:)
+          @expression = expression.freeze
+          @fields = fields.uniq.freeze
+          @sources = sources.uniq.freeze
+          @warnings = warnings.uniq.freeze
+          @evaluator = evaluator
+          freeze
+        end
+
+        # @rbs (_FilterView view) -> bool
+        def match?(view) = !!@evaluator.call(view)
+        # @rbs () -> bool
+        def fast? = !sources.include?(:dissect)
+      end
+
+      class Compiler
+        # @rbs (?catalog: untyped) -> void
+        def initialize(catalog: nil)
+          @resolver = FieldResolver.new(catalog)
+          @fields = [] #: Array[String]
+          @sources = [] #: Array[Symbol]
+          @warnings = [] #: Array[String]
+        end
+
+        # @rbs (String expression) -> Program
+        def compile(expression)
+          @fields = [] #: Array[String]
+          @sources = [] #: Array[Symbol]
+          @warnings = [] #: Array[String]
+          parser = Parser.new(expression)
+          ast = parser.parse
+          evaluator = compile_node(ast)
+          Program.new(expression: expression.dup, fields: @fields, sources: @sources,
+                      warnings: parser.warnings + @warnings, evaluator: evaluator)
+        end
+
+        private
+
+        # @rbs (Node node) -> ^(untyped) -> bool
+        def compile_node(node)
+          case node.kind
+          when :true then ->(_) { true }
+          when :not
+            child = compile_node(node.left)
+            ->(view) { !child.call(view) }
+          when :and, :or
+            left = compile_node(node.left)
+            right = compile_node(node.right)
+            node.kind == :and ? ->(view) { left.call(view) && right.call(view) } :
+                                ->(view) { left.call(view) || right.call(view) }
+          when :test then compile_test(node)
+          else raise ArgumentError, "Unknown filter node: #{node.kind}"
+          end
+        end
+
+        # @rbs (Node node) -> ^(untyped) -> bool
+        def compile_test(node)
+          reference = @resolver.resolve(node.left.value)
+          @fields << reference.name
+          @sources << reference.source
+          @warnings << "Unknown field: #{reference.name}" unless reference.known
+          if reference.protocol
+            Types.fail_at("Protocols only support presence tests", node.right.token) if node.right
+            return ->(view) { view.layer?(reference.name) }
+          end
+          return ->(view) { !Array(view.values(reference.name)).compact.empty? } unless node.right
+
+          operator = node.right.operator
+          predicate = %i[ne any_ne].include?(operator) ?
+            Predicate.new(:eq, node.right.values, node.right.token) : node.right
+          comparison = Types.predicate(predicate, reference.type)
+          lambda do |view|
+            values = Array(view.values(reference.name)).compact
+            type = @resolver.normalize_type(view.field_type(reference.name)) if !reference.type && view.respond_to?(:field_type)
+            if operator == :ne
+              values.none? { |value| comparison.call(value, type) }
+            elsif operator == :any_ne
+              values.any? { |value| !comparison.call(value, type) }
+            else
+              values.any? { |value| comparison.call(value, type) }
+            end
+          end
+        end
+      end
+
+      # @rbs (String expression, ?catalog: untyped) -> Program
+      def self.compile(expression, catalog: nil)
+        Compiler.new(catalog: catalog).compile(expression)
+      end
+    end
+  end
+end

data/lib/vanken/core/display_filter/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Vanken
+  module Core
+    module DisplayFilter
+      class SyntaxError < StandardError
+        attr_reader :position #: Integer
+        attr_reader :length #: Integer
+
+        # @rbs (String message, position: Integer, ?length: Integer) -> void
+        def initialize(message, position:, length: 1)
+          super(message)
+          @position = position
+          @length = length
+        end
+      end
+    end
+  end
+end

data/lib/vanken/core/display_filter/field_resolver.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../stores"
+
+module Vanken
+  module Core
+    module DisplayFilter
+      Reference = Data.define(
+        :name, #: String
+        :type, #: field_type?
+        :source, #: Symbol
+        :protocol, #: bool
+        :known #: bool
+      )
+
+      class FieldResolver
+        PROTOCOLS = %w[eth vlan arp ip ipv6 icmp icmpv6 igmp tcp udp gre vxlan dns dhcp ntp http tls data].freeze
+        FRAME_FIELDS = {
+          "frame.number" => :integer, "frame.len" => :integer, "frame.cap_len" => :integer,
+          "frame.time_epoch" => :float, "frame.time_relative" => :float, "frame.time_delta" => :float,
+          "frame.time_delta_displayed" => :float, "frame.interface_name" => :string,
+          "frame.direction" => :string, "frame.marked" => :boolean, "frame.ignored" => :boolean
+        }.freeze
+        VIRTUAL_FIELDS = {
+          "frame.protocols" => :string, "ip.addr" => :address, "ipv6.addr" => :address,
+          "eth.addr" => :mac, "tcp.port" => :integer, "udp.port" => :integer,
+          "tcp.stream" => :integer, "expert.severity" => :severity, "expert.code" => :string,
+          **%w[syn ack fin rst psh urg].to_h { |flag| ["tcp.flags.#{flag}", :boolean] }
+        }.freeze
+
+        # @rbs (?untyped catalog) -> void
+        def initialize(catalog = nil)
+          @catalog = catalog
+        end
+
+        # @rbs (String name) -> Reference
+        def resolve(name)
+          entry = @catalog&.lookup(name)
+          type = FRAME_FIELDS[name] || VIRTUAL_FIELDS[name] || metadata(entry, :type)
+          if name == "tcp.analysis.flags" || Core::AnnotationStore::FLAGS.any? { |flag| name == "tcp.analysis.#{flag}" }
+            type = :boolean
+          end
+          protocol = !name.include?(".") && (PROTOCOLS.include?(name) || @catalog&.protocol?(name))
+          source = if FRAME_FIELDS.key?(name)
+            :frame
+          elsif name == "tcp.stream" || name.start_with?("tcp.analysis.", "expert.")
+            :annotation
+          elsif protocol || %w[tcp.port udp.port].include?(name)
+            :column
+          else
+            metadata(entry, :source) || :dissect
+          end
+          Reference.new(name, normalize_type(type), source.to_sym, !!protocol, !!(type || entry || protocol))
+        end
+
+        # @rbs (untyped type) -> field_type?
+        def normalize_type(type)
+          return nil unless type
+
+          name = type.to_s.downcase
+          return :integer if /\A(?:u?int\d*|integer|bitfield|bit_field|bits)\z/.match?(name)
+          return :float if %w[float double time timestamp number].include?(name)
+          return :boolean if %w[boolean bool].include?(name)
+          return :address if %w[ipv4 ipv6 ipaddr address].include?(name)
+          return :mac if %w[mac macaddr mac_address].include?(name)
+          return :bytes if %w[bytes byte_array raw binary].include?(name)
+          return :string if %w[string str text].include?(name)
+          return :severity if name == "severity"
+
+          nil
+        end
+
+        private
+
+        # @rbs (untyped entry, Symbol key) -> untyped
+        def metadata(entry, key)
+          return nil unless entry
+          return entry[key] || entry[key.to_s] if entry.is_a?(Hash)
+          return entry.public_send(key) if entry.respond_to?(key)
+
+          nil
+        end
+      end
+    end
+  end
+end