PyDivert

https://ffalcinelli.github.io/pydivert/
Admin
PyDivert is a powerful Python binding for WinDivert that allows users to capture, modify, drop, and...
Tokens:28,379
Snippets:185
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install PyDivert using uv

Source: https://ffalcinelli.github.io/pydivert

Install the PyDivert library using uv.

```bash
uv add pydivert
```

--------------------------------

### Get IP Protocol and Protocol Start

Source: https://ffalcinelli.github.io/pydivert

Returns a tuple containing the IP protocol (e.g., TCP, UDP) and the starting byte offset of the protocol data. Handles both IPv4 and IPv6, including extension headers. Returns (None, None) if the packet format is unexpected or out of bounds.

```python
proto: int | None
        start: int | None

        if self.address_family == socket.AF_INET:
            proto, start = self._parse_ipv4_protocol()
        elif self.address_family == socket.AF_INET6:
            proto, start = self._parse_ipv6_protocol()
        else:
            start = None
            proto = None

        out_of_bounds = (
            (proto == Protocol.TCP and start is not None and start + 20 > len(self.raw))
            or (proto == Protocol.UDP and start is not None and start + 8 > len(self.raw))
            or (proto in {Protocol.ICMP, Protocol.ICMPV6} and start is not None and start + 4 > len(self.raw))
        )
        if out_of_bounds:
            # special-case tcp/udp so that we can rely on .protocol for the port properties.
            start = None
```

--------------------------------

### Install PyDivert using pip

Source: https://ffalcinelli.github.io/pydivert

Install the PyDivert library using pip.

```bash
pip install pydivert
```

--------------------------------

### Parse IPv4 Protocol and Start

Source: https://ffalcinelli.github.io/pydivert

Parses the protocol and starting byte offset for an IPv4 packet.

```python
proto = self.raw[9]
        start = (self.raw[0] & 0b1111) * 4
        return proto, start
```

--------------------------------

### Parse IPv6 Protocol and Start with Extension Headers

Source: https://ffalcinelli.github.io/pydivert

Parses the protocol and starting byte offset for an IPv6 packet, skipping over extension headers like Fragment, AH, Hop-by-Hop, Destination Options, and Routing headers.

```python
proto = self.raw[6]

        # skip over well-known ipv6 headers
        start = 40
        while proto in IPV6_EXT_HEADERS:
            if start >= len(self.raw):
                # less than two bytes left
                return None, None
            if proto == Protocol.FRAGMENT:
                hdrlen = 8
            elif proto == Protocol.AH:
                hdrlen = (self.raw[start + 1] + 2) * 4  # type: ignore[operator]
            else:
                # Protocol.HOPOPT, Protocol.DSTOPTS, Protocol.ROUTING
                hdrlen = (self.raw[start + 1] + 1) * 8  # type: ignore[operator]
            proto = self.raw[start]
            start += hdrlen  # type: ignore[operator]
        return proto, start
```

--------------------------------

### Check WinDivert Registration Status

Source: https://ffalcinelli.github.io/pydivert

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

```python
124    @staticmethod
125    def is_registered() -> bool:
126        """
127        Check if the WinDivert service is currently installed on the system.
128        """
129        return service.is_registered()
```

--------------------------------

### Packet Address and Port Properties

Source: https://ffalcinelli.github.io/pydivert

Properties for getting and setting source/destination addresses and ports.

```python
@property
def src_addr(self) -> str | None:
    """
    - The source address, if the packet is valid IPv4 or IPv6.
    - None, otherwise.
    """
    if self.ip:
        return self.ip.src_addr
    return None

@src_addr.setter
def src_addr(self, val: str) -> None:
    if self.ip:
        self.ip.src_addr = val

@property
def dst_addr(self) -> str | None:
    """
    - The destination address, if the packet is valid IPv4 or IPv6.
    - None, otherwise.
    """
    if self.ip:
        return self.ip.dst_addr
    return None

@dst_addr.setter
def dst_addr(self, val: str) -> None:
    if self.ip:
        self.ip.dst_addr = val

@property
def src_port(self) -> int | None:
    """
    - The source port, if the packet is valid TCP or UDP.
    - None, otherwise.
    """
    if self._port:
        return self._port.src_port
    return None

@src_port.setter
def src_port(self, val: int) -> None:
    if self._port:
        self._port.src_port = val

@property
def dst_port(self) -> int | None:
    """
    - The destination port, if the packet is valid TCP or UDP.
    - None, otherwise.
    """
    if self._port:
        return self._port.dst_port
    return None

@dst_port.setter
def dst_port(self, val: int) -> None:
    if self._port:
        self._port.dst_port = val
```

--------------------------------

### GET /get_param

Source: https://ffalcinelli.github.io/pydivert

Retrieves a specific WinDivert parameter value.

```APIDOC
## GET /get_param

### Description
Get a WinDivert parameter value based on the provided parameter name.

### Parameters
#### Query Parameters
- **name** (Param) - Required - The parameter name to retrieve.

### Response
#### Success Response (200)
- **value** (int) - The parameter value.
```

--------------------------------

### Check WinDivert Service Registration

Source: https://ffalcinelli.github.io/pydivert

Checks if the WinDivert service is currently installed and registered on the system. Returns a boolean value indicating the service status.

```python
WinDivert.is_registered()
```

--------------------------------

### WinDivertGetParam - Get Parameter

Source: https://ffalcinelli.github.io/pydivert

Retrieves a WinDivert parameter. Consult pydivert.Param for a list of available parameters.

```APIDOC
## GET /get_param

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

### Method
GET

### Endpoint
/get_param

### Parameters
#### Query Parameters
- **name** (Param) - Required - The parameter to retrieve. See pydivert.Param for options.

### Response
#### Success Response (200)
- **value** (int) - The parameter value.

#### Response Example
```json
{
  "value": 1
}
```
```

--------------------------------

### Get source IP address

Source: https://ffalcinelli.github.io/pydivert

Returns the source IP address if the packet is valid IPv4 or IPv6. Otherwise, returns None.

```python
if self.ip:
            return self.ip.src_addr
        return None
```

--------------------------------

### Get destination IP address

Source: https://ffalcinelli.github.io/pydivert

Returns the destination IP address if the packet is valid IPv4 or IPv6. Otherwise, returns None.

```python
if self.ip:
            return self.ip.dst_addr
        return None
```

--------------------------------

### Get UDPHeader from packet

Source: https://ffalcinelli.github.io/pydivert

Returns a UDPHeader instance if the packet is valid UDP. Otherwise, returns None.

```python
if ipproto == Protocol.UDP and proto_start is not None:
            return UDPHeader(self, proto_start)
        return None
```

--------------------------------

### Get source port

Source: https://ffalcinelli.github.io/pydivert

Returns the source port if the packet is valid TCP or UDP. Otherwise, returns None.

```python
if self._port:
            return self._port.src_port
        return None
```

--------------------------------

### Structural Pattern Matching for Packet Analysis

Source: https://ffalcinelli.github.io/pydivert

Filter and analyze network packets using Python's structural pattern matching (PEP 634). This example distinguishes between HTTP and HTTPS traffic.

```python
import pydivert
from pydivert.packet import Packet
from pydivert.packet.tcp import TCPHeader

with pydivert.WinDivert("tcp") as w:
    for packet in w:
        match packet:
            case Packet(tcp=TCPHeader(dst_port=80)):
                print("HTTP Traffic")
            case Packet(tcp=TCPHeader(dst_port=443)):
                print("HTTPS Traffic")
        w.send(packet)

```

--------------------------------

### Get destination port

Source: https://ffalcinelli.github.io/pydivert

Returns the destination port if the packet is valid TCP or UDP. Otherwise, returns None.

```python
if self._port:
            return self._port.dst_port
        return None
```

--------------------------------

### Get WinDivert Parameter

Source: https://ffalcinelli.github.io/pydivert

Retrieves a WinDivert parameter value using its name. Refer to pydivert.Param for a list of available parameters.

```python
def get_param(self, name: Param) -> int:
        """
        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: https://reqrypt.org/windivert-doc.html#divert_get_param

        :return: The parameter value.
        """
        value = c_uint64(0)
        windivert_dll.WinDivertGetParam(self._handle, name, byref(value))  # type: ignore[attr-defined]
        return value.value

```

--------------------------------

### Get ICMPHeader from packet

Source: https://ffalcinelli.github.io/pydivert

Returns an ICMPHeader instance if the packet is valid ICMPv4 or ICMPv6. Otherwise, returns None.

```python
return self.icmpv4 or self.icmpv6
```

--------------------------------

### open

Source: https://ffalcinelli.github.io/pydivert

Opens a WinDivert handle for the specified filter.

```APIDOC
## open

### Description
Opens a WinDivert handle for the given filter. Any packet that matches the filter will be diverted to the handle.
```

--------------------------------

### Initialize WinDivert Handle

Source: https://ffalcinelli.github.io/pydivert

Creates a WinDivert handle with specified filter, layer, priority, and flags. The filter string defines which packets are captured or modified.

```python
with pydivert.WinDivert() as w:
    for packet in w:
        print(packet)
        w.send(packet)

```

```python
def __init__(
        self,
        filter: str = "true",
        layer: Layer = Layer.NETWORK,
        priority: int = 0,
        flags: Flag = Flag.DEFAULT
    ) -> None:
        """
        Creates a WinDivert handle.

        :param filter: The packet filter string (e.g. "tcp.DstPort == 80").
        :param layer: The WinDivert layer (e.g. Layer.NETWORK, Layer.FLOW).
        :param priority: The priority of the handle (higher priority handles see packets first).
        :param flags: WinDivert flags (e.g. Flag.SNIFF, Flag.DROP).
        """
        self._handle = None
        self._event = None
        self._filter = filter.encode()
        self._layer = layer
        self._priority = priority

```

--------------------------------

### Define WinDivert Parameters

Source: https://ffalcinelli.github.io/pydivert

Defines parameters for setting WinDivert queue configurations.

```python
87class Param(IntEnum):
88    """
89    See https://reqrypt.org/windivert-doc.html#divert_set_param
90    """
91
92    QUEUE_LEN = 0  # Packet queue length 1 < default 512 (actually 1024) < 8192
93    QUEUE_TIME = 1  # Packet queue time 128 < default 512 < 2048
94    QUEUE_SIZE = 2  # Packet queue size (bytes)  4096 (4KB) < default 4194304 (4MB) < 33554432 (32MB)
```

--------------------------------

### Get WinDivert Address

Source: https://ffalcinelli.github.io/pydivert

Retrieves the address and metadata associated with a packet as a `WINDIVERT_ADDRESS` structure.

```APIDOC
## GET /packet/wd_addr

### Description
Gets the address and metadata as a `WINDIVERT_ADDRESS` structure for the packet.

### Method
GET

### Endpoint
`/packet/wd_addr`

### Response
#### Success Response (200)
- **wd_addr** (WinDivertAddress) - The `WINDIVERT_ADDRESS` structure containing packet metadata.

#### Response Example
```json
{
  "wd_addr": {
    "Timestamp": 1678886400,
    "Layer": 1,
    "Event": 0,
    "Outbound": 1,
    "Loopback": 0,
    "Impostor": 0,
    "Sniffed": 1,
    "IPChecksum": 1,
    "TCPChecksum": 1,
    "UDPChecksum": 0,
    "Network": {
      "IfIdx": 10,
      "SubIfIdx": 0
    },
    "Flow": null,
    "Socket": null,
    "Reflect": null
  }
}
```
```

--------------------------------

### Initialize WinDivert Handle

Source: https://ffalcinelli.github.io/pydivert

Creates a WinDivert handle with specified filter, layer, priority, and flags. The filter string defines which packets to capture. Use Layer.NETWORK for network traffic and Layer.FLOW for flow control. Flags like Flag.SNIFF and Flag.DROP modify behavior.

```python
with pydivert.WinDivert() as w:
    for packet in w:
        print(packet)
        w.send(packet)
```

--------------------------------

### Run tests in Vagrant

Source: https://ffalcinelli.github.io/pydivert

Executes the test suite within a Windows 11 Vagrant environment using the specified project environment path.

```bash
vagrant up
vagrant powershell -c '$env:UV_PROJECT_ENVIRONMENT="C:/pydivert_venv"; cd C:/pydivert; uv run pytest'
```

--------------------------------

### Get TCPHeader from packet

Source: https://ffalcinelli.github.io/pydivert

Returns a TCPHeader instance if the packet is valid TCP. Otherwise, returns None.

```python
if ipproto == Protocol.TCP and proto_start is not None:
            return TCPHeader(self, proto_start)
        return None
```

--------------------------------

### Packet Class Initialization

Source: https://ffalcinelli.github.io/pydivert

Initializes a new Packet instance with raw bytes and optional metadata.

```python
def __init__(
    self,
    raw: bytes | bytearray | memoryview,
    interface: tuple[int, int] | None = None,
    direction: Direction = Direction.OUTBOUND,
    timestamp: int = 0,
    loopback: bool = False,
    impostor: bool = False,
    sniffed: bool = False,
    ip_checksum: bool = False,
    tcp_checksum: bool = False,
    udp_checksum: bool = False,
    layer: Layer = Layer.NETWORK,
    event: int = 0,
    flow: Any | None = None,
    socket: Any | None = None,
    reflect: Any | None = None,
) -> None:
    if isinstance(raw, (bytes, bytearray)):
        raw = memoryview(bytearray(raw))
    self.raw: memoryview = raw
    """The raw packet bytes as a `memoryview`."""
    self.interface: tuple[int, int] = interface or (0, 0)
    """The interface index and sub-interface index where the packet was captured."""
    self.direction: Direction = direction
    """The packet direction (inbound or outbound)."""
    self.timestamp: int = timestamp
    """The capture timestamp (QueryPerformanceCounter value)."""
    self._loopback: bool = loopback
    self._impostor: bool = impostor
    self._sniffed: bool = sniffed
    self.ip_checksum: bool = ip_checksum
    """Indicates if the IP checksum was verified by hardware offloading."""
    self.tcp_checksum: bool = tcp_checksum
    """Indicates if the TCP checksum was verified by hardware offloading."""
    self.udp_checksum: bool = udp_checksum
    """Indicates if the UDP checksum was verified by hardware offloading."""
    self.layer: Layer = layer
    """The WinDivert layer that captured this packet."""
    self.event: int = event
    """The WinDivert event type."""
    self.flow: Any | None = flow
    """The flow metadata (for Layer.FLOW)."""
    self.socket: Any | None = socket
    """The socket metadata (for Layer.SOCKET)."""
    self.reflect: Any | None = reflect
    """The reflect metadata (for Layer.REFLECT)."""
    self._cached_buff_len: int | None = None
    self._cached_buff_id: int | None = None
    self._cached_buff: Any | None = None
```

--------------------------------

### Get ICMPv6Header from packet

Source: https://ffalcinelli.github.io/pydivert

Returns an ICMPv6Header instance if the packet is valid ICMPv6. Otherwise, returns None.

```python
if ipproto == Protocol.ICMPV6 and proto_start is not None:
            return ICMPv6Header(self, proto_start)
        return None
```

--------------------------------

### Asynchronously receive packets with recv_async

Source: https://ffalcinelli.github.io/pydivert

Uses Windows Overlapped I/O to receive packets without blocking the main event loop. Requires an open WinDivert handle and event.

```python
251    async def recv_async(self, bufsize: int = DEFAULT_PACKET_BUFFER_SIZE) -> Packet:
252        """
253        Asynchronously receives a diverted packet using Windows Overlapped I/O.
254        """
255        if self._handle is None or self._event is None:
256            raise RuntimeError("WinDivert handle is not open")
257
258        if self._recv_buf is None or len(self._recv_buf) != bufsize:
259            self._recv_buf = bytearray(bufsize)
260            self._recv_buf_c = (c_char * bufsize).from_buffer(self._recv_buf)
261
262        packet = self._recv_buf
263        packet_ = self._recv_buf_c
264        address = WinDivertAddress()
265        recv_len = c_uint(0)
266        overlapped = Overlapped(hEvent=self._event)
267
268        # Keep references to objects used in overlapped I/O
269        # These are attached to the overlapped object to prevent GC
270        overlapped._packet = packet
271        overlapped._address = address
272        overlapped._recv_len = recv_len
273        self._pending_ops.append(overlapped)
274
275        try:
276            # Call the async version from DLL
277            res = windivert_dll.WinDivertRecvEx(
278                self._handle, packet_, bufsize, byref(recv_len), 0, byref(address), None, byref(overlapped)
279            )  # type: ignore[attr-defined]
280
281            if not res:
282                error = windivert_dll.GetLastError()
283                if error == windivert_dll.ERROR_IO_PENDING:
284                    # Wait for the event in a thread pool without blocking the main event loop
285                    loop = asyncio.get_running_loop()
286                    await loop.run_in_executor(None, windivert_dll.WaitForSingleObject, self._event, INFINITE)
287                else:
288                    raise windivert_dll.WinError(error)
289            # Operation completed successfully (either synchronously or after waiting)
290            self._pending_ops.remove(overlapped)
291            return self._parse_packet(packet[: recv_len.value], recv_len.value, address)
292        except asyncio.CancelledError:
293            # If cancelled, the overlapped object remains in _pending_ops to prevent GC
294            # until the handle is closed, which will cancel the pending operation.
295            raise
296        except Exception:
297            if overlapped in self._pending_ops:
298                self._pending_ops.remove(overlapped)
299            raise
```

--------------------------------

### Method open()

Source: https://ffalcinelli.github.io/pydivert

Opens a WinDivert handle for the specified filter, allowing packets matching the filter to be diverted.

```APIDOC
## open()

### Description
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.

### Parameters
- The method uses instance attributes: filter, layer, priority, and flags.
```

--------------------------------

### Get ICMPv4Header from packet

Source: https://ffalcinelli.github.io/pydivert

Returns an ICMPv4Header instance if the packet is valid ICMPv4. Otherwise, returns None.

```python
if ipproto == Protocol.ICMP and proto_start is not None:
            return ICMPv4Header(self, proto_start)
        return None
```

--------------------------------

### Define Checksum Options

Source: https://ffalcinelli.github.io/pydivert

Defines options for calculating checksums in WinDivert.

```python
108class CalcChecksumsOption(IntFlag):
109    """
110    See https://reqrypt.org/windivert-doc.html#divert_helper_calc_checksums
111    """
112
113    NO_IP_CHECKSUM = 1
114    NO_ICMP_CHECKSUM = 2
115    NO_ICMPV6_CHECKSUM = 4
116    NO_TCP_CHECKSUM = 8
117    NO_UDP_CHECKSUM = 16
118    NO_REPLACE = 2048
```

--------------------------------

### Simple Firewall: Dropping Packets

Source: https://ffalcinelli.github.io/pydivert

Implement a basic firewall by filtering packets from a specific IP address and not re-injecting them, effectively dropping the traffic.

```python
import pydivert

# Block all traffic from a specific IP address
with pydivert.WinDivert("ip.SrcAddr == 1.2.3.4") as w:
    for packet in w:
        print(f"Blocking packet from {packet.src_addr}")
        # Packet is dropped here

```

--------------------------------

### POST /send_ex

Source: https://ffalcinelli.github.io/pydivert

Injects a packet into the network stack with support for overlapped IO and optional checksum recalculation.

```APIDOC
## POST /send_ex

### Description
Injects a packet into the network stack. Recalculates the checksum before sending unless specified otherwise. Supports overlapped IO.

### Parameters
#### Request Body
- **packet** (Packet) - Required - The packet to send.
- **recalculate_checksum** (bool) - Optional - Whether to recalculate checksums before sending (default: True).
- **flags** (int) - Optional - WinDivert send flags (default: 0).
- **overlapped** (Overlapped) - Optional - An optional Overlapped structure for overlapped IO.

### Response
#### Success Response (200)
- **bytes_sent** (int | None) - The number of bytes sent if synchronous, or None if ERROR_IO_PENDING occurred.
```

--------------------------------

### Get packet payload

Source: https://ffalcinelli.github.io/pydivert

Returns the packet payload if it's valid TCP, UDP, ICMP, or ICMPv6. Otherwise, returns None.

```python
if self._payload:
            return self._payload.payload
        return None
```

--------------------------------

### WinDivert Parameter Setting

Source: https://ffalcinelli.github.io/pydivert

This section details how to set parameters for WinDivert using the pydivert library. It includes the Python method signature, a description of its functionality, and the underlying C function signature.

```APIDOC
## set_param

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

### Method
`set_param(self, name: Param, value: int) -> int`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (Param) - Required - The parameter to set.
- **value** (int) - Required - The value to set for the parameter.

### Request Example
```json
{
  "name": "Param.IP_HDR_INCL",
  "value": 1
}
```

### Response
#### Success Response (200)
- **return_value** (int) - The parameter value.

#### Response Example
```json
{
  "return_value": 1
}
```

### Remarks
This method remaps the C function `WinDivertSetParam`.
For more info on the C call visit: https://reqrypt.org/windivert-doc.html#divert_set_param
```

--------------------------------

### Open WinDivert Handle

Source: https://ffalcinelli.github.io/pydivert

Initializes a handle for packet diversion based on a filter, layer, priority, and flags.

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

```python
if self.is_open:
    raise RuntimeError("WinDivert handle is already open.")
self._handle = windivert_dll.WinDivertOpen(self._filter, self._layer, self._priority, self._flags)  # type: ignore[attr-defined]
self._event = windivert_dll.CreateEventW(None, False, False, None)  # type: ignore[attr-defined]
```

--------------------------------

### send_async

Source: https://ffalcinelli.github.io/pydivert

Asynchronously injects a packet into the network stack using Windows Overlapped I/O.

```APIDOC
## send_async

### Description
Asynchronously injects a packet into the network stack using Windows Overlapped I/O.

### Parameters
- **packet** (Packet) - Required - The packet object to inject.
- **recalculate_checksum** (bool) - Optional - Whether to recalculate checksums before sending. Defaults to True.

### Response
- **int** - The number of bytes actually sent.
```

--------------------------------

### matches

Source: https://ffalcinelli.github.io/pydivert

Evaluates a packet against a WinDivert filter string.

```APIDOC
## matches

### Description
Evaluates the packet against the given packet filter string using the WinDivertHelperEvalFilter function.

### Parameters
#### Parameters
- **filter** (str) - Required - The WinDivert filter string to evaluate.
- **layer** (Layer) - Optional - The network layer to apply the filter against.
```

--------------------------------

### Payload Modification

Source: https://ffalcinelli.github.io/pydivert

Modify the payload of captured packets. This example filters for TCP packets with a payload and redacts a specific token if found.

```python
import pydivert

# Filter for TCP packets with payload
with pydivert.WinDivert("tcp.PayloadLength > 0") as w:
    for packet in w:
        if b"secret-token" in packet.payload:
            # Redact the token
            packet.payload = packet.payload.replace(b"secret-token", b"REDACTED")
        w.send(packet)

```

--------------------------------

### Get WinDivert Address Structure

Source: https://ffalcinelli.github.io/pydivert

Retrieves the address and associated metadata of a packet as a `WINDIVERT_ADDRESS` structure. This structure contains information such as timestamp, layer, event type, direction, and checksum status.

```python
address = WinDivertAddress()
address.Timestamp = self.timestamp  # type: ignore
address.Layer = self.layer  # type: ignore
address.Event = self.event  # type: ignore
address.Outbound = 1 if self.direction == Direction.OUTBOUND else 0  # type: ignore
address.Loopback = 1 if self.is_loopback else 0  # type: ignore
address.Impostor = 1 if self.is_impostor else 0  # type: ignore
address.Sniffed = 1 if self.is_sniffed else 0  # type: ignore
address.IPChecksum = 1 if self.ip_checksum else 0  # type: ignore
address.TCPChecksum = 1 if self.tcp_checksum else 0  # type: ignore
address.UDPChecksum = 1 if self.udp_checksum else 0  # type: ignore

if self.layer in (Layer.NETWORK, Layer.NETWORK_FORWARD):
    address.Network.IfIdx, address.Network.SubIfIdx = self.interface  # type: ignore
elif self.layer == Layer.FLOW and self.flow:
    ctypes.pointer(address.Flow)[0] = self.flow
elif self.layer == Layer.SOCKET and self.socket:
    ctypes.pointer(address.Socket)[0] = self.socket
elif self.layer == Layer.REFLECT and self.reflect:
    ctypes.pointer(address.Reflect)[0] = self.reflect

return address
```

--------------------------------

### send

Source: https://ffalcinelli.github.io/pydivert

Injects a packet into the network stack synchronously.

```APIDOC
## send

### Description
Injects a packet into the network stack. Recalculates the checksum before sending unless recalculate_checksum=False is passed.

### Parameters
- **packet** (Packet) - Required - The packet object to inject.
- **recalculate_checksum** (bool) - Optional - Whether to recalculate checksums before sending. Defaults to True.

### Response
- **int** - The number of bytes actually sent.
```

--------------------------------

### POST /set_param

Source: https://ffalcinelli.github.io/pydivert

Sets a specific WinDivert parameter value.

```APIDOC
## POST /set_param

### Description
Set a WinDivert parameter to a specific value.

### Parameters
#### Request Body
- **name** (Param) - Required - The parameter name to set.
- **value** (int) - Required - The value to assign to the parameter.

### Response
#### Success Response (200)
- **result** (int) - The result of the set operation.
```

--------------------------------

### Get WinDivert Address Structure

Source: https://ffalcinelli.github.io/pydivert

Retrieves the packet's address and metadata as a `WINDIVERT_ADDRESS` structure. Populates fields based on packet properties like layer, direction, and checksum status.

```python
@property
def wd_addr(self) -> WinDivertAddress:
        """
        Gets the address and metadata as a `WINDIVERT_ADDRESS` structure.
        :return: The `WINDIVERT_ADDRESS` structure.
        """
        address = WinDivertAddress()
        address.Timestamp = self.timestamp  # type: ignore
        address.Layer = self.layer  # type: ignore
        address.Event = self.event  # type: ignore
        address.Outbound = 1 if self.direction == Direction.OUTBOUND else 0  # type: ignore
        address.Loopback = 1 if self.is_loopback else 0  # type: ignore
        address.Impostor = 1 if self.is_impostor else 0  # type: ignore
        address.Sniffed = 1 if self.is_sniffed else 0  # type: ignore
        address.IPChecksum = 1 if self.ip_checksum else 0  # type: ignore
        address.TCPChecksum = 1 if self.tcp_checksum else 0  # type: ignore
        address.UDPChecksum = 1 if self.udp_checksum else 0  # type: ignore

        if self.layer in (Layer.NETWORK, Layer.NETWORK_FORWARD):
            address.Network.IfIdx, address.Network.SubIfIdx = self.interface  # type: ignore
        elif self.layer == Layer.FLOW and self.flow:
            ctypes.pointer(address.Flow)[0] = self.flow
        elif self.layer == Layer.SOCKET and self.socket:
            ctypes.pointer(address.Socket)[0] = self.socket
        elif self.layer == Layer.REFLECT and self.reflect:
            ctypes.pointer(address.Reflect)[0] = self.reflect

        return address
```

--------------------------------

### Retrieve WinDivert Parameters

Source: https://ffalcinelli.github.io/pydivert

Implementation for fetching specific WinDivert parameters using the underlying DLL.

```python
def get_param(self, name: Param) -> int:
    """
    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: https://reqrypt.org/windivert-doc.html#divert_get_param

    :return: The parameter value.
    """
    value = c_uint64(0)
    windivert_dll.WinDivertGetParam(self._handle, name, byref(value))  # type: ignore[attr-defined]
    return value.value
```

--------------------------------

### Send Packet Synchronously with WinDivert

Source: https://ffalcinelli.github.io/pydivert

Injects a packet into the network stack synchronously. Checksums are recalculated by default unless disabled.

```python
    def send(self, packet: Packet, recalculate_checksum: bool = True) -> int:
        """
        Injects a packet into the network stack.
        Recalculates the checksum before sending unless recalculate_checksum=False is passed.

        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,
                __out_opt UINT *pSendLen,
                __in const PWINDIVERT_ADDRESS pAddr
            );

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

        :return: The return value is the number of bytes actually sent.
        """
        if recalculate_checksum:
            packet.recalculate_checksums()

        send_len = c_uint(0)
        raw = packet.raw
        buff = (c_char * len(packet.raw)).from_buffer(raw)
        windivert_dll.WinDivertSend(self._handle, buff, len(packet.raw), byref(send_len), byref(packet.wd_addr))  # type: ignore[attr-defined]
        return send_len.value
```

--------------------------------

### Asynchronously Inject Packet with pydivert

Source: https://ffalcinelli.github.io/pydivert

Use this method to asynchronously inject a packet into the network stack using Windows Overlapped I/O. Ensure the WinDivert handle and event are open before calling. Checksums are recalculated by default.

```python
async def send_async(self, packet: Packet, recalculate_checksum: bool = True) -> int:
        """
        Asynchronously injects a packet into the network stack using Windows Overlapped I/O.
        """
        if self._handle is None or self._event is None:
            raise RuntimeError("WinDivert handle is not open")

        if recalculate_checksum:
            packet.recalculate_checksums()

        send_len = c_uint(0)
        raw = packet.raw
        buff = (c_char * len(packet.raw)).from_buffer(raw)
        wd_addr = packet.wd_addr
        overlapped = Overlapped(hEvent=self._event)

        # Keep references to objects used in overlapped I/O
        # These are attached to the overlapped object to prevent GC
        overlapped._packet = packet
        overlapped._buff = buff
        overlapped._wd_addr = wd_addr
        overlapped._send_len = send_len
        self._pending_ops.append(overlapped)

        try:
            # Call the async version from DLL
            res = windivert_dll.WinDivertSendEx(
                self._handle,
                buff,
                len(packet.raw),
                byref(send_len),
                0,
                byref(wd_addr),
                ctypes.sizeof(WinDivertAddress),
                byref(overlapped),
            )  # type: ignore[attr-defined]

            if not res:
                error = windivert_dll.GetLastError()
                if error == windivert_dll.ERROR_IO_PENDING:
                    # Wait for the event in a thread pool without blocking the main event loop
                    loop = asyncio.get_running_loop()
                    await loop.run_in_executor(None, windivert_dll.WaitForSingleObject, self._event, INFINITE)
                else:
                    raise windivert_dll.WinError(error)

            # Operation completed successfully
            self._pending_ops.remove(overlapped)
            return send_len.value
        except asyncio.CancelledError:
            # If cancelled, the overlapped object remains in _pending_ops to prevent GC
            # until the handle is closed, which will cancel the pending operation.
            raise
        except Exception:
            if overlapped in self._pending_ops:
                self._pending_ops.remove(overlapped)
            raise
```

--------------------------------

### WinDivert Configuration Enumerations

Source: https://ffalcinelli.github.io/pydivert

Definitions for WinDivert layers, flags, parameters, checksum options, packet directions, and transport protocols.

```APIDOC
## WinDivert Configuration Enumerations

### Description
These enumerations define the configuration constants for interacting with the WinDivert driver via PyDivert.

### Layers (Layer)
- **NETWORK** (0) - Network layer (capture/inject IP packets).
- **NETWORK_FORWARD** (1) - Network forward layer.
- **FLOW** (2) - Flow layer (capture/inject connection events).
- **SOCKET** (3) - Socket layer (capture/inject socket events).
- **REFLECT** (4) - Reflect layer.

### Flags (Flag)
- **DEFAULT** (0) - Default flags.
- **SNIFF** (1) - Sniff mode: packets are not diverted, but a copy is sent to the application.
- **DROP** (2) - Drop mode: packets are dropped by default.
- **RECV_ONLY** (4) - The handle is for receiving only.
- **SEND_ONLY** (8) - The handle is for sending only.
- **NO_INSTALL** (16) - Do not install the driver.
- **FRAGMENTS** (32) - Divert all fragments (requires WinDivert 2.2+).

### Parameters (Param)
- **QUEUE_LEN** (0) - Packet queue length.
- **QUEUE_TIME** (1) - Packet queue time.
- **QUEUE_SIZE** (2) - Packet queue size (bytes).

### Checksum Options (CalcChecksumsOption)
- **NO_IP_CHECKSUM** (1)
- **NO_ICMP_CHECKSUM** (2)
- **NO_ICMPV6_CHECKSUM** (4)
- **NO_TCP_CHECKSUM** (8)
- **NO_UDP_CHECKSUM** (16)
- **NO_REPLACE** (2048)

### Direction (Direction)
- **OUTBOUND** (0)
- **INBOUND** (1)

### Protocols (Protocol)
- **HOPOPT** (0), **ICMP** (1), **TCP** (6), **UDP** (17), **ROUTING** (43), **FRAGMENT** (44), **AH** (51), **ICMPV6** (58), **NONE** (59), **DSTOPTS** (60)
```

--------------------------------

### Open WinDivert Handle

Source: https://ffalcinelli.github.io/pydivert

Opens a WinDivert handle for a given filter. Packets matching the filter are diverted to the handle and can be read using receive(). Requires WinDivert DLL.

```python
168    def open(self) -> None:
169        """
170        Opens a WinDivert handle for the given filter.
171        Unless otherwise specified by flags, any packet that matches the filter will be diverted to the handle.
172        Diverted packets can be read by the application with receive().
173
174        The remapped function is WinDivertOpen::
175
176            HANDLE WinDivertOpen(
177                __in const char *filter,
178                __in WINDIVERT_LAYER layer,
179                __in INT16 priority,
180                __in UINT64 flags
181            );
182
183        For more info on the C call visit: https://reqrypt.org/windivert-doc.html#divert_open
184        """
185        if self.is_open:
186            raise RuntimeError("WinDivert handle is already open.")
187        self._handle = windivert_dll.WinDivertOpen(self._filter, self._layer, self._priority, self._flags)  # type: ignore[attr-defined]
188        self._event = windivert_dll.CreateEventW(None, False, False, None)  # type: ignore[attr-defined]
```

--------------------------------

### Send Packet with WinDivertSendEx

Source: https://ffalcinelli.github.io/pydivert

Injects a packet into the network stack, supporting checksum recalculation and overlapped I/O. Returns the number of bytes sent or None if the operation is pending.

```python
def send_ex(
        self,
        packet: Packet,
        recalculate_checksum: bool = True,
        flags: int = 0,
        overlapped: Overlapped | None = None
    ) -> int | None:
        """
        Injects a packet into the network stack (extended version).
        Recalculates the checksum before sending unless recalculate_checksum=False is passed.
        Supports overlapped IO.

        The remapped function is WinDivertSendEx::

            BOOL WinDivertSendEx(
                __in HANDLE handle,
                __in PVOID pPacket,
                __in UINT packetLen,
                __out_opt UINT *pSendLen,
                __in UINT64 flags,
                __in const PWINDIVERT_ADDRESS pAddr,
                __in UINT addrLen,
                __inout_opt LPOVERLAPPED lpOverlapped
            );

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

        :param packet: The packet to send.
        :param recalculate_checksum: Whether to recalculate checksums before sending.
        :param flags: WinDivert send flags (currently unused, should be 0).
        :param overlapped: An optional `Overlapped` structure for overlapped IO.
        :return: The number of bytes sent if synchronous, or `None` if `ERROR_IO_PENDING` occurred.
        """
        if recalculate_checksum:
            packet.recalculate_checksums()

        send_len = c_uint(0)
        raw = packet.raw
        buff = (c_char * len(packet.raw)).from_buffer(raw)
        windivert_dll._init()

        wd_addr = packet.wd_addr
        addr_len = ctypes.sizeof(WinDivertAddress)

        try:
            windivert_dll.WinDivertSendEx(  # type: ignore[attr-defined]
                self._handle, buff, len(packet.raw), byref(send_len), flags, byref(wd_addr), addr_len, overlapped
            )
        except OSError as e:
            if overlapped is not None and getattr(e, "winerror", None) == windivert_dll.ERROR_IO_PENDING:
                # Store references to prevent garbage collection
                overlapped._packet_raw = packet.raw
                overlapped._address = wd_addr
                overlapped._send_len = send_len
                return None
            raise

        return send_len.value

```

--------------------------------

### close

Source: https://ffalcinelli.github.io/pydivert

Closes the currently open WinDivert handle.

```APIDOC
## close

### Description
Closes the handle opened by open() and clears pending operations.
```

--------------------------------

### Define WinDivert Layers

Source: https://ffalcinelli.github.io/pydivert

Defines the available WinDivert layers for packet capture and injection.

```python
30class Layer(IntEnum):
31    """
32    WinDivert layers.
33    See https://reqrypt.org/windivert-doc.html#divert_open
34    """
35
36    NETWORK = 0
37    """Network layer (capture/inject IP packets)."""
38    NETWORK_FORWARD = 1
39    """Network forward layer."""
40    FLOW = 2
41    """Flow layer (capture/inject connection events)."""
42    SOCKET = 3
43    """Socket layer (capture/inject socket events)."""
44    REFLECT = 4
45    """Reflect layer."""
```

--------------------------------

### Accessing IP and ICMP Headers

Source: https://ffalcinelli.github.io/pydivert

Cached properties for retrieving IP and ICMP header instances from a packet.

```python
@cached_property
def ipv4(self) -> IPv4Header | None:
    """
    - An IPv4Header instance, if the packet is valid IPv4.
    - None, otherwise.
    """
    if self.address_family == socket.AF_INET:
        return IPv4Header(self)
    return None

@cached_property
def ipv6(self) -> IPv6Header | None:
    """
    - An IPv6Header instance, if the packet is valid IPv6.
    - None, otherwise.
    """
    if self.address_family == socket.AF_INET6:
        return IPv6Header(self)
    return None

@cached_property
def ip(self) -> IPHeader | None:
    """
    - An IPHeader instance, if the packet is valid IPv4 or IPv6.
    - None, otherwise.
    """
    return self.ipv4 or self.ipv6

@cached_property
def icmpv4(self) -> ICMPv4Header | None:
    """
    - An ICMPv4Header instance, if the packet is valid ICMPv4.
    - None, otherwise.
    """
    ipproto, proto_start = self.protocol
    if ipproto == Protocol.ICMP and proto_start is not None:
        return ICMPv4Header(self, proto_start)
    return None

@cached_property
def icmpv6(self) -> ICMPv6Header | None:
    """
    - An ICMPv6Header instance, if the packet is valid ICMPv6.
    - None, otherwise.
    """
    ipproto, proto_start = self.protocol
    if ipproto == Protocol.ICMPV6 and proto_start is not None:
        return ICMPv6Header(self, proto_start)
    return None

@cached_property
def icmp(self) -> ICMPHeader | None:
    """
    - An ICMPHeader instance, if the packet is valid ICMPv4 or ICMPv6.
    - None, otherwise.
    """
    return self.icmpv4 or self.icmpv6
```

--------------------------------

### Packet Header and Protocol Parsing

Source: https://ffalcinelli.github.io/pydivert

Properties for identifying address families, protocols, and accessing IP/ICMP headers.

```APIDOC
## Packet Header and Protocol Parsing

### Description
These properties allow for the inspection of network layer information and protocol-specific headers.

### Properties
- **address_family** (int | None) - Returns socket.AF_INET for IPv4, socket.AF_INET6 for IPv6, or None.
- **protocol** (tuple[int | None, int | None]) - Returns a tuple of (ipproto, proto_start). ipproto is the IP protocol; proto_start is the offset of protocol data.
- **ipv4** (IPv4Header | None) - Returns an IPv4Header instance if valid, otherwise None.
- **ipv6** (IPv6Header | None) - Returns an IPv6Header instance if valid, otherwise None.
- **ip** (IPHeader | None) - Returns an IPHeader instance if valid IPv4 or IPv6, otherwise None.
- **icmpv4** (ICMPv4Header | None) - Returns an ICMPv4Header instance if valid ICMPv4, otherwise None.
```

--------------------------------

### Define WinDivert Flags

Source: https://ffalcinelli.github.io/pydivert

Defines flags for configuring WinDivert handle behavior.

```python
49class Flag(IntFlag):
50    """
51    WinDivert flags.
52    See https://reqrypt.org/windivert-doc.html#divert_open
53    """
54
55    DEFAULT = 0
56    """Default flags."""
57    SNIFF = 1
58    """Sniff mode: packets are not diverted, but a copy is sent to the application."""
59    DROP = 2
60    """Drop mode: packets are dropped by default."""
61    RECV_ONLY = 4
62    """The handle is for receiving only."""
63    SEND_ONLY = 8
64    """The handle is for sending only."""
65    NO_INSTALL = 16
66    """Do not install the driver."""
67    FRAGMENTS = 32
68    """Divert all fragments (requires WinDivert 2.2+)."""
69    # Deprecated/Invalid flags in WinDivert 2.x
70    # OVERLAPPED = 64
71    # FULL_PROCESS_IDS = 128
72    # NO_CHECKSUM = 1024
```

--------------------------------

### Asyncio Packet Capture and Re-injection

Source: https://ffalcinelli.github.io/pydivert

Asynchronously capture TCP packets destined for port 80 using asyncio and re-inject them. Requires Python 3.10+ for native asyncio support.

```python
import asyncio
import pydivert

async def main():
    # Asynchronously capture packets
    async with pydivert.WinDivert("tcp.DstPort == 80") as w:
        async for packet in w:
            print(f"Async captured: {packet}")
            await w.send_async(packet)

if __name__ == "__main__":
    asyncio.run(main())

```
Tokens:
Raw