Packet Batch (AF_XDP)

Description

Packet Batch is a collection of high-performance applications and tools designed for generating and sending network packets. It serves two main purposes: penetration testing, which involves assessing network security by simulating various attacks like Denial of Service (DoS); and network monitoring, which involves analyzing and inspecting network traffic.

Features

• The ability to send multiple network packets in a chain via sequences and multiple payloads inside of a single sequence coming from the same source.
• Support for sending from randomized source IPs within range(s) indicated by CIDR.
• Support for randomized payload data within a specific range in length.
• UDP, TCP, and ICMP layer 4 protocols supported.
• Optional layer 3 and 4 checksum calculation in the event you want the NIC's hardware to calculate checksums for generated outgoing packets.

Disclaimer

I do NOT support using these tools maliciously or as a part of a targeted attack. I've made these tools to perform penetration tests against my own firewalls along with occasionally debugging network issues such as packets not arriving to their destination correctly.

Showcase

These are just a couple of basic tests I performed between two virtual machines on my home server.

NOTE - Since the above demos, there was a change in Packet Batch that allows for more precise/randomized IPs/ports via seeding here (using the seed, nanoseconds since boot, instead of the UNIX timestamp which is shown above). Therefore, Packet Batch will now send from a more randomized IP/port than what is shown above!

AF_XDP

This is a special version of Packet Batch that utilizes AF_XDP sockets instead of AF_PACKETv3 (which is what the standard version uses). I recommend using this version over the standard version due to performance improvements, but you must keep in mind the following.

1. AF_XDP sockets require a more recent Linux kernel.
2. The TCP cooked and oneconnection settings are NOT available in this version due to no cooked sockets support in AF_XDP.

The above is why we aren't utilizing AF_XDP sockets in the standard version.

From the benchmarks I've concluded on my home server running Proxmox VMs, AF_XDP sockets send around 5 - 10% more packets per second than the standard version and the amount of packets per second it is sending is a lot more consistent (regardless of the batch size option explained below). I won't have solid benchmarks until I perform these tests on full dedicated hardware which should happen in early 2022.

Building And Installing

Building and installing this project is fairly easy and just like the standard version. It includes building the Packet Batch Common repository which requires JSON-C. As long as you use the --recursive flag with git, it should retrieve all of the required submodules automatically located in the modules/ directory. Otherwise, you will need to go into the Common repository and execute the git submodule update --init command. We use make to build and install the application.

The following commands should work for Ubuntu/Debian-based systems. However, you should be able to install this on other Linux distros with a few adjustments as well.

# Update apt.
sudo apt update

# Install Git if it isn't already installed.
sudo apt install -y git

# Clone this repository along with its submodules.
git clone --recursive https://github.com/Packet-Batch/PB-AF-XDP.git

# Install build essentials/tools and needed libaries for JSON-C.
sudo apt install -y build-essential clang cmake pkgconf

# Install LibELF for BPF.
sudo apt install -y libelf-dev

# Change the current working directory to PB-AF-XDP/.
cd PB-AF-XDP/

# Execute ./build.sh file to build and install dependencies and main project which requires sudo privileges.
# WARNING - If you don't have sudo available on your system, please look at the ./build.sh file and execute make commands as root in order.
# NOTE - You may also look at the .github/workflows/build.yml.
# NOTE - The first argument represents the amount of threads to use with make. 0 uses the amount of available threads on the system and supplying no argument uses 1 thread.
./build.sh 0

# You may use the following to clean the build. You must run this as root or sudo because of the Common's cleanup.
sudo make clean

Installation Video!

Warning! - The installation video is a bit outdated, but should show most of the installation process. Since the video was made, we've switched to json-c from libyaml and use a build script to build the project and its dependencies (./build.sh).

After installing, the executable is copied to the /usr/bin/ directory which should be included in your $PATH. Therefore, you may use the application globally (in any directory).

For example.

pcktbatch -c /path/to/conf.json

Command Line Usage

Basic

Basic command line usage may be found below.

Usage: pcktbatch -c <configfile> [-v -h]

-c --cfg => Path to the config file.
-l --list => Print basic information about sequences.
-v --verbose => Provide verbose output.
-h --help => Print out help menu and exit program.

First Sequence Override

If you wanted to quickly send packets and don't want to create a config file, you may specify command line options to override the first sequence. You must also specify the -z or --cli flag in order to do this.

The following command line options are available to override the first sequence.

-z --cli => Enables the first sequence/packet override.

--interface => The interface to send out of.    --block => Whether to enable blocking mode (0/1).       --track => Track packet and byte statistics and print at the end (0/1). Will impact performance!
--maxpckts => The maximum amount of packets to send during this sequence before exiting.
--maxbytes => The maximum amount of bytes to send during this sequence before exiting.
--pps => The amount of packets per second to limit this sequence to (0 = disabled).
--bps => The amount of bytes per second to limit this sequence to (0 = disabled)
--delay => The delay in-between sending packets on each thread.
--threads => The amount of threads and sockets to spawn (0 = CPU count).
--l4csum => Whether to calculate the layer-4 checksum (TCP, UDP, and ICMP) (0/1).

--smac => The ethernet source MAC address to use.
--dmac => The ethernet destination MAC address to use.

--minttl => The minimum IP TTL to use.
--maxttl => The maximum IP TTL to use.
--minid => The minimum IP ID to use.
--maxid => The maximum IP ID to use.
--sip => The source IP (one range is supported in CIDR format).
--dip => The destination IP.
--protocol => The protocol to use (TCP, UDP, or ICMP).
--tos => The IP TOS to use.
--l3csum => Whether to calculate the IP header checksum or not (0/1).

--usport => The UDP source port.
--udport => The UDP destination port.

--tsport => The TCP source port.
--tdport => The TCP source port.
--syn => Set the TCP SYN flag (0/1).
--ack => Set the TCP ACK flag (0/1).
--psh => Set the TCP PSH flag (0/1).
--rst => Set the TCP RST flag (0/1).
--fin => Set the TCP FIN flag (0/1).
--urg => Set the TCP URG flag (0/1).
--ece => Set the TCP ECE flag (0/1).
--cwr => Set the TCP CWR flag (0/1).

--pmin => The minimum payload data.
--pmax => The maximum payload data.
--pstatic => Use static payload (0/1).
--pexact => The exact payload string.
--pfile => Whether to parse a file as the 'pexact' string instead.
--pstring => Parse the 'pexact' string or file as a string instead of hexadecimal.

AF_XDP

There is additional command line usage with the AF_XDP version which may be found below.

--queue => If set, all AF_XDP/XSK sockets are bound to this specific queue ID.
--nowakeup => If set, all AF_XDP/XSK sockets are bound without the wakeup flag.
--sharedumem => If set, all AF_XDP/XSK sockets use the same UMEM area.
--batchsize => How many packets to send at once (default 1).
--forceskb => If set, all AF_XDP/XSK sockets are bound using the SKB flag instead of DRV mode.
--zerocopy => If set, all AF_XDP/XSK sockets are attempted to be bound with zero copy mode.
--copy => If set, all AF_XDP/XSK sockets are bound with copy mode.

NOTE - The batch size indicates how many packets to send at the same time, but this is the same packet data. This may or may not speed up performance, but personally I didn't see much of an impact.

NOTE - By default, each socket is created in a separate thread specified in the config and is bound to a separate queue ID (incremented by 1). With that said, shared UMEM is not supported by default and each socket has its own UMEM area. The XDP wakeup flag is also specified by default which should improve performance.

Configuration File

If you want to use more than one sequence or more control, you will need to specify sequences inside of a config file using the JSON syntax.

Before continuing, here is information on the types used below with the config.

Here is the full config file format.

{
    "interface": "devint",
    "sequences": [
        {
            ...
        },
        {
            ...
        }
    ]
}

Sequence Object

The sequence object has the following fields.

{
    "interface": "dev",
    "block": true,
    "time": 20,
    "delay": 100000,
    "eth": {
        ...
    },
    "ip": {
        ...
    },
    "tcp": {
        ...
    },
    "udp": {
        ...
    },
    "icmp": {
        ...
    },
    "payloads": [
        ...
    ]
}

{
    "interface": "dev",
    "block": true,
    "maxpckts": 3000,
    "time": 0,
    "delay": 0,
    "eth": {
        ...
    },
    "ip": {
        ...
    },
    "tcp": {
        ...
    },
    "udp": {
        ...
    },
    "icmp": {
        ...
    },
    "payloads": [
        ...
    ]
}

{
    "interface": "dev",
    "block": true,
    "pps": 300,
    "time": 0,
    "delay": 0,
    "eth": {
        ...
    },
    "ip": {
        ...
    },
    "tcp": {
        ...
    },
    "udp": {
        ...
    },
    "icmp": {
        ...
    },
    "payloads": [
        ...
    ]
}

Ethernet Object

The ethernet object contains the following fields.

{
    "smac": "09:EB:23:AB:2D:B1",
    "dmac": "08:EC:4B:23:F2:E3"
}

IP Object

The IP object contains the following fields.

{
    "sip": "192.168.2.2",
    "dip": "192.168.2.3",
    "protocol": "tcp",
    "csum": true,
    "ttl": {
        ...
    },
    "id": {
        ...
    },
    "ranges": [
        ...
    ]
}

{
    "sip": null,
    "dip": "10.3.0.2",
    "protocol": "udp",
    "csum": true,
    "ranges": [
        "10.4.0.0/24",
        "10.5.0.0/24"
    ]
}

TTL Object

The TTL object contains the following fields.

{
    "min": 64,
    "max": 128
}

ID Object

The ID object contains the following.

{
    "min": 4000,
    "max": 9000
}

TCP Object

The TCP object contains the following fields.

{
    "dport": 80,
    "syn": true
}

UDP Object

The UDP object contains the following.

{
    "sport": 27005,
    "dport": 27015
}

ICMP Object

The ICMP object contains the following fields.

{
    "code": 0,
    "type": 8
}

Payload Object

The payload object contains the following fields.

{
    "exact": "01 FB 02 FC"
}

{
    "length": {
        "min": 0,
        "max": 5
    }
}

{
    "exact": "./mypayload.txt",
    "isfile": true
}

{
    "exact": "GET / HTTP/1.0\r\nHost: 1.2.3.4\r\n\r\n",
    "isstring": true
}

Length Object

The length object contains the following fields.

If you are looking for full examples, please check out this repository.

NOTE - The default config path is /etc/pcktbatch/conf.json. This may be changed via the -c and --cfg flags as explained under the Command Line Usage section below.

Credits

• Christian Deacon