dpkt¶

dpkt is a python module for fast, simple packet creation / parsing, with definitions for the basic TCP/IP protocols

Getting Started¶

Installation¶

DKPT is now available directly from pypi :)

Install the Code¶

pip install dpkt

Checkout the Code¶

git clone https://github.com/kbandla/dpkt.git

Examples¶

Examples in dpkt/examples¶

Print Packets Example¶

This example uses DPKT to read in a pcap file and print out the contents of the packets This example is focused on the fields in the Ethernet Frame and IP packet

Code Excerpt

# For each packet in the pcap process the contents
for timestamp, buf in pcap:

    # Print out the timestamp in UTC
    print 'Timestamp: ', str(datetime.datetime.utcfromtimestamp(timestamp))

    # Unpack the Ethernet frame (mac src/dst, ethertype)
    eth = dpkt.ethernet.Ethernet(buf)
    print 'Ethernet Frame: ', mac_addr(eth.src), mac_addr(eth.dst), eth.type

    # Make sure the Ethernet frame contains an IP packet
    if not isinstance(eth.data, dpkt.ip.IP):
        print 'Non IP Packet type not supported %s\n' % eth.data.__class__.__name__
        continue

    # Now unpack the data within the Ethernet frame (the IP packet)
    # Pulling out src, dst, length, fragment info, TTL, and Protocol
    ip = eth.data

    # Pull out fragment information (flags and offset all packed into off field, so use bitmasks)
    do_not_fragment = bool(ip.off & dpkt.ip.IP_DF)
    more_fragments = bool(ip.off & dpkt.ip.IP_MF)
    fragment_offset = ip.off & dpkt.ip.IP_OFFMASK

    # Print out the info
    print 'IP: %s -> %s   (len=%d ttl=%d DF=%d MF=%d offset=%d)\n' % \
          (inet_to_str(ip.src), inet_to_str(ip.dst), ip.len, ip.ttl, do_not_fragment, more_fragments, fragment_offset)

Example Output

Timestamp:  2004-05-13 10:17:07.311224
Ethernet Frame:  00:00:01:00:00:00 fe:ff:20:00:01:00 2048
IP: 145.254.160.237 -> 65.208.228.223   (len=48 ttl=128 DF=1 MF=0 offset=0)

Timestamp:  2004-05-13 10:17:08.222534
Ethernet Frame:  fe:ff:20:00:01:00 00:00:01:00:00:00 2048
IP: 65.208.228.223 -> 145.254.160.237   (len=48 ttl=47 DF=1 MF=0 offset=0)

...

dpkt/examples/print_packets.py

Use DPKT to read in a pcap file and print out the contents of the packets This example is focused on the fields in the Ethernet Frame and IP packet

examples.print_packets.mac_addr(address)[source]¶

Convert a MAC address to a readable/printable string

Parameters:	address (str) – a MAC address in hex form (e.g. ‘’)
Returns:	Printable/readable MAC address
Return type:	str

examples.print_packets.inet_to_str(inet)[source]¶

Convert inet object to a string

Parameters:	inet (inet struct) – inet network address
Returns:	Printable/readable IP address
Return type:	str

examples.print_packets.print_packets(pcap)[source]¶

Print out information about each packet in a pcap

Parameters:	pcap – dpkt pcap reader object (dpkt.pcap.Reader)

examples.print_packets.test()[source]¶: Open up a test pcap file and print out the packets

Print ICMP Example¶

This example expands on the print_packets example. It checks for ICMP packets and displays the ICMP contents.

Code Excerpt

# For each packet in the pcap process the contents
for timestamp, buf in pcap:

    # Unpack the Ethernet frame (mac src/dst, ethertype)
    eth = dpkt.ethernet.Ethernet(buf)

    # Make sure the Ethernet data contains an IP packet
    if not isinstance(eth.data, dpkt.ip.IP):
        print 'Non IP Packet type not supported %s\n' % eth.data.__class__.__name__
        continue

    # Now grab the data within the Ethernet frame (the IP packet)
    ip = eth.data

    # Now check if this is an ICMP packet
    if isinstance(ip.data, dpkt.icmp.ICMP):
        icmp = ip.data

        # Pull out fragment information (flags and offset all packed into off field, so use bitmasks)
        do_not_fragment = bool(ip.off & dpkt.ip.IP_DF)
        more_fragments = bool(ip.off & dpkt.ip.IP_MF)
        fragment_offset = ip.off & dpkt.ip.IP_OFFMASK

        # Print out the info
        print 'Timestamp: ', str(datetime.datetime.utcfromtimestamp(timestamp))
        print 'Ethernet Frame: ', mac_addr(eth.src), mac_addr(eth.dst), eth.type
        print 'IP: %s -> %s   (len=%d ttl=%d DF=%d MF=%d offset=%d)' % \
              (inet_to_str(ip.src), inet_to_str(ip.dst), ip.len, ip.ttl, do_not_fragment, more_fragments, fragment_offset)
        print 'ICMP: type:%d code:%d checksum:%d data: %s\n' % (icmp.type, icmp.code, icmp.sum, repr(icmp.data))

Example Output

Timestamp:  2013-05-30 22:45:17.283187
Ethernet Frame:  60:33:4b:13:c5:58 02:1a:11:f0:c8:3b 2048
IP: 192.168.43.9 -> 8.8.8.8   (len=84 ttl=64 DF=0 MF=0 offset=0)
ICMP: type:8 code:0 checksum:48051 data: Echo(id=55099, data='Q\xa7\xd6}\x00\x04Q\xe4\x08\t\n\x0b\x0c\r\x0e\x0f\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f !"#$%&\'()*+,-./01234567')

Timestamp:  2013-05-30 22:45:17.775391
Ethernet Frame:  02:1a:11:f0:c8:3b 60:33:4b:13:c5:58 2048
IP: 8.8.8.8 -> 192.168.43.9   (len=84 ttl=40 DF=0 MF=0 offset=0)
ICMP: type:0 code:0 checksum:50099 data: Echo(id=55099, data='Q\xa7\xd6}\x00\x04Q\xe4\x08\t\n\x0b\x0c\r\x0e\x0f\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f !"#$%&\'()*+,-./01234567')

...

dpkt/examples/print_icmp.py

This example expands on the print_packets example. It checks for ICMP packets and displays the ICMP contents.

examples.print_icmp.mac_addr(address)[source]¶

Convert a MAC address to a readable/printable string

Parameters:	address (str) – a MAC address in hex form (e.g. ‘’)
Returns:	Printable/readable MAC address
Return type:	str

examples.print_icmp.inet_to_str(inet)[source]¶

Convert inet object to a string

Parameters:	inet (inet struct) – inet network address
Returns:	Printable/readable IP address
Return type:	str

examples.print_icmp.print_icmp(pcap)[source]¶

Print out information about each packet in a pcap

Parameters:	pcap – dpkt pcap reader object (dpkt.pcap.Reader)

examples.print_icmp.test()[source]¶: Open up a test pcap file and print out the packets

Print HTTP Requests Example¶

This example expands on the print_packets example. It checks for HTTP request headers and displays their contents.

NOTE: We are not reconstructing ‘flows’ so the request (and response if you tried to parse it) will only parse correctly if they fit within a single packet. Requests can often fit in a single packet but Responses almost never will. For proper reconstruction of flows you may want to look at other projects that use DPKT (http://chains.readthedocs.io and others)

Code Excerpt

# For each packet in the pcap process the contents
for timestamp, buf in pcap:

    # Unpack the Ethernet frame (mac src/dst, ethertype)
    eth = dpkt.ethernet.Ethernet(buf)

    # Make sure the Ethernet data contains an IP packet
    if not isinstance(eth.data, dpkt.ip.IP):
        print 'Non IP Packet type not supported %s\n' % eth.data.__class__.__name__
        continue

    # Now grab the data within the Ethernet frame (the IP packet)
    ip = eth.data

    # Check for TCP in the transport layer
    if isinstance(ip.data, dpkt.tcp.TCP):

        # Set the TCP data
        tcp = ip.data

        # Now see if we can parse the contents as a HTTP request
        try:
            request = dpkt.http.Request(tcp.data)
        except (dpkt.dpkt.NeedData, dpkt.dpkt.UnpackError):
            continue

        # Pull out fragment information (flags and offset all packed into off field, so use bitmasks)
        do_not_fragment = bool(ip.off & dpkt.ip.IP_DF)
        more_fragments = bool(ip.off & dpkt.ip.IP_MF)
        fragment_offset = ip.off & dpkt.ip.IP_OFFMASK

        # Print out the info
        print 'Timestamp: ', str(datetime.datetime.utcfromtimestamp(timestamp))
        print 'Ethernet Frame: ', mac_addr(eth.src), mac_addr(eth.dst), eth.type
        print 'IP: %s -> %s   (len=%d ttl=%d DF=%d MF=%d offset=%d)' % \
              (inet_to_str(ip.src), inet_to_str(ip.dst), ip.len, ip.ttl, do_not_fragment, more_fragments, fragment_offset)
        print 'HTTP request: %s\n' % repr(request)

Example Output

Timestamp:  2004-05-13 10:17:08.222534
Ethernet Frame:  00:00:01:00:00:00 fe:ff:20:00:01:00 2048
IP: 145.254.160.237 -> 65.208.228.223   (len=519 ttl=128 DF=1 MF=0 offset=0)
HTTP request: Request(body='', uri='/download.html', headers={'accept-language': 'en-us,en;q=0.5', 'accept-encoding': 'gzip,deflate', 'connection': 'keep-alive', 'keep-alive': '300', 'accept': 'text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,image/jpeg,image/gif;q=0.2,*/*;q=0.1', 'user-agent': 'Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.6) Gecko/20040113', 'accept-charset': 'ISO-8859-1,utf-8;q=0.7,*;q=0.7', 'host': 'www.ethereal.com', 'referer': 'http://www.ethereal.com/development.html'}, version='1.1', data='', method='GET')

Timestamp:  2004-05-13 10:17:10.295515
Ethernet Frame:  00:00:01:00:00:00 fe:ff:20:00:01:00 2048
IP: 145.254.160.237 -> 216.239.59.99   (len=761 ttl=128 DF=1 MF=0 offset=0)
HTTP request: Request(body='', uri='/pagead/ads?client=ca-pub-2309191948673629&random=1084443430285&lmt=1082467020&format=468x60_as&output=html&url=http%3A%2F%2Fwww.ethereal.com%2Fdownload.html&color_bg=FFFFFF&color_text=333333&color_link=000000&color_url=666633&color_border=666633', headers={'accept-language': 'en-us,en;q=0.5', 'accept-encoding': 'gzip,deflate', 'connection': 'keep-alive', 'keep-alive': '300', 'accept': 'text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,image/jpeg,image/gif;q=0.2,*/*;q=0.1', 'user-agent': 'Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.6) Gecko/20040113', 'accept-charset': 'ISO-8859-1,utf-8;q=0.7,*;q=0.7', 'host': 'pagead2.googlesyndication.com', 'referer': 'http://www.ethereal.com/download.html'}, version='1.1', data='', method='GET')

...

dpkt/examples/print_http_requests.py

This example expands on the print_packets example. It checks for HTTP request headers and displays their contents. NOTE: We are not reconstructing ‘flows’ so the request (and response if you tried to parse it) will only

parse correctly if they fit within a single packet. Requests can often fit in a single packet but Responses almost never will. For proper reconstruction of flows you may want to look at other projects that use DPKT (http://chains.readthedocs.io and others)

examples.print_http_requests.mac_addr(address)[source]¶

Convert a MAC address to a readable/printable string

Parameters:	address (str) – a MAC address in hex form (e.g. ‘’)
Returns:	Printable/readable MAC address
Return type:	str

examples.print_http_requests.inet_to_str(inet)[source]¶

Convert inet object to a string

Parameters:	inet (inet struct) – inet network address
Returns:	Printable/readable IP address
Return type:	str

examples.print_http_requests.print_http_requests(pcap)[source]¶

Print out information about each packet in a pcap

Parameters:	pcap – dpkt pcap reader object (dpkt.pcap.Reader)

examples.print_http_requests.test()[source]¶: Open up a test pcap file and print out the packets

Jon Oberheide’s Examples¶

[@jonoberheide’s](https://twitter.com/jonoberheide) old examples still apply:

Jeff Silverman Docs/Code¶

Jeff Silverman has some code and documentation.

API Reference¶

The dpkt API reference section is currently a work in progress, please have patience as we fill in and improve the documentation.

dpkt Modules

dpkt.ah module¶

Authentication Header.

class dpkt.ah.AH(*args, **kwargs)[source]¶

Parameters:	buf – A buffer with format “yymnddhhmm”
Returns:	A floating point number, indicates seconds since the Epoch.

Parameters:	buf – A buffer with Sleazy ASN.1 data.
Returns:	A list of (id, value) tuples from ASN.1 BER/DER encoded buffer.
Raises:	UnpackError – An error occurred the ASN.1 length exceed.

Parameters:	buf – string containing SSL/TLS messages. May have an incomplete record on the end
Returns:	[TLSRecord] int, total bytes consumed, != len(buf) if an incomplete record was left at the end.

dpkt¶

Getting Started¶

Installation¶

Install the Code¶

Checkout the Code¶

Examples¶

Examples in dpkt/examples¶

Print Packets Example¶

Print ICMP Example¶

Print HTTP Requests Example¶

Jon Oberheide’s Examples¶

Jeff Silverman Docs/Code¶

API Reference¶

API Reference¶

dpkt.ah module¶

dpkt.aim module¶

dpkt.aoe module¶

dpkt.aoeata module¶

dpkt.aoecfg module¶

dpkt.arp module¶

dpkt.asn1 module¶

dpkt.bgp module¶

dpkt.cdp module¶

dpkt.crc32c module¶

dpkt.decorators module¶

dpkt.dhcp module¶

dpkt.diameter module¶

dpkt.dns module¶

dpkt.dpkt module¶

dpkt.dtp module¶

dpkt.esp module¶

dpkt.ethernet module¶

dpkt.gre module¶

dpkt.gzip module¶

dpkt.h225 module¶

dpkt.hsrp module¶

dpkt.http module¶

dpkt.icmp module¶

dpkt.icmp6 module¶

dpkt.ieee80211 module¶

dpkt.igmp module¶

dpkt.ip module¶

dpkt.ip6 module¶

dpkt.ipx module¶

dpkt.llc module¶

dpkt.loopback module¶

dpkt.mrt module¶

dpkt.netbios module¶

dpkt.netflow module¶

dpkt.ntp module¶

dpkt.ospf module¶

dpkt.pcap module¶

dpkt.pim module¶

dpkt.pmap module¶

dpkt.ppp module¶

dpkt.pppoe module¶

dpkt.qq module¶

dpkt.radiotap module¶

dpkt.radius module¶

dpkt.rfb module¶

dpkt.rip module¶

dpkt.rpc module¶

dpkt.rtp module¶

dpkt.rx module¶

dpkt.sccp module¶

dpkt.sctp module¶

dpkt.sip module¶

dpkt.sll module¶

dpkt.smb module¶

dpkt.snoop module¶

dpkt.ssl module¶

dpkt.ssl_ciphersuites module¶

dpkt.stp module¶

dpkt.stun module¶

dpkt.tcp module¶

dpkt.telnet module¶

dpkt.tftp module¶

dpkt.tns module¶

dpkt.tpkt module¶

dpkt.udp module¶