Overview

• • jNetPcap SDK Overview

    jNetPcap is a Java library for packet capture and protocol analysis, providing a modern Java API on top of libpcap/WinPcap/Npcap. It combines familiar pcap semantics with high-performance protocol dissection.

    Key Features

    • Native libpcap integration via Java Foreign Function & Memory (FFM) API

    • Zero-copy packet access with direct memory binding

    • Protocol dissection up to Layer 4 (Ethernet, IP, TCP, UDP, etc.)

    • IP fragment reassembly and TCP segment tracking

    • Fluent configuration via ProtocolStack and PacketPolicy

    Design Principles

    Principle	Implementation
    Packet-centric	Single packet at a time, synchronous processing
    Zero-allocation fast path	Pre-allocated headers, hasHeader() binding
    Single-threaded	No internal threading, user controls concurrency
    libpcap semantics	Familiar dispatch(), loop(), next() patterns
    L4 cap	Application layer (L5+) processing via jNetWorks

    Module Structure

    jnetpcap-sdk/
    ├── jnetpcap-api           High-level API: NetPcap, PacketHandler
    ├── jnetpcap-bindings      Low-level libpcap FFM bindings
    ├── sdk-protocol-core      Protocol infrastructure
    └── sdk-protocol-tcpip     TCP/IP protocol pack

    Module Descriptions

    Module	Description
    jnetpcap-api	User-facing API with NetPcap, Packet, PacketHandler
    jnetpcap-bindings	Direct libpcap bindings via Foreign Function API
    sdk-protocol-core	Core protocol interfaces, dissectors, descriptors
    sdk-protocol-tcpip	Ethernet, IPv4/IPv6, TCP, UDP, ICMP headers

    Why L2-L4 Only?

    jNetPcap intentionally limits protocol processing to Layers 2-4. This is a deliberate design decision aligned with the packet-centric nature of the libpcap API and typical use cases.

    Packet-Centric Model

    The libpcap model delivers individual packets via callbacks. Each packet is processed independently and synchronously within the callback scope. This model works well for:

    • Packet inspection and filtering

    • Header extraction and logging

    • Simple traffic analysis

    • Protocol statistics

    However, application-layer protocols (L5+) require fundamentally different processing:

    Requirement	Packet Model (L2-L4)	Stream Model (L5+)
    State	Stateless or simple flow tracking	Complex session state
    Reassembly	IP fragments, TCP segments	HTTP messages, TLS records
    Scope	Single packet	Multiple packets spanning time
    Output	Same packet, enriched	Higher-level objects (HTTP request, TLS session)
    Tokens	Attached to packet	Dedicated processing streams

    When to Use jNetWorks

    For application-layer protocol processing, jNetWorks provides the necessary infrastructure:

    Feature	jNetPcap	jNetWorks
    PacketStream	N/A	L2-L4 packets with full token support
    ProtocolStream	N/A	Higher-level protocol objects (TcpSegment, HttpRequest)
    DataStream	N/A	Reassembled application data
    TokenStream	Callback only	Dedicated stream for token processing
    Parallelism	Single-threaded	Multi-stream with hash distribution

    Example: HTTP Processing

    jNetPcap - Can see TCP packets but not HTTP structure:

    pcap.dispatch(count, packet -> {
        if (packet.hasHeader(tcp)) {
            // See raw TCP, but HTTP spans multiple packets
            // No way to reassemble HTTP request/response
        }
    });

    jNetWorks - Full HTTP object access:

    ProtocolStream<HttpMessage> http = net.createProtocolStream(stack, HttpMessage.class);
    
    while (http.isActive()) {
        HttpMessage message = http.take();
        try {
            if (message.isRequest()) {
                System.out.println(message.method() + " " + message.uri());
            }
            // Complete HTTP message, reassembled from TCP stream
        } finally {
            http.release(message);
        }
    }

    Token Processing

    jNetPcap delivers tokens via the packet callback, limiting what can be done:

    pcap.dispatch(count, packet -> {
        for (Token t : packet.tokens()) {
            // Must process synchronously, in callback
            // Cannot parallelize, cannot queue
        }
    });

    jNetWorks provides dedicated token streams for asynchronous processing:

    TokenStream tokens = net.createTokenStream(stack, IdsTokens.ALERTS);
    
    // Separate thread processes tokens
    while (tokens.isActive()) {
        Token token = tokens.take();
        try {
            alertSystem.process(token);  // Can be async, queued, parallel
        } finally {
            tokens.release(token);
        }
    }

    Summary

    Use jNetPcap for:

    • Packet capture and inspection

    • L2-L4 header analysis

    • Simple traffic monitoring

    • Development and debugging

    Use jNetWorks for:

    • Application-layer protocol analysis

    • High-speed production capture

    • Full TCP/TLS/HTTP reassembly

    • Token-based analysis pipelines

    Quick Example

    try (NetPcap pcap = NetPcap.openOffline("capture.pcap")) {
        
        Ip4 ip = new Ip4();
        Tcp tcp = new Tcp();
        
        pcap.dispatch(1000, packet -> {
            if (packet.hasHeader(ip) && packet.hasHeader(tcp)) {
                System.out.printf("%s:%d → %s:%d%n",
                    ip.src(), tcp.srcPort(),
                    ip.dst(), tcp.dstPort());
            }
        });
    }

    Architecture

    ┌─────────────────────────────────────────────────────────────────┐
    │                        User Application                          │
    ├─────────────────────────────────────────────────────────────────┤
    │                         jnetpcap-api                             │
    │     NetPcap, Packet, PacketHandler, ProtocolStack               │
    ├─────────────────────────────────────────────────────────────────┤
    │      sdk-protocol-core          │       sdk-protocol-tcpip      │
    │   Dissector, Descriptor, Header │   Ip4, Tcp, Udp, Ethernet     │
    ├─────────────────────────────────────────────────────────────────┤
    │                       jnetpcap-wrapper                           │
    │              libpcap FFM bindings (Pcap, PcapIf)                │
    ├─────────────────────────────────────────────────────────────────┤
    │                    libpcap / WinPcap / Npcap                     │
    └─────────────────────────────────────────────────────────────────┘

    Configuration with ProtocolStack

    ProtocolStack stack = new ProtocolStack();
    
    // Enable IP reassembly
    stack.setProtocol(new IpProtocol())
         .enableReassembly(true)
         .fragmentTimeout(30);
    
    // Configure packet policy
    stack.setPacketPolicy(PacketPolicy.zeroCopy())
         .descriptorType(DescriptorTypeInfo.NET);
    
    // Create capture with stack
    try (NetPcap pcap = NetPcap.create("en0", stack)) {
        pcap.dispatch(count, handler);
    }

    Comparison with jNetWorks

    Feature	jNetPcap	jNetWorks
    Backend	libpcap only	DPDK, Napatech, PCAP
    Throughput	~1-10 Gbps	Up to 800 Gbps
    Threading	Single-threaded	Multi-stream parallel
    Protocol depth	L2-L4	L2-L7+
    TCP reassembly	Basic	Full with flow tracking
    TLS decryption	No	Yes
    Use case	Development, low-speed capture	Production, high-speed capture

    Requirements

    • Java 22+ (for FFM API)

    • libpcap 1.10+ / Npcap 1.60+ / WinPcap 4.1.3

    • Linux, macOS, or Windows

    Maven Dependency

    <dependency>
        <groupId>com.slytechs.jnet.jnetpcap</groupId>
        <artifactId>jnetpcap-api</artifactId>
        <version>3.0.0</version>
    </dependency>

    Or use the starter POM for all modules:

    <dependency>
        <groupId>com.slytechs.jnet.jnetpcap</groupId>
        <artifactId>jnetpcap-sdk</artifactId>
        <version>3.0.0</version>
        <type>pom</type>
    </dependency>

    Next Steps

    • Getting Started - Installation and first capture

    • Packet Capture - Live and offline capture

    • Protocol Headers - Working with headers

    • ProtocolStack Configuration - Advanced configuration