Class: PacketGen::Packet
- Inherits:
-
Object
- Object
- PacketGen::Packet
- Defined in:
- lib/packetgen/packet.rb
Overview
An object of type Packet handles a network packet. This packet may contain multiple protocol headers, starting from MAC layer or from Network (OSI) layer.
Creating a packet is fairly simple:
Packet.gen 'IP', src: '192.168.1.1', dst: '192.168.1.2'
Create a packet
Packets may be hand-made or parsed from a binary string:
Packet.gen('IP', src: '192.168.1.1', dst: '192.168.1.2').add('UDP', sport: 45000, dport: 23)
Packet.parse(binary_string)
Access packet information
pkt = Packet.gen('IP').add('UDP')
# read information
pkt.udp.sport
pkt.ip.ttl
# set information
pkt.udp.dport = 2323
pkt.ip.ttl = 1
pkt.ip(ttl: 1, id: 1234)
Save a packet to a file
pkt.write('file.pcapng')
Get packets
Packets may be captured from wire:
Packet.capture do |packet|
do_some_stuffs
end
packets = Packet.capture(iface: 'eth0', max: 5) # get 5 packets from eth0
Packets may also be read from a file:
packets = Packet.read(file.pcapng)
Save packets to a file
Packet.write 'file.pcapng', packets
Instance Attribute Summary collapse
-
#cache_headers ⇒ Boolean
Activaye or deactivate header cache (activated by default).
-
#headers ⇒ Array<Header::Base>
readonly
Get packet headers, ordered as they appear in the packet.
Class Method Summary collapse
-
.capture(**kwargs) {|packet, timestamp| ... } ⇒ Array<Packet>
Capture packets from wire.
-
.gen(protocol, options = {}) ⇒ Packet
Create a new Packet.
-
.parse(binary_str, first_header: nil) ⇒ Packet
Parse a binary string and generate a Packet from it.
-
.read(filename) ⇒ Array<Packet>
Read packets from
filename
. -
.write(filename, packets) ⇒ void
Write packets to
filename
.
Instance Method Summary collapse
- #==(other) ⇒ Boolean
- #===(other) ⇒ Boolean
-
#add(protocol, options = {}) ⇒ self
Add a protocol header in packet.
-
#body ⇒ Types
Get packet body.
-
#body=(str) ⇒ void
Set packet body.
-
#calc ⇒ void
Recalculate all calculatable fields (for now: length and checksum).
-
#calc_checksum ⇒ void
Recalculate all packet checksums.
-
#calc_length ⇒ void
Recalculate all packet length fields.
-
#decapsulate(*hdrs) ⇒ self
Remove headers from
self
. -
#encapsulate(other, parsing: false) ⇒ self
Encapulate another packet in
self
. -
#initialize ⇒ Packet
constructor
A new instance of Packet.
-
#insert(prev, protocol, options = {}) ⇒ self
Insert a header in packet.
-
#inspect ⇒ String
Get packet as a pretty formatted string.
-
#is?(protocol) ⇒ Boolean
Check if a protocol header is embedded in packet.
-
#parse(binary_str, first_header: nil) ⇒ Packet
Parse a binary string and populate Packet from it.
-
#reply ⇒ Packet
Forge a new packet from current one with all possible fields inverted.
-
#reply! ⇒ self
Invert all possible fields in packet to create a reply.
-
#to_f(filename) ⇒ Array
(also: #write)
Write packet to a PCapNG file on disk.
-
#to_s ⇒ String
Get binary string (i.e. binary string sent on or received from network).
-
#to_w(iface = nil, calc: true, number: 1, interval: 1) ⇒ void
Send packet on wire.
Constructor Details
#initialize ⇒ Packet
Returns a new instance of Packet.
127 128 129 130 131 |
# File 'lib/packetgen/packet.rb', line 127 def initialize @headers = [] @header_cache = {} @cache_headers = true end |
Instance Attribute Details
#cache_headers ⇒ Boolean
Activaye or deactivate header cache (activated by default)
56 57 58 |
# File 'lib/packetgen/packet.rb', line 56 def cache_headers @cache_headers end |
#headers ⇒ Array<Header::Base> (readonly)
Get packet headers, ordered as they appear in the packet.
53 54 55 |
# File 'lib/packetgen/packet.rb', line 53 def headers @headers end |
Class Method Details
.capture(**kwargs) {|packet, timestamp| ... } ⇒ Array<Packet>
Capture packets from wire. Same arguments as Capture#initialize
87 88 89 90 91 92 93 94 95 |
# File 'lib/packetgen/packet.rb', line 87 def self.capture(**kwargs, &block) capture = Capture.new(**kwargs) if block capture.start(&block) else capture.start end capture.packets end |
.gen(protocol, options = {}) ⇒ Packet
Create a new Packet
62 63 64 |
# File 'lib/packetgen/packet.rb', line 62 def self.gen(protocol, ={}) self.new.add protocol, end |
.parse(binary_str, first_header: nil) ⇒ Packet
75 76 77 |
# File 'lib/packetgen/packet.rb', line 75 def self.parse(binary_str, first_header: nil) new.parse binary_str, first_header: first_header end |
.read(filename) ⇒ Array<Packet>
Read packets from filename
. May read Pcap and Pcap-NG formats.
For more control (on Pcap-ng only), see PacketGen::PcapNG::File.
106 107 108 109 110 111 112 |
# File 'lib/packetgen/packet.rb', line 106 def self.read(filename) PcapNG::File.new.read_packets(filename) rescue StandardError => e raise ArgumentError, e unless File.extname(filename.downcase) == '.pcap' Pcap.read(filename) end |
.write(filename, packets) ⇒ void
This method returns an undefined value.
Write packets to filename
For more options, see PacketGen::PcapNG::File.
120 121 122 123 124 |
# File 'lib/packetgen/packet.rb', line 120 def self.write(filename, packets) pf = PcapNG::File.new pf.array_to_file packets pf.to_f filename end |
Instance Method Details
#==(other) ⇒ Boolean
321 322 323 |
# File 'lib/packetgen/packet.rb', line 321 def ==(other) to_s == other.to_s end |
#===(other) ⇒ Boolean
328 329 330 331 332 333 334 335 336 337 |
# File 'lib/packetgen/packet.rb', line 328 def ===(other) case other when PacketGen::Packet self == other when String is? other else false end end |
#add(protocol, options = {}) ⇒ self
Add a protocol header in packet.
138 139 140 141 142 143 144 145 146 |
# File 'lib/packetgen/packet.rb', line 138 def add(protocol, ={}) klass = check_protocol(protocol) # options[:packet]= self is speedier than options.merge(packet: self) [:packet] = self header = klass.new() add_header header self end |
#body ⇒ Types
Get packet body
204 205 206 |
# File 'lib/packetgen/packet.rb', line 204 def body last_header[:body] if last_header.respond_to? :body end |
#body=(str) ⇒ void
This method returns an undefined value.
Set packet body
211 212 213 |
# File 'lib/packetgen/packet.rb', line 211 def body=(str) last_header.body = str end |
#calc ⇒ void
This method returns an undefined value.
Recalculate all calculatable fields (for now: length and checksum)
197 198 199 200 |
# File 'lib/packetgen/packet.rb', line 197 def calc calc_length calc_checksum end |
#calc_checksum ⇒ void
This method returns an undefined value.
Recalculate all packet checksums
181 182 183 184 185 |
# File 'lib/packetgen/packet.rb', line 181 def calc_checksum headers.reverse_each do |header| header.calc_checksum if header.respond_to? :calc_checksum end end |
#calc_length ⇒ void
This method returns an undefined value.
Recalculate all packet length fields
189 190 191 192 193 |
# File 'lib/packetgen/packet.rb', line 189 def calc_length headers.reverse_each do |header| header.calc_length if header.respond_to? :calc_length end end |
#decapsulate(*hdrs) ⇒ self
Remove headers from self
274 275 276 277 278 279 280 281 282 283 284 |
# File 'lib/packetgen/packet.rb', line 274 def decapsulate(*hdrs) hdrs.each do |hdr| prev_hdr = previous_header(hdr) next_hdr = next_header(hdr) headers.delete(hdr) add_header(next_hdr, previous_header: prev_hdr) if prev_hdr && next_hdr end invalidate_header_cache rescue ArgumentError => e raise FormatError, e. end |
#encapsulate(other, parsing: false) ⇒ self
Encapulate another packet in self
262 263 264 265 266 |
# File 'lib/packetgen/packet.rb', line 262 def encapsulate(other, parsing: false) other.headers.each_with_index do |h, i| add_header h, parsing: i.positive? || parsing end end |
#insert(prev, protocol, options = {}) ⇒ self
Insert a header in packet
154 155 156 157 158 159 160 161 162 163 164 165 166 |
# File 'lib/packetgen/packet.rb', line 154 def insert(prev, protocol, ={}) klass = check_protocol(protocol) nxt = prev.body # options[:packet]= self is speedier than options.merge(packet: self) [:packet] = self header = klass.new() add_header header, previous_header: prev idx = headers.index(prev) + 1 headers[idx, 0] = header header[:body] = nxt self end |
#inspect ⇒ String
Get packet as a pretty formatted string.
311 312 313 314 315 316 317 |
# File 'lib/packetgen/packet.rb', line 311 def inspect str = Inspect.dashed_line(self.class) headers.each do |header| str << header.inspect end str << Inspect.inspect_body(body) end |
#is?(protocol) ⇒ Boolean
174 175 176 177 |
# File 'lib/packetgen/packet.rb', line 174 def is?(protocol) klass = check_protocol protocol headers.any?(klass) end |
#parse(binary_str, first_header: nil) ⇒ Packet
Parse a binary string and populate Packet from it.
292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 |
# File 'lib/packetgen/packet.rb', line 292 def parse(binary_str, first_header: nil) headers.clear if first_header.nil? # No decoding forced for first header. Have to guess it! first_header = guess_first_header(binary_str) raise ParseError, "cannot identify first header in string: #{binary_str.inspect}" if first_header.nil? end add first_header headers[-1, 1] = last_header.read(binary_str) # Decode upper headers recursively decode_bottom_up self end |
#reply ⇒ Packet
Forge a new packet from current one with all possible fields inverted. The new packet may be a reply to current one.
353 354 355 356 |
# File 'lib/packetgen/packet.rb', line 353 def reply pkt = dup pkt.reply! end |
#reply! ⇒ self
Invert all possible fields in packet to create a reply.
342 343 344 345 346 347 |
# File 'lib/packetgen/packet.rb', line 342 def reply! headers.each do |header| header.reply! if header.respond_to?(:reply!) end self end |
#to_f(filename) ⇒ Array Also known as: write
Write packet to a PCapNG file on disk.
225 226 227 |
# File 'lib/packetgen/packet.rb', line 225 def to_f(filename) PcapNG::File.new.read_array([self]).to_f(filename) end |
#to_s ⇒ String
Get binary string (i.e. binary string sent on or received from network).
217 218 219 |
# File 'lib/packetgen/packet.rb', line 217 def to_s first_header.to_s end |
#to_w(iface = nil, calc: true, number: 1, interval: 1) ⇒ void
This method returns an undefined value.
Send packet on wire. Use first header #to_w
method.
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 |
# File 'lib/packetgen/packet.rb', line 238 def to_w(iface=nil, calc: true, number: 1, interval: 1) iface ||= PacketGen.default_iface if first_header.respond_to? :to_w self.calc if calc number.times do first_header.to_w(iface) sleep interval if number > 1 end else type = first_header.protocol_name raise WireError, "don't known how to send a #{type} packet on wire" end end |