redhound 1.0.1 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fc9146df6d249b2bdd3ca7c529c6d72eaad8c78970e6cc21d4be41f9e233a25
-  data.tar.gz: 9f66932249c4235042d3934579fdf7f9be92ad531f30e1e5c05ed1a55ae436e4
+  metadata.gz: dd9c749a43481a575813ed4bacad00dbc54dfecc7701e63a0baeb6789a1d8680
+  data.tar.gz: 791efd1f3e810c7e67bcf5abfbbc3e02aa0db460bd8dca51b83beecd94797bae
 SHA512:
-  metadata.gz: 4ee95bd38fa1717c5286ae994db3b4d2c024c07119489d65f7b48a2cd9f5337b1a0cf0ebf36659f37d113052aaee178cd8ee29d50c2d995bee06d97443335fc6
-  data.tar.gz: 895d8f8b92858aaf63ac5bfc9b7ee2dc4a4fb594313e20052a96bdf893380aaae4853988c8e2966657ea3f2788eabf604a3ef44ebb16cf9954f0df5c4aeef444
+  metadata.gz: 99e69fb1319c95448572dcfc2151da08987523b95301c1b50f1f1345b269752cd98e4ddcd3c24f711866bc6b7754793061b51f1d208f92428dfd337a007ac444
+  data.tar.gz: 1081108559a19f9f17b0c482dc91285f4950b1f7dda81c4f1221e2eac76206831839d265d50139182060c203e12dfd7752e434ecfae2fa5479310260b039fa7f

data/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+## 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.rc1'` 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,76 @@
+# 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`.
+
+`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.
+
+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, 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.0.0.rc1 is 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,45 @@
+# 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 icmp.ident icmp.seq
+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.
+
+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.

data/docs/USAGE.md

@@ -0,0 +1,82 @@
+# 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 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.
+
+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.

data/docs/VALIDATION.md

@@ -0,0 +1,59 @@
+# Release validation
+
+## 2.0.0.rc1
+
+The implementation covers the v2 roadmap: the packet/dissector API, network and
+application protocols, Ruby cBPF compiler/VM, Linux socket/ring and macOS BPF
+backends, capture files/rotation/privilege drop, bounded stateful analysis,
+statistics, follow output and documentation. This is a release candidate,
+not a claim that time-dependent GA acceptance checks have completed.
+
+Reproducible checks:
+
+- `bundle exec rake`: RSpec, generated RBS and Steep.
+- `REDHOUND_COVERAGE_GATE=1 bundle exec rake`: at least 90% total line coverage
+  and 95% protocol line coverage.
+- `bundle exec rspec spec/differential`: tcpdump filter match/bytecode parity
+  (163 expressions across five link types), tshark protocol and stateful analysis
+  field/statistics/follow comparisons.
+- `FUZZ_ITERATIONS=1000000 bundle exec rspec spec/fuzz`: strict parser fuzzing.
+- `sudo -E env "PATH=$PATH" REDHOUND_LIVE=1 bundle exec rspec --tag live`:
+  native capture, attached filters, kernel time, snaplen, stop and loopback.
+- `sudo -E env "PATH=$PATH" REDHOUND_LIVE=1 REDHOUND_NETNS=1 bundle exec rspec spec/integration/netns_capture_spec.rb --tag live`:
+  Linux veth socket/ring parity and offloaded VLAN restoration/filtering.
+- `bundle exec yard stats --list-undoc`: documented public API.
+- `actionlint`: test and release workflow validation.
+
+Fixtures are generated without runtime dependencies. Golden output freezes
+addresses and timestamps, and validates all JSON snapshots against the schema.
+The CI matrix checks Ruby 3.3/3.4/4.0/head, Linux/macOS live capture and tool
+comparisons. Scheduled runs execute one million fuzz cases. Benchmark jobs warn
+on a summary throughput regression over 15% compared with the previous commit.
+
+Local validation on 2026-10-01: Linux aarch64 Ruby 3.4 passed all 171 non-live
+examples, including tcpdump/tshark differential checks, and five live capture
+examples using socket and ring backends. Native macOS Ruby 4.0 passed unit,
+golden and filter checks; BPF ioctl constants match the installed SDK. Native
+BPF loopback and en0 Ethernet capture, attached filters, timestamps, truncation,
+termination, privilege dropping and pcapng metadata passed the macOS CI job.
+The Linux namespace test passed socket/ring parity and offloaded VLAN checks.
+Ruby 3.3/3.4/4.0/head all passed the CI type, signature and coverage gates.
+Whole-library line coverage measured 90.92%; isolated protocol line coverage
+measured 99.90%. See [benchmarks](../bench/RESULTS.md)
+for throughput figures and measurement limits.
+
+## Remaining GA acceptance gates
+
+- Run a 24-hour continuous capture stability check.
+- Run a 72-hour rotation soak and record RSS, descriptor counts and drop rates.
+- Run an hour of high-load aarch64 socket/ring comparison before changing its
+  automatic backend default.
+- Confirm x86_64 single-core throughput and live drop targets on the specified
+  workload; file benchmarks alone cannot establish loss-free live throughput.
+- Keep rc1 available for two weeks, classify reports, and fix critical/high
+  failures before GA.
+
+These elapsed-time/hardware gates are not marked complete by unit tests.
+Promote to 2.0.0 only after their evidence is recorded. A 1.x maintenance
+end date is set at GA plus six months; no maintenance branch is created by this
+main-only implementation.

data/docs/json-schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ydah/redhound/blob/main/docs/json-schema.json",
+  "title": "Redhound packet",
+  "description": "One packet object emitted by Packet#to_h, NDJSON, or an element of the JSON output array. Nanosecond timestamps and lengths are integers; byte fields use hexadecimal strings; repeated fields use arrays.",
+  "type": "object",
+  "required": ["frame", "layers", "diagnostics"],
+  "additionalProperties": false,
+  "properties": {
+    "frame": {
+      "type": "object",
+      "required": ["number", "time_epoch_ns", "time", "caplen", "len", "interface", "direction", "linktype"],
+      "additionalProperties": false,
+      "properties": {
+        "number": { "type": "integer", "minimum": 1 },
+        "time_epoch_ns": { "type": "integer" },
+        "time": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{9}Z$" },
+        "caplen": { "type": "integer", "minimum": 0 },
+        "len": { "type": "integer", "minimum": 0 },
+        "interface": { "type": ["string", "null"] },
+        "direction": { "enum": ["in", "out", null] },
+        "linktype": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "layers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["protocol", "offset", "length", "embedded", "fields"],
+        "additionalProperties": false,
+        "properties": {
+          "protocol": { "type": "string" },
+          "offset": { "type": "integer", "minimum": 0 },
+          "length": { "type": "integer", "minimum": 0 },
+          "embedded": { "type": "boolean" },
+          "fields": { "type": "object", "additionalProperties": { "$ref": "#/$defs/fieldValue" } }
+        }
+      }
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["layer", "severity", "code", "message", "field"],
+        "additionalProperties": false,
+        "properties": {
+          "layer": { "type": "string" },
+          "severity": { "enum": ["note", "warn", "warning", "error"] },
+          "code": { "type": "string" },
+          "message": { "type": "string" },
+          "field": { "type": ["string", "null"] }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "fieldValue": {
+      "anyOf": [
+        { "type": ["string", "number", "boolean", "null"] },
+        { "type": "array", "items": { "$ref": "#/$defs/fieldValue" } }
+      ]
+    }
+  }
+}

data/exe/redhound

@@ -4,4 +4,5 @@
 $LOAD_PATH << File.join(__dir__, '../lib')
 require 'redhound'
 
-Redhound::Command.new.run(ARGV.dup)
+RubyVM::YJIT.enable if defined?(RubyVM::YJIT) && RubyVM::YJIT.respond_to?(:enable) && !ARGV.include?('--no-yjit')
+exit Redhound::CLI::Command.new.run(ARGV.dup)