Module: Caper

Extended by:
FFI::Library
Defined in:
lib/caper.rb,
lib/caper/bpf.rb,
lib/caper/bsd.rb,
lib/caper/crt.rb,
lib/caper/addr.rb,
lib/caper/dead.rb,
lib/caper/live.rb,
lib/caper/pcap.rb,
lib/caper/stat.rb,
lib/caper/dumper.rb,
lib/caper/packet.rb,
lib/caper/in_addr.rb,
lib/caper/offline.rb,
lib/caper/version.rb,
lib/caper/time_val.rb,
lib/caper/typedefs.rb,
lib/caper/data_link.rb,
lib/caper/interface.rb,
lib/caper/exceptions.rb,
lib/caper/file_header.rb,
lib/caper/copy_handler.rb,
lib/caper/error_buffer.rb,
lib/caper/packet_header.rb,
lib/caper/common_wrapper.rb,
lib/caper/capture_wrapper.rb

Defined Under Namespace

Modules: AF, CRT Classes: Addr, BPFInstruction, BPFProgram, CaptureWrapper, CommonWrapper, CopyHandler, DataLink, Dead, Dumper, ErrorBuffer, FileHeader, Handler, In6Addr, InAddr, Interface, LibError, Live, Offline, Packet, PacketHeader, ReadError, SockAddr, SockAddrDl, SockAddrFamily, SockAddrIn, SockAddrIn6, Stat, StatEx, TimeVal, TimeoutError, UnsupportedDataLinkError

Constant Summary collapse

DEFAULT_SNAPLEN =

Default snapshot length for packets

65535
VERSION =

caper version

'0.1.2'

Class Method Summary collapse

Class Method Details

.device_names ⇒ Object

Returns an array of device names for each interface found on the system.



149
150
151
 
# File 'lib/caper/pcap.rb', line 149

def Caper.device_names
  Caper.enum_for(:each_device).map {|dev| dev.name }
end

.dump_devices ⇒ Object

Returns an array of device name and network/netmask pairs for each interface found on the system.

If an interface does not have an address assigned, its network/netmask value is returned as a nil value.



140
141
142
143
144
145
 
# File 'lib/caper/pcap.rb', line 140

def Caper.dump_devices
  Caper.enum_for(:each_device).map do |dev| 
    net = begin; Caper.lookupnet(dev.name); rescue LibError; end
    [dev.name, net]
  end
end

.each_device {|dev| ... } ⇒ nil

List all capture devices and yield them each to a block

Yields:

  • (dev)

Yield Parameters:

  • dev (Interface) —

    An Interface structure for each device.

Returns:

  • (nil)

Raises:

  • (LibError) —

    On failure, an exception is raised with the relevant error message from libpcap.



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/caper/pcap.rb', line 112

def Caper.each_device
  devices = ::FFI::MemoryPointer.new(:pointer)
  errbuf = ErrorBuffer.create()

  Caper.pcap_findalldevs(devices, errbuf)
  node = devices.get_pointer(0)

  if node.null?
    raise(LibError, "pcap_findalldevs(): #{errbuf.to_s}")
  end

  device = Interface.new(node)

  while device
    yield(device)
    device = device.next
  end

  Caper.pcap_freealldevs(node)
  return nil
end

.lib_version ⇒ String

Get the version information for libpcap.

Returns:

  • (String) —

    Information about the version of the libpcap library being used; note that it contains more information than just a version number.



162
163
164
 
# File 'lib/caper/pcap.rb', line 162

def Caper.lib_version
  Caper.pcap_lib_version
end

.lib_version_number ⇒ String

Extract just the version number from the lib_version string.

Returns:

  • (String) —

    Version number.



172
173
174
175
176
 
# File 'lib/caper/pcap.rb', line 172

def Caper.lib_version_number
  if lib_version() =~ /libpcap version (\d+\.\d+.\d+)/
    return $1
  end
end

.lookupdev ⇒ String

Find the default device on which to capture.

Returns:

  • (String) —

    Name of default device

Raises:

  • (LibError) —

    On failure, an exception is raised with the relevant error message from libpcap.



17
18
19
20
21
22
23
 
# File 'lib/caper/pcap.rb', line 17

def Caper.lookupdev
  e = ErrorBuffer.create()
  unless name = Caper.pcap_lookupdev(e)
    raise(LibError, "pcap_lookupdev(): #{e.to_s}")
  end
  return name
end

.lookupnet(device) {|netp, maskp| ... } ⇒ nil, String

Determine the IPv4 network number and mask relevant with a network device.

Parameters:

  • device (String) —

    The name of the device to look up.

Yields:

  • (netp, maskp)

Yield Parameters:

  • netp (FFI::MemoryPointer) —

    A pointer to the network return value.

  • maskp (FFI::MemoryPointer) —

    A pointer to the netmask return value.

Returns:

  • (nil, String) —

    The IPv4 network number and mask presented as “n.n.n.n/m.m.m.m”. nil is returned when a block is specified.

Raises:

  • (LibError) —

    On failure, an exception is raised with the relevant error message from libpcap.



50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/caper/pcap.rb', line 50

def Caper.lookupnet(device)
  netp  = FFI::MemoryPointer.new(find_type(:bpf_uint32))
  maskp = FFI::MemoryPointer.new(find_type(:bpf_uint32))
  errbuf = ErrorBuffer.create()
  unless Caper.pcap_lookupnet(device, netp, maskp, errbuf) == 0
    raise(LibError, "pcap_lookupnet(): #{errbuf.to_s}")
  end
  if block_given?
    yield(netp, maskp)
  else
    return( netp.get_array_of_uchar(0,4).join('.') << "/" <<
            maskp.get_array_of_uchar(0,4).join('.') )
  end
end

.open_dead(opts = {}, &block) ⇒ Object

Opens a new Dead pcap interface for compiling filters or opening a capture for output. See Dead.new() for arguments.



79
80
81
82
 
# File 'lib/caper/pcap.rb', line 79

def Caper.open_dead(opts={}, &block)
  ret = Dead.new(opts, &block)
  return block_given? ? ret.close : ret
end

.open_file(path, opts = {}, &block) ⇒ Object

Same as open_offline



92
93
94
 
# File 'lib/caper/pcap.rb', line 92

def Caper.open_file(path, opts={}, &block)
  open_offline(path, opts, &block)
end

.open_live(opts = {}, &block) ⇒ Object

Opens a new Live device for capturing from the network. See Live.new() for arguments.

If passed a block, the block is passed to Live.new() and the Live object is closed after completion of the block



71
72
73
74
 
# File 'lib/caper/pcap.rb', line 71

def Caper.open_live(opts={},&block)
  ret = Live.new(opts, &block)
  return block_given? ? ret.close : ret
end

.open_offline(path, opts = {}, &block) ⇒ Object

Opens a saved capture file for reading. See Offline.new for arguments.



86
87
88
89
 
# File 'lib/caper/pcap.rb', line 86

def Caper.open_offline(path, opts={}, &block)
  ret = Offline.new(path, opts={}, &block)
  return block_given? ? ret.close : ret
end