Crate packet_rs

packet_rs

packet_rs is a rust based alternative to the popular python Scapy packet library. It tries to provide a scapy like API interface to define new headers and construct packets.

• The headers module, defines commonly used network packet headers and allows for defining new header types
• The Packet struct, a convenient abstraction of a network packet and container to hold a group of headers
• The parser module, provides a super fast packet deserializer to compose Packets from slices

Terminology

• Packet refers to a container which represents a network packet
• Headers are network headers like ARP, IP, Vxlan, etc
• Slice is a network packet represented as a series of u8 bytes

Create a header

A header is a network protocol header and allows to individually get/set each field in the header

let mut eth = Ether::new();
eth.set_dst(0xaabbccddeeff);
println!("{}", eth.etype());

Create a Packet

A packet is an ordered list of headers.

• Push or pop headers into the packet
• Mutably/immutably retrieve existing headers
• Set a custom payload

let mut pkt = Packet::new();
pkt.push(Ether::new());
pkt.push(IPv4::new());
pkt.push(Packet::udp(1023, 1234, 95));

Parse a byte stream

Parse a byte stream to generate a Packet or a PacketSlice

• The parser fast module is zero-copy and generates a PacketSlice. PacketSlice has the same lifetime as the byte stream.
• The parser slow module creates a new packet from the byte stream.

Both of the above parsing options provide full access to all the headers and each field within the header.

let mut pkt: Packet = parser::slow::parse(&data.as_slice());
let eth: &mut Ether = (&mut pkt["Ether"]).into();
println!("{}", eth.etype());

Similar semantics apply for fast parsing except where a PacketSlice is returned.

• parser::slow::parse_ethernet for parsing from an Ethernet header and below and then edit it
• parser::fast::parse_ipv4 for parsing`] from an IPv4 and below and is read-only

Define a header

Define a header which can go into a new protocol stack

make_header!(
MyHeader 4
(
    field_1: 0-2,
    field_2: 3-3,
    field_3: 4-15,
    field_4: 16-31
)
vec![0x0, 0xa, 0x8, 0x0]      // <= optional default data
);

// Create the custom header
let hdr = MyHeader::new();

// make_header! generates helper methods and associated functions for each field in the header
println!("{}", hdr.field_2());   // fetch the field_2 value
hdr.set_field_2(1);              // set the field_2 value
hdr.show();                      // display the MyHeader header

Python support

packet_rs supports Rust bindings for Python. All of the pre-defined header and Packet APIs are available as Python APIs Please refer to examples/pkt.py and pyo3/maturin documentation on how to use the bindings.

cargo build --features python-module

Modules

headers

Headers module which includes all pre-defined headers

parser

Parser module to deserialize network packets

utils

Helper utilities to generate packets

Macros

make_header

Defines a header

Structs

Packet

Structure used to hold an ordered list of headers

PacketSlice

Structure used to hold an ordered list of header slices