The two typical ways to start analyzing packets are via PyShark’s FileCapture and LiveCapture modules. The first will import packets from a saved capture file, and the latter will sniff from a network interface on the local machine. Running these modules will return a capture object which I will cover in depth in the next post. For now, let’s see what we can do with these two modules.

Both modules offer similar parameters that affect packets returned in the capture object. These definitions are taken directly out of the docstrings for these modules:

  • interface: [LiveCapture only] Name of the interface to sniff on. If not given, takes the first available.
  • bpf_filter: [LiveCapture only] A BPF (tcpdump) filter to apply on the cap before reading.
  • input_file: [FileCapture only] File path of the capture (PCAP, PCAPNG)
  • keep_packets: Whether to keep packets after reading them via next(). Used to conserve memory when reading large caps.
  • display_filter: A display (wireshark) filter to apply on the cap before reading it.
  • only_summaries: Only produce packet summaries, much faster but includes very little information.
  • decryption_key: Optional key used to encrypt and decrypt captured traffic.
  • encryption_type: Standard of encryption used in captured traffic (must be either ‘WEP’, ‘WPA-PWD’, or ‘WPA-PWK’. Defaults to WPA-PWK).

Only_Summaries

Using only_summaries will return packets in the capture object with just the summary info of each packet (similar to the default output of tshark):

This option makes the capture file reading much faster, although each packet will only have the attributes shown below available. This info can be plenty if you’re just wanting to get the IP addresses to build a conversation list in the sniff, or maybe some bandwidth statistics with the time and packet lengths:

Keep_Packets

PyShark only reads packets into memory when it’s about to do something with the packets. As you work through the packets, PyShark appends each packet to a list attribute of the capture object named _packet. When working with a large amount of packets this list can take up a lot of memory so PyShark gives us the option to only keep one packet in memory at a time. If keep_packets is set to False (default is True), PyShark will read in a packet and then flush it from memory when it moves on to read in the next packet. I have found that this speeds up the processing time of packet iteration a bit, and every second helps!

Display_Filter and BPF_Filter

The filters available in these modules can be helpful in keeping your application focused on the traffic you’re wanting to analyze. Similar to Wireshark or tshark sniffing, a BPF filter can be used to specify interesting traffic that makes it into the returned capture object. BPF filters don’t offer as much flexibility as Wireshark’s display filters, but you’d be surprised how creative you can be with the available keywords and offset filters. For help with BPF filters used in capturing packets, check out Wireshark’s guide here. Here’s an example of using a BPF filter when sniffing to target HTTP traffic:

When reading in a saved capture file, you can use the display_filter option to harness Wireshark’s amazing dissectors to limit the packets returned. Here’s the first few packets in my test.pcap file without a filter:

And with a display filter for DNS traffic only:

 Caveats with LiveCapture

I discovered a strange behavior when trying to iterate through a LiveCapture returned capture object. It appears that when you try to iterate through the list, it starts the sniff over again and iterates in real time (as packets are received on the interface). There’s no way (that I’ve found yet) to store the packets, the LiveCapture is meant to process packets in real time only.

There are some powerful options for opening and sniffing packets for processing. Check out the next article here where I go into what can be done with the capture object that is returned from these modules.

Series Navigation<< Intro to PyShark for Programmatic Packet AnalysisPyShark – Using the capture Object >>

This article has 10 comments

  1. Pingback: Graphing packet details with PyShark, pygal, and Flask | thePacketGeek

  2. takao

    I am trying (as you mention above) to find a wat to save packets received through LiveCapture method.

    I am trying the Livecapture with output_file argument. So far no much luck, when
    I use the output_file the Livecapture stores traffic to the file (cap = pyshark.LiveCapture(interface=’eth0′, out_file=”/tmp/test.pcap’) but no packets stored in the cap object. Furthermore the timeout and packet_count arguments I use in sniff have no effect. The packet sniffing continues until I execute cap.close(). Did you have any luck with the out_file option in LiveCapture method?

    1. Mat

      Hi Takao,

      I’ve also run into some similar issues with the arguments not seeming to take effect (the packet_count and filter arguments specifically). If you’re just looking to sniff some packets and save to a file, you might want to look into using scapy instead. I’ve found that pyShark is good for using the Wireshark decoders, but scapy is stronger for sniffing/generating packets. Check out this post: http://wp.me/p3aslj-5i

  3. Irvin

    Hi,

    With Pyshark 0.3.6.1, I was able to get the LiveCapture method to save to a file with something like this:

    cap = pyshark.LiveCapture(interface=’eth0′, output_file=’/tmp/pcaps/newpcap.pcapng’)
    cap.sniff()

    The only tricky part was that in Interactive mode, there’s no way (that i know of), of stopping the capture, other than interrupting it with Ctrl+C (KeyboardInterrupt). Though when running as a script from within a file (or IDE), cap.close() does work well enough to stop the capture and close the file.

    1. Irvin

      Oh, also I forgot to mention that the ‘output_file’ parameter only takes absolute paths and that the file-path has to already exist before the LiveCapture method runs. If the path doesn’t exist in advance, it seems to fail silently with nothing written.

      Though if you just put a file name like newpcap.pcapng it will write this file to your current working directory.

      ‘/tmp/pcaps/newpcap.pcapng’ requires that the path ‘/tmp/pcaps/’ is already in existence. It won’t create it for you.

      1. Mat

        This is identical behavior to python’s built-in open() function. Although, I’m surprised you don’t get an IOError Exception with the message: ‘IOError: [Errno 2] No such file or directory’ when the file doesn’t already exist. Pyshark may be catching the error and handling it silently which I think is broken behavior.

    2. Mat

      There’s two quick ways to end the live capture in a script without using ctrl+c:

      Use the timeout or packet_count arguments in the sniff() method. This example below will stop sniffing after 60 seconds or when the packet_count hits 100:
      cap = pyshark.LiveCapture(interface=’eth0′, output_file=’/tmp/pcaps/newpcap.pcapng’)
      cap.sniff(packet_count=100, timeout=60)

  4. aminema

    Hi Mat,
    I’m trying to capture live packet and display them in real time.
    I use bellow code for capture 100 packets. The problem is i can access packets when capturing complete .

    cap = pyshark.LiveCapture(interface=’eth0′)
    cap.sniff(packet_count=100)
    print (cap)

    How can i display each captured packet during was captured?
    thanks.

Leave a Reply

Your email address will not be published. Required fields are marked *