slytechs-repos / jnetpcap-wrapper

jNetPcap v2, a libpcap network packet capture using powerful Java API on Linux, Windows, Mac, etc..

jNetPcap Wrapper

Unlock Network Packet Analysis in Java with jNetPcap Wrapper

jNetPcap Wrapper is a libpcap java library. This is version 2 release of the popular jNetPcap library, previously hosted on SourceForge.net.

Overview

Harness the power of libpcap within your Java applications using jNetPcap Wrapper, a bridge that grants you seamless access to low-level network monitoring capabilities.

Key Features:

• Capture and Analyze Network Traffic: Intercept packets in real-time, delving into their contents for in-depth analysis and insights.
• Streamlined Integration: Effortlessly incorporate the library into your projects using dependency managers like Maven or by manually adding it to your classpath.
• Intuitive Java API: Interact with network data through a familiar Java interface, eliminating the need for complex native code.
• Packet Capture and Handling: Employ the Pcap class to initiate packet capture on a chosen network interface, and utilize PcapPacketHandler to process captured packets efficiently.
• Precise Packet Filtering: Implement granular filters to isolate specific packets based on criteria such as port numbers, protocols, or IP addresses, refining your analysis.

Key Steps to Get Started:

• Installation: Add jNetPcap Wrapper as a dependency in your Maven project's pom.xml file or download and manually integrate it into your classpath.
• Interface Selection: Instantiate a Pcap object, representing the network interface you intend to monitor.
• Packet Handling: Create a PcapPacketHandler instance to process captured packets as they arrive.
• Filtering (Optional): Craft filters to narrow down captured packets based on specific constraints using the library's filtering capabilities.

Unlock a Realm of Network Analysis Possibilities:

• Construct custom network monitoring tools.
• Develop sophisticated packet analyzers.
• Implement intrusion detection systems.
• Design network forensic tools.
• Conduct comprehensive network troubleshooting and optimization.

See Also

If you are looking for protocol enabled version of this library, please see the full jNetPcap SDK or for advanced functionality the jNetWorks SDK library.

Documentation

See Wiki pages for user guides and examples.

See Javadocs reference documentation.

Where are the protocols found in v1?

If you are looking for protocol support, same as it was available in v1, this functionality has been moved to other modules. In this way, jNetPcap Wrapper module's functionality is focused on providing accurate modeling of native libpcap APIs in java.

For protocols and familiar v1 APIs such as

Packet pack = ...;
Ip4 ip4 = new Ip4();
if (packet.hasHeader(ip4))
  System.out.printf("IPv4.version=%d%n", ip4.version());

please use jnetpcap-sdk module which extends that basic jNetPcap Wrapper API (ie. NetPcap extends Pcap) by providing additional protocol level features and API.

Note: The protocol definitions are in their own modules called protocol packs found in protocol-pack-sdk repository and maven artifacts.

Examples

To get started lets take a look at a couple of examples.

Capturing and transmitting packets is straight forward and easy out of the box.

Note! jNetPcap also provides many useful utilities to help in working with the data received, such as byte arrays to hex string, and hex string to byte array, and much more. More advanced utility packet handlers such as no-copy on capture, are provides as well and discussed in the Wiki pages.

Capture a Live Packet

This quick example demonstrates how to capture one or more packets from a live network.

void main() throws PcapException {
	int PACKET_COUNT = 1;
	List<PcapIf> devices = Pcap.findAllDevs();

	try (Pcap pcap = Pcap.create(devices.get(0))) {
		pcap.activate();

		pcap.loop(PACKET_COUNT, (String msg, PcapHeader header, byte[] packet) -> {

			System.out.println(msg);
			System.out.printf("Packet [timestamp=%s, wirelen=%-4d caplen=%-4d %s]%n",
					Instant.ofEpochMilli(header.toEpochMilli()),
					header.wireLength(),
					header.captureLength(),
					PcapUtils.toHexCurleyString(packet, 0, 6));

		}, "Hello World");
	}
}

Which produces the following output:

Hello World
Packet [timestamp=2011-03-01T20:45:13.266Z, wirelen=74   caplen=74   {00:26:62:2f:47:87}]

Transmit a Packet With Data-Link Header

This example demonstrates how to transmit a raw packet on a live network.

The packet we will transmit looks like this:

Frame 1: 74 bytes on wire (592 bits), 74 bytes captured (592 bits)
Ethernet II, Src: ASUSTekC_b3:01:84 (00:1d:60:b3:01:84), Dst: Actionte_2f:47:87 (00:26:62:2f:47:87)
Internet Protocol Version 4, Src: 192.168.253.5, Dst: 192.168.253.6
Transmission Control Protocol, Src Port: 57678 (57678), Dst Port: http (80), Seq: 0, Len: 0

We use Wireshark to convert a previously captured packet to a hex string (right click packet -> copy -> "... as a Hex Stream") and then jNetPcap's utility method PcapUtils.parseHexString() to further convert into a java byte array, which we send as a raw packet:

void main() throws PcapException {

	/* raw bytes of our packet, spaces ignored */
	final String ETHERNET = "0026622f4787 001d60b30184 0800";
	final String IPv4 = "4500003ccb5b4000400628e4 c0a8FD05 c0a8FD06";
	final String TCP = "e14e00508e50190100000000a00216d08f470000020405b40402080a0021d25a0000000001030307";
	final byte[] packetBytes = PcapUtils.parseHexString(ETHERNET + IPv4 + TCP);

	List<PcapIf> devices = Pcap.findAllDevs();

	try (Pcap pcap = Pcap.create(devices.get(0))) {
		pcap.activate();

		/* Transmit our packet */
		pcap.sendPacket(packetBytes);
	}
}

This example produces no output, but if you monitor the network, you will see our non-routable packet being sent from the example host.

Note! Pcap.inject() can also be used to transmit packets. We can also transmit data in ByteBuffer object, and a foreign native MemorySegment, all covered under advanced topics in wiki.

Statistics Snapshots

Our last example shows how to take statistic snapshots using Pcap API. The native libpcap library is able to capture statistics, even when our main thread is a sleep and only wakes up to take a snapshot of the current counters, store them in a PcapStat record and return them to our main thread. Then we simply print out the statistics structure values, sleep for 1 second and loop once again. For a total of 5 seconds or 5 loops.

void main() throws PcapException, InterruptedException {
	List<PcapIf> devices = Pcap.findAllDevs();

	try (Pcap pcap = Pcap.create(devices.get(0))) {
		pcap.activate();

		long secondsRemaining = 5;

		while (secondsRemaining-- > 0) {
			PcapStat stats = pcap.stats();

			System.out.println(stats);

			TimeUnit.SECONDS.sleep(1);
		}
	}
}

Produces the following output:

PcapStatRecord[recv=0, drop=0, ifdrop=0, capt=0, sent=0, netdrop=0]
PcapStatRecord[recv=137, drop=0, ifdrop=0, capt=0, sent=0, netdrop=0]
PcapStatRecord[recv=340, drop=0, ifdrop=0, capt=0, sent=0, netdrop=0]
PcapStatRecord[recv=477, drop=0, ifdrop=0, capt=0, sent=0, netdrop=0]
PcapStatRecord[recv=677, drop=0, ifdrop=0, capt=0, sent=0, netdrop=0]

How To Run The Examples

To run these exmamples the following command line arguments need to be added:

On Linux platforms (How to install libpcap on Linux)

-Djava.library.path=/usr/lib/x86_64-linux-gnu --enable-native-access=org.jnetpcap --enable-preview

On Windows platforms(How to install Npcap on Windows)

-Djava.library.path=C:\Windows\SysWOW64 --enable-native-access=org.jnetpcap --enable-preview

On MacOS platforms (native libpcap installed via Homebrew)

-Djava.library.path=/usr/local/Cellar/libpcap/${VERSION}/lib --enable-native-access=org.jnetpcap --enable-preview

On MacOS platforms (native libpcap installed via Mac Ports)

-Djava.library.path=/opt/local/lib --enable-native-access=org.jnetpcap --enable-preview

Note that the --enable-preview command line option is only required until Foreign Function feature becomes permanent, possibly in JDK 21 LTS.

For more examples

See the [wiki] pages. Project's unit tests are also a great source for usage examples of every single function in the module.

For extensive API usage examples, please see the dedicated jnetpcap-examples module.

Dependencies

jNetPcap library has no external java dependencies except for modules provided by the java runtime.

Java Dependencies for Module: org.jnetpcap

• No java dependencies except for standard java modules and the Foreign Function feature, currently in java preview (enabled with --enable-preview VM args option), but one which is expected to be a permanent feature, in the near future.

Native Library Dependencies

• The only native dependency is the native libpcap library itself, which has to be installed prior to jNetPcap module initializing. On Microsoft Windows platforms, install WinPcap or Npcap tools instead.

Installation

Here are several methods for installing jNetPcap software.

Maven Artifact Config

<dependency>
    <groupId>com.slytechs.jnet.jnetpcap</groupId>
    <artifactId>jnetpcap-wrapper</artifactId>
    <version>2.1.0</version>
</dependency>

Using the latest version number released to Maven Central

Download Release Package

Latest release: download link

Compile From Source

You will find instructions on how to compile from source on our Wiki Pages.

Contact

• [e-mail] for commercial and licensing questions
• jNetPcap Issue Tracker

Compatibility with jNetPcap version 1

There are API and license changes between version 1 and 2 of jNetPcap. Please see wiki home page for details.

Git Branches

So everyone is on the same page, we follow the following branching model.

Note 'main' branch replaces old 'master' branch references in document as per Github recommendation.