PacketGen

PacketGen provides simple ways to generate, send and capture network packets.

Installation

PacketGen depends on PcapRub, which needs pcap development files to install. On Debian, you have to do:

sudo apt install libpcap-dev

Installation using RubyGems is then easy:

gem install packetgen

Or add it to a Gemfile:

gem 'packetgen'

Usage

Easily create packets

PacketGen.gen('IP')             # generate a IP packet object
PacketGen.gen('TCP')            # generate a TCP over IP packet object
PacketGen.gen('IP').add('TCP')  # the same
PacketGen.gen('Eth')            # generate a Ethernet packet object
PacketGen.gen('IP').add('IP')   # generate a IP-in-IP tunnel packet object

# Generate a IP packet object, specifying addresses
PacketGen.gen('IP', src: '192.168.1.1', dst: '192.168.1.2')

# get binary packet
PacketGen.gen('IP').to_s

Send packets on wire

# send Ethernet packet
PacketGen.gen('Eth', src: '00:00:00:00:00:01', dst: '00:00:00:00:00:02').to_w
# send IP packet
PacketGen.gen('IP', src: '192.168.1.1', dst: '192.168.1.2').to_w
# send forged IP packet over Ethernet
PacketGen.gen('Eth', src: '00:00:00:00:00:01', dst: '00:00:00:00:00:02').add('IP').to_w('eth1')
# send a IEEE 802.11 frame
PacketGen.gen('RadioTap').
          add('Dot11::Management', mac1: client, mac2: bssid, mac3: bssid).
          add('Dot11::DeAuth', reason: 7).
          to_w('wlan0')

Parse packets from binary data

packet = PacketGen.parse(binary_data)

Capture packets from wire

# Capture packets from first network interface, action from a block
PacketGen.capture do |packet|
  do_stuffs_with_packet
end

# Capture some packets, and act on them afterward
packets = PacketGen.capture(iface: 'eth0', max: 10)   # return when 10 packets were captured

# Use filters
packets = PacketGen.capture(iface: 'eth0', filter: 'ip src 1.1.1.2', max: 1)

Easily manipulate packets

# access header fields
pkt = PacketGen.gen('IP').add('TCP')
pkt.ip.src = '192.168.1.1'
pkt.ip(src: '192.168.1.1', ttl: 4)
pkt.tcp.dport = 80

# access header fields when multiple header of one kind exist
pkt = PacketGen.gen('IP').add('IP')
pkt.ip.src = '192.168.1.1'  # set outer src field
pkt.ip(2).src = '10.0.0.1'  # set inner src field

# test packet types
pkt = PacketGen.gen('IP').add('TCP')
pkt.is? 'TCP'   # => true
pkt.is? 'IP'    # => true
pkt.is? 'UDP'   # => false

# encapulsate/decapsulate packets
pkt2 = PacketGen.gen('IP')
pkt2.encapsulate pkt                   # pkt2 is now a IP/IP/TCP packet
pkt2.decapsulate(pkt2.ip)              # pkt2 is now inner IP/TCP packet

Read/write PcapNG files

# read a PcapNG file, containing multiple packets
packets = PacketGen.read('file.pcapng')
packets.first.udp.sport = 65535
# write only one packet to a PcapNG file
pkt.write('one_packet.pcapng')
# write multiple packets to a PcapNG file
PacketGen.write('more_packets.pcapng', packets)

Add custom header/protocol

Since v1.1.0, PacketGen permits adding your own header classes. First, define the new header class. For example:

module MyModule
 class MyHeader < PacketGen::Header::Base
   define_field :field1, PacketGen::Types::Int32
   define_field :field2, PacketGen::Types::Int32
 end
end

Then, class must be declared to PacketGen:

PacketGen::Header.add_class MyModule::MyHeader

Finally, bindings must be declared:

# bind MyHeader as IP protocol number 254 (needed by Packet#parse and Packet#add)
PacketGen::Header::IP.bind_header MyModule::MyHeader, protocol: 254

And use it:

pkt = Packet.gen('IP').add('MyHeader', field1: 0x12345678)
pkt.myheader.field2.read 0x01

Interactive console

PacketGen provides an interactive console: pgconsole.

In this console, context includes PacketGen module to give direct access to PacketGen classes. A special config object gives local network configuration:

$ pgconsole
pg(main)> config
=> #<PacketGen::Config:0x00559f27d2afe8
 @hwaddr="75:74:73:72:71:70",
 @iface="eth0",
 @ipaddr="192.168.0.2">
pg(main)> packets = capture(max: 5)
pg(main)> exit

If pry gem is installed, it is used as backend for pgconsole, else IRB is used.

Plugins

PacketGen provides a plugin system (see wiki).

Available plugins (available as gem) are:

packetgen-plugin-ipsec: add support for ESP and IKEv2 protocols. Before PacketGen3, these protocols were included in packetgen.
packetgen-plugin-smb: add support for SMB protocol suite.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/lemontree55/packetgen.

License

MIT License (see LICENSE)

Other sources

All original code maintains its copyright from its original authors and licensing.

packetgen

Runtime