# windivert

> Node Bindings for Divert, currently only supports windows.

Latest version **1.0.2** (published 2025-08-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install windivert
pnpm add windivert
yarn add windivert
bun add windivert
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2025-08-23 |
| First published | 2016-04-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 504.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| GitHub stars | 8 |
| Maintainers | zysen |
| Keywords | deep packet inspection, packet filtering, packet blocking, firewall, packet crafting, packet modification |

## Links

- npm: https://www.npmjs.com/package/windivert
- Repository: https://github.com/Zysen/node-divert
- Homepage: https://github.com/Zysen/node-divert#readme
- Issues: https://github.com/Zysen/node-divert/issues
- npm.io page: https://npm.io/package/windivert

## Dependencies (3)

- [bindings](https://npm.io/package/bindings.md) ^1.5.0
- [is-admin](https://npm.io/package/is-admin.md) ^4.0.0
- [node-addon-api](https://npm.io/package/node-addon-api.md) ^8.3.0

## Recent versions

- 1.0.2 (latest) — 2025-08-23
- 1.0.1 — 2025-08-23
- 1.0.0 — 2019-12-21
- 0.0.19 — 2019-12-12
- 0.0.18 — 2019-12-12
- 0.0.17 — 2019-12-12
- 0.0.16 — 2017-03-22
- 0.0.15 — 2017-03-22
- 0.0.14 — 2017-03-22
- 0.0.13 — 2017-03-22
- 0.0.12 — 2017-03-22
- 0.0.11 — 2016-05-25
- 0.0.10 — 2016-04-03
- 0.0.9 — 2016-04-03
- 0.0.8 — 2016-04-03
- … 6 more at https://npm.io/package/windivert/versions

## README

# node-windivert: NodeJS bindings for WinDivert

## Introduction
node-windivert provides NodeJS bindings for the WinDivert project, enabling packet sniffing, modification, injection, and blocking capabilities on Windows systems. WinDivert is a powerful packet capture and modification tool that operates at the Windows Network Stack level.

For more information about WinDivert, visit: https://reqrypt.org/windivert.html
Original WinDivert documentation: https://github.com/basil00/Divert/blob/master/README

## Usage
Basic installation and usage:
```javascript
// Install via npm
npm install windivert

// Basic usage example
const wd = require("windivert");

// Create WinDivert instance with filter
const handle = await wd.createWindivert(
    "tcp.DstPort==80 or tcp.SrcPort==80", // Filter string
    wd.LAYERS.NETWORK,                     // Network layer
    wd.FLAGS.DEFAULT                       // Default flags
);

// Open the handle to start capturing
handle.open();

// Add packet receiver
wd.addReceiveListener(handle, (packet, addr) => {
    console.log("Received packet with length:", packet.length);
    // Return values:
    // - modified packet: to send modified packet
    // - undefined: to send original packet
    // - false: to block/drop the packet
    return packet; 
});

// When done, close the handle
// handle.close();
```

## Other Examples

### Blocking Packets
```javascript
const wd = require("windivert");

// Create WinDivert instance for blocking
const handle = await wd.createWindivert(
    "tcp.DstPort==80 or tcp.SrcPort==80",
    wd.LAYERS.NETWORK,
    wd.FLAGS.DEFAULT  // You can use DEFAULT flag for selective blocking
);

// Open the handle
handle.open();

// Add packet receiver that selectively blocks packets
wd.addReceiveListener(handle, (packet, addr) => {
    // You can implement your blocking logic here
    // Example: Block packets larger than 1000 bytes
    if (packet.length > 1000) {
        console.log("Blocking large packet:", packet.length);
        return false; // Return false to block/drop this packet
    }
    
    // Example: Block packets based on content
    if (packet.includes(Buffer.from("BLOCK_ME"))) {
        console.log("Blocking packet containing BLOCK_ME");
        return false; // Return false to block/drop this packet
    }
    
    // Example: Let other packets pass through
    console.log("Allowing packet:", packet.length);
    return undefined; // Return undefined to let the packet pass
});

// When done, close the handle
// handle.close();

// Alternative: Block all packets using FLAGS.DROP
const blockAllHandle = await wd.createWindivert(
    "tcp.DstPort==80 or tcp.SrcPort==80",
    wd.LAYERS.NETWORK,
    wd.FLAGS.DROP // Use DROP flag to block all matching packets
);
blockAllHandle.open();
```

### Modifying Packets
```javascript
const wd = require("windivert");

// Create WinDivert instance
const handle = await wd.createWindivert(
    "tcp.DstPort==80 or tcp.SrcPort==80",
    wd.LAYERS.NETWORK,
    wd.FLAGS.DEFAULT
);

// Open the handle
handle.open();

// Add packet receiver that modifies packets
wd.addReceiveListener(handle, (packet, addr) => {
    // Create a copy of the packet
    const modifiedPacket = Buffer.from(packet);
    
    // Modify the packet as needed
    const searchStr = Buffer.from("BOB");
    const replaceStr = Buffer.from("SAM");
    
    const index = modifiedPacket.indexOf(searchStr);
    if (index >= 0) {
        replaceStr.copy(modifiedPacket, index);
    }
    
    return modifiedPacket;
});

// When done, close the handle
// handle.close();
```

### DPI Circumvention Example
See `examples/goodbyeDPI.js` for a comprehensive example of Deep Packet Inspection circumvention implementation.

## Building

### Prerequisites
1. Ensure node-gyp is installed and properly configured
   - Follow installation instructions at: https://github.com/nodejs/node-gyp
2. Install Visual Studio build tools https://visualstudio.microsoft.com/visual-cpp-build-tools/

### Build Steps
1. Download WinDivert-2.2.2-A.zip from https://reqrypt.org/windivert.html
2. Extract the contents into the bin directory
3. Run the following commands:
```bash
node-gyp clean
node-gyp configure
node-gyp build
```

### Development Commands
```bash
npm run test         # Run goodbyeDPI example
npm run build:dev    # Build in debug mode
npm run build        # Build in release mode
npm run rebuild:dev  # Clean and build in debug mode
npm run rebuild      # Clean and build in release mode
npm run clean        # Clean build files
```

Note: The module will automatically use the custom-built binary from `build/Release` if it exists, instead of the precompiled binaries in `./bin`.

---
_Source: https://npm.io/package/windivert · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._