pcap-analysis¶

Analyze packet capture format (.pcap or .pcapng) files.

About¶

Contributors¶

Tyler N. Thieding (Primary Author)

Development¶

Repository:	https://gitlab.com/TNThieding/pcap-analysis/

License¶

Copyright 2020 Tyler N. Thieding

Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the "Software"), to deal in the Software
without restriction, including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

API Reference¶

Classes
- PacketAnalyzer
Analyzers
- ARP
- BOOTP
- DHCP
- ICMP

Analyze packet capture format (pcap) files.

Classes ¶

PacketAnalyzer ¶

class pcap_analysis.PacketAnalyzer(pcap_file)¶

Packet analyzer interface.

Parameters:	pcap_file (str) – path to packet capture file (i.e., pcap or`pcapng`)

arp¶: Address resolution protocol (ARP) analyzer accessor.

bootp¶: Bootstrap protocol (BOOTP) analyzer accessor.

dhcp¶: Dynamic host configuration protocol (DHCP) analyzer accessor.

icmp¶: Internet control message protocol (ICMP) analyzer accessor.

Analyzers ¶

Access analyzer class instances through the PacketAnalyzer class. They should not be instantiated directly and used standalone!

ARP ¶

class pcap_analysis._analyzers.arp.Arp¶

Address resolution protocol (ARP) analyzer.

did_device_arp_for(mac_address, target_ip)¶

Check if the specified device ARPed for the specified target IP address.

Parameters:	mac_address (str) – device MAC address target_ip (str) – target IP address
Returns:	device sent ARP packet(s)
Return type:	bool

did_device_receive_response(mac_address, target_ip)¶

Check if the specified device received an ARP reply from the specified target IP address.

If the device received a response, the IP and MAC address are included in the ARP table accessible with the get_arp_table method.

Parameters:	mac_address (str) – device MAC address target_ip (str) – target IP address
Returns:	device received ARP reply
Return type:	bool

get_arp_table(mac_address, include_gratuitous=True)¶

Generate a hypothetical ARP table based on network traffic.

Parameters:	mac_address (str) – device MAC address include_gratuitous (bool) – include gratuitous ARP entries
Returns:	generated ARP table
Return type:	dict
Raises:	ValueError – specified MAC address not observed in network traffic

get_gratuitous_arp_ips(mac_address)¶

Get set of IP address(es) announced via gratuitous ARP for the specified device.

Parameters:	mac_address (str) – device MAC address
Returns:	announced IP addresses
Return type:	set of str
Raises:	ValueError – no gratuitous ARP packets sent from specified MAC address

get_probed_ips(mac_address)¶

Get set of IP address(es) probed by the specified device.

Parameters:	mac_address (str) – device MAC address
Returns:	probed IP addresses
Return type:	set of str
Raises:	ValueError – no probe ARP packets sent from specified MAC address

BOOTP ¶

class pcap_analysis._analyzers.bootp.Bootp¶

Bootstrap protocol (BOOTP) analyzer.

did_client_make_request(mac_address)¶

Check if a device requested an IP address using BOOTP.

Parameters:	mac_address (str) – client device MAC address
Returns:	client made BOOTP request
Return type:	bool

did_client_receive_ip_address(mac_address)¶

Check if a device received an IP address using BOOTP.

Parameters:	mac_address (str) – client device MAC address
Returns:	client received IP address
Return type:	bool

get_received_ip_address(mac_address)¶

Get IP address assigned to device via BOOTP.

Parameters:	mac_address (str) – client device MAC address
Returns:	assigned IP address
Return type:	str
Raises:	ValueError – no IP address assigned to specified MAC address

DHCP ¶

class pcap_analysis._analyzers.dhcp.Dhcp¶

Dynamic host configuration protocol (DHCP) analyzer.

did_client_make_request(mac_address)¶

Check if a device requested an IP address using DHCP.

Parameters:	mac_address (str) – client device MAC address
Returns:	client made DHCP request
Return type:	bool

did_client_receive_ip_address(mac_address)¶

Check if a device received an IP address using DHCP.

Parameters:	mac_address (str) – client device MAC address
Returns:	client received IP address
Return type:	bool

get_received_ip_address(mac_address)¶

Get IP address assigned to device via DHCP.

Parameters:	mac_address (str) – client device MAC address
Returns:	assigned IP address
Return type:	str
Raises:	ValueError – no IP address assigned to specified MAC address

ICMP ¶

class pcap_analysis._analyzers.icmp.Icmp¶

Internet control message protocol (ICMP) analyzer.

did_device_ping(source_host_ip, target_host_ip)¶

Check if the specified source device pinged the specified target IP address.

Parameters:	source_host_ip (str) – source IP address target_host_ip (str) – target IP address
Returns:	device pined specified target
Return type:	bool

get_mean_rtt(source_host_ip, target_host_ip)¶

Calculate average round-trip time for the specified source and target hosts.

Parameters:	source_host_ip (str) – source IP address target_host_ip (str) – target IP address
Returns:	average round-trip time
Return type:	float

get_ping_count(source_host_ip, target_host_ip)¶

Count ping requests from source host to target host that received a response.

Parameters:	source_host_ip (str) – source IP address target_host_ip (str) – target IP address
Returns:	number of ping requests with a corresponding response
Return type:	int

Installation¶

Requirements¶

Python 2.7 or 3.5+
Wireshark

Installation Steps¶

Install pcap-analysis from the command line using pip:

pip install pcap-analysis

Release Notes¶

[0.1.1] Fix analyzer class internal attribute logic. (2020-06-29)¶

Previously, analyzer classes attached internal-use attributes to the class itself. Now, these attributes are instance attributes as expected.

[0.1.0] Initial beta release. (2020-06-28)¶

Release initial beta version of pcap-analysis package with analyzers for the following protocols:

ARP
BOOTP
DHCP
ICMP (Pings Only)

Known Limitations¶

This package contains the following known limitations:

None

Usage¶

Under construction! Coming soon…