#pcap #pcapng #pcap-ng

pcarp

A pure-Rust library for reading pcap-ng files

10 releases (5 stable)

1.2.0 Jul 13, 2020
1.1.1 Oct 10, 2019
1.1.0 Jun 23, 2019
1.0.1 Feb 21, 2019
0.1.2 Nov 8, 2018

#234 in Network programming

Download history 1300/week @ 2021-08-17 1262/week @ 2021-08-24 794/week @ 2021-08-31 1227/week @ 2021-09-07 1491/week @ 2021-09-14 801/week @ 2021-09-21 932/week @ 2021-09-28 1969/week @ 2021-10-05 2070/week @ 2021-10-12 1479/week @ 2021-10-19 841/week @ 2021-10-26 739/week @ 2021-11-02 1257/week @ 2021-11-09 900/week @ 2021-11-16 1175/week @ 2021-11-23 578/week @ 2021-11-30

4,072 downloads per month
Used in feeless

Unlicense

56KB
725 lines

pcarp

A pure-Rust library for reading pcap-ng files.

  • Correct: Agrees with tshark across a broad test suite.
  • Fast: Zero-copy. Performance is in libpcap's ballpark.
  • Flexible input: Takes anything which implements Read.
  • Flexible output: Exposes a streaming-iterator-style API.
  • Reliable: No panics, even on malformed input.

Limitations

pcarp is a simple library: it reads pcap-ng files and that's it. Limitations compared to libpcap:

  • No support for legacy pcap; pcarp is pcap-ng-only.
  • No support for writing; pcarp is read-only.
  • No dissection of any kind. pcarp gives you the raw packet data. If you want to parse ethernet/IP/TCP/whatever protocol, try pnet or rshark.
  • No filtering. This one follows from "no dissection".

API

Are your pcaps gzipped? No problem: Capture::new() takes anything which implements Read, so just wrap your File in a GzDecoder first.

The output API is streaming-iterator-style (advance() and get()), and an iterator-style API is also included for convenience.

Conformance

The integration test suite consists of all the pcapng files I could scrape from the Wireshark wiki. See integration_tests/ for details.

Safety

It's our intention that pcarp should never panic, even given malformed or malicious input. The library is fuzzed to help ensure that this is the case, but fuzzing isn't perfect. If you experience a crash, please report it to the authors.

It's currently possible to construct bad blocks which pcarp can't move past. In other words: you can insert one of these malformed blocks into an otherwise good pcap and instead of reporting a single error and moving on, pcarp will give you an infinite series of errors. If your input is untrusted, don't assume that your stream will terminate.

Performance

I've benchmarked the decoding time against the pcap library (which uses libpcap) over a variety of pcaps. libpcap dominates the benchmarks, but not by a huge amount. Interestingly, the savings come mostly from spending less time in the kernel. Somehow libpcap is performing fewer syscalls than pcarp...

License

The software itself is in the public domain.

Some of the documentation is copied from the pcap spec, so the copyright is owned by the IETF; these places are cleary marked. The pcaps used by the integration tests are distributed by the Wireshark Foundation under the terms of the GNU GPL.

Dependencies

~375–570KB
~10K SLoC