pktgen
is a packet generator which allows creating streams of network
packets using a declarative approach. Packet wrangling is done using Scapy,
making it possible to easily generate almost any kind of packet supported by
it.
Contents
- Support most of the packet types supported by Scapy.
- Additional elements which allow defining complex package sets.
- Define contents of packet flows in a declarative way (see spec file syntax below for an glimpse of the syntax).
- Output of packet streams to
pcap
dump files, the same format used bytcpdump
and supprted by many network tools which uselibpcap
.
The pktgen-localdeps
script can be used to run pktgen
with the
dependencies installed in a local virtualenv, which will be created in the
.env
subdirectory automatically. The script forwards the arguments to
pktgen
.
It is possible to specify which Python interpreter to use by defining the
PYTHON
environment variable:
PYTHON=/usr/local/bin/python2.7 ./pktgen-localdeps [...]
Packet generation spec files are written in the HiPack format, like in the following example:
# Comments span to the end of lines ip { .src "1.2.3.4" .dst "5.6.7.8" tcp { .flags = "" randbytes { .size 50 } } }
Items are interpreted in the following way:
- Blocks (HiPack dictionaries) describe an element.
- Keys starting with a period (e.g.
.flags
) are attributes of the element. - A key without a leading period (e.g.
tcp
) names the kind of the child element. - A number of elements map to their Scapy equivalents, and support all the attributes accepted their Scapy counterparts.
Generates payload for packets with fixed data
. The strings used to
specify the data may contain hex escapes, allowing to include any binary
data.
Example:
raw { .data "Unicode networked computers icon: \01\F5\A7 (U+1F5A7)" }
Packets with no payload can be created by using an empty string:
raw { .data "" }
Generates a payload of random bytes, of a given size
. Optionally it is
possible to specify a deviation
, which makes the size to be taken as an
average sample of a Gaussian distribution with the given deviation.
Example:
randbytes { .size 50 .deviation 10 }
Picks from several choices which have an associated probability of being chosen.
Example:
pdist [ { .probability 0.33, raw { .data "A" } } { .probability 0.66, raw { .data "B" } } ]
For each TCP/IP packet, yields each original packet followed by the corresponding ACK packet flowing in the opposite direction. Generated ACK packets have no payload.
The packets used as input for the tcpip-ack
element must have both
TCP and IP framing (both v4 and v6 are supported), as in the following
example:
tcpip-ack { ip { .src "1.2.3.4" .dst "6.7.8.9" tcp { .sport 80 .dport 32000 raw { .data "payload" } } } }
Element | Scapy constructor | Aliases |
ipv4 |
IP() |
ip , ip4 |
ipv6 |
IPv6() |
ip6 |
tcp |
TCP() |
ย |
A description of the additions on top of Scapy follows.
The tcp
element supports generating varying sequence numbers. This
is indicated by setting the .seq
attribute to a string value (instead
of a number) with the name of the method to use. The following methods
are supported:
increasing
- The sequence number is increased by one for each packet, starting from zero.
random
- The sequence number is a random number between 0 and 16386.
Example:
tcp { .seq "increasing" raw { .data "payload" } }