### Home Classes Methods

### In Files

- lib/packetfu/pcap.rb

### Parent

Struct.new(:endian, :head, :body)

### Methods

- ::file_to_array
- ::new
- ::read
- ::read_packet_bytes
- ::read_packets
- #a2f
- #a2f!
- #append
- #array_to_file
- #array_to_file!
- #clear
- #f2a
- #file_to_array
- #init_fields
- #read
- #read!
- #read_packet_bytes
- #read_packets
- #readfile
- #to_f
- #to_file
- #to_s
- #write

### Included Modules

- StructFu

### Files

- .document
- README.rdoc

### Class/Module Index

Quicksearch

- PacketFu
- PacketFu::ARPHeader
- PacketFu::ARPHeaderMixin
- PacketFu::ARPPacket
- PacketFu::AddrIpv6
- PacketFu::Capture
- PacketFu::Config
- PacketFu::EthHeader
- PacketFu::EthHeaderMixin
- PacketFu::EthMac
- PacketFu::EthNic
- PacketFu::EthOui
- PacketFu::EthPacket
- PacketFu::HSRPHeader
- PacketFu::HSRPHeaderMixin
- PacketFu::HSRPPacket
- PacketFu::ICMPHeader
- PacketFu::ICMPHeaderMixin
- PacketFu::ICMPPacket
- PacketFu::IPHeader
- PacketFu::IPHeaderMixin
- PacketFu::IPPacket
- PacketFu::IPv6Header
- PacketFu::IPv6HeaderMixin
- PacketFu::IPv6Packet
- PacketFu::Inject
- PacketFu::InvalidHeader
- PacketFu::InvalidPacket
- PacketFu::LLDPHeader
- PacketFu::LLDPHeaderMixin
- PacketFu::LLDPPacket
- PacketFu::Octets
- PacketFu::Packet
- PacketFu::PcapFile
- PacketFu::PcapHeader
- PacketFu::PcapPacket
- PacketFu::PcapPackets
- PacketFu::Read
- PacketFu::TCPHeader
- PacketFu::TCPHeaderMixin
- PacketFu::TCPPacket
- PacketFu::TcpEcn
- PacketFu::TcpFlags
- PacketFu::TcpHlen
- PacketFu::TcpOption
- PacketFu::TcpOption::ECHO
- PacketFu::TcpOption::ECHOREPLY
- PacketFu::TcpOption::EOL
- PacketFu::TcpOption::MSS
- PacketFu::TcpOption::NOP
- PacketFu::TcpOption::SACK
- PacketFu::TcpOption::SACKOK
- PacketFu::TcpOption::TS
- PacketFu::TcpOption::WS
- PacketFu::TcpOptions
- PacketFu::TcpReserved
- PacketFu::Timestamp
- PacketFu::UDPHeader
- PacketFu::UDPHeaderMixin
- PacketFu::UDPPacket
- PacketFu::Utils
- PacketFu::Write
- StructFu
- StructFu::Int
- StructFu::Int16
- StructFu::Int16be
- StructFu::Int16le
- StructFu::Int32
- StructFu::Int32be
- StructFu::Int32le
- StructFu::Int8
- StructFu::IntString
- StructFu::String
- Struct

No matching classes.

# PacketFu::PcapFile

PcapFile is a complete libpcap file struct, made up of two elements, a PcapHeader and PcapPackets.

See wiki.wireshark.org/Development/LibpcapFileFormat

PcapFile also can behave as a singleton class, which is usually the better way to handle pcap files of really any size, since it doesn't require storing packets before handing them off to a given block. This is really the way to go.

### Public Class Methods

file_to_array(fname) click to toggle source

Takes a given file and returns an array of the packet bytes. Here for backwards compatibilty.

    # File lib/packetfu/pcap.rb, line 243
    def file_to_array(fname)
            PcapFile.new.file_to_array(:f => fname)
    end

new(args={}) click to toggle source

    # File lib/packetfu/pcap.rb, line 321
    def initialize(args={})
            init_fields(args)
            @filename = args.delete :filename
            super(args[:endian], args[:head], args[:body])
    end

read(fname,&block) click to toggle source

Takes a given file name, and reads out the packets. If given a block, it will yield back a PcapPacket object per packet found.

    # File lib/packetfu/pcap.rb, line 249
    def read(fname,&block)
            file_header = PcapHeader.new
            pcap_packets = PcapPackets.new
            unless File.readable? fname
                    raise ArgumentError, "Cannot read file `#{fname}'"
            end
            begin
            file_handle = File.open(fname, "rb")
            file_header.read file_handle.read(24)
            packet_count = 0
            pcap_packet = PcapPacket.new(:endian => file_header.endian)
            while pcap_packet.read file_handle.read(16) do
                    len = pcap_packet.incl_len
                    pcap_packet.data = StructFu::String.new.read(file_handle.read(len.to_i))
                    packet_count += 1
                    if pcap_packet.data.size < len.to_i
                            warn "Packet ##{packet_count} is corrupted: expected #{len.to_i}, got #{pcap_packet.data.size}. Exiting."
                            break
                    end
                    if block
                            yield pcap_packet
                    else
                            pcap_packets << pcap_packet.clone
                    end
            end
            ensure
                    file_handle.close
            end
            block ? packet_count : pcap_packets
    end

read_packet_bytes(fname,&block) click to toggle source

Takes a filename, and an optional block. If a block is given, yield back the raw packet data from the given file. Otherwise, return an array of parsed packets.

    # File lib/packetfu/pcap.rb, line 283
    def read_packet_bytes(fname,&block)
            count = 0
            packets = [] unless block
            read(fname) do |packet|
                    if block
                            count += 1
                            yield packet.data.to_s
                    else
                            packets << packet.data.to_s
                    end
            end
            block ? count : packets
    end

Also aliased as: file_to_array
read_packets(fname,&block) click to toggle source

Takes a filename, and an optional block. If a block is given, yield back parsed packets from the given file. Otherwise, return an array of parsed packets.

This is a brazillian times faster than the old methods of extracting packets from files.

    # File lib/packetfu/pcap.rb, line 305
    def read_packets(fname,&block)
            count = 0
            packets = [] unless block
            read_packet_bytes(fname) do |packet|
                    if block
                            count += 1
                            yield Packet.parse(packet)
                    else
                            packets << Packet.parse(packet)
                    end
            end
            block ? count : packets
    end

### Public Instance Methods

a2f(args={}) click to toggle source
Alias for: array_to_file
a2f!(arr) click to toggle source
Alias for: array_to_file!
append(filename='out.pcap') click to toggle source

Shorthand method for appending to a file. Can take either :file => 'name.pcap' or simply 'name.pcap'

    # File lib/packetfu/pcap.rb, line 496
    def append(filename='out.pcap')
            if filename.kind_of?(Hash)
                    f = filename[:filename] || filename[:file] || filename[:f] || 'out.pcap'
            else
                    f = filename.to_s
            end
            self.to_file(:filename => f, :append => true)
    end

array_to_file(args={}) click to toggle source

Takes an array of packets (as generated by file_to_array), and writes them to a file. Valid arguments are:

    :filename
    :array      # Can either be an array of packet data, or a hash-value pair of timestamp => data.
    :timestamp  # Sets an initial timestamp
    :ts_inc     # Sets the increment between timestamps. Defaults to 1 second.
    :append     # If true, then the packets are appended to the end of a file.

    # File lib/packetfu/pcap.rb, line 406
    def array_to_file(args={})
            if args.kind_of? Hash
                    filename = args[:filename] || args[:file] || args[:f]
                    arr = args[:array] || args[:arr] || args[:a]
                    ts = args[:timestamp] || args[:ts] || Time.now.to_i
                    ts_inc = args[:timestamp_increment] || args[:ts_inc] || 1
                    append = !!args[:append]
            elsif args.kind_of? Array
                    arr = args
                    filename = append = nil
            else
                    raise ArgumentError, "Unknown argument. Need either a Hash or Array."
            end
            unless arr.kind_of? Array
                    raise ArgumentError, "Need an array to read packets from"
            end
            arr.each_with_index do |p,i|
                    if p.kind_of? Hash # Binary timestamps are included
                            this_ts = p.keys.first
                            this_incl_len = p.values.first.size
                            this_orig_len = this_incl_len
                            this_data = p.values.first
                    else # it's an array
                            this_ts = Timestamp.new(:endian => self[:endian], :sec => ts + (ts_inc * i)).to_s
                            this_incl_len = p.to_s.size
                            this_orig_len = this_incl_len
                            this_data = p.to_s
                    end
                    this_pkt = PcapPacket.new({:endian => self[:endian],
                                                                                                                      :timestamp => this_ts,
                                                                                                                            :incl_len => this_incl_len,
                                                                                                                            :orig_len => this_orig_len,
                                                                                                                            :data => this_data }
                                                                                                                     )
                    self[:body] << this_pkt
            end
            if filename
                    self.to_f(:filename => filename, :append => append)
            else
                    self
            end
    end

Also aliased as: a2f
array_to_file!(arr) click to toggle source

Just like array_to_file, but clears any existing packets from the array first.

    # File lib/packetfu/pcap.rb, line 452
    def array_to_file!(arr)
            clear
            array_to_file(arr)
    end

Also aliased as: a2f!
clear() click to toggle source

Clears the contents of the PcapFile.

    # File lib/packetfu/pcap.rb, line 340
    def clear
            self[:body].clear
    end

f2a(args={}) click to toggle source
Alias for: file_to_array
file_to_array(args={}) click to toggle source

file_to_array() translates a libpcap file into an array of packets. Note that this strips out pcap timestamps -- if you'd like to retain timestamps and other libpcap file information, you will want to use read() instead.

    # File lib/packetfu/pcap.rb, line 384
    def file_to_array(args={})
            filename = args[:filename] || args[:file] || args[:f]
            if filename
                    self.read! File.open(filename, "rb") {|f| f.read}
            end
            if args[:keep_timestamps] || args[:keep_ts] || args[:ts]
                    self[:body].map {|x| {x.timestamp.to_s => x.data.to_s} }
            else
                    self[:body].map {|x| x.data.to_s}
            end
    end

Also aliased as: f2a
init_fields(args={}) click to toggle source

Called by initialize to set the initial fields.

    # File lib/packetfu/pcap.rb, line 328
    def init_fields(args={})
            args[:head] = PcapHeader.new(:endian => args[:endian]).read(args[:head])
            args[:body] = PcapPackets.new(:endian => args[:endian]).read(args[:body])
            return args
    end

read(str) click to toggle source

Reads a string to populate the object. Note that this appends new packets to any existing packets in the PcapFile.

    # File lib/packetfu/pcap.rb, line 346
    def read(str)
            force_binary(str)
            self[:head].read str[0,24]
            self[:body].read str
            self
    end

read!(str) click to toggle source

Clears the contents of the PcapFile prior to reading in a new string.

    # File lib/packetfu/pcap.rb, line 354
    def read!(str)
            clear
            force_binary(str)
            self.read str
    end

read_packet_bytes(fname=@filename,&block) click to toggle source

Calls the class method with this object's @filename

    # File lib/packetfu/pcap.rb, line 369
    def read_packet_bytes(fname=@filename,&block)
            raise ArgumentError, "Need a file" unless fname
            return self.class.read_packet_bytes(fname, &block)
    end

read_packets(fname=@filename,&block) click to toggle source

Calls the class method with this object's @filename

    # File lib/packetfu/pcap.rb, line 375
    def read_packets(fname=@filename,&block)
            raise ArgumentError, "Need a file" unless fname
            return self.class.read_packets(fname, &block)
    end

readfile(file) click to toggle source

A shorthand method for opening a file and reading in the packets. Note that readfile clears any existing packets, since that seems to be the typical use.

    # File lib/packetfu/pcap.rb, line 363
    def readfile(file)
            fdata = File.open(file, "rb") {|f| f.read}
            self.read! fdata
    end

to_f(args={}) click to toggle source
Alias for: to_file
to_file(args={}) click to toggle source

Writes the PcapFile to a file. Takes the following arguments:

    :filename # The file to write to.
    :append   # If set to true, the packets are appended to the file, rather than overwriting.

    # File lib/packetfu/pcap.rb, line 463
    def to_file(args={})
            filename = args[:filename] || args[:file] || args[:f]
            unless (!filename.nil? || filename.kind_of?(String))
                    raise ArgumentError, "Need a :filename for #{self.class}"
            end
            append = args[:append]
            if append
                    if File.exists? filename
                            File.open(filename,'ab') {|file| file.write(self.body.to_s)}
                    else
                            File.open(filename,'wb') {|file| file.write(self.to_s)}
                    end
            else
                    File.open(filename,'wb') {|file| file.write(self.to_s)}
            end
            [filename, self.body.sz, self.body.size]
    end

Also aliased as: to_f
to_s() click to toggle source

Returns the object in string form.

    # File lib/packetfu/pcap.rb, line 335
    def to_s
            self[:head].to_s + self[:body].map {|p| p.to_s}.join
    end

write(filename='out.pcap') click to toggle source

Shorthand method for writing to a file. Can take either :file => 'name.pcap' or simply 'name.pcap'

    # File lib/packetfu/pcap.rb, line 485
    def write(filename='out.pcap')
            if filename.kind_of?(Hash)
                    f = filename[:filename] || filename[:file] || filename[:f] || 'out.pcap'
            else
                    f = filename.to_s
            end
            self.to_file(:filename => f.to_s, :append => false)
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.