Windows Packet Filter provides official, idiomatic Go bindings via the github.com/wiresock/ndisapi-go module. The Go library provides a user-mode interface to the Windows Packet Filter driver for low-level packet capture, inspection, modification, and injection at the NDIS layer, communicating directly via Windows syscalls without cgo runtime dependencies.
Installation
Install the reviewed revision into your Go module:
go get github.com/wiresock/[email protected]
Key Features
- Direct Windows Syscalls: Interacts directly with the WinpkFilter driver using Windows IOCTL system calls without requiring cgo or external C toolchains.
- Multi-Adapter Support: Simultaneously configure and capture packets from physical Ethernet, Wi-Fi, and virtual network interfaces.
- Flexible Filtering Modes: Put adapters into packet snooping (Listen) or transparent inline diversion (Tunnel) modes.
- Raw Packet Injection: Inject forged or modified Ethernet frames bidirectionally to the network adapter or up the TCP/IP stack.
- Concurrency: Coordinate access to shared
NdisApiinstance state and packet buffers. Do not callClosewhile driver operations are in flight; the low-level API does not provide a blanket synchronization guarantee for every method.
Getting Started Example
Install the Windows Packet Filter runtime before running this example on Windows. It opens the driver and lists TCP/IP-bound adapters without changing filtering modes or capturing traffic. GetTcpipBoundAdaptersInfo returns a *TcpAdapterList; only entries below AdapterCount are populated.
package main
import (
"fmt"
"log"
"github.com/wiresock/ndisapi-go"
)
func main() {
api, err := ndisapi.NewNdisApi()
if err != nil {
log.Fatalf("Failed to open the Windows Packet Filter driver: %v", err)
}
defer api.Close()
if !api.IsDriverLoaded() {
log.Print("Windows Packet Filter driver is unavailable. Install the runtime and check driver access permissions.")
return
}
adapters, err := api.GetTcpipBoundAdaptersInfo()
if err != nil {
log.Printf("Failed to query network adapters: %v", err)
return
}
if adapters.AdapterCount == 0 {
fmt.Println("No TCP/IP bound network adapters found.")
return
}
fmt.Printf("Found %d network adapter(s):\n", adapters.AdapterCount)
for i := uint32(0); i < adapters.AdapterCount; i++ {
name := api.ConvertWindows2000AdapterName(string(adapters.AdapterNameList[i][:]))
fmt.Printf(" [%d] %s (adapter handle bytes: % X)\n", i, name, adapters.AdapterHandle[i])
}
}
Authoritative Resources
- Package Documentation: pkg.go.dev/github.com/wiresock/ndisapi-go
- GitHub Repository: github.com/wiresock/ndisapi-go
- Issue Tracker: github.com/wiresock/ndisapi-go/issues
Pinned revision and verified API fixes
The installation command pins v1.0.2-0.20261016140712-b560dc6740fa, the Go pseudo-version for merged commit b560dc6740fa. It includes the static-table serialization fix and the corrections merged in PR #21. A pseudo-version identifies an exact commit; it is not a new release tag. Use the pinned command above to obtain these fixes.
- Static filter writes:
SetPacketFilterTable()serializes the eight-byte native header and contiguous filter entries, usinglen(StaticFilters)for the count. The olderv1.0.1tag sends a Go slice header instead; avoid that implementation for setting static tables. - Table reads and statistics:
GetPacketFilterTable()validates the returned byte count and table size before decoding entries.GetPacketFilterTableResetStats()queries capacity, reads a correctly sized native buffer, returns the observed counters, and resets the stored statistics. The previous workaround of avoiding this method is no longer needed with the pinned version. Check the returned error from either method. - NDISWAN detection:
IsNdiswanInterfaces()now checks network-class registry component IDs and linkage exports with case-insensitive matching. It supports IP, IPv6, and BH miniports through the corresponding helpers; registry access is read-only. - Adapter mode:
GetAdapterMode()issues the GET IOCTL and reads the active flags without changing them.
See the pinned source for static-table operations, NDISWAN lookup, and adapter-mode queries. These fixes were verified with the installed Windows Packet Filter 3.6.2.1 driver in a Windows 11 x64 VM. ARM64 was compiled, not runtime-tested.