Skip to main content

Network Capture, a Python Module

TCPdump is one of my favorite network packet analysis tools in existence today.  In the past year I have enjoyed TCPdump so much that I have wanted to learn more about the project.  So, I thought a good place to start would be to get involved contributing on GitHub.  My contributions are not much, but they help me learn the ins and outs of the project and how to use some of the more advanced features as I come up in issues or pull requests.  During my time thus far I have noticed that a lot of filtering questions tend to come up on how to use filters or how to interpret the documentation for using filtering with TCPdump.  Either way, there is a demand for TCPdump users to analyze traffic and pick out only the valuable pieces out from a search criteria.   This make sense, but it also made me think... what if there was an easy way to just plug in search criteria based on a network interface or host address and have TCPdump write that information out to a text file.  That way it was easy to quickly dissect and if users wanted to do a deeper dive then there was a pcap file for analysis as well.  This sounded to me like an opportunity, and that's where the idea for Network Capture, a Python Module was born from. 

Note: Network Capture is only available as of right now for Linux.  macOS and Windows are still being developed.  Network Capture does use Python 3 as it does utilize asyncio.  


Using Network Capture

Network Capture is a thin wrapper around TCPdump that allows users to plug in TCPdump arguments along with a comma separated list of keywords to search on.  Network Capture then uses Python to execute a packet capture and perform a text based filter based upon your input.  The packet capture is written to a standard pcap file and the text based filter is written to a txt file when a keyword match is found.  The ASCII output is also written to STDOUT in your terminal, so you can see the info from the traffic being captured and a message will be displayed when a filtering keyword is found in the capture. 

Below is an example where a capture is executed on the interface en0 and a text based search is performed for the keywords: "error,get,ssl,https,http."  I ran the search for a few seconds and was able to capture 2 results referencing a CNAME with SSL in the capture info.

# Capture all ASCII output containing error,get,ssl,https,http from the interface en0
$ python3 -i en0 -keys error,get,ssl,https,http
# In under 2 seconds I captured this traffic to my txt file.  (IP's are hidden for security purposes)
** Keyword found. Writing to log **
09:12:23.718569 IP *.*.*.* > *.*.*.*: 21122 2/0/0 CNAME, A (87)
** Keyword found. Writing to log **
09:12:24.405874 IP *.*.*.* > *.*.*.*: 22411 5/0/0 CNAME, CNAME, A *.*.*.*, A *.*.*.*, A *.*.*.* (180)

In Summary

Network Module is still very much a work in progress but the initial functionality should be available to test out on any Linux system with TCPdump installed.  As mentioned above, macOS and Windows support is still being tested but I would love to hear if anyone tries Network Capture on either of these platforms.  I have 3 main goals for the immediate future of the project:

  1. Add better error handling support.
  2. Add tests to the project.
  3. Port the -keys filtering argument over to the pcap as well.  I have found a way to do this but I am still trying to validate this.


Please check out the project on my GitHub here, and if you have any questions, comments, or concerns, I'd love to hear about them so please leave a comment and I will get back to you as soon as possible.  Thank you!

Member for

3 years 9 months
Matt Eaton

Long time mobile team lead with a love for network engineering, security, IoT, oss, writing, wireless, and mobile.  Avid runner and determined health nut living in the greater Chicagoland area.