rlugojr / npcap

Nmap Project's packet sniffing library for Windows, based on WinPcap/Libpcap improved with NDIS 6 and LWF.

Npcap


Npcap is an update of WinPcap to NDIS 6 Light-Weight Filter (LWF) technique. It supports Windows Vista, 7, 8 and 10. It is sponsored by the Nmap Project and developed by Yang Luo under Google Summer of Code 2013 and 2015. It also received many helpful tests from Wireshark, libpcap and NetScanTools.

Features

1. NDIS 6 Support: Npcap makes use of new NDIS 6 Light-Weight Filter (LWF) API in Windows Vista and later (the legacy driver is used on XP). It's faster than the deprecated NDIS 5 API, which Microsoft could remove at any time.
2. Latest libpcap API Support: Npcap provides support for the latest libpcap API by accepting libpcap as a Git submodule. The latest libpcap 1.8.0 has integrated more fascinating features and functions than the deprecated libpcap 1.0.0 shipped by WinPcap. Moreover, since Linux already has a good support for latest libpcap API, using Npcap on Windows facilitates your software to base on the same API on both Windows and Linux.
3. Extra Security: Npcap can be restricted so that only Administrators can sniff packets. If a non-Admin user tries to utilize Npcap through software such as Nmap or Wireshark, the user will have to pass a User Account Control (UAC) dialog to utilize the driver. This is conceptually similar to UNIX, where root access is generally required to capture packets.
4. WinPcap Compatibility: If you choose WinPcap Compatible Mode at install-time, Npcap will use the WinPcap-style DLL directories c:\Windows\System32 and servcie name npf, allowing software built with WinPcap in mind to transparently use Npcap instead. If compatability mode is not selected, Npcap is installed in a different location C:\Windows\System32\Npcap with a different service name npcap so that both drivers can coexist on the same system. In this case, applications which only know about WinPcap will continue using that, while other applications can choose to use the newer and faster Npcap driver instead.
5. Loopback Packet Capture: Npcap is able to sniff loopback packets (transmissions between services on the same machine) by using the Windows Filtering Platform (WFP). After installation, Npcap will create an adapter named Npcap Loopback Adapter for you. If you are a Wireshark user, choose this adapter to capture, you will see all loopback traffic the same way as other non-loopback adapters. Try it by typing in commands like ping 127.0.0.1 (IPv4) or ping ::1 (IPv6).
6. Loopback Packet Injection: Npcap is also able to send loopback packets using the Winsock Kernel (WSK) technique. User-level software such as Nping can just send the packets out using Npcap Loopback Adapter just like any other adapter. Npcap then does the magic of removing the packet's Ethernet header and injecting the payload into the Windows TCP/IP stack.
7. Raw 802.11 Packet Capture: Npcap is able to see 802.11 packets instead of fake Ethernet packets on ordinary wireless adapters. You need to select the Support raw 802.11 traffic (and monitor mode) for wireless adapters option in the installation wizard to enable this feature. When your adapter is in Monitor Mode, Npcap will supply all 802.11 data + control + management packets with radiotap headers. When your adapter is in Managed Mode, Npcap will only supply Ethernet packets. Npcap directly supports to use Wireshark to capture in Monitor Mode. Meantime, Npcap also provides the WlanHelper.exe tool to help you switch to Monitor Mode on your own. See more details about this feature in section For software that use Npcap raw 802.11 feature. See more details about radiotap here: http://www.radiotap.org/

Documentation

Npcap Users' Guide

Get the code

Run git clone https://github.com/nmap/npcap: pull this repo. This repo contains libpcap as a submodule, so make sure that you have also pulled all the submodules.

Build

Run installer\Build.bat: build all DLLs and the driver. The DLLs need to be built using Visual Studio 2013. And the driver needs to be built using Visual Studio 2015 with Windows SDK 10 10586 & Windows Driver Kit 10 10586. The build of wpcap.dll also requires to install Win flex-bison. Please unzip the downloaded package and add the directory to the PATH environment variable.

Packaging

Run installer\Deploy.bat: copy the files from build directories to deployment directories and sign the files. Generate an installer named npcap-%VERSION%.exe using NSIS 2.51 with the advanced logging special build and SysRestore plug-in (special build for Npcap) and sign the installer.

Build SDK (optional)

Run build_sdk.bat: copy the headers, libraries, examples and docs from build directories to npcap-sdk directory and package them into a zip file named npcap-sdk-<VERSION>.zip in the installer folder using 7-Zip.

Generating debug symbols (optional)

Run installer\Deploy_Symbols.bat: copy the debug symbol files (.PDB) from build directories to deployment directories and package them into a zip file named npcap-<VERSION>-DebugSymbols.zip using 7-Zip.

Downloads

1. Download and install the latest Npcap installer: https://github.com/nmap/npcap/releases
2. Use Nmap or Wireshark to test Npcap.

Development kit

Npcap has its own SDK for Non-WinPcap Compatible Mode. By using it, your software will run under Non-WinPcap Compatible Mode. We don't update the SDK as frequently as the binaries. The latest SDK is Npcap SDK 0.07 r9.

If you only want to build your software under WinPcap Compatible Mode (which is NOT recommended), please use the legacy WinPcap 4.1.2 Developer's Pack instead.

Bug report

Please report any bugs or issues about Npcap at: Nmap issues on GitHub. In your report, please provide your DiagReport output, user software version (e.g. Nmap, Wireshark), reproduce steps and other information you think necessary. If your issue occurs only on a special OS version (e.g. Win10 1511, 1607), please mention it in the report.

Diagnostic report

Npcap has provided a diagnostic utility called DiagReport. It provides a lot of information including OS metadata, Npcap related files, install options, registry values, services, etc. You can simply click the C:\Program Files\Npcap\DiagReport.bat file to run DiagReport. It will pop up a text report via Notepad (it's stored in: C:\Program Files\Npcap\DiagReport.txt). Please always submit it to us if you encounter any issues.

For Vista users: DiagReport is a script written by Windows PowerShell, and Vista doesn't have it installed by default. So if you are using Vista, you need to install PowerShell 2.0 (KB968930) on your system. Please download it here for x86 and here for x64. Win7 and later systems have built-in PowerShell support and don't need to do anything about it.

General installation log

Npcap keeps track of the installation in a log file: C:\Program Files\Npcap\install.log, please submit it together in your report if you encounter issues about the installation (e.g. the installer halts).

Driver installation log

Npcap keeps track of the driver installation (aka commands run by NPFInstall.exe) in a log file: C:\Program Files\Npcap\NPFInstall.log, please submit it together in your report if you encounter issues about the driver installation and Npcap Loopback Adapter.

There's another system-provided driver installation log in: C:\Windows\INF\setupapi.dev.log. If you encounter errors about the driver/service installation, please copy the Npcap-related lines out and send them together in your report.

Driver log

If you think the driver doesn't function well, you can open an Administrator command prompt, enter sc query npcap to query the driver status and net start npcap to start the driver (replace npcap with npf if you installed Npcap in WinPcap Compatible Mode). The command output will inform you whether there's an error. If the driver is running well, but the issue still exists, then you need to check the driver's log. Normal Npcap releases don't switch on the driver log function for performance. So you have to install a debug version Npcap. We don't build a debug version for every release. Currently, the latest debug version is Npcap 0.07 r16. If the currently available debug version Npcap doesn't have your issue, you can ask me to build a debug version Npcap for a specific version in mail. I'll be happy to do that. When you have got an appropriate debug version Npcap, you need to use DbgView to read the Windows kernel log (which contains our driver log). You may need to turn on DbgView before installing Npcap, if the error occurs when the driver loads. When done, save the DbgView output to a file and submit it in your report.

Blue screen of death (BSoD) dump

If you encountered BSoD when using Npcap, please attach the minidump file (in C:\Windows\Minidump) to your report together with the Npcap version. We may ask you to provide the full dump (C:\Windows\MEMORY.DMP) for further troubleshooting.

License

See: LICENSE

Contact

• [email protected] (Nmap development list, this is preferred)
• [email protected] (Yang Luo's email, if your issue needs to be kept private, please contact me via this mail)