stephengroat / packetfu

PacketFu, a mid-level packet manipulation library for Ruby

PacketFu

A library for reading and writing packets to an interface or to a libpcap-formatted file.

It is maintained here.

Setup

To install the gem, type

gem install packetfu

To install from source, type

gem install bundler
git clone https://github.com/packetfu/packetfu.git
cd packetfu
bundle install

Quick Start

The best way to test your installation is by using packetfu-shell, like so

$ rvmsudo ruby examples/packetfu-shell.rb
 _______  _______  _______  _        _______ _________ _______
(  ____ )(  ___  )(  ____ \| \    /\(  ____ \\__   __/(  ____ \|\     /|
| (    )|| (   ) || (    \/|  \  / /| (    \/   ) (   | (    \/| )   ( |
| (____)|| (___) || |      |  (_/ / | (__       | |   | (__    | |   | |
|  _____)|  ___  || |      |   _ (  |  __)      | |   |  __)   | |   | |
| (      | (   ) || |      |  ( \ \ | (         | |   | (      | |   | |
| )      | )   ( || (____/\|  /  \ \| (____/\   | |   | )      | (___) |
|/       |/     \|(_______/|_/    \/(_______/   )_(   |/       (_______)
 ____________________________              ____________________________
(                            )            (                            )
| 01000001 00101101 01001000 )( )( )( )( )( 00101101 01000001 00100001 |
|                            )( )( )( )( )(                            |
(____________________________)            (____________________________)
                               PacketFu
             a mid-level packet manipulation library for ruby

>>> PacketFu Shell 1.1.12.
>>> Use $packetfu_default.config for salient networking details.
IP:  192.168.0.100   Mac: ac:bc:32:85:47:3f   Gateway: ec:08:6b:62:bc:d2
Net: 192.168.0.0                              Iface:   en0
>>> Packet capturing/injecting enabled.
<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>
2.3.0 :001 >

Once you're a this point, you're in an IRB (aka: REPL) interface when you can start creating and injection packets with PacketFu.

Here's an example of creating a TCPPacket and sending it out on the wire:

2.3.0 :002 > packet = TCPPacket.new(:config => Utils.whoami?)
 => --EthHeader-------------------------------------------
  eth_dst      ec:08:6b:62:bc:d2 PacketFu::EthMac
  eth_src      ac:bc:32:85:47:3f PacketFu::EthMac
  eth_proto    0x0800            StructFu::Int16
--IPHeader--------------------------------------------
  ip_v         4                 Integer
  ip_hl        5                 Integer
  ip_tos       0                 StructFu::Int8
  ip_len       20                StructFu::Int16
  ip_id        0x77e4            StructFu::Int16
  ip_frag      0                 StructFu::Int16
  ip_ttl       32                StructFu::Int8
  ip_proto     6                 StructFu::Int8
  ip_sum       0xffff            StructFu::Int16
  ip_src       192.168.0.100     PacketFu::Octets
  ip_dst       0.0.0.0           PacketFu::Octets
--TCPHeader-------------------------------------------
  tcp_src      42653             StructFu::Int16
  tcp_dst      0                 StructFu::Int16
  tcp_seq      0x8d65fbbf        StructFu::Int32
  tcp_ack      0x00000000        StructFu::Int32
  tcp_hlen     5                 PacketFu::TcpHlen
  tcp_reserved 0                 PacketFu::TcpReserved
  tcp_ecn      0                 PacketFu::TcpEcn
  tcp_flags    ......            PacketFu::TcpFlags
  tcp_win      16384             StructFu::Int16
  tcp_sum      0x7f29            StructFu::Int16
  tcp_urg      0                 StructFu::Int16
  tcp_opts                       PacketFu::TcpOptions

2.3.0 :003 > packet.ip_dst = "8.8.8.8"
 => "8.8.8.8"
2.3.0 :004 > packet.tcp_dst = 53
 => 53
2.3.0 :005 > packet.to_w
 => [1, 1, 54]

Documentation

PacketFu is yard-compatible (as well as sdoc/rdoc, if you prefer). You can generate local documentation easily with either yard doc . or sdoc, and view doc/index.html with your favored browser. Once that's done, navigate at the top, and read up on how to create a Packet or Capture from an interface with show_live or whatever.

Supported Rubies

This project is integrated with travis-ci and is regularly tested to work with the following rubies:

To checkout the current build status and what rubies we're currently supporting, click here.

Supported OSs

This project is designed for use on Linux (Ubuntu|RHEL|BSD primarily) and OSX platforms and it is the intention of the PacketFu team to support those OSs to ensure PacketFu runs on them. That said, PacketFu can and has been known to run on Windows as well as other unix-style platforms, but it's not actively supported in the sense that we may help from the community to help fill that gap. If that is something you are interested in helping with, we welcome your support.

Authors

PacketFu is maintained primarily by Tod Beardsley [email protected] and Jonathan Claudius [email protected], with help from Open Source Land.

See LICENSE for licensing details.