This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Python binding to windivert driver

Project Description

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

$ 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)

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:

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.

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:

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:

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.

>>> 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

$ 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.

Release History

Release History

This version
History Node

2.0.9

History Node

2.0.7

History Node

2.0.6

History Node

2.0.5

History Node

2.0.4

History Node

2.0.3

History Node

2.0.1

History Node

2.0.0

History Node

1.0.2

History Node

1.0.1

History Node

0.1

History Node

0.0.7

History Node

0.0.6

History Node

0.0.5

History Node

0.0.4

History Node

0.0.3

History Node

0.0.2

History Node

0.0.1

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
pydivert-2.0.9-py2.py3-none-any.whl (86.8 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Feb 17, 2017
pydivert-2.0.9.tar.gz (72.9 kB) Copy SHA256 Checksum SHA256 Source Feb 17, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting