API

Wireshark Dissector APIs

APIs for wireshark’s dissectors.

This module provides consistent APIs for using wireshark’s dissector in different scenarios. viz. using with live packet capture and using with a PCAP file. A couple of dissector classes are provided that can be directly used.

WishpyDissectorQueuePython : Can be used with wishpy.libpcap.lib.capturer.Capturer WishpyDissectorFile: Can be used for printing json data from a pcap(ish) file.

Example:

>>> d = WishpyDissectorFile('file.pcap')
>>> for packet in d.run():
    print(packet)

class wishpy.wireshark.lib.dissector.WishpyDissectorBase(*args, **kw)

A Class that wraps the underlying dissector from epan module of libwireshark. Right now this simply prints the dissector tree.

__init__(*args, **kw)

Initialize self. See help(type(self)) for accurate signature.

apply_filter(filter_str, overwrite=False)

Applies a filter given by the filter_str to the dissection.

Args:

filter_str: str - A string that is in a wireshark filter format.

Returns:

result: (int, str) - Result of application 0 success. Negative value suggesting error. Caller should check the error.

Note: Right now it is recommended to run this method before run method is called on the dissector.

cleanup_epan_dissector()

Cleans up internal dissector object.

clear_filter()

Clears the dfilter if any.

init_epan_dissector()

Initializes epan_dissect_t and epan_session objects. These objects are passed to the run method.

classmethod packet_to_json(handle_ptr)

An example method that depicts how to use internal dissector API.

classmethod print_dissected_tree_details(dissector)

classmethod print_dissected_tree_details_api(dissector)

Print a packets Protocol tree using proto_tree_json API

classmethod print_dissected_tree_json_node(node_ptr, level=1)

Returns a string representing dissected tree using the ftypes API.

classmethod print_dissected_tree_json_node_pretty(node_ptr, level=1)

Returns a string that represents a dissected tree.

run(*args, **kw)

A generator function ``yield``ing at-least the dissected packets.

Implementing this as a generator function helps one to run code that looks like

>>> for dissected in dissector.run(count=1):
    # do stuff with the dissected packet

This is particularly convenient while performing live capture on an interface or dissecting a huge file.

class wishpy.wireshark.lib.dissector.WishpyDissectorFile(filename)

Dissector class for PCAP Files.

__init__(filename)

Initialize self. See help(type(self)) for accurate signature.

run(count=0, skip=-1)

Actual function that performs the Dissection.

Right now since we are only supporting dissecting packets from Wiretap supported files, only dissects packets from a pcap(ish) file.

class wishpy.wireshark.lib.dissector.WishpyDissectorQueue(*args, **kw)

Dissector class for packets received from a Queue(ish) object.

dissect_one_packet()

Dissects a single packet

This should typically call fetch and the perform dissection. All the queue based ‘dissectors’ will dissect one packet at a time, so it’s better that this function is in the base class.

fetch()

Implement this function to fetch a single packet from the queue.

Implementation of this function should return the object of the type Hdr and PacketData

class wishpy.wireshark.lib.dissector.WishpyDissectorQueuePython(queue)

Dissector class for Python Standard Library Queue.

__init__(queue)

Initialize self. See help(type(self)) for accurate signature.

fetch()

Blocking Fetch from a Python Queue.

run(count=0)

yield’s the packet, up to maximum of count packets.

if count is <= 0, infinite iterator.

stop()

Stop’s the generator by setting internal state.

exception wishpy.wireshark.lib.dissector.WishpyEpanLibAlreadyInitialized

Error raised trying to initialize already initialized EPAN Library.

exception wishpy.wireshark.lib.dissector.WishpyEpanLibUninitializedError

Error raised during initialization of EPAN library.

exception wishpy.wireshark.lib.dissector.WishpyErrorInitDissector

Error raised during initialization of dissector and or dissector session.

exception wishpy.wireshark.lib.dissector.WishpyErrorWthOpen

Error raised during opening a Pcap file.

wishpy.wireshark.lib.dissector.cleanup_process()

Per process cleanup. de-init of epan/wtap modules.

wishpy.wireshark.lib.dissector.setup_process()

This method should be called once per process (note: Not thread.) This will perform underlying library initialization, so that eventually dissectors can run.

libpcap Capturer APIs

Capture API using the libpcap.

class wishpy.libpcap.lib.capturer.PCAPHeader(ts_sec, ts_usec, len, caplen)

caplen

captured length of the packet.

len

length of the packet.

ts_sec

seconds part of the timestamp.

ts_usec

micro-seconds part of the timestamp.

class wishpy.libpcap.lib.capturer.WishpyCapturer

Base WishpyCapturer class.

Following API are provided open, close, start, stop.

close()

close: Perform any resource cleanup related to the capturer.

open()

open: Opens the capturer.

Use this to perform any Capturer specific initialization. For instance, our API deals with Packet Capture Pipelines that can be connected using Python Queues. So Setting up Queues etc. can be performed here in this method.

start(**kw)

start: Start actual capture of packets.

Implement in such a way tha it should be possible to start/stop capture multiple times for an instance of the capturer.

stop(**kw)

stop: Stop actual capture of packets.

Implement in such a way that it should be possible to start/stop capture multiple times for an instance of the capturer.

exception wishpy.libpcap.lib.capturer.WishpyCapturerCaptureError

class wishpy.libpcap.lib.capturer.WishpyCapturerFileToQueue(filename, queue, **kw)

A Libpcap capturer class that wraps a PCAP file.

This class provides the Capturer API wrapping a PCAP file. Note: For the dissection part it is better to directly use wishpy.wireshark.lib.dissector.WishpyDissectorFile. This class should be used when you want to take packets from a PCAP file and do something other than ‘dissect’ing them.

__init__(filename, queue, **kw)

Constructor

Args:

filename: PCAP file to be opened for reading.

queue: Queue to send packets to.

close()

Closes internal libpcap handle

libpcap’s pcap_close function is called and our activated flag is set to False.

open()

Opens the filename for PCAP Capture.

Returns: None Raises: WishpyCapturerOpenError: If failure to open a file.

class wishpy.libpcap.lib.capturer.WishpyCapturerIfaceToQueue(iface, queue, snaplen=0, promisc=True, timeout=10, **kw)

libpcap based packet capturer for an interface on the system.

This capturer captures packet from the OS interface and posts them, on the Queue. Right now it is not completely abstracted out what gets posted on the queue. Assume they are tuples like - (header, data)

__init__(iface, queue, snaplen=0, promisc=True, timeout=10, **kw)

Constructor

Args:

queue: Python Queue like objects that supported Get/Put APIs.

Get/Put APIs should be thread/process safe. (eg. Queue, multiprocessing Queue etc.)

iface: string - An Interface Name on the local OS.

snaplen: integer (optional), Maximum Capture length of the data.

Default - Don’t set Capture length (ie. if input value is 0.)

promisc: Boolean (optional). Default True To determine whether to start capturing in ‘promiscuous’ mode.

timeout: integer - Timeout in miliseconds to wait before next ‘batch’ of captured packets is returned

(This value maps directly to libpcap: packet buffer timeout.) Default value is 10ms. Use lower values for more ‘responsive’ capture, higher values for larger batches.

**kw: Possible Keyword argument’s that can be supported.

close()

Closes internal libpcap handle

libpcap’s pcap_close function is called and our activated flag is set to False.

open()

Open’s the Capturerer readying it for performing capture.

Calls libpcap’s pcap_create and depending upon requested parameters during the Constructor, those values are set and finally activates the handle.

exception wishpy.libpcap.lib.capturer.WishpyCapturerOpenError

class wishpy.libpcap.lib.capturer.WishpyCapturerQueue(queue, **kw)

Base Class for Sending Packets to Python Queue like objects.

__init__(queue, **kw)

Constructor

Args:

queue: Python Queue like objects that supported Get/Put APIs

The Get/Put APIs should be in a thread/process safe manner. (eg. Queue, multiprocessing Queue etc.)

**kw: Possible keyword arguments.

start(count=-1, serialize=True)

Starts capturing of the packets.

Note: This is a blocking function.

An application should call this function from a separate thread of execution. Calls internal pcap_loop function of libpcap.

Args:

count: (optional) if specified should be a positive integer

specifying maximum number of packets to be captured.

serialize: (optional) bool - Serialize data

If specified serializes the header and data to PCAPHeader and bytes objects (default True)

Returns:

On Success Nothing.

When pcap_loop returns, A special tuple - ('stop', b'') is placed on the queue. For the consumer of the queue, this should signal end of data transfer from the producer.

Raises:

On Error Condition wishpy.wireshark.lib.WishpyCapturerCaptureError.

stop()

Stops the capture.

Simply calls internal libpcap’s pcap_breakloop