{"id":4703,"library":"pydivert","title":"PyDivert","description":"PyDivert is a powerful Python binding for the WinDivert driver, enabling user-mode applications to capture, modify, and drop network packets on Windows. It offers features like advanced filtering, on-the-fly packet manipulation, and re-injection into the network stack. Version 3.1.0 is the current release, and the library demonstrates an active release cadence, with major updates supporting modern Python features (like asyncio) and WinDivert 2.2+ capabilities, including bundled driver binaries.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"https://github.com/ffalcinelli/pydivert.git","tags":["network","packet capture","firewall","windows","windivert","tcp/ip","network manipulation"],"install":[{"cmd":"pip install pydivert","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.10+ (64-bit) for full compatibility and features.","package":"Python","optional":false},{"reason":"PyDivert is a Windows-specific library, requiring Windows 11 (64-bit) or compatible Windows Server versions. It will not work on Linux or macOS.","package":"Windows OS","optional":false},{"reason":"Interacting with the WinDivert driver requires the application to run with administrator privileges.","package":"Administrator Privileges","optional":false},{"reason":"The necessary 64-bit WinDivert DLL and driver are bundled with PyDivert, so no manual installation is typically required.","package":"WinDivert driver","optional":false}],"imports":[{"note":"Main entry point for capturing and diverting packets.","symbol":"WinDivert","correct":"from pydivert import WinDivert"},{"note":"Represents a network packet for inspection and modification.","symbol":"Packet","correct":"from pydivert import Packet"},{"note":"Used to specify WinDivert capture layers (e.g., NETWORK, FLOW, SOCKET).","symbol":"Layer","correct":"from pydivert import Layer"},{"note":"Used to specify WinDivert handle flags (e.g., SNIFF, DROP).","symbol":"Flag","correct":"from pydivert import Flag"}],"quickstart":{"code":"import pydivert\nimport os\n\n# NOTE: This script requires administrator privileges to run.\n# On Windows, you might need to run your terminal/IDE as Administrator.\n\n# Example: Capture and re-inject all outbound TCP packets to port 80 (HTTP).\n# Packets captured are removed from the network stack; they must be re-injected to proceed.\nwith pydivert.WinDivert(\"tcp.DstPort == 80 and outbound\") as w:\n    print(\"Capturing outbound TCP packets to port 80. Press Ctrl+C to stop.\")\n    try:\n        for packet in w:\n            print(f\"Captured: {packet.src_addr}:{packet.src_port} -> {packet.dst_addr}:{packet.dst_port}\")\n            w.send(packet) # Re-inject the packet back into the stack\n    except KeyboardInterrupt:\n        print(\"\\nStopped capturing.\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to capture outbound TCP packets destined for port 80 and then re-inject them back into the network stack. It highlights the basic usage of `pydivert.WinDivert` as a context manager and iterating over captured packets. Remember to run this with administrator privileges."},"warnings":[{"fix":"Review the official PyDivert 3.x documentation and update `Packet` constructor calls and `wd_addr` usage to align with the new API. Ensure new metadata fields are handled if custom packet creation is performed.","message":"PyDivert 3.0.0 introduced significant breaking changes, primarily affecting the `Packet` class constructor. It now accepts additional metadata fields (like `layer`, `event`, `flow`, `socket`, `reflect`), and the `interface` parameter became optional with a default of (0,0). Additionally, the `wd_addr` property now returns a full `WINDIVERT_ADDRESS` for all supported layers. Existing code that manually constructs `Packet` objects or relies on the previous `wd_addr` signature will require updates.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always run Python scripts or the application that uses PyDivert with administrator privileges (e.g., 'Run as administrator' on Windows).","message":"PyDivert requires administrator privileges to operate because it interacts directly with the Windows kernel-mode network driver. Running your application without these privileges will result in a runtime error or the application hanging when attempting to open a `WinDivert` handle.","severity":"gotcha","affected_versions":"All"},{"fix":"Always remember to call `w.send(packet)` after processing a packet if you want it to proceed through the network stack. Implement logic to explicitly drop packets if that is the desired behavior.","message":"When `pydivert.WinDivert` captures a packet using `recv()` (or by iterating over the `WinDivert` object), that packet is removed from the Windows network stack. If you intend for the packet to continue to its original destination or be injected elsewhere, you *must* explicitly call `w.send(packet)`. If `send()` is not called, the packet will be silently dropped.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your development and deployment environment is a supported Windows operating system. Consider alternative packet manipulation libraries if cross-platform compatibility is a requirement (e.g., `scapy` on Linux/macOS).","message":"PyDivert is a binding for WinDivert, which is a Windows-specific driver. Therefore, PyDivert itself is exclusively compatible with Microsoft Windows operating systems (64-bit editions, specifically Windows 11+ for full modern feature support). It will not function on Linux, macOS, or other non-Windows platforms.","severity":"gotcha","affected_versions":"All"},{"fix":"Implement robust input validation for all user-provided data, especially filter strings. Minimize the scope of administrator privileges for your application.","message":"Due to its low-level interaction with the network stack, applications using PyDivert should adhere to strict security best practices. This includes employing the principle of least privilege (only running necessary components with admin rights) and rigorously validating all external inputs, especially those used in filter strings or packet modification logic, to prevent potential vulnerabilities or system instability.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}