Overview Packet Analysis

This repository contains code related to the Python module PyShark, which is a wrapper for the Wireshark command-line interface (CLI) for TShark. The latter using the Wireshark dissectors to sniff and capture packets from a network inteface. The real power of PyShark is its capability to access to all of the packet decoders built into TShark.

PyShark can operate in either LiveCapture or FileCapture modes. Both modes have methods that can be used to parse specific packet level attributes, which includes protocols and their associated ports.

LiveCapture Usage examples:

Basic Capture

capture = pyshark.LiveCapture(interface='your capture interface')
for packet in capture:
   # do something with the packet

LiveCapture with packet count

PyShark LiveCapture has a featured named sniff_continuously that allows you to limit the number of packets captured.

capture = pyshark.LiveCapture(interface='your capture interface')
for packet in capture.sniff_continuously(packet_count=10):
   # do something with the packet

LiveCapture with timeout

PyShark LiveCapture also has a featured named sniff< that allows you to set a capture timeout period.

capture = pyshark.LiveCapture(interface='your capture interface')
capture.sniff(timeout=10)
packets = [pkt for pkt in capture._packets]
capture.close()
for packet in packets:
   # do something with the packet

LiveCapture with BPF_Filter

The PyShark LiveCapture mode has a BPF_Filter that allows you to prefilter the packets being captured. The example below show how to parse Domain Name System (DNS) packets from a LiveCapture session.

capture = pyshark.LiveCapture(interface='your capture interface', bpf_filter='udp port 53')
for packet in capture:
   # do something with the packet

The FileCapture mode of PyShark also has prefilter capabilities via the Display_Filter. The example below show how to parse Domain Name System (DNS) packets from a FileCapture session.

FileCapture Display_Filter

capture = pyshark.FileCapture(pcap_file, display_filter='dns')
for packet in capture:
   # do something with the packet

Function Level Filtering

This type of packet filtering does not use the built-in PyShark's functions BPF_Filter or Display_Filter.

if hasattr(packet, 'udp') and packet[packet.transport_layer].dstport == '53':

or

if hasattr(packet, 'tcp'):
  if packet[packet.transport_layer].dstport == '80' or packet[packet.transport_layer].dstport == '443':

Accessing packet data elements:

All packets have layers, but these layers vary based on the packet type. These layers can be queried and the data elements within these layers can be extracted. Layer types can be accessed using the following parameter:

packet.layers

Common Layers:

• ETH Layer - Ethernet
• IP Layer - Internet Protocol
• TCP Layer - Transmission Control Protocol
• UDP Layer - User Datagram Protocol
• ARP Layer - Address Resolution Protocol

Other Layers:

• BROWSER Layer - Web browser
• DATA Layer - Normal data payload of a protocol
• DB-LSP-DISC Layer - Dropbox LAN Sync Discovery
• DHCP Layer - Dynamic Host Configuration Protocol
• HTTP Layer - Hypertext Transfer Protocol
• LLMNR Layer - Link-Local Multicast Name Resolution
• MAILSLOT Layer - Mailslot protocol is part of the SMB protocol family
• MSNMS Layer - Microsoft Network Messenger Service
• NAT-PMP Layer - NAT Port Mapping Protocol
• NBDGM Layer - NetBIOS Datagram Service
• NBNS Layer - NetBIOS Name Service
• SMB Layer - Server Message Block
• SNMP Layer - Simple Network Management Protocol
• SSDP Layer - Simple Service Discovery Protocol
• TLS Layer - Transport Layer Security,
• XML Layer - Extensible Markup Language

Parsing examples:

PyShark has a lot of flexibility to parse various types of information from an individual network packet. Below are some of the items that can be parsed using the transport_layer and IP layer.

Example One:

protocol = packet.transport_layer
source_address = packet.ip.src
source_port = packet[packet.transport_layer].srcport
destination_address = packet.ip.dst
destination_port = packet[packet.transport_layer].dstport 
packet_time = packet.sniff_time
packet_timestamp = packet.sniff_timestamp

Output Example One:

Protocol type: UDP
Source address: 192.168.3.1
Source port: 53
Destination address: 192.168.3.131
Destination port: 58673
Date and Time: 2011-01-25 13:57:18.356677
Timestamp: 1295981838.356677000

Example Two:

This example shows how to access the field elements within the HTTP layer. The code below queries a Packet Capture (PCAP) file for all the URLs within the HTTP layer with the field name request.full_uri.

cap_file = 'traffic_flows_small.pcap'
capture = pyshark.FileCapture(pcap_file)
for packet in capture:
   if hasattr(packet, 'http'):
     field_names = packet.http._all_fields
     field_values = packet.http._all_fields.values()
     for field_name in field_names:
        for field_value in field_values:
           if field_name == 'http.request.full_uri' and field_value.startswith('http'):
             print(f'{field_value}')

Output Example Two:

https://stackoverflow.com/questions/tagged/python
https://stackoverflow.com/questions/tagged/python-3.x
https://stackoverflow.com/search?q=pyshark

Additional parsing examples:

Here are some additional parsing examples that I posted to GitHub Gist.

• Extract the conversation header information from a PCAP packet

• Extract DNS elements from a PCAP packet

• Extract the HTTP information from IPv4 and ICMPv6 packets

• Extract specific IPv6 elements from a PCAP packet

Prerequisites

TShark has to be installed and accessible via your $PATH, which Python queries for PyShark. For this experiment TShark was installed using Homebrew.

The package Wireshark installs the command line utility TShark. The command used to install Wireshark was:

brew install wireshark

References:

• PyShark: Is the Python wrapper for TShark, that allows Python packet parsing using wireshark dissectors.

• TShark: TShark is a terminal oriented version of Wireshark designed for capturing and displaying packets when an interactive user interface isn't necessary or available.

• Wireshark: Wireshark is a network packet analysis tool that captures packets in real time and displays them in a graphic interface.

• Homebrew: Package Manager for macOS and Linux.

• Berkeley Packet Filter (BPF) syntax

• Display Filter syntax

Notes:

PyShark has limited documentation, so I would highly recommend reviewing the source code in the PyShark GitHub repository. Several of the parameters listed in this README were pulled directly from the source code.

The code within this repository is not production ready. It was strictly designed for experimental testing purposes only.