Crate pcap

pcap is a packet capture library available on Linux, Windows and Mac. This crate supports creating and configuring capture contexts, sniffing packets, sending packets to interfaces, listing devices, and recording packet captures to pcap-format dump files.

Capturing packets

The easiest way to open an active capture handle and begin sniffing is to use .open() on a Device. You can obtain the “default” device using Device::lookup(), or you can obtain the device(s) you need via Device::list().

use pcap::Device;

let mut cap = Device::lookup().unwrap().unwrap().open().unwrap();

while let Ok(packet) = cap.next_packet() {
    println!("received packet! {:?}", packet);
}

Capture’s .next_packet() will produce a Packet which can be dereferenced to access the &[u8] packet contents.

Custom configuration

You may want to configure the timeout, snaplen or other parameters for the capture handle. In this case, use Capture::from_device() to obtain a Capture<Inactive>, and proceed to configure the capture handle. When you’re finished, run .open() on it to turn it into a Capture<Active>.

use pcap::{Device, Capture};

let main_device = Device::lookup().unwrap().unwrap();
let mut cap = Capture::from_device(main_device).unwrap()
                  .promisc(true)
                  .snaplen(5000)
                  .open().unwrap();

while let Ok(packet) = cap.next_packet() {
    println!("received packet! {:?}", packet);
}

Abstracting over different capture types

You can abstract over live captures (Capture<Active>) and file captures (Capture<Offline>) using generics and the Activated trait, for example:

use pcap::{Activated, Capture};

fn read_packets<T: Activated>(mut capture: Capture<T>) {
    while let Ok(packet) = capture.next_packet() {
        println!("received packet! {:?}", packet);
    }
}

Structs

• Address
  Address information for an interface
• BpfInstruction
• BpfProgram
• Capture
  This is a pcap capture handle which is an abstraction over the pcap_t provided by pcap. There are many ways to instantiate and interact with a pcap handle, so phantom types are used to express these behaviors.
• Device
  A network device name and pcap’s description of it.
• DeviceFlags
• IfFlags
  Network device flags.
• Linktype
  This is a datalink link type.
• Packet
  Represents a packet returned from pcap.
• PacketHeader
  Represents a packet header provided by pcap, including the timeval, caplen and len.
• PacketIter
  Implement an Iterator of Packet
• PacketStream
  Implement Stream for async use of pcap
• Savefile
  Abstraction for writing pcap savefiles, which can be read afterwards via Capture::from_file().
• Stat
  Packet statistics for a capture

Enums

• Active
  Phantom type representing an active capture handle.
• ConnectionStatus
  Indication of whether the adapter is connected or not; for wireless interfaces, “connected” means “associated with a network”.
• Dead
  Phantom type representing a dead capture handle. This can be use to create new save files that are not generated from an active capture. Implements Activated because it behaves nearly the same as a live handle.
• Direction
  The direction of packets to be captured. Use with Capture::direction.
• Error
  An error received from pcap
• Inactive
  Phantom type representing an inactive capture handle.
• Offline
  Phantom type representing an offline capture handle, from a pcap dump file. Implements Activated because it behaves nearly the same as a live handle.
• Precision
  Timestamp resolution types
• TimestampType
  Timestamp types

Traits

• Activated
  Captures can be in different states at different times, and in these states they may or may not have particular capabilities. This trait is implemented by phantom types which allows us to punt these invariants to the type system to avoid runtime errors.
• PacketCodec
  This trait is used to implement Stream and Iterator feature. This is almost like map().
• State
  Captures can be in different states at different times, and in these states they may or may not have particular capabilities. This trait is implemented by phantom types which allows us to punt these invariants to the type system to avoid runtime errors.

Functions

• open_raw_fd^⚠
  Open a raw file descriptor.

Type Aliases

• TstampTypeDeprecated
  An old name for TimestampType, kept around for backward-compatibility.