NAME¶

bittwiste -- pcap capture file editor

SYNOPSIS¶

bittwiste [ -I input ] [ -O output ] [ -L layer ] [ -X payload ] [ -C ] [ -M linktype ] [ -D offset ] [ -R range ] [ -S timeframe ] [ -N repeat ] [ -G gaprange ] [ -P seed ] [ -T header ] [ header-specific-options ] [ -h ]

DESCRIPTION¶

This document describes the bittwiste program, the pcap(3) capture file editor. Bittwiste is designed to work only with Ethernet frame, e.g. link type DLT_EN10MB in pcap(3), with a maximum frame size of 1514 bytes which is equivalent to an MTU of 1500 bytes, 14 bytes for Ethernet header.

Bittwiste can currently edit Ethernet, ARP, IPv4, IPv6, ICMPv4, ICMPv6, TCP, and UDP headers. IPv6 packets with extension headers or next header field not matching ICMPv6, TCP, or UDP are not supported; bittwiste will simply write such packets as is to output trace file as it encounters them in the input trace file.

If run with the -X flag, you can append your own payload after any of the supported headers; specified using the -L and -T flag. Bittwiste will, if not run with the -C flag, recalculate the checksums for IPv4, ICMPv4, ICMPv6, TCP, and UDP headers, except for the last fragment of a fragmented IPv4 datagram; bittwiste does not currently support checksum correction for the last fragment of a fragmented IPv4 datagram.

While parsing the packets in an input trace file, bittwiste will skip, i.e. write to output trace file as is, any truncated packet, for example, an ICMPv4 packet with a captured length of 25 bytes (we need at least 28 bytes; 14 bytes for Ethernet header, minimum 20 bytes for IP header, and 4 bytes for ICMPv4 header) does not give enough information on its ICMPv4 header for bittwiste to read and modify it. In this case, you can utilize the -L and -T flag to copy the original packet up to its IP header and append your customized ICMPv4 header and data to the packet using the -X flag. When specifying payload that covers the ICMPv4, ICMPv6, TCP, or UDP header and its data, you can use zeros, e.g. 0000 for 2 bytes of zeros, for the header checksum which is then corrected automatically by bittwiste.

In order to simplify the way options are specified, you can only edit packets of a specific type supplied to the -T flag per execution of bittwiste on an input trace file. In addition, the -T flag must appear last among the general options which are the -I, -O, -L, -X, -C, -M, -D, -R, -S, -N, -G, and -P flag.

OPTIONS¶

-I input

Input pcap based trace file. Typically, input should be a file path to a pcap based trace file. However, for convenience, the following template names are also accepted to load trace file from one of the built-in templates:

eth : Ethernet header
arp : ARP header
ip : IPv4 header
ip6 : IPv6 header
icmp : ICMPv4 header
icmp6 : ICMPv6 header
tcp : IPv4 TCP header
ip6tcp : IPv6 TCP header
udp : IPv4 UDP header
ip6udp : IPv6 UDP header

Example: -I icmp

-O output

Output trace file.

-L layer

Copy up to the specified layer and discard the remaining data. Value for layer must be either 2, 3, or 4 where 2 for Ethernet, 3 for ARP, IPv4, or IPv6, and 4 for ICMPv4, ICMPv6, TCP, or UDP.

-X payload

Append payload in hex digits to the end of each packet.
Example: -X 0302aad1
-X flag is ignored if -L and -T flag are not specified.

-C

Specify this flag to disable checksum correction. Checksum correction is applicable for non-fragmented supported packets only.

-M linktype

Replace the linktype stored in the pcap file header. Typically, value for linktype is 1 for Ethernet.
Example: -M 12 (for raw IP), -M 51 (for PPPoE)

For the complete list, see:
https://www.tcpdump.org/linktypes.html

-D offset

Delete the specified byte offset from each packet.
First byte (starting from link layer header) starts from 1.
-L, -X, -C and -T flag are ignored if -D flag is specified.
Example: -D 15-40, -D 10, or -D 18-9999

-R range

Save only the specified range of packets.
Example: -R 5-21 or -R 9

-S timeframe

Save only the packets within the specified timeframe with up to one-second resolution using DD/MM/YYYY,HH:MM:SS as the format for start and end time in timeframe.
Example: -S 22/10/2006,21:47:35-24/10/2006,13:16:05
-S flag is evaluated after -R flag.

-N repeat

Duplicate packets from the input trace file repeat times. Use this flag to create a stream of packets, each with, for example, a random tcp sequence number, from a 1-packet trace file.
Example: -N 100000
-N flag is evaluated after -R and -S flag.

-G gaprange

Apply inter-packet gap between packets in microseconds from 1 to (2^31 - 1). Values in gaprange are inclusive and selected randomly. A single value implies a fixed gap.
Example: -G 1000-10000 or -G 1000
-G flag is evaluated after -R, -S, and -N flag.

-P seed

Positive integer to seed the random number generator (RNG) used, for example, to generate random port number. If unset, current timestamp will be used as the RNG seed.

bittwiste uses Mersenne Twister for high-speed uniformly distributed random number generation.

-T header

Edit only the specified header. Possible keywords for header are, eth, arp, ip, ip6, icmp, icmp6, tcp, or udp. -T flag must appear last among the general options.

-h

Print version information and usage.

header-specific-options

Each packet that matches the type supplied to the -T flag is modified based on the options described below:

Options for eth (RFC 894):

SEE ALSO¶

bittwist(1), pcap(3), tcpdump(1)

BUGS¶

File your bug report and send to:

Addy Yeow <ayeowch@gmail.com>

Make sure you are using the latest stable version before submitting your bug report.

When running bittwiste with both the -N and -G flags, large inter-packet gap may result in the packet timestamp beyond Unix epoch 2147483647 (2038-01-19 03:14:07 UTC) to overflow. This is due to the use of signed 32-bit integer to store timestamp in pcap(3) header. Simply changing the data type, e.g. using unsigned 64-bit integer, would break the compatibility of the output trace file with existing systems.

The workaround built into bittwiste is to use Unix epoch 946684800 (2020-01-01 00:00:00 UTC) as the starting reference timestamp when -G flag is specified. This translates to a maximum timespan of 38 years or 559165 packets in the output trace file when using the maximum inter-packet gap, i.e. -G 2147483647.

COPYRIGHT¶

Copyright (C) 2006 - 2023 Addy Yeow <ayeowch@gmail.com>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

AUTHORS¶

Original author and current maintainer:

Addy Yeow

The current version is available from https://bittwist.sourceforge.io