# nmap/npcap architecture

> Architecture diagram of the GitHub repository nmap/npcap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nmap/npcap
- Repository: https://github.com/nmap/npcap

## Overview

##### Project type and purpose
- Npcap is a system-level packet capture and injection library for Windows.
- It consists of a kernel-mode driver (npf.sys), user-mode helper services, a WinPcap-compatible API (wpcap.dll/Packet.dll), installer modules, SDK headers/libs, example apps, build scripts, and documentation.

##### File structure
Top-level directories:
– Common: shared header definitions for both driver and user-mode components.
– wpcap: WinPcap API compatibility layer (wpcap.dll).
– packetWin7: kernel-mode driver source (npf) and helper projects for Windows 7+ (NDIS, WFP).
– installer: scripts and projects for driver/service installation (NPFInstall, registry, callouts).
– Examples-pcap & Examples: sample applications showing how to call the API.
– docs: API reference, developer guide, internals docs (XML/HTML/PDF).
– test: test harness, scripts, props.
– build scripts (.bat, .cmake) at root to build SDK, examples, libs, docs.

##### README for additional insights
- The README confirms Npcap replaces WinPcap, improves speed, reliability, security, and includes OEM licensing.
- It points to a developer guide and internals documentation that describe driver internals, installer behavior, and API usage.

a. Main components to include
– Kernel-mode driver (“npf.sys”): interfaces with NDIS/WFP to capture/inject packets.
– User-mode API libraries (wpcap.dll / Packet.dll): expose pcap_* functions, wrap DeviceIoControl calls.
– Helper service (NpcapHelper.exe): user-mode service for loopback capture via Windows Filtering Platform (WFP).
– Installer service (NPFInstall.exe / callout modules): installs and registers the driver, helper service, loopback interfaces.
– Example applications: UDPdump, basic_dump, stats, etc., linking against wpcap.dll.
– Build & packaging scripts: build_sdk.bat, build_lib, create_examples, installer scripts.
– Documentation assets (docs folder): XML/HTML/PDF guides, developer reference.

b. Relationships and data flow
1. Installation flow: installer scripts ➔ NPFInstall.exe ➔ installs npf.sys driver as Windows service ➔ registers device names, callouts.
2. Runtime capture flow: user app calls pcap_open_live (wpcap.dll) ➔ DeviceIoControl to npf.sys ➔ driver hooks NDIS/WFP, captures packets ➔ buffers returned to wpcap.dll ➔ user app processes data.
3. Injection flow: user app calls pcap_sendpacket ➔ wpcap.dll ➔ DeviceIoControl to driver ➔ driver injects packet via NDIS.
4. Loopback capture: NpcapHelper.exe registers WFP callouts ➔ intercepts loopback traffic ➔ forwards packets to driver capture paths.
5. Build flow: build scripts invoke MSBuild/CMake to compile driver, libraries, examples; produce SDK package.

c. Architectural patterns / design principles
– Layered architecture:
- Kernel layer: driver interacts with Windows networking stack.
- API layer: WinPcap-compatible DLLs.
- Application layer: sample and third-party apps.
- Installer layer: separate installer for service registration and security.
– Separation of concerns: capture/inject in kernel, API abstraction in DLL, loopback in helper service.
– Compatibility shim: wpcap.dll implements old WinPcap API over new driver.
– Modular build: scripts orchestrate discreet build steps for docs, examples, libs, installer.

d. Key technologies / frameworks
– Windows NDIS (Driver), WFP (loopback).
– Visual C++ solutions/projects (.vcxproj) for driver, helper, installer, examples.
– CMake, batch scripts for cross-component builds.
– XML/HTML for documentation generation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Packaging Layer
    subgraph "Build & Packaging"
        direction TB
        BuildScripts["Build Scripts\n(build_sdk.bat,\nbuild_test.bat,\ncreate_docs.bat,\ncreate_examples.bat,\ncreate_include.bat,\ncreate_lib.bat)"]:::build
        PackagingOutput["SDK Package\n(libs, docs,\nexamples)"]:::build
    end

    %% Installation Layer
    subgraph "Installation"
        direction TB
        Installer["Installer Service\n(NPFInstall.exe)"]:::user
        InstallerScripts["Installer Scripts & Utilities\n(installer/Build.bat,\nCheckStatus.bat,\nDiagReport.bat/ps1,\nFixInstall.bat)"]:::build
    end

    %% Runtime Layer
    subgraph "Runtime"
        direction TB
        Apps["Sample Applications\n(UDPdump, basic_dump,\nstats, etc.)"]:::user
        APIDLL["API DLL\n(wpcap.dll / Packet.dll)"]:::user
        Helper["Helper Service\n(NpcapHelper.exe)"]:::user
        Common["Common Shared Headers"]:::build
        KernelDriver["Kernel Driver\n(npf.sys)"]:::kernel
    end

    %% Documentation & Testing
    subgraph "Documentation"
        direction TB
        Docs["Documentation Assets\n(XML/HTML/PDF)"]:::docs
    end

    subgraph "Testing"
        direction TB
        Test["Test Harness & Props\n(make_test.bat,\nstatic.props,\nREADME.md)"]:::build
    end

    %% Build Relationships
    BuildScripts -->|builds| PackagingOutput
    PackagingOutput -->|supplies artifacts| Installer
    PackagingOutput -->|supplies artifacts| Runtime

    InstallerScripts -->|invokes| Installer
    Installer -->|installs| KernelDriver
    Installer -->|registers| Helper

    %% Runtime Data Flows
    Apps -->|pcap_open_live / pcap_sendpacket| APIDLL
    APIDLL -->|DeviceIoControl| KernelDriver
    KernelDriver -->|captures/injects| APIDLL
    Helper -->|registers WFP callouts & intercepts loopback| KernelDriver
    Common -->|shared headers used by| KernelDriver
    Common -->|shared headers used by| APIDLL

    %% Documentation & Testing Relations
    Docs -->|references| APIDLL
    Docs -->|references| KernelDriver
    Test -->|tests| APIDLL
    Test -->|tests| KernelDriver

    %% Click Events
    click KernelDriver "https://github.com/nmap/npcap/blob/master/packetWin7/npf/npf/npf.vcxproj"
    click APIDLL "https://github.com/nmap/npcap/blob/master/packetWin7/Dll/Project/Packet.vcxproj"
    click Helper "https://github.com/nmap/npcap/blob/master/packetWin7/Helper/NpcapHelper/NpcapHelper.vcxproj"
    click Installer "https://github.com/nmap/npcap/blob/master/packetWin7/NPFInstall/NPFInstall/NPFInstall.vcxproj"
    click Common "https://github.com/nmap/npcap/blob/master/Common/Packet32.h"
    click Apps "https://github.com/nmap/npcap/tree/master/Examples-pcap/"
    click BuildScripts "https://github.com/nmap/npcap/blob/master/build_sdk.bat"
    click InstallerScripts "https://github.com/nmap/npcap/blob/master/installer/Build.bat"
    click Docs "https://github.com/nmap/npcap/blob/master/docs/npcap-api.xml"
    click Test "https://github.com/nmap/npcap/blob/master/test/make_test.bat"

    %% Styling
    classDef kernel fill:#fdd,stroke:#f00,stroke-width:1px;
    classDef user fill:#ddf,stroke:#00f,stroke-width:1px;
    classDef build fill:#dfd,stroke:#0a0,stroke-width:1px;
    classDef docs fill:#ffd,stroke:#aa0,stroke-width:1px;
```
