Abstract
A guide to Npcap, a packet capture and network analysis framework for Windows, for users and software developers. Npcap is a modern, safe, and compatible update to WinPcap.
Table of Contents
This Manual describes the programming interface and the source code of Npcap. It provides detailed descriptions of the functions and structures exported to programmers, along with complete documentation of the Npcap internals. Several tutorials and examples are provided as well.
Npcap is an architecture for packet capture and network analysis for Windows operating systems, consisting of a software library and a network driver.
Most networking applications access the network through widely-used operating system primitives such as sockets. It is easy to access data on the network with this approach since the operating system copes with the low level details (protocol handling, packet reassembly, etc.) and provides a familiar interface that is similar to the one used to read and write files.
Sometimes, however, the “easy way” is not up to the task, since some applications require direct access to packets on the network. That is, they need access to the “raw” data on the network without the interposition of protocol processing by the operating system.
The purpose of Npcap is to give this kind of access to Windows applications. It provides facilities to:
This set of capabilities is obtained by means of a device driver, which is installed inside the networking portion of the Windows kernel, plus a couple of DLLs.
All of these features are exported through a powerful programming interface, easily usable by applications. The main goal of this manual is to document this interface, with the help of several examples.
The Npcap programming interface can be used by many types of network tools for analysis, troubleshooting, security and monitoring. In particular, classical tools that rely on Npcap are:
Npcap receives and sends the packets independently from the host protocols, like TCP/IP. This means that it isn't able to block, filter or manipulate the traffic generated by other programs on the same machine: it simply “sniffs” the packets that transit on the wire. Therefore, it does not provide the appropriate support for applications like traffic shapers, QoS schedulers and personal firewalls.
Npcap is an update of WinPcap to the NDIS 6 Light-Weight Filter (LWF) API. It supports Windows Vista, 7, 8 and 10. It is developed by the Nmap Project as a continuation of the project started by Yang Luo under Google Summer of Code 2013 and 2015. It also received many helpful tests from Wireshark and NetScanTools.
Npcap carries on the WinPcap legacy, but is not without its own innovations. Here are some of the most exciting improvements and new features that Npcap adds:
NDIS 6 Support: Npcap makes use of the new NDIS Lightweight Filter driver in Windows Vista and later. This driver type is faster and has less overhead than the legacy NDIS 5 Intermediate Driver type used by WinPcap.
Latest libpcap API Support: Npcap provides support for the latest libpcap API by accepting libpcap as a Git submodule. The latest libpcap 1.8 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.
“Admin-only Mode” Support: Npcap supports to restrict its use to Administrators for safety purpose. If Npcap is installed with the option “Restrict Npcap driver's access to Administrators only” checked, when a non-Admin user tries to start a user software (Nmap, Wireshark, etc), the User Account Control (UAC) dialog will prompt asking for Administrator privilege. Only when the end user chooses Yes, the driver can be accessed. This is similar to UNIX where you need root access to capture packets.
Loopback Packet Capture: Npcap is able to see Windows loopback packets 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).
Loopback Packets Injection: Besides loopback packets capturing, Npcap can also send out loopback packets using the Winsock Kernel (WSK) technique. A user software (e.g. Nmap) can just send packets out using “Npcap Loopback Adapter” like other adapters. “Npcap Loopback Adapter” will automatically remove the packet's Ethernet header and inject the payload into Windows TCP/IP stack.
Raw 802.11 Packets Capture Support: 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 uses Npcap raw 802.11 feature”.
See more details about radiotap here:
http://www.radiotap.org/
“WinPcap API-compatible Mode” Support: “WinPcap API-compatible Mode” makes Npcap a strict WinPcap replacement by using the same DLL location and service name as WinPcap. This is useful for testing or migrating from software that only uses WinPcap, but because Npcap is masquerading as WinPcap, software will not be able to be aware of and use Npcap's newer features. It's notable that before installing in this mode, any existing WinPcap installation will be uninstalled and replaced.
The purpose of this manual is to provide a comprehensive and easy way to browse the documentation of the Npcap architecture. You will find three main sections: the section called “Npcap Users' Guide”, the section called “Developing software with Npcap”, and the section called “Npcap internals”.
the section called “Npcap Users' Guide” is for end users of Npcap, and primarily concerns installation options, hardware compatibility, and bug reporting procedures.
the section called “Developing software with Npcap” is for programmers who need to use Npcap from an application: it contains information about functions and data structures exported by the Npcap API, a manual for writing packet filters, and information on how to include it in an application. A tutorial with several code samples is provided as well; it can be used to learn the basics of the Npcap API using a step-by-step approach, but it also offers code snippets that demonstrate advanced features.
the section called “Npcap internals” is intended for Npcap developers and maintainers, or for people who are curious about how this system works: it provides a general description of the Npcap architecture and explains how it works. Additionally, it documents the complete device driver structure, the source code, the Packet.dll interface and the low-level Npcap API. If you want to understand what happens inside Npcap or if you need to extend it, this is the section you will want to read.
We call Npcap an architecture rather than library because packet capture is a low level mechanism that requires a strict interaction with the network adapter and with the operating system, in particular with its networking implementation, so a simple library is not sufficient.
For consistency with the literature, we will use the term packet even though frame is more accurate since the capture process is done at the data-link layer and the data-link header is included in the captured data.
Even though Npcap source code is publicly available for review, it is not open source software and my not be redistributed without special permission from the Nmap Project. The Npcap License allows end users to download, install, and use Npcap from our site for free. Software providers (open source or otherwise) which want to use Npcap functionality are welcome to point their users to npcap.org for those users to download and install.
We fund the Npcap project by selling licenses to companies who wish to redistribute Npcap within their products. The Npcap OEM edition allows companies to silently and seamlessly install Npcap during their product's installation rather than asking users to download and install Npcap themselves. The Npcap OEM commercial license also includes support, updates and indemnification. This is similar to the commercial licenses we offer for embedding Nmap in commercial software. More details are available from the Npcap OEM page.
The latest Npcap release can always be found on the Npcap website as an executable installer and as a source code archive.