{"id":15029771,"url":"https://github.com/kaitoy/pcap4j","last_synced_at":"2025-05-15T01:04:18.586Z","repository":{"id":2066397,"uuid":"3005042","full_name":"kaitoy/pcap4j","owner":"kaitoy","description":"A Java library for capturing, crafting, and sending packets.","archived":false,"fork":false,"pushed_at":"2022-09-05T12:47:30.000Z","size":15231,"stargazers_count":1193,"open_issues_count":75,"forks_count":313,"subscribers_count":67,"default_branch":"v1","last_synced_at":"2025-04-06T17:09:52.322Z","etag":null,"topics":["capture-packets","java","java-library","jna","libpcap","npcap","pcap-library","sending-packets","winpcap"],"latest_commit_sha":null,"homepage":"https://www.pcap4j.org/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kaitoy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["kaitoy"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"custom":null}},"created_at":"2011-12-18T07:47:00.000Z","updated_at":"2025-04-04T07:48:22.000Z","dependencies_parsed_at":"2022-08-06T12:00:30.684Z","dependency_job_id":null,"html_url":"https://github.com/kaitoy/pcap4j","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaitoy%2Fpcap4j","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaitoy%2Fpcap4j/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaitoy%2Fpcap4j/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaitoy%2Fpcap4j/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaitoy","download_url":"https://codeload.github.com/kaitoy/pcap4j/tar.gz/refs/heads/v1","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248784957,"owners_count":21161207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["capture-packets","java","java-library","jna","libpcap","npcap","pcap-library","sending-packets","winpcap"],"created_at":"2024-09-24T20:11:36.150Z","updated_at":"2025-04-13T21:29:06.089Z","avatar_url":"https://github.com/kaitoy.png","language":"Java","funding_links":["https://github.com/sponsors/kaitoy"],"categories":["网络编程","Network"],"sub_categories":[],"readme":"[Japanese](/README_ja.md)\n\n\u003cimg alt=\"Pcap4J\" title=\"Pcap4J\" src=\"https://github.com/kaitoy/pcap4j/raw/v1/www/images/logos/pcap4j-logo-color.png\" width=\"70%\" style=\"margin: 0px auto; display: block;\" /\u003e\n\n[Logos](https://github.com/kaitoy/pcap4j/blob/v1/www/logos.md)\n\n[![Slack](http://pcap4j-slackin.herokuapp.com/badge.svg)](https://pcap4j-slackin.herokuapp.com/)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.pcap4j/pcap4j-distribution/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.pcap4j/pcap4j-distribution)\n\n[![Build Status](https://travis-ci.org/kaitoy/pcap4j.svg?branch=v1)](https://travis-ci.org/kaitoy/pcap4j)\n[![CircleCI](https://circleci.com/gh/kaitoy/pcap4j/tree/v1.svg?style=svg)](https://circleci.com/gh/kaitoy/pcap4j/tree/v1)\n[![Build status](https://ci.appveyor.com/api/projects/status/github/kaitoy/pcap4j?branch=v1\u0026svg=true)](https://ci.appveyor.com/project/kaitoy/pcap4j/branch/v1)\n[![Coverage Status](https://coveralls.io/repos/kaitoy/pcap4j/badge.svg)](https://coveralls.io/r/kaitoy/pcap4j)\n[![Code Quality: Java](https://img.shields.io/lgtm/grade/java/g/kaitoy/pcap4j.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/kaitoy/pcap4j/context:java)\n[![Total Alerts](https://img.shields.io/lgtm/alerts/g/kaitoy/pcap4j.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/kaitoy/pcap4j/alerts)\n\nPcap4J\n======\n\nPcap4J is a Java library for capturing, crafting and sending packets.\nPcap4J wraps a native packet capture library ([libpcap](http://www.tcpdump.org/),\n[WinPcap](http://www.winpcap.org/), or [Npcap](https://github.com/nmap/npcap)) via [JNA](https://github.com/twall/jna)\nand provides you Java-Oriented APIs.\n\nContents\n--------\n\n* [Download](#download)\n* [Why Pcap4J was born](#why-pcap4j-was-born)\n* [Features](#features)\n* [How to use](#how-to-use)\n    * [System requirements](#system-requirements)\n        * [Dependencies](#dependencies)\n        * [Platforms](#platforms)\n        * [Others](#others)\n    * [Documents](#documents)\n    * [How to run samples](#how-to-run-samples)\n    * [How to use in Maven project](#how-to-use-in-maven-project)\n    * [About native library loading](#about-native-library-loading)\n        * [WinPcap or Npcap](#winpcap-or-npcap)\n    * [Docker](#docker)\n* [How to build](#how-to-build)\n* [Contributing Code](#contributing-code)\n* [License](#license)\n* [Contacts](#contacts)\n\nDownload\n--------\n\nPcap4J is available on the Maven Central Repository.\n\n* Pcap4J 1.8.2\n    * without source: [pcap4j-distribution-1.8.2-bin.zip](http://search.maven.org/remotecontent?filepath=org/pcap4j/pcap4j-distribution/1.8.2/pcap4j-distribution-1.8.2-bin.zip)\n    * with    source: [pcap4j-distribution-1.8.2-src.zip](http://search.maven.org/remotecontent?filepath=org/pcap4j/pcap4j-distribution/1.8.2/pcap4j-distribution-1.8.2-src.zip)\n* Snapshot builds\n    * https://oss.sonatype.org/content/repositories/snapshots/org/pcap4j/pcap4j-distribution/\n\nWhy Pcap4J was born\n-------------------\nI have been developing an SNMP network simulator (SNeO, available at the link below) by Java,\nwhich needed to capture packets and I found the [pcap](http://en.wikipedia.org/wiki/Pcap) was useful for it.\nAlthough there are some implementations of the pcap such as libpcap (for UNIX) and WinPcap (for Windows),\nbecause they are both native libraries, a Java wrapper library was necessary in order to use them for SNeO.\nI researched it and found three Java wrapper libraries for pcap: [jpcap](http://jpcap.sourceforge.net/),\n[jNetPcap](http://jnetpcap.com/), and [Jpcap](http://netresearch.ics.uci.edu/kfujii/Jpcap/doc/).\nBut both jpcap and jNetPcap were unsuitable for SNeO because they seemed to be designed for mainly capturing packets\nand not to be useful for making and sending packets so much. On the other hand, Jpcap looked useful for\nmaking and sending packets. But it had a defect in capturing ICMP packets and\nits development seemed to be stopped long ago.\nThat's why I started developing Pcap4j.\n\nFeatures\n--------\n\n* Capturing packets via a network interface and converting them into Java objects.\n  You can get/set each field of a packet header via the Java object converted from the packet.\n  You can also craft a packet object from scratch.\n* Sending packet objects to a real network.\n* Supported protocols:\n    * Ethernet, Linux SLL, raw IP, PPP (RFC1661, RFC1662), BSD (Mac OS X) loopback encapsulation, and Radiotap\n    * IEEE 802.11\n        * Probe Request\n    * LLC and SNAP\n    * IEEE802.1Q\n    * ARP\n    * IPv4 (RFC791 and RFC1349) and IPv6 (RFC2460)\n    * ICMPv4 (RFC792) and ICMPv6 (RFC4443, RFC4861, and RFC6275)\n    * TCP (RFC793, RFC2018, and draft-ietf-tcpm-1323bis-21), UDP, and SCTP (only common header)\n    * GTPv1 (only GTP-U and GTP-C header)\n    * DNS (RFC1035, RFC3596, and RFC6844)\n* All built-in packet classes are serializable and thread-safe (practically immutable).\n* You can add a protocol support without modifying Pcap4J library itself.\n* Dumping and reading pcap-formatted files (e.g. a capture file of Wireshark).\n\nHow to use\n----------\n\n#### System requirements ####\n\n##### Dependencies #####\nPcap4j 1.1.0 or older needs Java 5.0+. Pcap4j 1.2.0 or newer needs Java 6.0+.\nAnd also a pcap native library (libpcap 1.0.0+, WinPcap 3.0+, or Npcap), jna, slf4j-api, and an implementation of logger for slf4j are required.\nI'm using the following libraries for the test.\n\n* libpcap 1.1.1\n* WinPcap 4.1.2\n* jna 5.1.0\n* slf4j-api 1.7.25\n* logback-core 1.0.0\n* logback-classic 1.0.0\n\n##### Platforms #####\nI tested Pcap4j on the following OSes with x86 or x64 processors.\n\n* Windows: XP, Vista, 7, [10](http://tbd.kaitoy.xyz/2016/01/12/pcap4j-with-four-native-libraries-on-windows10/), 2003 R2, 2008, 2008 R2, and 2012\n* Linux\n    * RHEL: 5, 6, and 7\n    * CentOS: 5, 6, and 7\n    * Ubuntu: 13\n* UNIX\n    * Solaris: 10\n    * FreeBSD: 10\n\nAnd tomute tested Pcap4j on Mac OS X. The report is [here](http://tomute.hateblo.jp/entry/2013/01/27/003209). Thank you, tomute!\n\nI hope Pcap4j can run on the other OSes supported by both JNA and libpcap.\n\n##### Others #####\nPcap4J needs administrator/root privileges.\nOr, if on Linux, you can run Pcap4J with a non-root user by granting capabilities `CAP_NET_RAW` and `CAP_NET_ADMIN`\nto your java command by the following command: `setcap cap_net_raw,cap_net_admin=eip /path/to/java`\n\n#### Documents ####\nThe latest JavaDoc is [here](https://www.javadoc.io/doc/org.pcap4j/pcap4j-distribution/1.8.2).\nEach version's JavaDoc is on the [Maven Central Repository](http://search.maven.org/#search|ga|1|g%3A%22org.pcap4j%22).\n\nRefer to [here](https://github.com/kaitoy/pcap4j/blob/v1/www/pcap4j_modules.md) for information about Pcap4J modules.\n\nBecause Pcap4J is a wrapper of a pcap native library, the following documents help you to understand how to use Pcap4J.\n\n* [Programming with pcap](http://www.tcpdump.org/pcap.html)\n* [WinPcap Manuals](http://www.winpcap.org/docs/default.htm)\n* [Mapping between pcap API and Pcap4J API](https://github.com/kaitoy/pcap4j/blob/v1/www/api_mappings.md)\n\nYou can learn how to write Pcap4J programs from [samples](https://github.com/kaitoy/pcap4j/tree/v1/pcap4j-sample/src/main/java/org/pcap4j/sample).\n\nLearn more about Pcap4j from the following documents:\n\n* [Learn about packet class](https://github.com/kaitoy/pcap4j/blob/v1/www/Packet.md)\n* [Learn about Packet Factory](https://github.com/kaitoy/pcap4j/blob/v1/www/PacketFactory.md)\n* [How to add protocol support](https://github.com/kaitoy/pcap4j/blob/v1/www/HowToAddProtocolSupport.md)\n* [kaitoy's blog](http://tbd.kaitoy.xyz/tags/pcap4j/)\n\n#### How to run samples ####\nSee the following examples:\n\n* [org.pcap4j.sample.Loop](https://github.com/kaitoy/pcap4j/blob/v1/www/sample_Loop.md)\n* [org.pcap4j.sample.SendArpRequest](https://github.com/kaitoy/pcap4j/blob/v1/www/sample_SendArpRequest.md)\n\nIf you want to run a sample in pcap4j-sample on Eclipse,\nadd pcap4j-packetfactory-static or pcap4j-packetfactory-propertiesbased project\nto the top of User Entries in Classpath tab of the Run Configuration for the sample.\n\n#### How to use in Maven project ####\nAdd a dependency to the pom.xml as like below:\n\n```xml\n\u003cproject xmlns=\"http://maven.apache.org/POM/4.0.0\"\n  xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n  xsi:schemaLocation=\"http://maven.apache.org/POM/4.0.0\n                      http://maven.apache.org/xsd/maven-4.0.0.xsd\"\u003e\n  ...\n  \u003cdependencies\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eorg.pcap4j\u003c/groupId\u003e\n      \u003cartifactId\u003epcap4j-core\u003c/artifactId\u003e\n      \u003cversion\u003e1.8.2\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eorg.pcap4j\u003c/groupId\u003e\n      \u003cartifactId\u003epcap4j-packetfactory-static\u003c/artifactId\u003e\n      \u003cversion\u003e1.8.2\u003c/version\u003e\n    \u003c/dependency\u003e\n       ...\n  \u003c/dependencies\u003e\n  ...\n\u003c/project\u003e\n```\n\n#### About native library loading ####\nBy default, Pcap4j loads the native libraries on the following conditions:\n\n* Windows\n    * search path: The paths in the `PATH` environment variable, etc. (See [MSDN](https://msdn.microsoft.com/en-us/library/7d83bc18.aspx) for the details.)\n    * file name: wpcap.dll and Packet.dll\n* Linux/UNIX\n    * search path: The search paths of shared libraries configured on the OS.\n      (e.g. The paths in the `LD_LIBRARY_PATH` environment variable)\n    * file name: libpcap.so\n* Mac OS X\n    * search path: The search paths of shared libraries configured on the OS.\n      (e.g. The paths in the `DYLD_LIBRARY_PATH` environment variable)\n    * file name: libpcap.dylib\n\nYou can use the following Java system properties to change the default behavior.\n\n* jna.library.path: The search path\n* org.pcap4j.core.pcapLibName: The full path of the pcap library (wpcap.dll, libpcap.so, or libpcap.dylib)\n* (Windows only) org.pcap4j.core.packetLibName: The full path of the packet library (Packet.dll)\n\n##### WinPcap or Npcap #####\nThere are two native pcap libraries for Windows; WinPcap and Npcap.\n\nThe development of WinPcap has stopped since version 4.1.3 (libpcap 1.0.0 base) was released on 3/8/2013,\nwhile Npcap is still being developed.\nSo, you should pick Npcap if you want to use new features or so.\n\nPcap4J can load WinPcap without tricks because it's installed in `%SystemRoot%\\System32\\`.\n\nOn the other hand, because Npcap is installed in `%SystemRoot%\\System32\\Npcap\\` by default,\nyou need to do either of the following so that Pcap4J can load it:\n\n* Add `%SystemRoot%\\System32\\Npcap\\` to `PATH`.\n* Set `jna.library.path` to `%SystemRoot%\\System32\\Npcap\\`.\n* Set `org.pcap4j.core.pcapLibName` to `%SystemRoot%\\System32\\Npcap\\wpcap.dll` and\n  `org.pcap4j.core.packetLibName` to `%SystemRoot%\\System32\\Npcap\\Packet.dll`.\n* Install Npcap with `WinPcap Compatible Mode` on.\n\n### Docker ###\n\n[![](https://images.microbadger.com/badges/image/kaitoy/pcap4j.svg)](https://microbadger.com/images/kaitoy/pcap4j)\n\nA Docker image for Pcap4J on CentOS is available at [Docker Hub](https://registry.hub.docker.com/u/kaitoy/pcap4j/).\n\nDownload it by `docker pull kaitoy/pcap4j` and execute `docker run kaitoy/pcap4j:latest` to start capturing packets from eth0 on the container.\n\nThis image is built everytime a commit is made on the Git repositry.\n\nHow to build\n------------\n\n1. Install libpcap, WinPcap, or Npcap:\n\n    Install WinPcap (if Windows) or libpcap (if Linux/UNIX).\n    It's needed for the unit tests which are run during a build.\n\n2. Install JDK:\n\n    Download and install JDK 9, 10, or 11, and set the environment variable ***JAVA_HOME*** properly.\n\n3. Add the JDK to [Maven toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html):\n\n    Create [toolchains.xml](https://maven.apache.org/ref/3.6.1/maven-core/toolchains.html) describing the JDK installed at the previous step and put it into `~/.m2/`.\n    `toolchains.xml` is like below:\n\n    ```xml\n    \u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n    \u003ctoolchains xmlns=\"http://maven.apache.org/TOOLCHAINS/1.1.0\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n      xsi:schemaLocation=\"http://maven.apache.org/TOOLCHAINS/1.1.0 http://maven.apache.org/xsd/toolchains-1.1.0.xsd\"\u003e\n      \u003ctoolchain\u003e\n        \u003ctype\u003ejdk\u003c/type\u003e\n        \u003cprovides\u003e\n          \u003cversion\u003e11\u003c/version\u003e\n        \u003c/provides\u003e\n        \u003cconfiguration\u003e\n          \u003cjdkHome\u003e/path/to/jdk-11\u003c/jdkHome\u003e\n        \u003c/configuration\u003e\n      \u003c/toolchain\u003e\n    \u003c/toolchains\u003e\n    ```\n\n4. Install Git:\n\n    Download [Git](http://git-scm.com/downloads) and install it.\n    This step is optional.\n\n5. Clone the Pcap4J repository:\n\n    If you installed Git, execute the following command: `git clone git@github.com:kaitoy/pcap4j.git`\u003cbr\u003e\n    Otherwise, download the repository as a [zip ball](https://github.com/kaitoy/pcap4j/zipball/v1) and extract it.\n\n6. Build:\n\n    Open a command prompt/a terminal, `cd` to the project root directory, and execute `./mvnw install`.\n    Note Administrator/root privileges are needed for the unit tests.\n\nContributing Code\n-----------------\n\n1. Fork this repository.\n2. Create a branch from v1 branch.\n3. Write code.\n\n    * Please refer to [This PR](https://github.com/kaitoy/pcap4j/pull/70) as an example when adding protocol support.\n    * This project follows [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). Execute the following command to format your code: `mvnw com.coveo:fmt-maven-plugin:format`\n\n4. Send a PR from the branch.\n\nLicense\n-------\n\n[LICENSE](/LICENSE)\n\nContacts\n--------\n\nKaito Yamada (kaitoy@pcap4j.org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaitoy%2Fpcap4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaitoy%2Fpcap4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaitoy%2Fpcap4j/lists"}