PyDivert API Reference

class pydivert.WinDivert(filter='true', layer=<Layer.NETWORK: 0>, priority=0, flags=0)

A WinDivert handle that can be used to capture packets. The main methods are .open(), .recv(), .send() and .close().

Use it like so:

with pydivert.WinDivert() as w:
    for packet in w:
        print(packet)
        w.send(packet)
static register()

An utility method to register the service the first time. It is usually not required to call this function, as WinDivert will register itself when opening a handle.

static is_registered()

Check if the WinDivert service is currently installed on the system.

static unregister()

Unregisters the WinDivert service. This function only requests a service stop, which may not be processed immediately if there are still open handles.

open()

Opens a WinDivert handle for the given filter. Unless otherwise specified by flags, any packet that matches the filter will be diverted to the handle. Diverted packets can be read by the application with receive().

The remapped function is WinDivertOpen:

HANDLE WinDivertOpen(
    __in const char *filter,
    __in WINDIVERT_LAYER layer,
    __in INT16 priority,
    __in UINT64 flags
);

For more info on the C call visit: http://reqrypt.org/windivert-doc.html#divert_open

is_open

Indicates if there is currently an open handle.

close()

Closes the handle opened by open().

The remapped function is WinDivertClose:

BOOL WinDivertClose(
    __in HANDLE handle
);

For more info on the C call visit: http://reqrypt.org/windivert-doc.html#divert_close

recv(bufsize=1500)

Receives a diverted packet that matched the filter. The return value is a pydivert.Packet.

The remapped function is WinDivertRecv:

BOOL WinDivertRecv(
    __in HANDLE handle,
    __out PVOID pPacket,
    __in UINT packetLen,
    __out_opt PWINDIVERT_ADDRESS pAddr,
    __out_opt UINT *recvLen
);

For more info on the C call visit: http://reqrypt.org/windivert-doc.html#divert_recv

send(packet, recalculate_checksum=True)

Injects a packet into the network stack. Recalculates the checksum before sending unless recalculate_checksum=False is passed. The return value is the number of bytes actually sent.

The injected packet may be one received from recv(), or a modified version, or a completely new packet. Injected packets can be captured and diverted again by other WinDivert handles with lower priorities.

The remapped function is WinDivertSend:

BOOL WinDivertSend(
    __in HANDLE handle,
    __in PVOID pPacket,
    __in UINT packetLen,
    __in PWINDIVERT_ADDRESS pAddr,
    __out_opt UINT *sendLen
);

For more info on the C call visit: http://reqrypt.org/windivert-doc.html#divert_send

get_param(name)

Get a WinDivert parameter. See pydivert.Param for the list of parameters.

The remapped function is WinDivertGetParam:

BOOL WinDivertGetParam(
    __in HANDLE handle,
    __in WINDIVERT_PARAM param,
    __out UINT64 *pValue
);

For more info on the C call visit: http://reqrypt.org/windivert-doc.html#divert_get_param

set_param(name, value)

Set a WinDivert parameter. See pydivert.Param for the list of parameters.

The remapped function is DivertSetParam:

BOOL WinDivertSetParam(
    __in HANDLE handle,
    __in WINDIVERT_PARAM param,
    __in UINT64 value
);

For more info on the C call visit: http://reqrypt.org/windivert-doc.html#divert_set_param

class pydivert.Packet(raw, interface, direction)

A single packet, possibly including an IP header, a TCP/UDP header and a payload. Creation of packets is cheap, parsing is done on first attribute access.

is_outbound

Indicates if the packet is outbound. Convenience method for .direction.

is_inbound

Indicates if the packet is inbound. Convenience method for .direction.

is_loopback
  • True, if the packet is on the loopback interface.
  • False, otherwise.
address_family
The packet address family:
  • socket.AF_INET, if IPv4
  • socket.AF_INET6, if IPv6
  • None, otherwise.
protocol
  • A (ipproto, proto_start) tuple.
    ipproto is the IP protocol in use, e.g. Protocol.TCP or Protocol.UDP.
    proto_start denotes the beginning of the protocol data.
    If the packet does not match our expectations, both ipproto and proto_start are None.
ipv4
  • An IPv4Header instance, if the packet is valid IPv4.
  • None, otherwise.
ipv6
  • An IPv6Header instance, if the packet is valid IPv6.
  • None, otherwise.
ip
  • An IPHeader instance, if the packet is valid IPv4 or IPv6.
  • None, otherwise.
icmpv4
  • An ICMPv4Header instance, if the packet is valid ICMPv4.
  • None, otherwise.
icmpv6
  • An ICMPv6Header instance, if the packet is valid ICMPv6.
  • None, otherwise.
icmp
  • An ICMPHeader instance, if the packet is valid ICMPv4 or ICMPv6.
  • None, otherwise.
tcp
  • An TCPHeader instance, if the packet is valid TCP.
  • None, otherwise.
udp
  • An TCPHeader instance, if the packet is valid UDP.
  • None, otherwise.
src_addr
  • The source address, if the packet is valid IPv4 or IPv6.
  • None, otherwise.
dst_addr
  • The destination address, if the packet is valid IPv4 or IPv6.
  • None, otherwise.
src_port
  • The source port, if the packet is valid TCP or UDP.
  • None, otherwise.
dst_port
  • The destination port, if the packet is valid TCP or UDP.
  • None, otherwise.
payload
  • The payload, if the packet is valid TCP, UDP, ICMP or ICMPv6.
  • None, otherwise.
recalculate_checksums(flags=0)

(Re)calculates the checksum for any IPv4/ICMP/ICMPv6/TCP/UDP checksum present in the given packet. Individual checksum calculations may be disabled via the appropriate flag. Typically this function should be invoked on a modified packet before it is injected with WinDivert.send(). Returns the number of checksums calculated.

See: https://reqrypt.org/windivert-doc.html#divert_helper_calc_checksums

class pydivert.packet.TCPHeader(packet, start=0)
ns

Indicates if the NS flag is set.

cwr

Indicates if the CWR flag is set.

ece

Indicates if the ECE flag is set.

urg

Indicates if the SYN flag is set.

ack

Indicates if the ACK flag is set.

psh

Indicates if the PSH flag is set.

rst

Indicates if the RST flag is set.

syn

Indicates if the SYN flag is set.

fin

Indicates if the FIN flag is set.

header_len

The TCP header length.

seq_num

The sequence number field.

ack_num

The acknowledgement number field.

window_size

The size of the receive window in bytes.

cksum

The TCP header checksum field.

urg_ptr

The Urgent Pointer field.

data_offset

The size of TCP header in 32bit words.

dst_port

The destination port.

payload

The packet payload data.

raw

The raw header, possibly including payload.

reserved

The reserved field.

src_port

The source port.

control_bits

The Control Bits field.

class pydivert.packet.UDPHeader(packet, start=0)
payload

The packet payload data.

dst_port

The destination port.

raw

The raw header, possibly including payload.

src_port

The source port.

cksum

The UDP header checksum field.

class pydivert.packet.IPv4Header(packet, start=0)
header_len

The IP header length in bytes.

hdr_len

The header length in words of 32bit.

packet_len

The total packet length, including all headers, as reported by the IP header.

tos

The Type Of Service field (six-bit DiffServ field and a two-bit ECN field).

ident

The Identification field.

reserved

Indicates if the RESERVED flag is set.

evil

Just an april’s fool joke for the RESERVED flag.

df

Indicates if the DF flag is set.

mf

Indicates if the MF flag is set.

ttl

The Time To Live field.

protocol

The Protocol field.

cksum

The IP header Checksum field.

flags

The flags field: RESERVED (the evil bit), DF (don’t fragment), MF (more fragments).

frag_offset

The Fragment Offset field in blocks of 8 bytes.

dscp

The Differentiated Services Code Point field (originally defined as Type of Service) also known as DiffServ.

diff_serv

The Differentiated Services Code Point field (originally defined as Type of Service) also known as DiffServ.

ecn

The Explicit Congestion Notification field.

dst_addr

The packet destination address.

raw

The raw header, possibly including payload.

src_addr

The packet source address.

class pydivert.packet.IPv6Header(packet, start=0)
dst_addr

The packet destination address.

payload_len

The Payload Length field.

raw

The raw header, possibly including payload.

src_addr

The packet source address.

next_hdr

The Next Header field. Replaces the Protocol field in IPv4.

hop_limit

The Hop Limit field. Replaces the TTL field in IPv4.

packet_len

The total packet length, including all headers, as reported by the IP header.

traffic_class

The Traffic Class field (six-bit DiffServ field and a two-bit ECN field).

flow_label

The Flow Label field.

diff_serv

The DiffServ field.

ecn

The Explicit Congestion Notification field.

class pydivert.packet.ICMPv4Header(packet, start=0)
cksum

The ICMP header checksum field.

code

The ICMP message code.

payload

The packet payload data.

raw

The raw header, possibly including payload.

type

The ICMP message type.

class pydivert.packet.ICMPv6Header(packet, start=0)
cksum

The ICMP header checksum field.

code

The ICMP message code.

payload

The packet payload data.

raw

The raw header, possibly including payload.

type

The ICMP message type.

class pydivert.Layer

See https://reqrypt.org/windivert-doc.html#divert_open

NETWORK = 0
NETWORK_FORWARD = 1
class pydivert.Flag

See https://reqrypt.org/windivert-doc.html#divert_open

DEFAULT = 0
SNIFF = 1
DROP = 2
NO_CHECKSUM = 1024
class pydivert.Param

See https://reqrypt.org/windivert-doc.html#divert_set_param

QUEUE_LEN = 0
QUEUE_TIME = 1
class pydivert.CalcChecksumsOption

See https://reqrypt.org/windivert-doc.html#divert_helper_calc_checksums

NO_IP_CHECKSUM = 1
NO_ICMP_CHECKSUM = 2
NO_ICMPV6_CHECKSUM = 4
NO_TCP_CHECKSUM = 8
NO_UDP_CHECKSUM = 16
class pydivert.Direction

See https://reqrypt.org/windivert-doc.html#divert_address

OUTBOUND = 0
INBOUND = 1
class pydivert.Protocol

Transport protocol values define the layout of the header that will immediately follow the IPv4 or IPv6 header. See http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml

HOPOPT = 0
ICMP = 1
TCP = 6
UDP = 17
ROUTING = 43
FRAGMENT = 44
AH = 51
ICMPV6 = 58
NONE = 59
DSTOPTS = 60