# packeteer

Terminal packet capture and analysis for Linux. Captures live traffic or
replays a saved file, decodes it from Ethernet up to the application
layer, and shows the result in a plain-text log, an interactive TUI, or a
graphical window.

Capture files are pcapng, so Wireshark reads them and interface metadata
survives the round trip.

## Build

Requires a C++20 compiler, CMake 3.20 or later, and libpcap. FTXUI,
doctest, SDL3 and Dear ImGui are fetched during configuration, so no
system packages are needed for them.

```
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
```

The binaries are `build/packeteer` (command line and TUI),
`build/packeteer_gui` (graphical), and `build/packeteer_tests`.

## Use

```
packeteer [options] [interface]
```

With no interface, the first available device is used.

| Option | Effect |
| --- | --- |
| `-t`, `--tui` | Interactive TUI instead of plain-text output |
| `-x` | Hex dump under each summary, plain-text mode only |
| `-c` | Show IPv4/TCP/UDP checksum validity |
| `-a` | Reassemble TCP streams and re-run HTTP parsing on the joined bytes |
| `-w <file>` | Write the capture to a pcapng file |
| `-r <file>` | Replay a pcapng file instead of a live device |
| `-f <expr>` | Capture filter in tcpdump/BPF syntax |
| `-g <term>` | Display filter: show only summaries containing `term` |
| `-h`, `--help` | Show usage |

In the TUI, press `/` to search interactively.

### Filters

`-f` is a kernel-level BPF filter. The kernel discards what does not
match, so those packets never reach the process, and `-w` writes only
what passed. Use it to cut volume at the source.

`-g` is a display filter applied after decoding. It changes what you see,
not what is captured, and does not affect `-w`.

`-f` cannot be combined with `-r`, because a saved file has already been
filtered at capture time.

### Checksums

Checksum validation is off by default. Most network cards compute the
real checksum in hardware, after the point where capture taps the packet.
Outbound and loopback packets therefore read as invalid even when nothing
is wrong. Turn it on with `-c` when you are looking at received traffic
and the distinction matters.

### TCP reassembly

`-a` joins TCP segments and parses the result, which catches an HTTP
request or response split across several packets that single-packet
dissection misses. In-order segments only. Out-of-order and retransmitted
segments are dropped rather than buffered.

## Protocol support

Link and network layers: Ethernet, ARP, IPv4, IPv6, ICMP, IGMP, LLDP.

Transport: TCP with stream reassembly, UDP, RTP, RTCP.

Application: DHCP, DNS, mDNS, HTTP, FTP, SMTP, SSH, TLS, QUIC, NTP, SNMP,
TFTP.

Fragmented IPv4 and IPv6 packets are reported as fragments. A non-first
fragment carries no transport header, so its payload is not decoded as
one.

## Capture backends

libpcap is the default and works on any interface it supports.

A second path uses a raw `AF_PACKET` socket with an mmap'd ring buffer,
which avoids libpcap's copies. It is Linux-only and built as
`packeteer_afpacket_demo`.

## Privileges

Packet capture needs `CAP_NET_RAW`. Grant it to the binary rather than
running as root:

```
sudo setcap cap_net_raw,cap_net_admin=eip build/packeteer
```

The capture handle is opened first and privileges are dropped immediately
afterwards, so the decoders never run with them.

## Tests

```
cmake --build build -j && ./build/packeteer_tests
```

Unit tests cover the decoders, the byte reader, the capture queue and the
filters. Twelve libFuzzer targets under `fuzz/` exercise the parsers
against malformed input; build them with
`-DPACKETEER_ENABLE_FUZZING=ON` and a Clang toolchain.