Package: capture-packets
capture-packets: User-friendly packet capturesPlease read before usingAll network traffic occurring on your machine is captured (unless you specify a more specific interface, default is all interfaces). Any TLS handshakes that occur within thecapture_packetswill have their secrets dumped as well so that TLS traffic within the packet capture can be decrypted. Any TLS handshakes not occurring within thecapture_packetscontext manager are unaffected.Do not send this data to anyone you do not trust. If you're using any authentication those secrets will likely be included in the packet capture. You should consider rotating your credentials after you've captured the packets to ensure there is zero chance of services being compromised. Use a secure channel (likemagic-wormhole) to distribute these files.Any maintainers who receives files from this utilityshould delete them as soon as possibleafter completing the requiring task.Installing and instructionsTo use this library you must have thedumpcaputility from tshark installed.Learn how to install dumpcap.Now we install the Python package from PyPI:$python-mpipinstallcapture-packetsAfter that's installed we create a script and place the problematic code
within thecapture_packetscontext manager:fromcapture_packetsimportcapture_packets# Wrap *all* of your networking code# in the capture_packets() context manager:withcapture_packets()aspcap:# You put the code that you want to capture below here:importurllib3http=urllib3.PoolManager()http.request("GET","https://service-that-is-not.working")# By the way, it's okay if an error happens in here. The# context manager still works and outputs the paths to stdout.# After capturing you can explore the captured packets:fromscapy.layers.dnsimportDNSQRpackets=pcap.packets(layers=DNSQR)assertpackets[0][DNSQR].qname==b"service-that-is-not.working."Once you see the last message your packets have been captured and are stored at the displayed path (in the above example, at/tmp/tmpcaxb58kt/captured-packets.tar). You can send the tarball to the maintainer requesting packets.IMPORTANT:Make sure that all of your code is enclosed within thecapture_packets()context manager.
Otherwise a crucial setup step to configure TLS secrets may be missed:importurllib3# === DON'T DO THIS ===# This won't work because TLS will get# configured outside the context manager.http=urllib3.HTTPSConnectionPool("service-that-is-not.working",443)withcapture_packets():http.request("GET","/")# === DO THIS INSTEAD ===withcapture_packets():# TLS is configured within capture_packets() block :tada:http=urllib3.HTTPSConnectionPool("service-that-is-not.working",443)http.request("GET","/")Why is this useful?There are networking issues that are impossible to debug without a packet capture and it's typically a difficult task for users to capture packets and TLS secrets themselves. This library is an attempt to make packet captures as simple as possible for users while still being comprehensive.What libraries are supported?If TLS isn't being used, then in theory any networking library will work.If TLS is being used then the library must support theSSLKEYLOGFILEenvironment variable to have TLS secrets dumped automatically as well. To name a few, urllib3, Requests, and any libraries that use those two libraries for HTTP will work with TLS.LicenseMIT