vanken 0.1.0

data/lib/vanken/capture/analyzer_worker.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "../../vanken"
+require_relative "analyzer_wire"
+
+module Vanken
+  module Capture
+    class AnalyzerWorker
+      class Reader
+        attr_accessor :limit, :interfaces
+        def initialize(directory)
+          @records = File.open(File.join(directory, "frames.idx"), "rb")
+          @data = File.open(File.join(directory, "frames.bin"), "rb")
+          @limit, @interfaces = 0, []
+        end
+        def metadata(number)
+          raise Vanken::Error, "frame outside published range" unless number.between?(1, @limit)
+          record = read_at(@records, Core::FrameStore::RECORD_SIZE, (number - 1) * Core::FrameStore::RECORD_SIZE)
+          raise Vanken::Error, "truncated analysis index" unless record.bytesize == Core::FrameStore::RECORD_SIZE
+          offset, caplen, original, time, link, interface, direction = record.unpack(Core::FrameStore::RECORD)
+          raise Vanken::Error, "invalid analysis frame" unless caplen <= 16 << 20 && original >= caplen && direction <= 2
+          {offset: offset, caplen: caplen, original_length: original, timestamp_ns: time, linktype: link,
+           interface: interface == 0xffff ? nil : @interfaces.fetch(interface), direction: [nil, :in, :out].fetch(direction), number: number}
+        end
+        def read(number)
+          meta = metadata(number)
+          bytes = meta[:caplen].zero? ? "".b : read_at(@data, meta[:caplen], meta[:offset])
+          raise Vanken::Error, "truncated analysis frame" unless bytes.bytesize == meta[:caplen]
+          Core::Frame.new(bytes: bytes, timestamp_ns: meta[:timestamp_ns], original_length: meta[:original_length],
+            linktype: meta[:linktype], interface: meta[:interface], direction: meta[:direction], number: number)
+        end
+        def close
+          @records.close
+          @data.close
+        end
+        private
+        def read_at(io, size, offset)
+          return io.pread(size, offset) if io.respond_to?(:pread)
+          io.seek(offset)
+          io.read(size) || "".b
+        end
+      end
+
+      class Context
+        attr_reader :store
+        def initialize(store) = (@store = store)
+        def time_value(number, _format, references:)
+          reference = references.select { |value| value <= number }.max || 1
+          (@store.metadata(number)[:timestamp_ns] - @store.metadata(reference)[:timestamp_ns]) / 1e9
+        end
+        def displayed_predecessor(number, snapshot)
+          return number - 1 if snapshot[:unfiltered_predecessor]
+          return snapshot[:last_displayed] || 0 if number > snapshot[:limit]
+          snapshot[:predecessors] ? snapshot[:predecessors].fetch(number, 0) : number - 1
+        end
+      end
+
+      def initialize(request)
+        @reader = Reader.new(request.fetch(:spool))
+        @dissector = Gateway::Dissector.new(verify_checksums: request.fetch(:verify_checksums))
+        @analysis = Gateway::Analysis.new(registry: @dissector.registry, **request.fetch(:analysis_options))
+        @columns = Core::ColumnStore.new
+        @annotations = Core::AnnotationStore.new(request.fetch(:spool), persist: false)
+        @catalog = Gateway::FieldCatalog.new
+        @seen_fields = @catalog.names.to_set
+        @context = Context.new(@reader)
+        @next = 1
+      end
+      def analyze(request)
+        first, last = request.values_at(:first, :last)
+        raise Vanken::Error, "nonsequential analysis batch" unless first == @next && last >= first && last - first < 256
+        @reader.limit, @reader.interfaces = last, request.fetch(:interfaces)
+        @packets = []
+        summaries, summary_index, details, definitions = +"".b, +"".b, {}, {}
+        (first..last).each do |number|
+          frame = @reader.read(number)
+          begin
+            packet = @dissector.dissect(frame)
+            @analysis.update(packet)
+            columns, annotation, info = packet.columns, packet.annotations, packet.info
+            packet.fields.each do |field|
+              next unless @seen_fields.add?(field.name)
+              definitions[field.name] = {type: field.type, source: :dissect, protocol: field.name.split(".").first}
+            end
+            if packet.reassembled?
+              details[number] = JSON.generate("nodes" => Gateway::DetailBuilder.new.build(packet).map(&:to_h), "info" => info,
+                "packet" => Gateway::PacketSnapshot.from_packet(packet).to_h) + "\n"
+            end
+          rescue StandardError => error
+            packet = nil
+            columns = {source: "", destination: "", protocol: "Malformed", src_port: -1, dst_port: -1, ip_proto: -1, layers: []}
+            annotation = {tcp_stream: -1, seq_rel: -1, ack_rel: -1, analysis_flags: [], expert_max: 3,
+              expert_items: [{severity: :error, code: "vanken.internal_error", protocol: "vanken", message: error.message}], extra: {}}
+            info = error.message
+          end
+          @packets << packet
+          @columns.append(columns)
+          @annotations.append(number, annotation)
+          summary_index << [summaries.bytesize].pack("Q<")
+          summaries << [info.bytesize].pack("L<") << info
+        end
+        @next = last + 1
+        @catalog.merge(definitions)
+        @batch = {first: first, last: last, columns: @columns.drain, annotations: @annotations.drain,
+          summaries: summaries, summary_index: summary_index, details: details, fields: definitions}
+        @batch.merge(matches: matches(request))
+      end
+      def matches(request)
+        expression = request.fetch(:expression)
+        return (@batch[:first]..@batch[:last]).to_a if expression.empty?
+        program = Core::DisplayFilter.compile(expression, catalog: @catalog)
+        snapshot = request.fetch(:snapshot).dup
+        @packets.each_with_index.filter_map do |packet, index|
+          number = @batch[:first] + index
+          next unless packet
+          matched = program.match?(Core::FrameView.new(@context, number, packet: packet, snapshot: snapshot))
+          snapshot[:last_displayed] = number if matched && !request[:historical_context]
+          number if matched
+        end
+      end
+      def close
+        @analysis.close
+      ensure
+        @reader.close
+      end
+      def self.run
+        $stdin.binmode
+        $stdout.binmode
+        worker = nil
+        loop do
+          request = AnalyzerWire.read($stdin)
+          response = case request.fetch(:command)
+          when :start
+            raise Vanken::Error, "duplicate analysis start" if worker
+            worker = new(request)
+            {pid: Process.pid}
+          when :analyze then worker.analyze(request)
+          when :match then {matches: worker.matches(request)}
+          when :stop then break
+          else raise Vanken::Error, "unknown analysis command"
+          end
+          AnalyzerWire.write($stdout, response)
+        rescue StandardError => error
+          AnalyzerWire.write($stdout, {error: "#{error.class}: #{error.message}"})
+          break
+        end
+      ensure
+        worker&.close
+      end
+    end
+  end
+end
+Vanken::Capture::AnalyzerWorker.run if $PROGRAM_NAME == __FILE__

data/lib/vanken/capture/control_protocol.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Vanken
+  module Capture
+    class ControlProtocol
+      TYPES = %w[hello started stats warning error stopped].freeze
+      MAX_LINE_BYTES = 65_536
+
+      def initialize(io)
+        @io = io
+      end
+
+      def write(type, **fields)
+        raise ArgumentError, "unknown control message: #{type}" unless TYPES.include?(type.to_s)
+
+        @io.write(JSON.generate(fields.merge(v: 1, type: type.to_s)) << "\n")
+        @io.flush
+      end
+
+      def self.parse(line)
+        return if line.bytesize > MAX_LINE_BYTES
+
+        value = JSON.parse(line)
+        value if value.is_a?(Hash) && value["v"] == 1 && TYPES.include?(value["type"])
+      rescue JSON::ParserError, EncodingError
+        nil
+      end
+    end
+  end
+end

data/lib/vanken/capture/filter_worker.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "set"
+require_relative "../errors"
+require_relative "../core/frame_store"
+require_relative "../core/stores"
+require_relative "../core/display_filter/compiler"
+require_relative "../gateway/dissector"
+
+module Vanken
+  module Capture
+    class FilterWorker
+      class Reader
+        attr_reader :count
+
+        def initialize(directory, annotations_json)
+          @files = []
+          @index = open_file(File.join(directory, "frames.idx"))
+          @data = open_file(File.join(directory, "frames.bin"))
+          @annotations = open_file(File.join(directory, "annotations.bin"))
+          @count = @index.size / Core::FrameStore::RECORD_SIZE
+          detail_index = File.join(directory, "reassembled.idx")
+          if File.file?(detail_index)
+            offsets = open_file(detail_index)
+            @detail_offsets = read_exact(offsets, (offsets.size / 16) * 16, 0).unpack("Q<*").each_slice(2).to_h
+            @details = open_file(File.join(directory, "details.jsonl"))
+          end
+          interface_path = File.join(directory, "interfaces.json")
+          @interfaces = File.file?(interface_path) ? JSON.parse(File.read(interface_path)) : []
+          @sparse = File.file?(annotations_json) ? JSON.parse(File.read(annotations_json)) : {}
+        rescue StandardError
+          close
+          raise
+        end
+
+        def metadata(number)
+          raise IndexError, "invalid frame number" unless number.is_a?(Integer) && number.between?(1, count)
+
+          offset, caplen, original, timestamp, linktype, interface, direction =
+            read_exact(@index, Core::FrameStore::RECORD_SIZE, (number - 1) * Core::FrameStore::RECORD_SIZE).unpack(Core::FrameStore::RECORD)
+          raise IOError, "invalid frame spool record" unless caplen <= 16 << 20 && caplen <= original && offset + caplen <= @data.size && direction <= 2
+
+          {offset: offset, caplen: caplen, original_length: original, timestamp_ns: timestamp,
+           linktype: linktype, interface: interface == 0xffff ? nil : @interfaces.fetch(interface),
+           direction: [nil, :in, :out].fetch(direction), number: number}
+        end
+
+        def frame(number)
+          values = metadata(number)
+          bytes = read_exact(@data, values.delete(:caplen), values.delete(:offset))
+          Core::Frame.new(**values, bytes: bytes)
+        end
+
+        def annotation(number)
+          stream, seq, ack, flags, severity =
+            read_exact(@annotations, Core::AnnotationStore::SIZE, (number - 1) * Core::AnnotationStore::SIZE).unpack(Core::AnnotationStore::FORMAT)
+          experts = @sparse.fetch("experts", {}).fetch(number.to_s, [])
+          {tcp_stream: stream, seq_rel: seq, ack_rel: ack, expert_max: severity, expert_items: experts,
+           analysis_flags: Core::AnnotationStore::FLAGS.each_with_index.filter_map { |name, index| name if flags & (1 << index) != 0 },
+           extra: @sparse.fetch("extras", {}).fetch(number.to_s, {})}
+        end
+
+        def packet_snapshot(number)
+          offset = @detail_offsets && @detail_offsets[number]
+          return nil unless offset
+          raise IOError, "invalid reassembled packet offset" unless offset < @details.size
+
+          @details.seek(offset)
+          record = JSON.parse(@details.gets || raise(IOError, "truncated reassembled packet snapshot"))
+          Gateway::PacketSnapshot.from_h(record.fetch("packet"))
+        end
+
+        def close = @files&.each { |io| io.close unless io.closed? }
+
+        private
+
+        def open_file(path)
+          File.open(path, "rb").tap { |io| @files << io }
+        end
+
+        def read_exact(io, length, offset)
+          return "".b if length.zero?
+
+          value = if io.respond_to?(:pread)
+            io.pread(length, offset)
+          else
+            io.seek(offset)
+            io.read(length)
+          end
+          raise IOError, "truncated filter spool" unless value && value.bytesize == length
+
+          value
+        rescue EOFError
+          raise IOError, "truncated filter spool"
+        end
+      end
+
+      class View
+        def initialize(reader, number, dissector, context)
+          @reader, @number, @dissector, @context = reader, number, dissector, context
+          @metadata = reader.metadata(number)
+        end
+
+        def layer?(name) = packet.layer?(name)
+        def field_type(name) = packet.field_type(name)
+
+        def values(name)
+          case name
+          when "frame.number" then [@number]
+          when "frame.len" then [@metadata[:original_length]]
+          when "frame.cap_len" then [@metadata[:caplen]]
+          when "frame.time_epoch" then [@metadata[:timestamp_ns] / 1e9]
+          when "frame.time_relative"
+            reference = @context[:references].reverse.find { |number, _| number <= @number }&.last || @context[:reference]
+            [(@metadata[:timestamp_ns] - reference) / 1e9]
+          when "frame.time_delta" then [delta(@number - 1)]
+          when "frame.time_delta_displayed" then [delta(@context[:predecessors].fetch(@number.to_s, @number - 1))]
+          when "frame.interface_name" then @metadata[:interface] ? [@metadata[:interface]["name"]].compact : []
+          when "frame.direction" then @metadata[:direction] ? [@metadata[:direction].to_s] : []
+          when "frame.marked" then [@context[:marked].include?(@number)]
+          when "frame.ignored" then [@context[:ignored].include?(@number)]
+          when "frame.protocols" then [packet.columns[:layers].join(":")]
+          when "tcp.stream" then annotation[:tcp_stream] >= 0 ? [annotation[:tcp_stream]] : []
+          when "tcp.seq_relative" then annotation[:seq_rel] >= 0 ? [annotation[:seq_rel]] : []
+          when "tcp.ack_relative" then annotation[:ack_rel] >= 0 ? [annotation[:ack_rel]] : []
+          when "tcp.analysis.flags" then annotation[:analysis_flags].empty? ? [] : [true]
+          when "expert.code" then annotation[:expert_items].map { |item| item["code"] }
+          when "expert.severity"
+            items = annotation[:expert_items].map { |item| item["severity"] }
+            items.empty? && annotation[:expert_max] > 0 ? [%w[note warning error].fetch(annotation[:expert_max] - 1)] : items
+          else
+            if name.start_with?("tcp.analysis.")
+              return [true] if annotation[:analysis_flags].include?(name.delete_prefix("tcp.analysis."))
+              return Array(annotation[:extra][name]).compact
+            end
+            packet.values(name)
+          end
+        end
+
+        private
+
+        def packet = @packet ||= @reader.packet_snapshot(@number) || @dissector.dissect(@reader.frame(@number))
+        def annotation = @annotation ||= @reader.annotation(@number)
+        def delta(previous) = previous && previous > 0 ? (@metadata[:timestamp_ns] - @reader.metadata(previous)[:timestamp_ns]) / 1e9 : 0.0
+      end
+
+      def self.call(payload)
+        validate(payload)
+        reader = Reader.new(payload.fetch("spool"), payload.fetch("annotations_json", File.join(payload.fetch("spool"), "annotations.json")))
+        first, last = payload.values_at("from", "to")
+        raise ArgumentError, "filter chunk exceeds stored frames" unless last <= reader.count + 1
+
+        dissector = Gateway::Dissector.new(decode_as: payload.fetch("decode_as", []), plugins: payload.fetch("plugins", []))
+        program = Core::DisplayFilter.compile(payload.fetch("expr"), catalog: Gateway::FieldCatalog.new)
+        context = {marked: Set.new(payload.fetch("marked", [])), ignored: Set.new(payload.fetch("ignored", [])),
+                   reference: payload.fetch("time_reference_ns") { reader.count.zero? ? 0 : reader.metadata(1)[:timestamp_ns] },
+                   references: payload.fetch("time_references_ns", {}).map { |number, timestamp| [Integer(number), timestamp] }.sort_by(&:first),
+                   predecessors: payload.fetch("displayed_predecessors", {})}
+        matches = (first...last).select { |number| program.match?(View.new(reader, number, dissector, context)) }
+        {"matches" => matches}
+      ensure
+        reader&.close
+      end
+
+      def self.validate(payload)
+        raise ArgumentError, "filter worker requires an object" unless payload.is_a?(Hash)
+        raise ArgumentError, "spool and expression must be strings" unless %w[spool expr].all? { |key| payload[key].is_a?(String) }
+        first, last = payload.values_at("from", "to")
+        raise ArgumentError, "invalid filter chunk" unless first.is_a?(Integer) && last.is_a?(Integer) && first >= 1 && last >= first
+        %w[decode_as plugins].each do |key|
+          values = payload.fetch(key, [])
+          raise ArgumentError, "#{key} must be an array of strings" unless values.is_a?(Array) && values.all? { |value| value.is_a?(String) }
+        end
+      end
+      private_class_method :validate
+    end
+  end
+end

data/lib/vanken/capture/helper_main.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "etc"
+require_relative "../version"
+require_relative "helper_options"
+require_relative "control_protocol"
+require_relative "privileges"
+require_relative "../gateway/live_capture"
+require_relative "../gateway/file_writer"
+
+module Vanken
+  module Capture
+    class HelperMain
+      def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr, env: ENV)
+        @stdin, @stdout, @env = stdin, stdout, env
+        @control = ControlProtocol.new(stderr)
+      end
+
+      def run(argv)
+        @control.write(:hello, pid: Process.pid, vanken: VERSION, redhound: Gateway::LiveCapture.version, ruby: RUBY_VERSION)
+        options = HelperOptions.parse(argv)
+        case options.command
+        when :list_interfaces then @stdout.puts(JSON.generate(Gateway::Interfaces.list)); return 0
+        when :check then return check(options)
+        when :version then @stdout.puts("Vanken #{VERSION}"); return 0
+        when :help then @stdout.puts("vanken-capture -i INTERFACE [--filter EXPR] [--snaplen N] [--no-promiscuous]\n  [--buffer-size BYTES] [--direction in|out|inout] [--backend auto|ring|socket|bpf]\n  [--drop-to UID:GID] [--stats-interval SEC] [--flush-interval SEC]\n  --list-interfaces | --check [--interface IF] | --version"); return 0
+        end
+
+        capture(options)
+      rescue ArgumentError => e
+        failure("internal", e.message, 2)
+      rescue Gateway::Interfaces::NotFound => e
+        failure("interface_not_found", e.message, 2)
+      rescue Gateway::LiveCapture::Error => e
+        failure(e.code, e.message, e.exit_code)
+      rescue Privileges::Error, Errno::EPERM, Errno::EACCES => e
+        failure("permission_denied", e.message, 3)
+      rescue Vanken::FileError, IOError, Errno::EPIPE, Errno::ENOSPC => e
+        failure("write_failed", e.message, 1)
+      rescue StandardError => e
+        failure("internal", e.message, 1)
+      end
+
+      private
+
+      def capture(options)
+        drop_to = options.drop_to || drop_target
+        if Process.euid.zero? && !drop_to
+          raise Privileges::Error, "privileged capture requires --drop-to UID:GID or an invoking user identity"
+        end
+        Gateway::Interfaces.find(options.capture[:interface])
+        source = Gateway::LiveCapture.open(**options.capture)
+        dropped = drop_to ? Privileges.drop!(*drop_to) : false
+        @stdout.binmode
+        writer = Gateway::FileWriter.open(@stdout, format: :pcapng, linktype: source.linktype, snaplen: options.capture[:snaplen])
+        @stop_reason = nil
+        previous_traps = %w[TERM INT].to_h { |signal| [signal, Signal.trap(signal) { @stop_reason ||= "signal" }] }
+        monitor = Thread.new do
+          Thread.current.report_on_exception = false
+          @stdin.read(1) until @stdin.eof?
+          @stop_reason ||= "stdin_closed"
+        rescue IOError, SystemCallError
+          @stop_reason ||= "stdin_closed"
+        end
+        @control.write(:started, interface: options.capture[:interface], linktype: source.linktype,
+                       snaplen: options.capture[:snaplen], backend: source.backend, filter: options.capture[:filter], privileges_dropped: dropped)
+        flushed_at = stats_at = monotonic
+        until @stop_reason || source.stopped?
+          packet = source.next_packet(timeout: 0.05)
+          writer << packet if packet
+          now = monotonic
+          if now - flushed_at >= options.flush_interval
+            writer.flush
+            flushed_at = now
+          end
+          if now - stats_at >= options.stats_interval
+            @control.write(:stats, **source.stats, ts: Time.now.to_f)
+            stats_at = now
+          end
+        end
+        stats = source.stats
+        writer.write_stats(stats)
+        writer.close
+        writer = nil
+        @control.write(:stopped, reason: @stop_reason || "source_closed", stats: stats)
+        0
+      ensure
+        monitor&.kill
+        monitor&.join
+        previous_traps&.each { |signal, handler| Signal.trap(signal, handler) }
+        begin
+          writer&.close
+        ensure
+          source&.close
+        end
+      end
+
+      def check(options)
+        interface = options.capture[:interface] || Gateway::Interfaces.list.find { |entry| entry[:up] }&.fetch(:name)
+        raise Gateway::Interfaces::NotFound, "no capture interfaces found" unless interface
+
+        source = Gateway::LiveCapture.open(**options.capture.merge(interface: interface))
+        @stdout.puts(JSON.generate(direct: true, interface: interface, backend: source.backend, platform: RUBY_PLATFORM, uid: Process.uid))
+        0
+      rescue Gateway::LiveCapture::Error => e
+        @stdout.puts(JSON.generate(direct: false, interface: interface, platform: RUBY_PLATFORM, uid: Process.uid, code: e.code, message: e.message))
+        e.exit_code
+      ensure
+        source&.close
+      end
+
+      def drop_target
+        return unless Process.euid.zero?
+        return [Process.uid, Process.gid] unless Process.uid.zero?
+
+        if @env["SUDO_UID"] && @env["SUDO_GID"]
+          uid, gid = Integer(@env["SUDO_UID"], 10), Integer(@env["SUDO_GID"], 10)
+        elsif @env["PKEXEC_UID"]
+          uid = Integer(@env["PKEXEC_UID"], 10)
+          gid = Etc.getpwuid(uid).gid
+        end
+        [uid, gid] if uid&.positive? && gid&.positive?
+      rescue ArgumentError
+        nil
+      end
+
+      def failure(code, message, exit_code)
+        @control.write(:error, code: code, message: message, fatal: true)
+        exit_code
+      rescue IOError, SystemCallError
+        exit_code
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/vanken/capture/helper_options.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Vanken
+  module Capture
+    class HelperOptions
+      attr_reader :command, :capture, :drop_to, :stats_interval, :flush_interval
+
+      def self.parse(argv)
+        new.parse(argv)
+      end
+
+      def initialize
+        @command = :capture
+        @capture = {interface: nil, filter: nil, snaplen: 262_144, promiscuous: true,
+                    buffer_size: 4 * 1024 * 1024, direction: :inout, backend: :auto}
+        @stats_interval = 1.0
+        @flush_interval = 0.05
+      end
+
+      def parse(argv)
+        modes = []
+        parser = OptionParser.new do |opts|
+          opts.on("-i", "--interface IF") { |v| @capture[:interface] = v }
+          opts.on("-f", "--filter EXPR") { |v| @capture[:filter] = v }
+          opts.on("--snaplen N", Integer) { |v| @capture[:snaplen] = bounded(v, 1..16_777_216, "snaplen") }
+          opts.on("--no-promiscuous") { @capture[:promiscuous] = false }
+          opts.on("--buffer-size N", Integer) { |v| @capture[:buffer_size] = bounded(v, 65_536..268_435_456, "buffer-size") }
+          opts.on("--direction VALUE", %w[in out inout]) { |v| @capture[:direction] = v.to_sym }
+          opts.on("--backend VALUE", %w[auto ring socket bpf]) { |v| @capture[:backend] = v.to_sym }
+          opts.on("--drop-to UID:GID") do |v|
+            raise ArgumentError, "drop-to must be a non-root UID:GID" unless v.match?(/\A[0-9]+:[0-9]+\z/)
+
+            @drop_to = v.split(":").map { |id| bounded(Integer(id, 10), 1..4_294_967_294, "drop-to") }
+          end
+          opts.on("--stats-interval SEC", Float) { |v| @stats_interval = bounded(v, 0.01..60, "stats-interval") }
+          opts.on("--flush-interval SEC", Float) { |v| @flush_interval = bounded(v, 0.001..1, "flush-interval") }
+          opts.on("--list-interfaces") { modes << :list_interfaces }
+          opts.on("--check") { modes << :check }
+          opts.on("--version") { modes << :version }
+          opts.on("-h", "--help") { modes << :help }
+        end
+        # OptionParser accepts long-option abbreviations by default; privileged inputs must be exact.
+        known = %w[--interface --filter --snaplen --no-promiscuous --buffer-size --direction --backend --drop-to --stats-interval --flush-interval --list-interfaces --check --version --help]
+        argv.each do |arg|
+          raise ArgumentError, "unknown option: #{arg}" if arg.start_with?("--") && !known.include?(arg.split("=", 2).first)
+        end
+        remaining = parser.parse(argv.dup)
+        raise ArgumentError, "unexpected arguments: #{remaining.join(' ')}" unless remaining.empty?
+        raise ArgumentError, "conflicting commands" if modes.length > 1
+
+        @command = modes.first || :capture
+        raise ArgumentError, "interface is required" if @command == :capture && @capture[:interface].to_s.empty?
+
+        self
+      rescue OptionParser::ParseError => e
+        raise ArgumentError, e.message
+      end
+
+      private
+
+      def bounded(value, range, name)
+        raise ArgumentError, "#{name} must be in #{range}" unless range.cover?(value)
+
+        value
+      end
+    end
+  end
+end