Class: Ronin::Scanners::Scanner

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Script
Defined in:
lib/ronin/scanners/scanner.rb

Overview

The Scanner base class allows for defining various types of scanners. All scanners are Enumerable, have Parameters and are Cacheable.

Metadata

A Scanner can be described by metadata, which is cached into the Ronin Database. The cacheable metadata must be defined within a cache block, so that the metadata is set only before the scanner is cached:

cache do
  self.name = 'ZIP Scanner'
  self.description = %{
    A scanner which finds ZIP files on a system.
  }
end

License

A Scanner may be associated with a specific software license using the license! method:

cache do
  # ...

  self.license! :mit
end

Methods

The primary method which will perform the scanning and yielding back of results is #scan.

The Scanner class defines three other methods for enumerating results using #scan:

  • #each - enumerates over the normalized results, using #normalize_result to normalize the results.
  • #each_resource - enumerates over resources that were created from the results, using #new_resource.
  • #import - saves the resources into the Database, while enumerating over the resources.

Scanner Base Classes

Specialized Scanner Classes

Direct Known Subclasses

HostNameScanner, IPScanner, Nmap, TCPPortScanner, UDPPortScanner, URLScanner

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Scanner) initialize(options = {})

Creates a new Ronin::Scanners::Scanner object.

Parameters:

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

    Additional options for the scanner.

Since:

  • 1.0.0



106
107
108
109
110
 
# File 'lib/ronin/scanners/scanner.rb', line 106

def initialize(options={})
  super(options)

  initialize_params(options)
end

Class Method Details

+ (Enumerator) each(options = {}) {|result| ... }

Initializes the scanner and imports the scan results.

Parameters:

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

    Options for the scanner.

Yields:

  • (result) —

    The given block will be passed each "result" from the scan.

Yield Parameters:

  • result (Object) —

    A "result" from the scan.

Returns:

  • (Enumerator) —

    If no block is given, an Enumerator will be returned.

See Also:

Since:

  • 1.0.0



133
134
135
 
# File 'lib/ronin/scanners/scanner.rb', line 133

def self.each(options={},&block)
  new(options).each(&block)
end

+ (Array<DataMapper::Resource>) import(options = {}) {|resource| ... }

Initializes the scanner and imports the scan results.

Parameters:

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

    Options for the scanner.

Yields:

  • (resource) —

    The given block will be passed every saved scanner result.

Yield Parameters:

  • resource (DataMapper::Resource) —

    A resource saved by the scanner.

Returns:

  • (Array<DataMapper::Resource>) —

    If no block is given, an Array of saved scanner resources will be returned.

See Also:

Since:

  • 1.0.0



188
189
190
191
192
193
194
 
# File 'lib/ronin/scanners/scanner.rb', line 188

def self.import(options={},&block)
  scanner = new(options)

  if block then scanner.import(&block)
  else          scanner.import.to_a
  end
end

+ (Array<DataMapper::Resource>) scan(options = {}) {|resource| ... }

Initializes the scanner and performs a scan.

Parameters:

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

    Options for the scanner.

Yields:

  • (resource) —

    The given block will be passed every scanned resource.

Yield Parameters:

  • resource (DataMapper::Resource) —

    A resource found by the scanner.

Returns:

  • (Array<DataMapper::Resource>) —

    If no block is given, an Array of scanned resources will be returned.

See Also:

Since:

  • 1.0.0



158
159
160
161
162
163
164
 
# File 'lib/ronin/scanners/scanner.rb', line 158

def self.scan(options={},&block)
  scanner = new(options)

  if block then scanner.each_resource(&block)
  else          scanner.each_resource.to_a
  end
end

Instance Method Details

- (Scanner, Enumerator) each {|result| ... }

Performs the scan.

Yields:

  • (result) —

    The given block will be passed each "result" from the scan.

Yield Parameters:

  • result (Object) —

    A "result" from the scan.

Returns:

  • (Scanner, Enumerator) —

    If no block was given, an Enumerator object will be returned.

Since:

  • 1.0.0



212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/ronin/scanners/scanner.rb', line 212

def each
  return enum_for(__method__) unless block_given?

  scan do |result|
    if result
      if (result = normalize_result(result))
        yield result
      end
    end
  end

  return self
end

- (Scanner, Enumerator) each_resource {|resource| ... }

Creates new resource objects from the scan results.

Yields:

  • (resource) —

    The given block will be passed each resource.

Yield Parameters:

  • resource (DataMapper::Resource) —

    A new or pre-existing resource.

Returns:

  • (Scanner, Enumerator) —

    If no block was given, an Enumerator object will be returned.

Since:

  • 1.0.0



242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/ronin/scanners/scanner.rb', line 242

def each_resource
  return enum_for(__method__) unless block_given?

  scan do |result|
    if result
      if (result = normalize_result(result))
        if (resource = new_resource(result))
          yield resource
        end
      end
    end
  end
end

- (Scanner, Enumerator) import {|resource| ... }

Imports the scan results into the Database.

Yields:

  • (resource) —

    The given block will be passed each resource, after it has been saved into the Database.

Yield Parameters:

  • resource (DataMapper::Resource) —

    A resource that exists in the Database.

Returns:

  • (Scanner, Enumerator) —

    If no block was given, an Enumerator object will be returned.

Since:

  • 1.0.0



273
274
275
276
277
278
279
 
# File 'lib/ronin/scanners/scanner.rb', line 273

def import
  return enum_for(__method__) unless block_given?

  each_resource do |resource|
    yield resource if resource.save
  end
end

- (DataMapper::Resource?) new_resource(result) (protected)

Creates a new Database resource.

Parameters:

  • result (Object) —

    A result from the scan.

Returns:

  • (DataMapper::Resource, nil) —

    The resource created from the result, or nil if a resource could not be created from the result.

Since:

  • 1.0.0



314
315
316
 
# File 'lib/ronin/scanners/scanner.rb', line 314

def new_resource(result)
  nil
end

- (Object) normalize_result(result) (protected)

The default method which normalizes results.

Parameters:

  • result (Object) —

    The incoming result.

Returns:

  • (Object) —

    The normalized result.

Since:

  • 1.0.0



296
297
298
 
# File 'lib/ronin/scanners/scanner.rb', line 296

def normalize_result(result)
  result
end

- (Object) scan(&block) (protected)

The default method which will actually perform the scanning.

Since:

  • 1.0.0



325
326
 
# File 'lib/ronin/scanners/scanner.rb', line 325

def scan(&block)
end