JDivert

JDivert is a powerful Java binding for WinDivert, a Windows driver that allows user-mode applications to capture, modify, and drop network packets sent to or from the Windows network stack.

---

Quick Start

Capture and re-inject all TCP traffic on port 80:

try (WinDivert w = new WinDivert("tcp.DstPort == 80").open()) {
    while (true) {
        Packet packet = w.recv();
        packet.getTcp().ifPresent(tcp -> {
            System.out.println("Captured TCP packet to port: " + tcp.getDstPort());
        });
        w.send(packet); 
    }
}

For more complex scenarios, see our Examples Guide.

---

Usage Hints

Prerequisites

• Operating System: Windows (64-bit).
• Privileges: Administrator privileges are required to load the WinDivert driver and open capture handles.
• Java: Version 8 or higher.

Basic Patterns

1. Always use try-with-resources: JDivert manages native handles and buffers. The WinDivert and WinDivertAsyncResult classes implement AutoCloseable to ensure these resources are released.
2. Filter specifically: Use the Filter Language to capture only the traffic you need. This happens in kernel-mode and is significantly faster than filtering in Java.
3. Handle Re-injection: When you receive a packet with recv(), it is removed from the network stack. If you don't call send(), the packet is dropped.

---

Building and Testing

Prerequisites

• Maven 3.9+
• Vagrant & VirtualBox (Required for full test execution)

Running Tests

Due to the nature of the WinDivert driver and its requirement for specific network stack interactions and Administrator privileges, the full test suite is designed to be executed within a clean, isolated Windows 11 environment managed by Vagrant.

1. Boot the VM:

   vagrant up

2. Sync and Execute: Run the following commands to sync the latest code to a local directory in the VM (avoiding synced folder permission issues) and execute the tests:

   vagrant winrm --command "robocopy C:\jdivert C:\local_jdivert /MIR /XD .git .vagrant target"
   vagrant winrm --command "cd C:\local_jdivert; mvn clean verify"

Note: While you can compile the project on any OS, actual packet capture tests will only succeed in the provided Vagrant environment or an elevated Windows session.

---

Architecture

JDivert bridges the gap between Java and the native WinDivert C library using JNA (with optional Project Panama support on Java 22+).

• Zero-Copy: Leverages direct buffers to process packets without redundant memory copying.
• Memory-Safe: Employs deterministic cleanup to prevent native memory leaks.
• Zero-Install: WinDivert binaries are bundled and extracted automatically into versioned temporary directories.

Read the full Architecture Overview for more details.

---

Installation

Maven

<dependency>
  <groupId>com.github.ffalcinelli</groupId>
  <artifactId>jdivert</artifactId>
  <version>3.0.0</version>
</dependency>

Gradle

implementation 'com.github.ffalcinelli:jdivert:3.0.0'

---

Credits

JDivert is a Java wrapper around the excellent WinDivert project created by basil00. We would like to thank the WinDivert community for providing such a powerful tool for network manipulation on Windows.

• WinDivert Official Website
• WinDivert GitHub Repository

---

Documentation

• Full API Reference (Javadoc)
• Architecture Overview
• Filter Language Guide
• Examples Guide
• Performance Considerations
• Troubleshooting Guide
• Security Policy

---

License

JDivert is dual-licensed under LGPL-3.0-or-later and GPL-2.0-or-later. Refer to the LICENSE, LICENSE-LGPL-3.0-or-later, and LICENSE-GPL-2.0-or-later files for the full license text.