API Documentation

Warning

The CLI is the official interface of this project. The API is documented here for sake of completeness and is not explicity designed to be one.


pcapgraph module

version file.

pcapgraph.check_requirements()[source]

Errors and quits if tshark is not installed.

On Windows, tshark may not be recognized by cmd even if Wireshark is installed. On Windows, this function will add the Wireshark folder to path so tshark can be called.

Changing os.environ will only affect the cmd shell this program is using (tested). Not using setx here as that could be potentially destructive.

Raises FileNotFonudError:
If wireshark/tshark is not found, raise an error as they are required.
pcapgraph.get_wireshark_version()[source]

Get the wireshark version in the form of ‘1.2.3’


pcapgraph.draw_graph

Draw graph will draw a text or image graph.

pcapgraph.draw_graph.draw_graph(pcap_packets, input_files, output_fmts, graph_opts)[source]

Draw a graph using matplotlib and numpy.

Parameters:
  • pcap_packets (dict) – All packets, where key is pcap filename/operation.
  • input_files (list) – List of input files that shouldn’t be deleted.
  • output_fmts (list) – The save file type. Supported formats are dependent on the capabilites of the system: [png, pdf, ps, eps, and svg]. See https://matplotlib.org/api/pyplot_api.html for more information.
  • graph_opts (dict) – Graph options.
pcapgraph.draw_graph.export_graph(pcap_names, save_fmt)[source]

Exports the graph to the screen or to a file.

Parameters:
  • pcap_names (list) – List of pcap_names
  • save_fmt (str) – File extension of output file
pcapgraph.draw_graph.generate_graph(pcap_packets, pcap_vars, empty_files, anonymize_names, show_packets)[source]

Generate the matplotlib graph.

Parameters:
  • pcap_packets (dict) – Dict returned by get_pcap_frame_dict() {<pcap>: {‘FRAME’: ‘TIMESTAMP’, …}, …}
  • pcap_vars (dict) – Contains all data required for the graph. {<pcap>: {‘pcap_start’: <timestamp>, ‘pcap_end’: <timestamp>}, …}
  • empty_files (list) – List of filenames of empty files.
  • anonymize_names (bool) – Whether to change filenames to random values.
  • show_packets (bool) – Whether to show each packet or the entire pcap.
pcapgraph.draw_graph.generate_text(pcap_times)[source]

Make useful text given pcap times.

Parameters:pcap_times (dict) – Packet capture names and start/stop timestamps.
Returns:Full textstring of text to written to file/stdout
Return type:(str)
pcapgraph.draw_graph.get_graph_vars(pcap_packets, new_files)[source]

Get Graph start-stop dict

Parameters:
  • pcap_packets (dict) – Frames and timestamps by pcap
  • new_files (list) – User inputted filenames
pcapgraph.draw_graph.get_x_minmax(start_times, end_times)[source]

Determine the horizontal (x) min and max values.

This function adds 1% to either side for padding.

Parameters:
  • start_times (np.array) – First packet unix timestamps of all pcaps.
  • end_times (np.array) – Last packet unix timestamps of all pcaps.
Returns:

min_x, max_x to be used for graph

Return type:

(tuple)

pcapgraph.draw_graph.output_file(save_format, pcap_packets, new_files, graph_opts)[source]

Save the specified file with the specified format.

Parameters:
  • save_format (str) – Extension of file to be saved.
  • pcap_packets (dict) – All packets, where key is pcap filename/operation.
  • new_files (list) – Files generated by PcapGraph.
  • graph_opts (dict) –

    All user CLI options exclude_empty (bool): Whether to exclude empty pcaps from graph. anonymize_names (bool): Whether to change filenames to random vals. show_packets (bool): Whether to use a horizontal bar to show a pcap

    or vertical lines to show packets.
pcapgraph.draw_graph.set_graph_vars(x_min, x_max, pcap_names, fig, axes)[source]

Set matplotlib’s plt object with appropriate graph parameters.

pcapgraph.draw_graph.set_horiz_barlines(pcap_packets)[source]

Set horizontal bar vertical lines instead of a fully-colored bar.

pcapgraph.draw_graph.set_horiz_bars(barlist)[source]

Set the horizontal bar colors.

Color theme is Metro UI, with an emphasis on darker colors. If there are more horiz bars than in the color array, loop and continue to set colors.

Parameters:barlist (list) – List of the horizontal bars.
pcapgraph.draw_graph.set_xticks(first, last)[source]

Generate the x ticks and return a list of them.

Parameters:
  • first (float) – Earliest timestamp of pcaps.
  • last (float) – Latest timestamp of pcaps.
Returns:

x_ticks (list(float)): List of unix epoch time values as xticks. x_label (string): Text to be used to label X-axis.

Return type:

(tuple)


pcapgraph.generate_example_pcaps

Script to create three packet captures to demonstrate PcapGraph.

pcapgraph.generate_example_pcaps.generate_example_pcaps(interface=None)[source]

This script will create 3 packet captures, each lasting 60 seconds and starting at 0s, 20s, 40s. After 100s, this script will stop. Packet capture 0s should have 66% in common with pcap 20s and 33% in common with pcap 40s. Indeed, this is what we see in the graph.

Parameters:interface (string) – Optional interface to specify for wireshark.

pcapgraph.get_filenames

Parse CLI options and return a list of filenames.

pcapgraph.get_filenames.get_all_file_and_directory_names(file_list)[source]
Parameters:file_list (list) – Every sysarg that doesn’t have a flag in front of it.
Returns:List of all filenames
Return type:(list)
pcapgraph.get_filenames.get_filenames(files)[source]

Return a validated list of filenames.

Parameters:files (list) – List of file params entered by user
Returns:List of files validated to be packet captures.
Return type:(list)
pcapgraph.get_filenames.get_filenames_from_directories(directories)[source]

Get all the packet captures from all provided directories.

This function is not recursive and searches one deep.

Parameters:directories (list) – List of user-inputted directories.
Returns:Filenames of all packet captures in specified directories.
Return type:(list)
pcapgraph.get_filenames.parse_cli_args(args)[source]

Parse args with docopt. Return a list of filenames

Parameters:args (dict) – Dict of args that have been passed in via docopt.
Returns:List of filepaths
Return type:(list)

pcapgraph.manipulate_frames


pcapgraph.pcap_math

Do algebraic operations on sets like union, intersect, difference.

class pcapgraph.pcap_math.PcapMath(filenames, strip_options)[source]

Bases: object

Prepare PcapMath object for one or multiple operations.

Every PcapMath object should start with the data structures filled with the data that each operation needs to function.

Parameters:
  • filenames (list) – List of filenames.
  • strip_options – Strip options (L2 and L3)
bounded_intersect_pcap()[source]

Get the pcap frame list for bounded_intersect_pcap

Create a bounding box around each packet capture where the bounds are the min and max packets in the intersection.

Returns:{<BOUNDED_PCAP_NAME>: {<FRAME>: <TIMESTAMP>, …}, …}
Return type:(dict)
difference_pcap(pivot_index=0)[source]

Given sets A = (1, 2, 3), B = (2, 3, 4), C = (3, 4, 5), A-B-C = (1).

Parameters:[int] (pivot_index) – Specify minuend by index of filename in list
Returns:{<FRAME>: <TIMESTAMP>, …}
Return type:(dict)
generate_intersection()[source]

Return the intersection of 2 or more pcaps.

get_minmax_common_frames()[source]

Get first, last frames of intersection pcap.

Returns:Packet strings of the packets that are at the beginning and end of the intersection pcap based on timestamps.
Return type:min_frame, max_frame (tuple(string))
Raises:assert – If intersection is empty.
intersect_pcap()[source]

Save pcap intersection. First filename is pivot packet capture.

generate_intersection also exists as the frame intersect part is used by other functions.

Returns:Intersection {<FRAME>: <TIMESTAMP>, …}
Return type:(dict)
inverse_bounded_intersect_pcap(new_pcap_frames, bounded_filenames, has_intersection)[source]

Inverse of bounded intersection = (bounded intersect) - (intersect)

Parameters:
  • new_pcap_frames (dict) – All frames and timestamps created by other operations thus far.
  • bounded_filenames (list) – Filenames of bounded intersections
  • has_intersection (bool) – Whether an intersection has been done
Returns:

Filenames of generated pcaps.

Return type:

(dict)

parse_set_args(args)[source]

Call the appropriate method per CLI flags.

difference, union, intersect consist of {<op>: {frame: timestamp, …}} bounded_intersect consists of {pcap: {frame: timestamp, …}, …}

Parameters:args (dict) – Dict of all arguments (including set args).
Returns:Return generated pcap frames dict with timestamps.
symmetric_difference_pcap()[source]

For sets A = (1, 2, 3), B = (2, 3, 4), C = (3, 4, 5), A△B△C = (1, 5)

For all pcaps, the symmetric difference produces a pcap that has the packets that are unique to only that pcap (unlike above where only one set is the result).

Returns:{<SYMDIFF_PCAP_NAME>: {<FRAME>: <TIMESTAMP>, …}, …}
Return type:(dict)
union_pcap()[source]

Given sets A = (1, 2, 3), B = (2, 3, 4), A + B = (1, 2, 3, 4).

About:
This method uses tshark to get identifying information on pcaps and then mergepcap to save the combined pcap.
Returns:{<FRAME>: <TIMESTAMP>, …}
Return type:(dict)

pcapgraph.save_file

Save file.

pcapgraph.save_file.get_canonical_hex(raw_packet, timestamp='')[source]

Convert the raw pcap hex to a form that text2cap can read from stdin.

hexdump and xxd can do this on unix-like platforms, but not on Windows.

tshark -r <file> -T json -x produces the “in” and text2pcap requires the “out” formats as shown below:

Per Text2pcap documentation: “Text2pcap understands a hexdump of the form generated by od -Ax -tx1 -v.”

In format:

247703511344881544abbfdd0800452000542bbc00007901e8fd080808080a301290000
082a563110001f930ab5b00000000a9e80d0000000000101112131415161718191a1b1c
1d1e1f202122232425262728292a2b2c2d2e2f3031323334353637

Out format:

0000  24 77 03 51 13 44 88 15 44 ab bf dd 08 00 45 20
0010  00 54 2b bc 00 00 79 01 e8 fd 08 08 08 08 0a 30
0020  12 90 00 00 82 a5 63 11 00 01 f9 30 ab 5b 00 00
0030  00 00 a9 e8 0d 00 00 00 00 00 10 11 12 13 14 15
0040  16 17 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25
0050  26 27 28 29 2a 2b 2c 2d 2e 2f 30 31 32 33 34 35
0060  36 37

NOTE: Output format doesn’t need an extra n between packets. So in the above example, the next line could be 0000 00 … for the next packet.

Parameters:
  • raw_packet (str) – The ASCII hexdump seen above in ‘In’
  • timestamp (str) – An optional packet timestamp that will precede the 0000 line of the packet hex.
Returns:

Packet in ASCII hexdump format like Out above

Return type:

formatted_string (str)

pcapgraph.save_file.reorder_packets(pcap)[source]

Union causes packets to be ordered incorrectly, so reorder properly.

Reorder packets, save to 2nd file. After this is done, replace initial file with reordered one. Append temporary file with ‘_’.

Parameters:pcap (str) – Filename of packet capture. Should end with ‘_’, which can be stripped off so that we can reorder to a diff file.
pcapgraph.save_file.save_pcap(pcap_dict, name, options)[source]

Save a packet capture given ASCII hexdump using text2pcap

Parameters:
  • pcap_dict (dict) – List of pcaps of frames to timestamps. Format: {<frame>: <timestamp>, …}
  • name (str) – Type of operation and name of savefile
  • options (dict) – Whether to encode with L2/L3 headers.