Class: Bilbo::Capture

Inherits:
Object
  • Object
show all
Defined in:
lib/bilbo/capture.rb

Overview

Capture packets simply.

Author:

  • Kent ‘picat’ Gruber

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ Capture

Create a new Bilbo capture instance.

Simple Defaults

You can let bilbo take care of things for you with its defaults:

cap = Bilbo::Capture.new(start: true)

Custom Options

You can also set you own options with defaults and check them easily:

cap = Bilbo::Capture.new(iface: "eth0")
cap.iface
# => "eth0"



38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/bilbo/capture.rb', line 38

def initialize(args={})
  @iface   = args[:iface]   || Pcap.lookupdev # lookup default interface
  @snaplen = args[:snaplen] || 65535          # default snaplen
  @promisc = args[:promisc] || false          # default promisc
  @timeout = args[:timeout] || 0              # default timeout
  start(args) if args[:start]
  if block_given?
    start
    @packet_stream.each { |packet| yield packet }
  end
end

Instance Attribute Details

#iface ⇒ String

interface to capture on

Returns:

  • (String) 


12
13
14
 
# File 'lib/bilbo/capture.rb', line 12

def iface
  @iface
end

#packet_stream ⇒ PCAPRUB::Pcap (readonly)

packet stream

Returns:

  • (PCAPRUB::Pcap) 


8
9
10
 
# File 'lib/bilbo/capture.rb', line 8

def packet_stream
  @packet_stream
end

#promisc ⇒ Boolean

capture packets in promiscuous mode

Returns:

  • (Boolean) 


20
21
22
 
# File 'lib/bilbo/capture.rb', line 20

def promisc
  @promisc
end

#snaplen ⇒ Integer

amount of data for each frame that is actually captured

Returns:

  • (Integer) 


16
17
18
 
# File 'lib/bilbo/capture.rb', line 16

def snaplen
  @snaplen
end

#timeout ⇒ Integer

capture packet timeout

Returns:

  • (Integer) 


24
25
26
 
# File 'lib/bilbo/capture.rb', line 24

def timeout
  @timeout
end

Instance Method Details

#packets(args = {}) ⇒ Object

Simple interface to work with the packet stream.

Examples:

Block


cap = Bilbo::Capture(iface: "eth0")
cap.start 
cap.packets do |packet|

end

Direct PCAP:Pcap Access


cap = Bilbo::Capture(iface: "eth0")
cap.start 
cap.packets 
# => <PCAPRUB::Pcap>
cap.packets.each do |packet|
  # do something with the packet
end
cap.packets.stats

Wrangle a few packets


cap = Bilbo::Capture(iface: "eth0")
cap.start 
cap.packets(count: 30)

Parameters:

  • args (Hash) (defaults to: {}) —

    options to wrangle streaming packets, totally optional

  • options (Hash) —

    a customizable set of options



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/bilbo/capture.rb', line 112

def packets(args={})
  if block_given?
    @packet_stream.each { |packet| yield packet }
  else
    if args[:count]
      packets = []
      @packet_stream.each do |packet| 
        packets << packet
        break if packets.count.eql? args[:count]
      end
      return packets
    end
    @packet_stream 
  end
end

#start(args = {}) ⇒ PCAPRUB::Pcap

Start the actual packet capturing.

Example

cap = Bilbo::Capture(iface: "eth0")
cap.start

Block Example

cap = Bilbo::Capture(iface: "eth0")
cap.start do |packet|
  # do something with packet
end

Parameters:

  • args (Hash) (defaults to: {}) —

    capture options when started

  • options (Hash) —

    a customizable set of options

Returns:

  • (PCAPRUB::Pcap) 


70
71
72
73
74
75
76
77
78
79
 
# File 'lib/bilbo/capture.rb', line 70

def start(args={})
  iface   = args[:iface]   || @iface   # default interface
  snaplen = args[:snaplen] || @snaplen # default snaplen
  promisc = args[:promisc] || @promisc # default promisc
  timeout = args[:timeout] || @timeout # default timeout
  @packet_stream = Pcap.open_live(iface, snaplen, promisc, timeout) 
  if block_given?
    @packet_stream.each { |packet| yield packet }
  end
end