redhound 1.0.1 → 2.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fc9146df6d249b2bdd3ca7c529c6d72eaad8c78970e6cc21d4be41f9e233a25
-  data.tar.gz: 9f66932249c4235042d3934579fdf7f9be92ad531f30e1e5c05ed1a55ae436e4
+  metadata.gz: 33f3a971291b9d5c6be138098ab5d6072717b8ffc79f418830f3538d8b9c4500
+  data.tar.gz: 191cf625ab53877b304432e4cd0b9caa6725afd1e4929bebaba31ef2382c0108
 SHA512:
-  metadata.gz: 4ee95bd38fa1717c5286ae994db3b4d2c024c07119489d65f7b48a2cd9f5337b1a0cf0ebf36659f37d113052aaee178cd8ee29d50c2d995bee06d97443335fc6
-  data.tar.gz: 895d8f8b92858aaf63ac5bfc9b7ee2dc4a4fb594313e20052a96bdf893380aaae4853988c8e2966657ea3f2788eabf604a3ef44ebb16cf9954f0df5c4aeef444
+  metadata.gz: 73fc49a4129a62cfdad32ee818adb4d1915f115f3bbe3f0a47b36d5d8a23c625d275d28a39e8307d4b8d1cc068b0d6be12409e2f99400f0135aa89383d58b0f9
+  data.tar.gz: 817303ae395d6f1b288bbab65105736d97f019cfb27dc6ba8edea787d7eab82fed9817d4a3fd0ee36e7e1407af17b48c50adab04412410b36f29044d778f0215

data/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 ## Unreleased
 
+## 2.0.0.rc2 - 2026-10-02
+
+### Features
+
+- Use the ring backend automatically on aarch64 Linux when mapping is available.
+
+### Bug fixes
+
+- Improve file reading and packet summary throughput while keeping stdin responsive.
+- Preserve readable fields in truncated headers and correct ICMP errors, IGMP reports, signed NTP precision, IPv6 extension boundaries and variable field locations.
+- Reject malformed TCP options and empty or conflicting HTTP Content-Length values; recognize HTTP when its first line spans segments on nonstandard ports.
+- Report incomplete IP/TCP data at EOF and flow eviction, distinguish retransmitted SYN/FIN packets, and handle IPv6 atomic fragments independently.
+- Account for retained buffer capacity when enforcing reassembly limits, bound pcapng interface metadata, and release analysis buffers even when output fails.
+- Keep capture timeouts and stopping responsive under rejected traffic and idle stdin, preserve partial input records across timeouts, and support replacing file-source filters.
+- Preserve wire lengths with attached filters, close capture files after write failures, and prevent metadata errors from corrupting pcapng interface numbering.
+- Correct macOS interface MAC/MTU and loopback link types; include interface and direction in packet output and show checksum/TCP options with verbose summaries.
+- Preserve negative and expanded-year timestamps and emit valid JSON for invalid UTF-8 diagnostics and interface names; reject invalid packet metadata before file serialization.
+- Include empty intervals in IO statistics and keep unknown IP protocol conversations separate.
+- Fall back to socket capture when Ruby 4.0 cannot map a packet ring, and explain unavailable explicit ring capture and receive-buffer/VLAN limitations.
+
+## 2.0.0.rc1 - 2026-10-01
+
+### Breaking changes
+
+- Replace the Analyzer/Builder/L2/L3/L4 API with Packet, Layer, Field and the Dissector DSL; use `Redhound.open`, `Redhound.capture` and `Redhound.dissect` for library integrations.
+- Use a one-line summary by default. Select `-V` or `-T tree` for detailed output; `-v` controls verbosity and `--version` prints the version.
+- Make `-w` save packets without dissection or display unless an output format is also selected.
+
+### Features
+
+- Read and write pcap and pcapng, including stdin/stdout, interface metadata and size/time rotation.
+- Capture on macOS BPF devices and Linux socket/TPACKET_V3 backends, including Linux `any`, directions, snaplen and drop statistics.
+- Compile tcpdump-style capture filters to validated cBPF for kernel capture and file filtering; support filter files and instruction dumps.
+- Decode VLAN/QinQ, LLC/SNAP, cooked/null/raw links, IPv6 extensions, ICMPv6/NDP, IGMPv3, DNS/mDNS/LLMNR, DHCP, NTP, HTTP/1.x, TLS hellos, GRE and VXLAN.
+- Track flows, reassemble IP fragments and TCP application messages, report TCP analysis flags/RTT, and follow TCP streams as ASCII, hex or exact bytes.
+- Add tree, hex, JSON/NDJSON and selected-field output, conversation/endpoint/interval/protocol statistics, decode-as overrides and custom Ruby dissectors.
+- Support privilege dropping after capture setup and write capture files with private permissions.
+
+### Bug fixes
+
+- Fix crashes on padded ARP, short frames and malformed packet headers.
+- Correct IPv4 and IPv6 fields, IP options and transport payload boundaries; label ICMP types/codes and avoid false checksum failures on incomplete IPv6 fragments.
+- Display TCP ports, sequence numbers, flags and payload lengths.
+- Escape terminal control characters in captured payloads.
+- Save packets before analysis and close captures reliably on termination or errors.
+- Capture larger frames with kernel timestamps and remove loopback duplicates.
+- List interfaces without duplicates and accept interface indexes.
+- Protect read inputs and their aliases from rotated-output overwrites, validate filters on empty captures, and stop stdin reads cleanly on termination.
+- Decode foreign-endian loopback capture headers correctly and preserve original wire lengths for truncated VLAN packets.
+- Handle HEAD responses and pipelined HTTP correctly, reassemble HTTP on nonstandard ports, and report missing or incomplete TCP data at FIN and EOF.
+
 ## 1.0.1 - 2025-01-17
 
 - Fix an NameError in Redhound::L3::Arp

data/README.md

@@ -1,51 +1,117 @@
 # Redhound [![Gem Version](https://badge.fury.io/rb/redhound.svg)](https://badge.fury.io/rb/redhound) [![Test](https://github.com/ydah/redhound/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/redhound/actions/workflows/main.yml)
 
-Pure Ruby packet analyzer.
-At this time, it is only guaranteed to work on Linux.
+Capture and analyze network packets in Pure Ruby. Redhound runs on Linux and
+macOS, reads and writes pcap/pcapng, compiles capture filters to cBPF, and
+provides summary, tree, hex and JSON output. No libpcap, Fiddle or runtime gem
+dependency is required. Ruby 3.3 or later is required.
 
-## Installation
+Version 2 is currently a release candidate. See [validation status](docs/VALIDATION.md)
+for remaining GA evaluation gates.
 
-Install the gem and add to the application's Gemfile by executing:
+## Installation
 
-```bash
-bundle add redhound
+```sh
+gem install redhound --pre
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or add `gem 'redhound', '~> 2.0.0.rc2'` to your Gemfile.
 
-```bash
-gem install redhound
+## Usage
+
+```sh
+redhound -D
+sudo redhound -i any 'tcp port 443'
+sudo redhound -i en0 -c 100 -w trace.pcapng
+redhound -r trace.pcapng -T tree
+redhound -r trace.pcap --stats conv,tcp
+redhound -r trace.pcap --follow tcp,ascii,0
 ```
 
-## Usage
+Live capture normally requires root or capture permissions. File analysis does
+not. `-i any` is Linux only; use `lo0`/`en0` on macOS. `-w` alone saves packets
+without dissection; add `-T summary` to also print them. Addresses are numeric
+by default. Use `-N` to resolve names.
+
+```text
+Usage: redhound [options] [filter expression]
+    -i, --interface IF               interface name, index or any
+    -D, --list-interfaces            list interfaces and exit
+    -r, --read FILE                  read pcap or pcapng (- for stdin)
+    -c, --count N                    stop after N packets
+    -s, --snaplen N                  capture length (default 262144)
+    -p, --no-promiscuous             disable promiscuous capture
+    -B, --buffer-size KiB            kernel buffer size
+    -Q, --direction DIR              capture direction
+    -F, --filter-file FILE           read a capture filter
+        --capture-backend BACKEND    capture backend
+    -w, --write FILE                 write capture (- for stdout)
+        --format FORMAT              capture file format
+    -C MB                            rotate after MB (decimal)
+    -G SECONDS                       rotate at this interval
+    -W N                             maximum rotation file count
+        --post-rotate-command CMD    command to run after closing each file
+    -U, --packet-buffered            flush each packet
+    -T, --output-format FORMAT       packet output format
+    -V                               show packet details
+    -q                               quick output and no capture statistics
+        --time-stamp-precision PRECISION
+                                     timestamp digits
+    -N, --resolve-names              resolve addresses
+    -n                               disable address resolution (default)
+        --stats SPEC                 io,N / conv,TYPE / endpoints,TYPE / phs
+        --follow SPEC                tcp,ascii|hex|raw,N
+        --decode-as RULE             e.g. udp.port==8443,dns
+    -I, --require FILE               load a custom dissector
+    -d                               dump cBPF instructions
+    -Z, --relinquish-privileges USER drop capture privileges
+        --list-protocols             list protocols and fields
+        --debug                      print error backtraces
+        --no-yjit                    disable automatic YJIT activation
+    -h, --help                       print help
+        --version                    print version
+  -e [-T fields: FIELD]   link header or selected field (repeatable)
+  -v / -vv / -vvv         verbosity and checksum verification
+  -t / -tt / -ttt / -tttt / -ttttt   timestamp style
+  -x / -xx / -X / -XX     hex dump, with link header / ASCII
+```
 
-```command
-   ___         ____                     __
-  / _ \___ ___/ / /  ___  __ _____  ___/ /
- / , _/ -_) _  / _ \/ _ \/ // / _ \/ _  /
-/_/|_|\__/\_,_/_//_/\___/\_,_/_//_/\_,_/
+See [usage and tcpdump option mapping](docs/USAGE.md),
+[supported protocols](docs/PROTOCOLS.md), [capture filters](docs/FILTERS.md),
+[Ruby API and plugins](docs/API.md), and [migration from 1.x](docs/MIGRATION.md).
 
-Version: 1.0.1
-Dump and analyze network packets.
+## Library
 
-Usage: redhound [options] ...
+```ruby
+require 'redhound'
 
-Options:
-    -i, --interface INTERFACE        name or idx of interface
-    -D, --list-interfaces            print list of interfaces and exit
-    -w FILE                          write packets to a pcap capture file format to file
-    -h, --help                       display this help and exit
-    -v, --version                    display version information and exit
-```
+Redhound.open('trace.pcapng', filter: 'udp port 53') do |reader|
+  reader.each { |packet| puts packet.summary }
+end
 
-## Contributing
+packet = Redhound.dissect(frame_bytes, linktype: :ethernet)
+p packet['ip.src']
+p packet.to_h
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/redhound. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/ydah/redhound/blob/main/CODE_OF_CONDUCT.md).
+## Development
 
-## License
+```sh
+bundle install
+bundle exec rbs collection install --frozen
+bundle exec rake
+bundle exec yard stats --list-undoc
+FUZZ_ITERATIONS=1000000 bundle exec rspec spec/fuzz
+sudo -E env "PATH=$PATH" REDHOUND_LIVE=1 bundle exec rspec --tag live
+```
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Differential tests use tcpdump/tshark as development tools. Fixtures are
+regenerated with `ruby -Ilib spec/fixtures/generators/applications.rb` and
+`ruby -Ilib spec/fixtures/generators/network.rb`. Update output snapshots with
+`UPDATE_GOLDEN=1 bundle exec rspec spec/golden`, then review the changes.
+See [benchmark results](bench/RESULTS.md) for reproducible performance checks.
 
-## Code of Conduct
+## Contributing and license
 
-Everyone interacting in the Redhound project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ydah/redhound/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome at [GitHub](https://github.com/ydah/redhound).
+Contributors must follow the [code of conduct](CODE_OF_CONDUCT.md).
+Redhound is available under the [MIT License](LICENSE.txt).

data/docs/API.md

@@ -0,0 +1,104 @@
+# Ruby API
+
+```ruby
+require 'redhound'
+
+Redhound.open('trace.pcapng', filter: 'tcp port 443') do |reader|
+  reader.each do |packet|
+    puts packet.summary
+    puts packet['ip.src']
+    p packet[:tcp]&.values
+    p packet.to_h
+  end
+end
+
+Redhound.capture(interface: 'lo', count: 10, filter: 'udp') do |packet|
+  puts packet.summary
+end
+
+packet = Redhound.dissect(frame_bytes, linktype: :ethernet,
+                         timestamp_ns: 1_700_000_000_123_456_789)
+Redhound::Writer.open('copy.pcapng') { |writer| writer << packet }
+```
+
+`Redhound.open` accepts a path, `-`, or a binary IO. Reader is Enumerable,
+provides `next_packet`, `stats`, `interfaces`, `stop`, and `close`; a block always
+closes it. `Redhound.capture` yields packets and closes the live source even if
+the block fails. Capture options include `snaplen`, `promiscuous`, `buffer_size`
+(bytes), `direction` (`:in`, `:out`, `:inout`), `backend`, and `filter`.
+On Linux Ruby 4.0, `backend: :auto` uses sockets because `IO::Buffer.map` cannot
+map packet sockets; explicit `:ring` raises `UnsupportedPlatform`. Ruby 3.3/3.4
+retain ring support.
+
+`next_packet(timeout:)` returns nil at its deadline without discarding a partial
+stdin/pipe record. `stop` interrupts a waiting read. `attach_filter(program)`
+replaces a source's capture filter; filtering preserves the original wire length.
+For pcapng input, retained interface metadata is limited to 4,096 interfaces and
+16 MiB across sections, with at most 4,096 options in a block. Excess input raises
+`FileFormatError` rather than growing memory without a bound.
+
+`Redhound.dissect` creates an immutable-byte Packet and decodes its layers lazily.
+Packet metadata includes `timestamp_ns`, `original_length`, `linktype`,
+`interface`, `direction`, and `number`. `caplen`, `truncated?`, and `time` expose
+capture properties. A symbol index selects the first Layer; a dotted string
+selects a decoded field value. `layers_of`, `innermost`, and `field_values` expose
+repeated or tunneled layers. Layer has `values`, `fields`, and `diagnostics`.
+`to_h` follows [json-schema.json](json-schema.json); bytes use hexadecimal strings,
+addresses use text, booleans remain booleans, repeated fields become arrays.
+`timestamp_ns` must be an Integer; calendar output preserves expanded years
+outside 0000..9999. `number` is positive, `direction` is `:in`, `:out`, or nil,
+and integer link types are restricted to 0..65535. Invalid UTF-8 field text,
+interface names, and diagnostic text use hexadecimal strings without discarding
+their original bytes.
+
+Each Field exposes its `name`, `type`, `value`, `raw_value`, `offset`, and
+`length`. For packet dissection, offsets are absolute captured byte positions;
+lengths describe the encoded source span. Complete fixed fields remain available
+when the rest of a header or its options are truncated. Derived values such as
+`tcp.len`, `data.len`, and `igmp.version` have zero source length. DNS compressed
+names refer to their encoded name/pointer span. Concatenated DHCP values and TLS
+handshakes crossing records span the first through last source byte, including
+intervening TLV/record headers; decoded values need not equal a direct byte slice.
+Likewise, chunked HTTP body spans include chunk framing. Stream-reassembled
+application fields use offsets in the logical PDU rather than the completing
+packet's `data`; `tcp.reassembled_from` identifies the contributing frames.
+
+Writer accepts `format: :pcap|:pcapng`, `linktype`, `snaplen`, `precision`,
+`packet_buffered`, `max_bytes`, `interval`, `file_count`, and
+`post_rotate_command`. `write`/`<<`, `flush`, `write_stats`, and `close` are
+available. Use a block for deterministic closure.
+
+## Custom dissectors
+
+```ruby
+class Example < Redhound::Dissector
+  protocol :example, name: 'Example protocol', short: 'EXAMPLE'
+  dissects_on 'udp.port', 9999
+  header do
+    uint16 :message_id, 'example.id'
+    uint8 :kind, 'example.kind'
+  end
+
+  def summary(layer)
+    "Example id #{layer[:message_id]}"
+  end
+end
+```
+
+Header fields support unsigned integers, signed `int8`, MAC/IPv4/IPv6 addresses
+and bit fields.
+Use `dissect(ctx, layer)` for bounded variable-length parsing through
+`ctx.cursor`; append fields with `layer.add`. `next_dissector(ctx, layer)` returns
+a registered dissector class, or nil. Child cursors cannot escape their packet
+bounds. Truncated input creates a diagnostic. `REDHOUND_STRICT=1` re-raises
+unexpected implementation errors for tests. Ordinary malformed input remains
+safe. Registry copies allow per-session decode-as rules without changing global
+registrations.
+
+`Analysis::Session#update(packet)` adds flow/stream analysis and completed
+application PDUs. It provides bounded flow/reassembly state and `snapshot`,
+`finish`; library users opt into it explicitly. Reassembly does not modify the
+packet's captured bytes. `Filter.compile(expression, linktype:)` returns a
+validated cBPF Program with `match?`, `evaluate`, `serialize`, and `disassemble`.
+
+Generate reference documentation with `bundle exec yard doc lib/**/*.rb`.

data/docs/FILTERS.md

@@ -0,0 +1,37 @@
+# Capture filters
+
+Redhound compiles filters to classic BPF in Ruby. Live capture attaches the verified program to the kernel; file capture executes the same instructions in the Ruby VM. No libpcap or external command is needed at runtime.
+
+```ruby
+program = Redhound::Filter.compile('ip and udp dst port 53', linktype: :ethernet)
+program.match?(packet)
+program.instructions                 # [code, jt, jf, k] tuples
+program.packed                       # native struct sock_filter bytes
+program.disassemble(format: :text)   # :ruby and :decimal are also available
+```
+
+Supported primitives include `ip`, `ip6`, `arp`, `rarp`, `tcp`, `udp`, `sctp`, `icmp`, `icmp6`, and `igmp`; `host`, `net`, `port`, `portrange`, `proto`; `src`, `dst`, `src or dst`, `src and dst`; Ethernet addresses and EtherTypes; `vlan [id]`; `greater`, `less`, `broadcast`, and `multicast`. Numeric IPv4 and IPv6 addresses, CIDR networks, IPv4 netmasks, host names, protocol names, and service names are resolved when compiling. For reserved protocol names after `proto`, tcpdump spells them with an escape, e.g. `ip proto \tcp`; Redhound also accepts the unescaped spelling.
+
+Identical qualifiers carry forward: `tcp dst port 80 or 443` means `tcp dst port 80 or tcp dst port 443`. Parenthesized operand lists work as well: `tcp dst port (80 or 443)`.
+
+As specified by [pcap-filter](https://github.com/the-tcpdump-group/libpcap/blob/master/pcap-filter.manmisc.in), `and` and `or` have **equal precedence** and associate from left to right; `not` binds more tightly. Thus `udp or tcp and port 443` means `(udp or tcp) and port 443`. Use parentheses to express a different grouping. This corrects the separate AND/OR precedence in the original design's EBNF and is checked against tcpdump.
+
+Arithmetic supports `len`, packet accesses of width 1, 2, or 4, `+ - * / % & | ^ << >>`, unary minus, and comparisons `= == != < <= > >=` with unsigned 32-bit values:
+
+```text
+ip[2:2] > 576
+tcp[tcpflags] & (tcp-syn | tcp-fin) != 0
+(ip[0] & 15) * 4 = 20
+icmp6[0] = 128
+len >= 100
+```
+
+Transport accesses and ports check IPv4 fragment offsets and honor IPv4 options. IPv6 ports require a directly following TCP/UDP/SCTP header; extension-header traversal (`protochain`) is outside the v2 subset. Plain protocol predicates additionally recognize an IPv6 fragment header's next-header field. `tcp[]`, `udp[]`, `icmp[]`, and `igmp[]` access IPv4 transport headers, matching libpcap; `icmp6[]` accesses a directly following ICMPv6 header.
+
+`vlan` changes the offsets for all following primitives, including those in subsequent `or` branches, matching tcpdump. Repeated `vlan` predicates support nested tags. Linux live Ethernet filters also recognize hardware-stripped tags through VLAN ancillary loads; the VM reads these from `packet.meta[:vlan_tci]` (including tag ID zero). Linux `any` filters compile for kernel network-layer bytes and protocol metadata, while file filters use the synthetic SLL2 header.
+
+Linktypes are Ethernet (1), RAW (101), Linux SLL (113), Linux SLL2 (276), NULL (0), LOOP (108), IPv4 (228), and IPv6 (229). Their corresponding symbol names are `:ethernet`, `:raw`, `:linux_sll`, `:linux_sll2`, `:null`, `:loop`, `:ipv4`, and `:ipv6`. Ethernet address and VLAN predicates require Ethernet. IPv4 `broadcast` without an interface netmask recognizes zero and all-one destinations; link broadcast compares the Ethernet destination.
+
+`FilterSyntaxError` supplies the original expression and error position. Programs are limited to 4096 instructions and 16 scratch words; oversized programs raise `FilterTooLarge`. The verifier rejects invalid opcodes, jumps, memory accesses, uninitialized scratch reads, and constant zero divisors. Truncated packet loads and dynamic zero divisors reject the packet. Conditional branches beyond 255 instructions use forward jump trampolines.
+
+The differential suite contains more than 160 expressions and compares selected packets and tcpdump-generated bytecode on Ethernet, RAW, SLL, SLL2, and NULL. tcpdump is a test dependency only. Historical protocols, `gateway`, and `protochain` are unsupported; network operands use numeric addresses rather than `/etc/networks` aliases.

data/docs/MIGRATION.md

@@ -0,0 +1,23 @@
+# Migrating from 1.x
+
+Redhound 2 replaces the former Analyzer/Builder/L2/L3/L4 classes with Packet,
+Layer, Field and Dissector. Those internal classes have been removed. Migrate
+library integrations to the APIs in [API.md](API.md). Ruby 3.3 remains the
+minimum version.
+
+The default CLI output is now a one-line summary. Use `-V` or `-T tree` for
+packet details. `-v` now increases verbosity; use `--version` to print the
+version. Numeric addresses remain the default.
+
+`-w` alone records packets without printing or parsing them. Use `-w capture.pcap
+-T summary` to save and display. Unknown protocols remain accessible as Data
+layers, and malformed headers produce diagnostics instead of terminating the
+capture. Payload text escapes terminal control bytes.
+
+Interface indexes and Linux `any` are supported. Linux loopback duplicates are
+removed. Capture timestamps come from the kernel; captured and original packet
+lengths are recorded separately. pcapng supports multiple interfaces and metadata.
+
+Version 2 is currently a prerelease. The two-week RC evaluation and long capture
+soak gates remain prerequisites for GA; a 1.x maintenance deadline will be
+announced when GA is published.

data/docs/PROTOCOLS.md

@@ -0,0 +1,54 @@
+# Supported protocols
+
+Built-in protocol registry (regenerate with `redhound --list-protocols`):
+
+```text
+data: Data
+eth: Ethernet eth.dst eth.src eth.type
+vlan: 802.1Q VLAN vlan.priority vlan.dei vlan.id vlan.etype
+llc: Logical Link Control llc.dsap llc.ssap llc.control
+sll: Linux cooked capture sll.pkttype sll.hatype sll.halen sll.src sll.etype
+sll2: Linux cooked capture v2 sll.etype sll.reserved sll.ifindex sll.hatype sll.pkttype sll.halen sll.src
+null: BSD loopback
+raw: Raw IP
+arp: Address Resolution Protocol arp.hw.type arp.proto.type arp.hw.size arp.proto.size arp.opcode
+ipv4: Internet Protocol v4 ip.version ip.hdr_len ip.dsfield.dscp ip.dsfield.ecn ip.len ip.id ip.flags.rb ip.flags.df ip.flags.mf ip.frag_offset ip.ttl ip.proto ip.checksum ip.src ip.dst
+ipv6: Internet Protocol v6 ipv6.version ipv6.tclass ipv6.flow ipv6.plen ipv6.nxt ipv6.hlim ipv6.src ipv6.dst
+ipv6_ext: IPv6 extension
+udp: User Datagram Protocol udp.srcport udp.dstport udp.length udp.checksum
+tcp: Transmission Control Protocol tcp.srcport tcp.dstport tcp.seq tcp.ack tcp.hdr_len tcp.reserved tcp.flags tcp.window_size_value tcp.checksum tcp.urgent_pointer
+icmp: Internet Control Message Protocol icmp.type icmp.code icmp.checksum
+icmpv6: ICMPv6 / Neighbor Discovery icmpv6.type icmpv6.code icmpv6.checksum
+igmp: Internet Group Management Protocol igmp.type igmp.max_resp igmp.checksum
+gre: Generic Routing Encapsulation gre.flags gre.proto
+vxlan: Virtual eXtensible LAN vxlan.flags vxlan.vni_word
+dns: Domain Name System
+dhcp: Dynamic Host Configuration Protocol dhcp.type dhcp.hw.type dhcp.hw.len dhcp.hops dhcp.id dhcp.secs dhcp.flags dhcp.ip.client dhcp.ip.your dhcp.ip.server dhcp.ip.relay
+ntp: Network Time Protocol ntp.flags.li ntp.flags.vn ntp.flags.mode ntp.stratum ntp.ppoll ntp.precision ntp.rootdelay ntp.rootdispersion ntp.refid ntp.reftime ntp.org ntp.rec ntp.xmt
+http: Hypertext Transfer Protocol
+tls: Transport Layer Security
+```
+
+Variable-length fields, including options, resource records, application headers
+and stream analysis, are added while parsing and appear in tree/JSON output.
+Unknown protocols produce a Data layer; unsupported encrypted TLS content stays
+opaque. HTTP is limited to HTTP/1.x. TLS parsing covers record framing and
+ClientHello/ServerHello metadata including SNI, ALPN and supported versions.
+DNS includes mDNS/LLMNR and TCP framing. IPv6 supports Hop-by-Hop, Routing,
+Fragment, Destination and AH headers; ESP stops dissection. GRE and VXLAN
+encapsulations decode inner packet layers.
+ICMP identifiers/sequences are emitted for echo, timestamp, and address-mask
+messages; fragmentation-needed errors expose `icmp.mtu` instead. IGMP reserved
+report bytes are not labeled as maximum-response times. NTP timestamps such as
+`ntp.xmt` preserve the unsigned 32.32 wire integer; their era-dependent calendar
+interpretation is left to the caller.
+
+Dissectors use checked cursors and parent payload boundaries. Truncation,
+malformed lengths, checksum failures and reassembly gaps are available as
+structured diagnostics. Checksum verification is enabled by `-v` or
+`Engine.new(verify_checksums: true)`; outgoing/offloaded packets are marked
+unverified.
+IPv6 No Next Header terminates the chain, and the 16-extension limit applies
+independently to each encapsulated IPv6 header. Variable wire fields carry source
+ranges; [API.md](API.md) describes compression, concatenation, and reassembly
+span semantics.

data/docs/USAGE.md

@@ -0,0 +1,86 @@
+# Using Redhound
+
+Ruby 3.3 or later is required. File analysis needs no capture privileges.
+Live capture uses Linux AF_PACKET or macOS BPF devices and normally requires
+root or an appropriate device/capability grant. Runtime dependencies are Ruby's
+standard libraries; neither libpcap nor a native extension is required.
+
+```sh
+redhound -D
+sudo redhound -i any 'tcp port 443'
+sudo redhound -i en0 -c 100 -w trace.pcapng
+redhound -r trace.pcapng -T tree
+redhound -r trace.pcap -T ndjson 'udp port 53'
+redhound -r trace.pcap -T fields -e ip.src -e tcp.dstport
+redhound -r trace.pcap --stats conv,tcp --stats io,1
+redhound -r trace.pcap --follow tcp,ascii,0
+```
+
+Options must precede the filter expression. Quote filters containing shell
+operators. Addresses are numeric by default; `-N` enables name resolution.
+`--help` lists every option. `--list-protocols` lists registered protocols and
+their declared fields. Dynamic fields also appear in detailed and JSON output.
+
+## Options for tcpdump users
+
+| tcpdump | Redhound |
+| --- | --- |
+| `-i`, `-D`, `-c`, `-s`, `-p`, `-B`, `-Q` | Same purpose; `-i any` is Linux only |
+| `-r`, `-w`, `-U` | Read/write pcap or pcapng; `-` selects stdin/stdout |
+| `-C`, `-G`, `-W` | Size/time rotation and file count |
+| `-e`, `-q`, `-v`, `-vv`, `-vvv` | Link header, short output, increasing detail/checksums |
+| `-t` through `-ttttt` | No time, epoch, delta, date/time, elapsed time |
+| `-x`, `-xx`, `-X`, `-XX` | Hex/ASCII, optionally including the link header |
+| `-F`, `-d`, `-dd`, `-ddd` | Filter file and cBPF listing |
+| `-Z USER` | Drop user/group privileges after opening capture and output |
+
+See [supported capture filters](FILTERS.md). Capture filters select packets;
+Wireshark display filters are not supported. `--decode-as udp.port==8443,dns`
+overrides port dispatch. `-I plugin.rb` loads a Ruby dissector before capture.
+
+## Saving and rotation
+
+`-w` alone saves raw packets without dissection. Add `-T summary` or `-V` to
+also display them. Binary output to stdout cannot be combined with text output.
+`--format pcapng` overrides the extension. pcapng preserves interface identities,
+nanosecond timestamps, packet directions and available drop statistics.
+
+`-C` uses decimal megabytes; `-G` uses seconds. Rotated files receive a five-digit
+sequence before the extension. With `-C -W`, names form an overwrite ring.
+With `-G -W` alone, capture stops after the requested number of files. `-G`
+expands strftime directives in the base name. Rotation happens when the next
+packet arrives. `--post-rotate-command 'gzip -f'` invokes an argument vector,
+appending the closed filename; it does not invoke a shell. Input files and their
+aliases are protected from output truncation, including rotated destinations.
+
+## Analysis and termination
+
+Displayed TCP packets receive stream IDs and analysis flags. IP fragments and
+TCP application messages are reassembled within bounded state. Conflicting
+IPv6 overlaps discard the datagram; IPv4/TCP retain first-seen bytes and report
+conflicts. Incomplete, expired or evicted state is diagnosed, not retained
+indefinitely. `--follow tcp,raw,N` emits the selected stream bytes without headers;
+ASCII and hex modes label the endpoints and directions.
+
+Statistics accept `io,SECONDS`, `conv,eth|ip|ipv6|tcp|udp`,
+`endpoints,eth|ip|ipv6|tcp|udp`, or `phs`; options can be repeated. Packet counts
+and byte totals use captured packets and original frame lengths. SIGUSR1 (and
+SIGINFO on macOS) prints a statistics snapshot; SIGINT/SIGTERM close output and
+capture sources cleanly. Capture statistics go to stderr. Exit status is 0 on
+success, 1 on capture/file failures and 2 on invalid arguments.
+
+## Platforms and limits
+
+Linux `auto` uses TPACKET_V3 on x86_64 and aarch64 and falls back to the socket backend when
+mapping is unavailable. Other Linux architectures default to sockets; `ring`
+can be selected explicitly. macOS uses BPF, with native timestamp precision
+reported by the device. Linux socket capture cannot recover NIC-stripped VLAN
+tags; choose the ring backend for that metadata.
+Ruby 4.0's `IO::Buffer.map` rejects packet sockets, so `auto` uses socket capture
+and explicit `ring` reports the mapping limitation. Use Ruby 3.3/3.4 for ring
+capture. If using sockets, disable receive VLAN offload on the receiving
+interface when VLAN tags are required (`ethtool -K IF rxvlan off`).
+
+Windows, Wi-Fi monitor mode, packet transmission, TLS decryption, complete
+HTTP/2/QUIC dissection, display-filter syntax and a TUI are outside v2's scope.
+See [release validation status](VALIDATION.md) before promoting a prerelease.