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.
You can install PyDivert by running
.. code-block:: text
$ pip install pydivertStarting 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) ================================= ===============
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 packetsPackets 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>_.
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)
breakpydivert.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})You can uninstall PyDivert by running
.. code-block:: text
$ pip uninstall pydivertIf the WinDivert driver is still running at that time, it will remove itself on the next reboot.
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