windows-filter-windivert/BUILD_INSTRUCTIONS.md

Build Instructions for Windows

Quick Start Guide

Follow these steps to build and run the DNS Packet Filter on Windows.

Prerequisites

1. Windows 10/11 (64-bit)
2. Visual Studio 2019 or later with C++ development tools
   • Or MinGW-w64 with GCC 8.0+
3. CMake 3.15 or later
   • Download from: https://cmake.org/download/

Step 1: Setup WinDivert Library

IMPORTANT: You need to download WinDivert on a Windows machine.

1. Download WinDivert 2.2:

   https://github.com/basil00/WinDivert/releases/download/v2.2.2/WinDivert-2.2.2-A.zip
   

2. Extract the ZIP file

3. Copy the required files:

   From WinDivert-2.2.2-A/include/:

   Copy: windivert.h
   To:   external/WinDivert/include/windivert.h
   

   From WinDivert-2.2.2-A/x64/:

   Copy: WinDivert.dll
   To:   external/WinDivert/lib/WinDivert.dll
   
   Copy: WinDivert64.sys
   To:   external/WinDivert/lib/WinDivert64.sys
   
   Copy: WinDivert.lib
   To:   external/WinDivert/lib/WinDivert.lib
   

4. Verify the directory structure:

   external/WinDivert/
   ├── include/
   │   └── windivert.h
   └── lib/
       ├── WinDivert.dll
       ├── WinDivert64.sys
       └── WinDivert.lib
   

Step 2: Build with CMake

Option A: Using Visual Studio

1. Open Command Prompt or PowerShell

2. Navigate to the project directory:

   cd C:\path\to\windows-filter
   

3. Create build directory:

   mkdir build
   cd build
   

4. Generate Visual Studio project files:

   cmake .. -G "Visual Studio 17 2022"
   

   For Visual Studio 2019, use:

   cmake .. -G "Visual Studio 16 2019"
   

5. Build the project:

   cmake --build . --config Release
   

6. Output files will be in build/Release/

Option B: Using Visual Studio IDE

1. Generate project files:

   mkdir build
   cd build
   cmake .. -G "Visual Studio 17 2022"
   

2. Open build/DNSPacketFilter.sln in Visual Studio

3. Set build configuration to Release

4. Build → Build Solution (or press F7)

5. Output files will be in build/Release/

Option C: Using MinGW

1. Ensure MinGW-w64 is in your PATH

2. Create build directory:

   mkdir build
   cd build
   

3. Generate Makefiles:

   cmake .. -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release
   

4. Build:

   mingw32-make
   

5. Output files will be in build/

Step 3: Verify Build Output

After successful build, check that these files exist in the output directory:

build/Release/  (or build/ for MinGW)
├── dns_filter.exe
├── WinDivert.dll
├── WinDivert64.sys
└── config/
    └── rules.json

Step 4: Run the Application

IMPORTANT: Must run as Administrator!

1. Open Command Prompt as Administrator:

   • Press Windows Key
   • Type "cmd"
   • Right-click "Command Prompt"
   • Select "Run as administrator"

2. Navigate to the build output directory:

   cd C:\path\to\windows-filter\build\Release
   

3. Run the application:

   dns_filter.exe
   

4. You should see:

   ==================================================
       Windows DNS Packet Filter
       Powered by WinDivert
   ==================================================
   
   Configuration file: config/rules.json
   
   Loaded X filtering rules
   ...
   DNS Packet Filter is now active!
   

5. Press Ctrl+C to stop

Troubleshooting

CMake Configuration Errors

Error: "Could not find WinDivert.lib"

Solution:

• Verify WinDivert files are in external/WinDivert/lib/
• Re-run Step 1 to copy the files correctly

Error: "CMake version too old"

Solution:

• Download latest CMake from https://cmake.org/download/
• Or use choco install cmake (if you have Chocolatey)

Build Errors

Error: "windivert.h: No such file or directory"

Solution:

• Verify external/WinDivert/include/windivert.h exists
• Re-run Step 1 to copy the header file

Error: "C++17 support required"

Solution:

• Update Visual Studio to 2017 or later
• Or update MinGW to GCC 8.0 or later

Runtime Errors

Error: "Access denied"

Solution:

• Run as Administrator (see Step 4)

Error: "WinDivert driver not found"

Solution:

• Ensure WinDivert64.sys is in the same directory as dns_filter.exe
• Check antivirus didn't quarantine the file

Error: "Failed to load configuration"

Solution:

• Verify config/rules.json exists in the same directory
• Check JSON syntax is valid

Testing the Build

1. Start the filter (as Administrator)

2. Open another Command Prompt and test DNS queries:

   nslookup example.com
   nslookup google.com
   

3. Check the log file:

   type dns_filter.log
   

4. You should see DNS queries being logged

Development Workflow

For development and testing:

1. Make code changes in src/ or include/

2. Rebuild:

   cd build
   cmake --build . --config Release
   

3. Test the changes:

   cd Release
   dns_filter.exe
   

Clean Build

To perform a clean build:

# Remove build directory
rmdir /s /q build

# Create new build
mkdir build
cd build
cmake .. -G "Visual Studio 17 2022"
cmake --build . --config Release

Advanced: Cross-Compilation

To build from Linux/macOS for Windows:

1. Install MinGW cross-compiler

2. Configure CMake with toolchain:

   cmake .. -DCMAKE_TOOLCHAIN_FILE=mingw-w64-toolchain.cmake
   

3. Build:

   make
   

Note: You still need to copy WinDivert files on the target Windows machine.

Next Steps

After successful build:

1. Read README.md for usage instructions
2. Edit config/rules.json to customize filtering rules
3. Review logs in dns_filter.log

Getting Help

If you encounter issues:

1. Check the Troubleshooting section above
2. Verify all prerequisites are installed correctly
3. Ensure WinDivert files are copied correctly
4. Check build output for specific error messages

---

Happy filtering!