https://github.com/giorgiopapini/netdump
A simple network packet analyzer using libpcap, supporting both real-time and offline analysis with ASCII visualization.
https://github.com/giorgiopapini/netdump
Last synced: 17 days ago
JSON representation
A simple network packet analyzer using libpcap, supporting both real-time and offline analysis with ASCII visualization.
- Host: GitHub
- URL: https://github.com/giorgiopapini/netdump
- Owner: giorgiopapini
- License: gpl-3.0
- Created: 2024-09-23T06:12:58.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-28T13:42:43.000Z (5 months ago)
- Last Synced: 2025-06-28T14:36:37.836Z (5 months ago)
- Language: C
- Homepage:
- Size: 27.6 MB
- Stars: 20
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cli-apps-in-a-csv - netdump - A simple network packet analyzer using libpcap, supporting both real-time and offline analysis with ASCII visualization. (<a name="networking"></a>Networking)
- awesome-cli-apps - netdump - A simple network packet analyzer using libpcap, supporting both real-time and offline analysis with ASCII visualization. (<a name="networking"></a>Networking)
README
## What is netdump?
Based on libpcap and completely built in C, netdump is a free and open-source network protocol analizer.
netdump is designed to cater to users with varying levels of expertise and backgrounds. It achieves this by providing an easy-to-use CLI tool, along with a straightforward netdump-devel package. This setup is ideal for users who need to analyze industry-specific protocols, those interested in building their own dissector implementations, and also for people who simply want to scan a network or a .pcap file.
Disclaimer: netdump is entirely independent and unrelated to any other programs named "netdump" or similar.
## Makefile configuration
At this time, support is limited to GNU Make only.
Check the default Makefile variable configuration using ```make show-config```.
If your system stores those files in different locations, you can run ```make install VARIABLE_NAME='/path/'```
Remember that these commands might need to be run with elevated privileges.
## Installation
Netdump can be executed on Unix-like operating systems conforming to the POSIX standard. It can be installed manually using make, or installed by using a package manager (RPM on Fedora, CentOS and RHEL).
You can install netdump in several ways depending on your goal:
1) Clone the repo and compile the program using ```make```.
2) Clone the repo and install the program inside ```/usr/local/bin``` by running ```make install```.
3) Install the program inside ```/usr/bin``` by using a package manager.
## Running netdump
There are several methods to execute netdump based upon the installation process you chose:
1) Execute ```./netdump``` if you just compiled the program using ```make```.
2) Execute ```/usr/local/bin/netdump``` (or ```netdump```) if you installed the program using ```make install```.
3) Execute ```netdump``` if you installed it using a package manager.
Some features, such as real-time network scanning, require netdump to be run with elevated privileges.
## Remove netdump
You can remove netdump from your system in several ways:
1) Execute ```make remove``` if you previously installed netdump using ```make install```.
2) Uninstall netdump using the package manager you used to install it.
Remember that these commands might need to be run with elevated privileges.
## Netdump commands
The general command format is this ```netdump - ... - ```.
Run the ```help``` command from anywhere inside the CLI tool to get a small doc about every command and its supported arguments.
Strings should be enclosed in "" to prevent netdump from misinterpreting uppercase letters, -, and other symbols.
### ```analyze```
This command is used to scan incoming and outgoing network traffic for a selected device.
The following table lists the allowed arguments for this command.
| Arg | Value | Description |
|--------|------------|---------|
| `-n` | int | Set a packet scanning limit |
| `-filter` | str | Filter packets (based upon libpcap's filter function) |
| `-dev` | str | Select an avaliable device for scanning network traffic |
| `-e` | none | Show datalink layer protocol header |
| `-nnet` | none | Don't show network layer protocol header |
| `-t` | none | Show transport layer protocol header |
| `-a` | none | Show application layer protocol header |
| `-nprom` | none | Turn off libpcap promiscuos mode |
| `-ntime` | none | Hide timestamp |
| `-npname` | none | Hide protocol name in the output |
| `-pktnum` | none | Show packet number |
| `-r` | str | Read a .pcap file |
| `-w` | str | Write a .pcap file with all the scanned packets |
### ```print```
This command is used to display detailed informations for a specific packet.
The following table lists the allowed arguments for this command.
| Arg | Value | Description |
|--------|------------|---------|
| `-n` | int | Choose a packet by its scanning order number |
| `-e` | none | Show datalink layer protocol header |
| `-nnet` | none | Don't show network layer protocol header |
| `-t` | none | Show transport layer protocol header |
| `-a` | none | Show application layer protocol header |
| `-ntime` | none | Hide timestamp |
| `-npname` | none | Hide protocol name in the output |
| `-output` | (std, raw, art) | Select output format |
| `-pktnum` | none | Show packet number |
### ```dissectors```
This command is used to manage custom dissectors.
The following table lists the allowed arguments for this command.
| Arg | Value | Description |
|--------|------------|---------|
| `-list` | none | Show custom dissectors list |
| `-add` | str | Add custom dissector |
| `-on` | str | Activate custom dissector (empty = all) |
| `-off` | str | Deactivate custom dissector (empty = all) |
## ```protocols```
This command is used to retrieve a list of supported protocols.
The following table lists the allowed arguments for this command.
| Arg | Value | Description |
|--------|------------|---------|
| `-tables` | none | Show supported protocol tables |
| `-from` | str | Show supported protocols from the specified tables |
| `-search` | int | Looks up a protocol by number. If 'from' is set, the search is limited to the specified tables |
### ```save```
This command is used to save scanned packets to a .pcap file.
The following table lists the allowed arguments for this command.
| Arg | Value | Description |
|--------|------------|---------|
| `-to` | str | Specify the destination file for saving scanned data |
| `-n` | int | Choose the single packet to save by its scanning order number |
### ```scantree```
This command is used to obtain the hierarchical structures of the protocols currently being scanned.
### ```reset```
This command is used to reset stored packets.
### ```devlist```
This command is used to retrieve a list of all available devices for scanning.
### ```clear```
This command is used to clear screen output.
### ```exit```
This command is used to exit program.
## Adding custom dissectors
To create a custom dissector, refer to the ```netdump-devel``` repo (https://github.com/giorgiopapini/netdump-devel).
The ```netdump-devel``` package allows you to compile your custom dissector as a shared library. Once compiled as a shared lib, you can add it to netdump using the following command:
```netdump dissectors -add "path-to-dissector.so"``` (.so if your system is Linux or *BSD. Otherwise, adjust it according to your system).
## Benchmark
I compared netdump with tcpdump in terms of speed, and these are the results I obtained (I disabled hostname resolution in tcpdump to make it faster).
The following are some of the comparisons I made. For others, check the assets folder.
However, the problem is that netdump does not support the extensive range of protocols that tcpdump does. Therefore, I focused on measuring TCP packets by adding "dummy" protocol handlers to the proto_tables that netdump queries while dissecting a TCP packet.
The result is still amazing.
[Watch the video](https://raw.githubusercontent.com/giorgiopapini/netdump/assets/assets/netdump_benchmark.mp4)
## Contributing
Contributions are welcome and really appreciated. To increase the popularity and usefulness of netdump, support for additional protocols is highly encouraged. Contributions of new protocol dissectors are especially welcome and appreciated, though all types of contributions are valued.
The following is a quick start guide explaining how to practically contribute to the project:
### 1. Fork the repo
Click the fork button to create your own fork of the project
### 2. Clone your own fork
```bash
git clone git@github.com:YOUR-USERNAME/netdump.git
cd netdump
```
### 3. Create a new branch
```bash
git checkout -b your-branch-name
```
### 4. Make your changes and push
Make your improvements or bug fixes than commit and push.
```bash
git add .
git commit -m "Describe your changes precisely"
git push origin your-branch-name
```
### 5. Submit a Pull Request
Go to the original repository and open a pull request from your fork.
## Screenshots
