{"id":15472254,"url":"https://github.com/sethmlarson/capture-packets","last_synced_at":"2025-06-27T16:31:44.433Z","repository":{"id":66168582,"uuid":"445044716","full_name":"sethmlarson/capture-packets","owner":"sethmlarson","description":"User-friendly packet captures","archived":false,"fork":false,"pushed_at":"2022-12-27T04:13:59.000Z","size":23,"stargazers_count":3,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-30T03:19:10.119Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sethmlarson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-06T04:52:36.000Z","updated_at":"2023-10-19T09:31:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"e32877f2-e201-48cb-9232-57fd782479f3","html_url":"https://github.com/sethmlarson/capture-packets","commit_stats":{"total_commits":4,"total_committers":2,"mean_commits":2.0,"dds":0.5,"last_synced_commit":"0e43bb55a14e80609abd367445fc3707a5dc9685"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/sethmlarson/capture-packets","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethmlarson%2Fcapture-packets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethmlarson%2Fcapture-packets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethmlarson%2Fcapture-packets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethmlarson%2Fcapture-packets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sethmlarson","download_url":"https://codeload.github.com/sethmlarson/capture-packets/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethmlarson%2Fcapture-packets/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262293069,"owners_count":23288653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T02:29:55.560Z","updated_at":"2025-06-27T16:31:44.389Z","avatar_url":"https://github.com/sethmlarson.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# capture-packets: User-friendly packet captures\n\n**It's recommended to read the below carefully before use:**\n\nAll network traffic occurring on your machine is captured (unless you specify a more specific interface, default is all interfaces).\nAny TLS handshakes that occur within the `capture_packets()` context will have their secrets dumped so that TLS traffic within the packet capture can be decrypted.\nAny TLS handshakes not occurring within the `capture_packets()` context are unaffected. This library uses [dumpcap](https://www.wireshark.org/docs/man-pages/dumpcap.html) to capture\npackets so dumpcap must be installed locally to use.\n\nThe following are some examples of data captured by dumpcap:\n\n- IP addresses\n- DNS requests and responses\n- TLS handshakes, SNI, decrypted application data\n- HTTP requests, responses, authentication\n\nIf the data goes over the network, this library will likely capture it and make it available to whoever has access to the packet capture files.\n\n**Do not send this data to anyone you do not trust**. **Do not make this data publicly, on GitHub, or send it over email**.\nIf credentials are in use, you should consider rotating your credentials after you've captured the packets to ensure there is zero chance of services being compromised.\nUse a secure channel (like [magic-wormhole](https://github.com/magic-wormhole/magic-wormhole)) to distribute these files.\nAnyone who receives files from this utility **should delete them as soon as possible** after completing the requiring task to avoid accidental disclosure of information.\n\n## User Guide\n\nTo use this library you must have the `dumpcap` utility from tshark installed. [Learn how to install dumpcap](https://tshark.dev/setup/install).\n\nNow we install the Python package from PyPI:\n\n```bash\n$ python -m pip install capture-packets\n```\n\nAfter that's installed we create a script and place the code\nwithin the `capture_packets` context manager:\n\n```python\nimport urllib3\nfrom capture_packets import capture_packets\n\n# Wrap *all* of your networking code\n# in the capture_packets() context manager:\nwith capture_packets() as pcap:\n\n    # You put the code that you want to capture below here:\n    http = urllib3.PoolManager()\n    http.request(\"GET\", \"https://example.com\")\n```\n\nThat's all it takes to capture some packets. But what if our network code is raising an error? We can suppress all exceptions within the same context using [`contextlib.suppress()`](https://docs.python.org/3/library/contextlib.html#contextlib.suppress):\n\n```python\nimport contextlib\nfrom capture_packets import capture_packets\n\n# Multiple context managers in one context!\n# You can make the 'Exception' type more specific if desired.\nwith contextlib.suppress(Exception), capture_packets() as pcap:\n\n    http = urllib3.PoolManager()\n\n    # Now if this request fails then we still exit the context manager.\n    http.request(\"GET\", \"https://service-that-is-not.working\")\n```\n\nIf we're sending them to someone else we likely want to use the `.tarball()` method:\n\n```python\n\u003e\u003e\u003e print(pcap.tarball())\n/tmp/tmpvuujy8s0.tar.gz\n```\n\nThis will return a new tarball path containing all the data about the packet capture.\nYou can send this tarball to anyone who needs access to the packet capture.\n\n### Examining packets locally\n\nOr if you want to dissect the data locally you can use the `.packets()` method to get a list of scapy packets.\nTLS packets are decrypted using the keylog file if necessary. You can read the [scapy documentation](https://scapy.readthedocs.io/en/latest/) for more information.\n\n```python\nfrom scapy.layers.dns import DNSQR\n\npackets = pcap.packets(layers=DNSQR)\nassert packets[0][DNSQR].qname == b\"service-that-is-not.working.\"\n```\n\n### TLS secrets must be configured within the context manager\n\n**IMPORTANT:** Make sure that all of your code is enclosed within the `capture_packets()` context manager.\nOtherwise a crucial setup step to configure TLS secrets may be missed:\n\n```python\nimport urllib3\n\n# This won't work because TLS will get\n# configured outside the context manager.\nhttp = urllib3.HTTPSConnectionPool(\"service-that-is-not.working\", 443)\n\nwith capture_packets():\n    http.request(\"GET\", \"/\")\n\n# Instead place your HTTP connections within the context manager\n# so that TLS secret dumping is configured properly.\nwith capture_packets():\n    # TLS is configured within capture_packets() block :tada:\n    http = urllib3.HTTPSConnectionPool(\"service-that-is-not.working\", 443)\n    http.request(\"GET\", \"/\")\n```\n\n### Reusable script template\n\nBelow is a simple script that maintainers can give to users to gather packet capture information about an issue:\n\n```python\n# Read the User Guide for capture-packets for more info:\n# https://github.com/sethmlarson/capture-packets\n\nimport contextlib\nfrom capture_packets import capture_packets\n\nwith contextlib.suppress(Exception), capture_packets() as pcap:\n\n    # YOUR CODE GOES HERE!\n\nprint(f\"Captured packets are here: {pcap.tarball()}\")\npcap.delete()\n```\n\n## Why is this useful?\n\nThere 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.\n\n## What libraries are supported?\n\nIf TLS isn't being used, then in theory any networking library will work.\n\nIf TLS is being used then the library must support the `SSLKEYLOGFILE` environment 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.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethmlarson%2Fcapture-packets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsethmlarson%2Fcapture-packets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethmlarson%2Fcapture-packets/lists"}