Project: pydivert

pydivert ^^^^^^^^

|appveyor| |codecov| |latest_release| |python_versions|

Python bindings for WinDivert_, a Windows driver that allows user-mode applications to capture/modify/drop network packets sent to/from the Windows network stack.

Requirements

• Python 2.7 or Python 3.4+ (32 or 64 bit)
• Windows Vista/7/8/10 or Windows Server 2008 (32 or 64 bit)
• Administrator Privileges

Installation

You can install PyDivert by running

.. code-block:: text

$ pip install pydivert

Starting with PyDivert 1.0.2, WinDivert_ is bundled with PyDivert and does not need to be installed separately.

WinDivert Version Compatibility

================================= =============== PyDivert WinDivert

0.0.7 1.0.x or 1.1.x 1.0.x (API-compatible with 0.0.7) 1.1.8 (bundled) 2.0.x 1.1.8 (bundled) 2.1.x 1.3 (bundled) ================================= ===============

Getting Started

PyDivert consists of two main classes: pydivert.WinDivert and pydivert.Packet. First, you usually want to create a WinDivert object to start capturing network traffic and then call .recv() to receive the first Packet that was captured. By receiving packets, they are taken out of the Windows network stack and will not be sent out unless you take action. You can re-inject packets by calling .send(packet). The following example opens a WinDivert handle, receives a single packet, prints it, re-injects it, and then exits:

.. code-block:: python

import pydivert

# Capture only TCP packets to port 80, i.e. HTTP requests.
w = pydivert.WinDivert("tcp.DstPort == 80 and tcp.PayloadLength > 0")

w.open()  # packets will be captured from now on

packet = w.recv()  # read a single packet
print(packet)
w.send(packet)  # re-inject the packet into the network stack

w.close()  # stop capturing packets

Packets that are not matched by the "tcp.DstPort == 80 and tcp.PayloadLength > 0" filter will not be handled by WinDivert and continue as usual. The syntax for the filter language is described in the WinDivert documentation <https://reqrypt.org/windivert-doc.html#filter_language>_.

Python Idioms

pydivert.WinDivert instances can be used as context managers for capturing traffic and as (infinite) iterators over packets. The following code is equivalent to the example above:

.. code-block:: python

import pydivert

with pydivert.WinDivert("tcp.DstPort == 80 and tcp.PayloadLength > 0") as w:
    for packet in w:
        print(packet)
        w.send(packet)
        break

Packet Modification

pydivert.Packet provides a variety of properties that can be used to access and modify the packet's headers or payload. For example, you can browse the web on port 1234 with PyDivert:

.. code-block:: python

import pydivert

with pydivert.WinDivert("tcp.DstPort == 1234 or tcp.SrcPort == 80") as w:
    for packet in w:
        if packet.dst_port == 1234:
            print(">") # packet to the server
            packet.dst_port = 80
        if packet.src_port == 80:
            print("<") # reply from the server
            packet.src_port = 1234
        w.send(packet)

Try opening http://example.com:1234/ in your browser!

WinDivert supports access and modification of a variety of TCP/UDP/ICMP attributes out of the box.

.. code-block:: python

>>> print(packet)
Packet({'direction': <Direction.OUTBOUND: 0>,
 'dst_addr': '93.184.216.34',
 'dst_port': 443,
 'icmpv4': None,
 'icmpv6': None,
 'interface': (23, 0),
 'ipv4': {'src_addr': '192.168.86.169',
          'dst_addr': '93.184.216.34',
          'packet_len': 81},
 'ipv6': None,
 'is_inbound': False,
 'is_loopback': False,
 'is_outbound': True,
 'payload': '\x17\x03\x03\x00$\x00\x00\x00\x00\x00\x00\x02\x05\x19q\xbd\xcfD\x8a\xe3...',
 'raw': <memory at 0x028924E0>,
 'src_addr': '192.168.86.169',
 'src_port': 52387,
 'tcp': {'src_port': 52387,
         'dst_port': 443,
         'syn': False,
         'ack': True,
         'fin': False,
         'rst': False,
         'psh': True,
         'urg': False,
         'header_len': 20,
         'payload': '\x17\x03\x03\x00$\x00\x00\x00\x00\x00\x00\x02\x05\x19q\xbd\xcfD\x8a\xe3...'},
 'udp': None})

Uninstalling PyDivert

You can uninstall PyDivert by running

.. code-block:: text

$ pip uninstall pydivert

If the WinDivert driver is still running at that time, it will remove itself on the next reboot.

API Reference Documentation

The API Reference Documentation for PyDivert can be found here <https://ffalcinelli.github.io/pydivert/>_.

.. |appveyor| image:: https://img.shields.io/appveyor/ci/ffalcinelli/pydivert/master.svg :target: https://ci.appveyor.com/project/ffalcinelli/pydivert :alt: Appveyor Build Status

.. |codecov| image:: https://img.shields.io/codecov/c/github/ffalcinelli/pydivert/master.svg :target: https://codecov.io/gh/ffalcinelli/pydivert :alt: Coverage Status

.. |latest_release| image:: https://img.shields.io/pypi/v/pydivert.svg :target: https://pypi.python.org/pypi/pydivert :alt: Latest Version

.. |python_versions| image:: https://img.shields.io/pypi/pyversions/pydivert.svg :target: https://pypi.python.org/pypi/pydivert :alt: Supported Python versions

.. _WinDivert: https://reqrypt.org/windivert.html