Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Statistics and Automation

Parsing PCAP Files with Python

Understand the pcap file format and decode Ethernet, IPv4, TCP and UDP headers with Python's struct module, then automate analysis and use tshark from scripts.

When you need the same analysis on a hundred capture files, clicking is too slow. Scripts can read packets and compute whatever you need. In this lesson you will decode a capture by hand with Python's struct module, which teaches exactly what the protocol headers contain, and then see how real projects automate with libraries and tshark.

The example builds a tiny pcap in memory, so everything runs in your browser without real network access. It is a stand-in for reading a real file with open("capture.pcap", "rb").

The classic pcap file format

A pcap file is simple:

  1. A global header of 24 bytes: magic number (0xa1b2c3d4, which also tells you the byte order), version, timezone offset, snapshot length, and link type (1 = Ethernet).
  2. A series of records, each with a 16-byte header (timestamp seconds, microseconds, captured length, original length) followed by that many bytes of packet data.

The newer pcapng format adds blocks (interface description, comments, name resolution) and is Wireshark's default. Libraries can read both; the idea is the same.

Python Build and read a pcap in memory

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Decoding the layers

Packets nest like envelopes: Ethernet contains IP, which contains TCP or UDP. Each parser reads its fixed header, then hands the remaining bytes to the next one.

flowchart LR
    A["Ethernet 14 B"] --> B["IPv4 20+ B"] --> C["TCP 20+ B / UDP 8 B"] --> D["Payload"]

Each layer's header tells you which layer comes next.

  • Ethernet: 6 bytes destination MAC, 6 bytes source MAC, 2 bytes EtherType (0x0800 = IPv4, 0x86dd = IPv6, 0x0806 = ARP).
  • IPv4: the first byte holds version (4) and header length in 32-bit words (IHL). Protocol field: 6 = TCP, 17 = UDP, 1 = ICMP. Source and destination addresses are 4 bytes each.
  • TCP: source and destination ports (2 bytes each), sequence and acknowledgment numbers (4 each), data offset, and flag bits (SYN, ACK, FIN, RST, PSH, URG).
Python Decode Ethernet, IPv4 and TCP flags

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The same function applied to every record in a real file gives you a packet list. Counting SYN-without-ACK per source reproduces the port scan detector from Spotting Port Scans.

Libraries and tshark in scripts

Writing parsers by hand is good for learning. For real work use:

  • scapy: read, build and dissect packets in Python. Convenient, but slower on large files.
  • dpkt or pyshark: fast parsing; pyshark wraps tshark and exposes Wireshark's dissected fields as Python attributes.
  • tshark with -T fields or -T json: the most complete dissection, driven with subprocess:
Python
import subprocess, csv, io

out = subprocess.run(
    ["tshark", "-r", "capture.pcapng", "-Y", "dns", "-T", "fields",
     "-e", "frame.time_relative", "-e", "dns.qry.name",
     "-E", "separator=,"],
    capture_output=True, text=True, check=True,
).stdout
for row in csv.reader(io.StringIO(out)):
    print(row)

This snippet needs tshark installed and a real file, so it is shown read-only. Always pass arguments as a list (never build a shell string from untrusted input), and check that a capture file is something you are permitted to read.

Robustness tips

  • Validate lengths before slicing. Malformed packets are common, and parsing code must not crash on them.
  • Handle VLAN tags (EtherType 0x8100) and IPv6 extension headers.
  • Stream large files: read record by record instead of loading everything into memory.
  • Mind the byte order: pcap files are written in the capturing machine's order; the magic number tells you which.
  • Never execute data from a capture. Treat payload bytes as untrusted input.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How long is the pcap global header?

    The global header is 24 bytes; each packet record then has a 16-byte header.
  2. 2. In an IPv4 header, which value of the protocol field means TCP?

    1 is ICMP, 6 is TCP, and 17 is UDP.
  3. 3. Why must parsing code validate lengths before slicing?

    Capture files can contain short or corrupt packets, so every read needs a bounds check.
  4. 4. Which approach gives the most complete protocol dissection from a script?

    tshark uses Wireshark's full set of dissectors, so scripts get the same fields as the GUI.

Summary

  • A pcap is a 24-byte header plus records of a 16-byte header and packet bytes.
  • Layers nest: Ethernet, then IP, then TCP or UDP, then payload.
  • struct decodes fixed headers; libraries and tshark handle the full protocol zoo.
  • Treat capture data as untrusted input and write defensive parsers.

Next: Decrypting TLS with a Key Log File