README.md

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 <command> -<arg_1> <value_1> ... -<arg_n> <value_n>. 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

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

git clone git@github.com:YOUR-USERNAME/netdump.git
cd netdump

3. Create a new branch

git checkout -b your-branch-name

4. Make your changes and push

Make your improvements or bug fixes than commit and push.

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