PyDivert

3.1.0 · active · verified Sun Apr 12

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.

Warnings

breaking 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.
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.
gotcha 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.
Fix: Always run Python scripts or the application that uses PyDivert with administrator privileges (e.g., 'Run as administrator' on Windows).
gotcha 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.
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.
gotcha 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.
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).
gotcha 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.
Fix: Implement robust input validation for all user-provided data, especially filter strings. Minimize the scope of administrator privileges for your application.

Install

pip install pydivert Install latest version

Imports

WinDivert
```
from pydivert import WinDivert
```
Main entry point for capturing and diverting packets.
Packet
```
from pydivert import Packet
```
Represents a network packet for inspection and modification.
Layer
```
from pydivert import Layer
```
Used to specify WinDivert capture layers (e.g., NETWORK, FLOW, SOCKET).
Flag
```
from pydivert import Flag
```
Used to specify WinDivert handle flags (e.g., SNIFF, DROP).

Quickstart

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.

import pydivert
import os

# NOTE: This script requires administrator privileges to run.
# On Windows, you might need to run your terminal/IDE as Administrator.

# Example: Capture and re-inject all outbound TCP packets to port 80 (HTTP).
# Packets captured are removed from the network stack; they must be re-injected to proceed.
with pydivert.WinDivert("tcp.DstPort == 80 and outbound") as w:
    print("Capturing outbound TCP packets to port 80. Press Ctrl+C to stop.")
    try:
        for packet in w:
            print(f"Captured: {packet.src_addr}:{packet.src_port} -> {packet.dst_addr}:{packet.dst_port}")
            w.send(packet) # Re-inject the packet back into the stack
    except KeyboardInterrupt:
        print("\nStopped capturing.")
    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →