recog 2.0.24 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6bcaa01bf7e7d6d81d2a46b792d905011a541b19
-  data.tar.gz: 8593c9b71ff2b349a1f46693e87c6218d383bd59
+  metadata.gz: 11aff7826c38e379d719a70b39406f4d861f8d3f
+  data.tar.gz: 98f54e902871cb73ddcffbb7e0f72be5b21bf143
 SHA512:
-  metadata.gz: 177feea5c499a7c29a802f5b2244edc8144fb7ddca69248e455a95e7e4bea211afb2ea7b6b50558cc89aa7deeb2a01068d126c6c55f4b5e270b71e8ed88d13ff
-  data.tar.gz: fdb3c3908a3f9168911b4e559fb56d90c2956b63ba0cfea49015d0d9fa90fcd3b82219271fc61ddffb70a2bc6e4e3a5a7c289054d08624b57a1d8b0bce5cc71a
+  metadata.gz: 398dc88dfda3030d5d0e8da3c0774fc95ec99c2506f9f15ba528ef5ec930591f02f43d313ec5ed06cb4b7bb28798ef71bf53a539a6b50b8158a7f0b69877e0ed
+  data.tar.gz: 19bf9ddccb4031ade9bf5d94feb4516df400816eaf81a894b24716e06ef7e5d5a2400bd0424d55875b38451fcad83edb7f99f7b00ac1e38fa059447682f17d0a

data/README.md

@@ -75,7 +75,7 @@ Matches can be tested on the command-line in a similar fashion:
 
 ```
     $ echo 'OpenSSH_6.6p1 Ubuntu-2ubuntu1' | bin/recog_match xml/ssh_banners.xml -
-    MATCH: {"service.version"=>"6.6p1", "openssh.comment"=>"Ubuntu-2ubuntu1", "service.vendor"=>"OpenBSD", "service.family"=>"OpenSSH", "service.product"=>"OpenSSH", "data"=>"OpenSSH_6.6p1 Ubuntu-2ubuntu1"}
+    MATCH: {"matched"=>"OpenSSH running on Ubuntu 14.04", "service.version"=>"6.6p1", "openssh.comment"=>"Ubuntu-2ubuntu1", "service.vendor"=>"OpenBSD", "service.family"=>"OpenSSH", "service.product"=>"OpenSSH", "os.vendor"=>"Ubuntu", "os.device"=>"General", "os.family"=>"Linux", "os.product"=>"Linux", "os.version"=>"14.04", "service.protocol"=>"ssh", "fingerprint_db"=>"ssh.banner", "data"=>"OpenSSH_6.6p1 Ubuntu-2ubuntu1"}
 ```
 
 ### Best Practices

data/features/data/matching_banners_fingerprints.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<fingerprints>
+<fingerprints protocol="ftp" database_type="service">
   <fingerprint pattern="^-{10} Welcome to Pure-FTPd (.*)-{10}$">
     <example>---------- Welcome to Pure-FTPd ----------</example>
     <description>Pure-FTPd
@@ -8,6 +8,7 @@
     <param pos="1" name="pureftpd.config"/>
     <param pos="0" name="service.family" value="Pure-FTPd"/>
     <param pos="0" name="service.product" value="Pure-FTPd"/>
+    <param pos="0" name="service.protocol" value="ftp"/>
   </fingerprint>
   <fingerprint pattern="^(\S+) FTP Server \(SunOS (\S+)\) ready\.?$" flags="REG_ICASE">
     <description>SunOS/Solaris</description>

data/features/data/multiple_banners_fingerprints.xml

@@ -16,10 +16,12 @@
     <param pos="1" name="pureftpd.config"/>
     <param pos="0" name="service.family" value="Pure-FTPd"/>
     <param pos="0" name="service.product" value="Pure-FTPd"/>
+    <param pos="0" name="service.protocol" value="ftp"/>
   </fingerprint>
   <fingerprint pattern="^(\S+) FTP Server \(SunOS (\S+)\) ready\.?$" flags="REG_ICASE">
     <description>SunOS/Solaris</description>
     <example>example.com FTP server (SunOS 5.7) ready.</example>
+    <param pos="0" name="service.protocol" value="ftp"/>
     <param pos="0" name="os.vendor" value="Sun"/>
     <param pos="0" name="os.family" value="Solaris"/>
     <param pos="0" name="os.product" value="Solaris"/>

data/features/match.feature

@@ -3,8 +3,8 @@ Feature: Match
     When I run `recog_match matching_banners_fingerprints.xml sample_banner.txt`
     Then it should pass with:
       """
-      MATCH: {"matched"=>"Pure-FTPd Config data can be zero or more of: [privsep] [TLS]", "pureftpd.config"=>"[privsep] [TLS] ", "service.family"=>"Pure-FTPd", "service.product"=>"Pure-FTPd", "data"=>"---------- Welcome to Pure-FTPd [privsep] [TLS] ----------"}
-      MATCH: {"matched"=>"SunOS/Solaris", "os.vendor"=>"Sun", "os.family"=>"Solaris", "os.product"=>"Solaris", "os.device"=>"General", "host.name"=>"polaris", "os.version"=>"5.8", "data"=>"polaris FTP server (SunOS 5.8) ready."}
+      MATCH: {"matched"=>"Pure-FTPd Config data can be zero or more of: [privsep] [TLS]", "pureftpd.config"=>"[privsep] [TLS] ", "service.family"=>"Pure-FTPd", "service.product"=>"Pure-FTPd", "service.protocol"=>"ftp", "fingerprint_db"=>"matching_banners_fingerprints", "data"=>"---------- Welcome to Pure-FTPd [privsep] [TLS] ----------"}
+      MATCH: {"matched"=>"SunOS/Solaris", "os.vendor"=>"Sun", "os.family"=>"Solaris", "os.product"=>"Solaris", "os.device"=>"General", "host.name"=>"polaris", "os.version"=>"5.8", "service.protocol"=>"ftp", "fingerprint_db"=>"matching_banners_fingerprints", "data"=>"polaris FTP server (SunOS 5.8) ready."}
       """
 
   Scenario: Fails at finding matches
@@ -19,14 +19,14 @@ Feature: Match
     When I run `recog_match multiple_banners_fingerprints.xml sample_banner.txt --multi-match`
     Then it should pass with:
       """
-      MATCHES: {"matched"=>"Generic FTP, Checks for the existence of the word FTP in the line", "data"=>"---------- Welcome to Pure-FTPd [privsep] [TLS] ----------"},{"matched"=>"Pure-FTPd Config data can be zero or more of: [privsep] [TLS]", "pureftpd.config"=>"[privsep] [TLS] ", "service.family"=>"Pure-FTPd", "service.product"=>"Pure-FTPd", "data"=>"---------- Welcome to Pure-FTPd [privsep] [TLS] ----------"}
-      MATCHES: {"matched"=>"Generic FTP, Checks for the existence of the word FTP in the line", "data"=>"polaris FTP server (SunOS 5.8) ready."},{"matched"=>"SunOS/Solaris", "os.vendor"=>"Sun", "os.family"=>"Solaris", "os.product"=>"Solaris", "os.device"=>"General", "host.name"=>"polaris", "os.version"=>"5.8", "data"=>"polaris FTP server (SunOS 5.8) ready."}
+      MATCHES: {"matched"=>"Generic FTP, Checks for the existence of the word FTP in the line", "service.protocol"=>"", "fingerprint_db"=>"multiple_banners_fingerprints", "data"=>"---------- Welcome to Pure-FTPd [privsep] [TLS] ----------"},{"matched"=>"Pure-FTPd Config data can be zero or more of: [privsep] [TLS]", "pureftpd.config"=>"[privsep] [TLS] ", "service.family"=>"Pure-FTPd", "service.product"=>"Pure-FTPd", "service.protocol"=>"ftp", "fingerprint_db"=>"multiple_banners_fingerprints", "data"=>"---------- Welcome to Pure-FTPd [privsep] [TLS] ----------"}
+      MATCHES: {"matched"=>"Generic FTP, Checks for the existence of the word FTP in the line", "service.protocol"=>"", "fingerprint_db"=>"multiple_banners_fingerprints", "data"=>"polaris FTP server (SunOS 5.8) ready."},{"matched"=>"SunOS/Solaris", "service.protocol"=>"ftp", "os.vendor"=>"Sun", "os.family"=>"Solaris", "os.product"=>"Solaris", "os.device"=>"General", "host.name"=>"polaris", "os.version"=>"5.8", "fingerprint_db"=>"multiple_banners_fingerprints", "data"=>"polaris FTP server (SunOS 5.8) ready."}
       """
 
   Scenario: Finds first matches using no-multi-match flag
     When I run `recog_match multiple_banners_fingerprints.xml sample_banner.txt --no-multi-match`
     Then it should pass with:
     """
-    MATCH: {"matched"=>"Generic FTP, Checks for the existence of the word FTP in the line", "data"=>"---------- Welcome to Pure-FTPd [privsep] [TLS] ----------"}
-    MATCH: {"matched"=>"Generic FTP, Checks for the existence of the word FTP in the line", "data"=>"polaris FTP server (SunOS 5.8) ready."}
+    MATCH: {"matched"=>"Generic FTP, Checks for the existence of the word FTP in the line", "service.protocol"=>"", "fingerprint_db"=>"multiple_banners_fingerprints", "data"=>"---------- Welcome to Pure-FTPd [privsep] [TLS] ----------"}
+    MATCH: {"matched"=>"Generic FTP, Checks for the existence of the word FTP in the line", "service.protocol"=>"", "fingerprint_db"=>"multiple_banners_fingerprints", "data"=>"polaris FTP server (SunOS 5.8) ready."}
     """

data/lib/recog/db.rb

@@ -13,13 +13,34 @@ class DB
   #   against strings that make sense for the {#match_key}
   attr_reader :fingerprints
 
-  # @return [String] Taken from the `fingerprints/matches` element, or
+  # @return [String] Taken from the `fingerprints/matches` attribute, or
   #   defaults to the basename of {#path} without the `.xml` extension.
   attr_reader :match_key
 
+  # @return [String] Taken from the `fingerprints/protocol` attribute, or
+  #   defaults to an empty string
+  attr_reader :protocol
+
+  # @return [String] Taken from the `fingerprints/database_type` attribute
+  #   defaults to an empty string
+  attr_reader :database_type
+
+  # @return [Float] Taken from the `fingerprints/preference` attribute,
+  #   defaults to 0.10.  Used when ordering databases, highest numbers
+  #   are given priority and are processed first.
+  attr_reader :preference
+
+  # Default Fingerprint database preference when it isn't specified in file
+  # Do not use a value below 0.10 so as to allow users to specify lower
+  # values in their own custom XML that will always run last.
+  DEFAULT_FP_PREFERENCE = 0.10
+
   # @param path [String]
   def initialize(path)
     @match_key = nil
+    @protocol = ''
+    @database_type = ''
+    @preference = DEFAULT_FP_PREFERENCE.to_f
     @path = path
     @fingerprints = []
 
@@ -30,24 +51,25 @@ class DB
   def parse_fingerprints
     xml = nil
 
-    File.open(self.path, "rb") do |fd|
+    File.open(self.path, 'rb') do |fd|
       xml = Nokogiri::XML(fd.read(fd.stat.size))
     end
 
     raise "#{self.path} is invalid XML: #{xml.errors.join(',')}" unless xml.errors.empty?
 
-    xml.xpath("/fingerprints").each do |fbase|
-      if fbase['matches']
-        @match_key = fbase['matches'].to_s
-      end
-    end
+    xml.xpath('/fingerprints').each do |fbase|
+
+      @match_key = fbase['matches'].to_s if fbase['matches']
+      @protocol = fbase['protocol'].to_s if fbase['protocol']
+      @database_type = fbase['database_type'].to_s if fbase['database_type']
+      @preference = fbase['preference'].to_f if fbase['preference']
 
-    unless @match_key
-      @match_key = File.basename(self.path).sub(/\.xml$/, '')
     end
 
-    xml.xpath("/fingerprints/fingerprint").each do |fprint|
-      @fingerprints << Fingerprint.new(fprint)
+    @match_key = File.basename(self.path).sub(/\.xml$/, '') unless @match_key
+
+    xml.xpath('/fingerprints/fingerprint').each do |fprint|
+      @fingerprints << Fingerprint.new(fprint, @match_key, @protocol)
     end
 
     xml = nil

data/lib/recog/db_manager.rb

@@ -13,8 +13,12 @@ class DBManager
   end
 
   def load_databases
-    Dir[self.path + "/*.xml"].each do |dbxml|
-      self.databases << DB.new(dbxml)
+    if File.directory?(self.path)
+      Dir[self.path + "/*.xml"].each do |dbxml|
+        self.databases << DB.new(dbxml)
+      end
+    else
+      self.databases << DB.new(self.path)
     end
   end
 

data/lib/recog/fingerprint.rb

@@ -27,23 +27,49 @@ class Fingerprint
   attr_reader :tests
 
   # @param xml [Nokogiri::XML::Element]
-  def initialize(xml)
+  # @param match_key [String] See Recog::DB
+  # @param protocol [String] Protocol such as ftp, mssql, http, etc.
+  def initialize(xml, match_key=nil, protocol=nil)
+    @match_key = match_key
+    @protocol = protocol
     @name   = parse_description(xml)
     @regex  = create_regexp(xml)
     @params = {}
     @tests = []
 
+    @protocol.downcase! if @protocol
     parse_examples(xml)
     parse_params(xml)
   end
 
+  def output_diag_data(message, data, exception)
+    STDERR.puts message
+    STDERR.puts exception.inspect
+    STDERR.puts "Length:   #{data.length}"
+    STDERR.puts "Encoding: #{data.encoding}"
+    STDERR.puts "Problematic data:\n#{data}"
+    STDERR.puts "Raw bytes:\n#{data.pretty_inspect}\n"
+  end
+
   # Attempt to match the given string.
   #
   # @param match_string [String]
   # @return [Hash,nil] Keys will be host, service, and os attributes
   def match(match_string)
     # match_string.force_encoding('BINARY') if match_string
-    match_data = @regex.match(match_string)
+    begin
+      match_data = @regex.match(match_string)
+    rescue Encoding::CompatibilityError => e
+      begin
+        # Replace invalid UTF-8 characters with spaces, just as DAP does.
+        encoded_str = match_string.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => '')
+        match_data = @regex.match(encoded_str)
+      rescue Exception => e
+        output_diag_data('Exception while re-encoding match_string to UTF-8', match_string, e)
+      end
+    rescue Exception => e
+      output_diag_data('Exception while running regex against match_string', match_string, e)
+    end
     return if match_data.nil?
 
     result = { 'matched' => @name }
@@ -58,6 +84,17 @@ class Fingerprint
         result[k] = match_data[ pos ]
       end
     end
+
+    # Use the protocol specified in the XML database if there isn't one
+    # provided as part of this fingerprint.
+    if @protocol
+      unless result['service.protocol']
+        result['service.protocol'] = @protocol
+      end
+    end
+
+    result['fingerprint_db'] = @match_key if @match_key
+
     return result
   end
 

data/lib/recog/nizer.rb

@@ -20,43 +20,116 @@ class Nizer
   }
 
   @@db_manager = nil
+  @@db_sorted = false
+
+
+  #
+  # Load fingerprints from a specific file or directory
+  # This will not preserve any fingerprints that have already been loaded
+  # @param path [String] Path to file or directory of XML fingerprints
+  def self.load_db(path = nil)
+    if path
+      @@db_manager = Recog::DBManager.new(path)
+    else
+      @@db_manager = Recog::DBManager.new
+    end
+
+    # Sort the databases, no behavior or result change for those calling
+    # Nizer.match or Nizer.multi_match as they have a single DB
+    @@db_manager.databases.sort! { |a, b| b.preference <=> a.preference }
+    @@db_sorted = true
+  end
+
+  #
+  # Destroy the current DBManager object
+  def self.unload_db
+    @@db_manager = nil
+    @@db_sorted = false
+  end
 
+  #
+  # Display the fingerprint databases in the order in which they will be used
+  # to match banners.  This is useful for fingerprint tuning and debugging.
+  def self.display_db_order
+    self.load_db unless @@db_manager
+
+    puts format('%s  %-22s  %-8s %s', 'Preference', 'Database', 'Type', 'Protocol')
+    @@db_manager.databases.each do |db|
+      puts format('%10.3f  %-22s  %-8s %s', db.preference, db.match_key,
+                  db.database_type, db.protocol)
+    end
+  end
+
+  #
+  # 2016.11 - Rewritten to be wrapper around #match_db_all, functionality
+  # and results must remain unchanged.
   #
   # Locate a database that corresponds with the `match_key` and attempt to
-  # find a matching {Fingerprint fingerprint}, stopping at the first hit. Returns `nil`
-  # when no matching database or fingerprint is found.
+  # find a matching {Fingerprint fingerprint}, stopping at the first hit.
+  # Returns `nil` when no matching database or fingerprint is found.
   #
   # @param match_key [String] Fingerprint DB name, e.g. 'smb.native_os'
-  # @return (see Fingerprint#match)
+  # @param match_string [String] String to match
+  # @return (see Fingerprint#match) or nil
   def self.match(match_key, match_string)
-    match_string = match_string.to_s.unpack("C*").pack("C*")
-    @@db_manager ||= Recog::DBManager.new
-    @@db_manager.databases.each do |db|
-      next unless db.match_key == match_key
-      db.fingerprints.each do |fprint|
-        m = fprint.match(match_string)
-        return m if m
-      end
-    end
-    nil
+    filter = { match_key: match_key, multi_match: false }
+    matches = self.match_all_db(match_string, filter)
+
+    matches[0] 
   end
 
+  #
+  # @param match_key [String] Fingerprint DB name, e.g. 'smb.native_os'
+  # @param match_string [String] String to match
+  # @return [Array] Array of Fingerprint#match or empty array
   def self.multi_match(match_key, match_string)
-    match_string = match_string.to_s.unpack("C*").pack("C*")
-    @@db_manager ||= Recog::DBManager.new
+    filter = { match_key: match_key, multi_match: true }
+    self.match_all_db(match_string, filter)
+  end
 
-    matches = Array.new #array to hold all fingerprint matches
+  #
+  # Search all fingerprint dbs and attempt to find matching
+  # {Fingerprint fingerprint}s. It will return the first match found
+  # unless the :multi_match option is used to request all matches.
+  # Returns an array of all matching fingerprints or an empty array.
+  #
+  # @param match_string [String] Service banner to match
+  # @param [Hash] filters This hash contains filters used to limit the
+  #   results to just those from specific types of fingerprints.
+  #   The values that these filters match come from the 'fingerprints' top
+  #   level element in the fingerprint DB XML or, in the case of 'protocol',
+  #   this value can be overridden at the individual fingerprint level by
+  #   setting a value for 'service.protocol'
+  #
+  #   With the exception of 'match_key', the filters below match the
+  #   'fingerprints' attributes with the same name.
+  # @option filters [String] :match_key Value from XML 'matches' or file name
+  # @option filters [String] :database_type fprint db type: service, util.os, etc.
+  # @option filters [String] :protocol Protocol (ftp, smtp, etc.)
+  # @option filters [Boolean] :multi_match Return all matches instead of first
+  # @return [Array] Array of Fingerprint#match or empty array
+  def self.match_all_db(match_string, filters = {})
+    match_string = match_string.to_s.unpack('C*').pack('C*')
+    matches = Array.new # array to hold all fingerprint matches
+
+    self.load_db unless @@db_manager
 
     @@db_manager.databases.each do |db|
-      next unless db.match_key == match_key
-
+      next if filters[:match_key] && !filters[:match_key].eql?(db.match_key)
+      next if filters[:database_type] && !filters[:database_type].eql?(db.database_type)
       db.fingerprints.each do |fp|
         m = fp.match(match_string)
-        matches.push(m) if m
+        if m
+          # Filter on protocol after match since each individual fp
+          # can contain its own 'protocol' value that overrides the
+          # one set at the DB level.
+          matches.push(m) unless filters[:protocol] && !filters[:protocol].eql?(m['service.protocol'])
+          return matches unless filters[:multi_match]
+        end
       end
     end
 
-    return matches
+    matches
   end
 
   #

data/lib/recog/version.rb

@@ -1,3 +1,3 @@
 module Recog
-  VERSION = '2.0.24'
+  VERSION = '2.1.0'
 end

data/spec/lib/fingerprint_self_test_spec.rb

@@ -21,6 +21,13 @@ describe Recog::DB do
         expect(db.match_key).not_to be_empty
       end
 
+      it "has valid 'preference' value" do
+          # Reserve values below 0.10 and above 0.90 for users
+          # See xml/fingerprints.xsd
+          expect(db.preference.class).to be ::Float
+          expect(db.preference).to be_between(0.10, 0.90)
+      end
+
       db.fingerprints.each_index do |i|
         fp = db.fingerprints[i]
 

data/spec/lib/recog/nizer_spec.rb

@@ -1,6 +1,12 @@
 require 'recog'
 require 'yaml'
 
+
+VALID_FILTER = {match_key: 'smb.native_os', protocol: 'smb', database_type: 'util.os'}
+NOMATCH_MATCH_KEY = {match_key: 'no_such_987', protocol: 'smb', database_type: 'util.os'}
+NOMATCH_PROTO = {match_key: 'smb.native_os', protocol: 'no_such_987', database_type: 'util.os'}
+NOMATCH_TYPE = {match_key: 'smb.native_os', protocol: 'smb', database_type: 'no_such_987'}
+
 describe Recog::Nizer do
   subject { described_class }
 
@@ -24,6 +30,15 @@ describe Recog::Nizer do
           end
         end
 
+        let(:nomatch_result) { subject.match('smb.native_os', 'no_such_987_76tgklh') }
+        it "returns a nil when data cannot be matched" do
+          expect(nomatch_result).to be_nil
+        end
+
+        let(:invalid_db_result) { subject.match('no_such_987', data) }
+        it "returns a nil when match_key search doesn't match" do
+          expect(invalid_db_result).to be_nil
+        end
       end
     end
 
@@ -36,6 +51,83 @@ describe Recog::Nizer do
     end
   end
 
+  describe ".match_all_db" do
+    File.readlines(File.expand_path(File.join('spec', 'data', 'smb_native_os.txt'))).each do |line|
+      data = line.strip
+      context "with smb_native_os:#{data}" do
+        let(:match_all_result) { subject.match_all_db(data, VALID_FILTER) }
+
+        it "returns an array" do
+          expect(match_all_result.class).to eq(::Array)
+        end
+
+        it "returns a successful match" do
+          expect(match_all_result[0]['matched']).to match(/^[A-Z]/)
+        end
+
+        it "correctly matches service or os" do
+          if data =~ /^Windows/
+            expect(match_all_result[0]['os.product']).to match(/^Windows/)
+          end
+        end
+
+        it "correctly matches protocol" do
+          expect(match_all_result[0]['service.protocol']).to eq('smb')
+        end
+
+        let(:no_filter_result) { subject.match_all_db(data) }
+        it "returns an array when searching without a filter" do
+          expect(no_filter_result.class).to eq(::Array)
+        end
+
+        it "returns a successful match when searching without a filter" do
+          expect(no_filter_result[0]['matched']).to match(/^[A-Z]/)
+        end
+
+        it "correctly matches service or os when searching without a filter" do
+          if data =~ /^Windows/
+            expect(no_filter_result[0]['os.product']).to match(/^Windows/)
+          end
+        end
+
+        let(:nomatch_db_result) { subject.match_all_db(data, NOMATCH_MATCH_KEY) }
+        it "returns an array when match_key search doesn't match" do
+          expect(nomatch_db_result.class).to eq(::Array)
+        end
+        it "returns an empty array when match_key search doesn't match" do
+          expect(nomatch_db_result).to be_empty
+        end
+
+        let(:nomatch_proto_result) { subject.match_all_db(data, NOMATCH_PROTO) }
+        it "returns an array when protocol search doesn't match" do
+          expect(nomatch_proto_result.class).to eq(::Array)
+        end
+        it "returns an empty array when protocol search doesn't match" do
+          expect(nomatch_proto_result).to be_empty
+        end
+
+        let(:nomatch_type_result) { subject.match_all_db(data, NOMATCH_TYPE) }
+        it "returns an array when database_type search doesn't match" do
+          expect(nomatch_type_result.class).to eq(::Array)
+        end
+        it "returns an empty array when database_type search doesn't match" do
+          expect(nomatch_proto_result).to be_empty
+        end
+      end
+    end
+
+    line = 'non-existent'
+    context "with non-existent match" do
+      let(:match_result) {subject.match_all_db(line) }
+      it "returns an array" do
+        expect(match_result.class).to eq(::Array)
+      end
+      it "returns an empty array" do
+        expect(match_result).to be_empty
+      end
+    end
+  end
+
   describe ".multi_match" do
     File.readlines(File.expand_path(File.join('spec', 'data', 'smb_native_os.txt'))).each do |line|
       data = line.strip
@@ -58,8 +150,46 @@ describe Recog::Nizer do
             end
           end
         end
+
+        let(:invalid_db_result) { subject.multi_match('no_such_987', data) }
+        it "returns an array when passed an invalid match_key" do
+          expect(invalid_db_result.class).to eq(::Array)
+        end
+
+        it "returns an empty array when passed an invalid match_key" do
+          expect(invalid_db_result).to be_empty
+        end
+      end
+
+    end
+
+    data = 'Windows Server 2012 R2 Standard 9600'
+    context "with {data}" do
+      let(:match_results) {subject.multi_match('smb.native_os', data) }
+
+      it "returns an array" do
+        expect(match_results.class).to eq(::Array)
+      end
+
+      it "returns at least two successful matches" do
+        expect(match_results.size).to be > 1
+      end
+
+      it "correctly matches os.product for all matches" do
+        match_results do |mr|
+          if data =~ /^Windows/
+            expect(mr['os.product']).to match(/^Windows/)
+          end
+        end
       end
 
+      it "correctly matches protocol for all matches" do
+        match_results do |mr|
+          if data =~ /^Windows/
+            expect(mr['service.protocol']).to eq('smb')
+          end
+        end
+      end
     end
 
     line = 'non-existent'
@@ -77,7 +207,6 @@ describe Recog::Nizer do
   end
 
   describe ".best_os_match" do
-
     # Demonstrates how this method picks up additional attributes from other members of the winning
     # os.product match group and applies them to the result.
     matches1 = YAML.load(File.read(File.expand_path(File.join('spec', 'data', 'best_os_match_1.yml'))))
@@ -134,8 +263,7 @@ describe Recog::Nizer do
 
   end
 
- describe ".best_service_match" do
-
+  describe ".best_service_match" do
     # Demonstrates how this method picks up additional attributes from other members of the winning
     # service.product match group and applies them to the result.
     matches1 = YAML.load(File.read(File.expand_path(File.join('spec', 'data', 'best_service_match_1.yml'))))
@@ -165,4 +293,38 @@ describe Recog::Nizer do
 
   end
 
+
+  describe '.load_db' do
+    file_path = File.expand_path(File.join('spec', 'data', 'test_fingerprints.xml'))
+    context "with #{file_path}" do
+      let(:fp_db) { subject.load_db(file_path) }
+      it "loads without error" do
+        expect(fp_db).to  be true
+        subject.unload_db()
+      end
+    end
+
+    context "with no path specified" do
+      let(:fp_db) { subject.load_db }
+      it "loads without error" do
+        expect(fp_db).to  be true
+        subject.unload_db()
+      end
+    end
+
+    context "with empty file path" do
+      it "raises an error" do
+        expect { subject.load_db('') }.to raise_error(Errno::ENOENT)
+        subject.unload_db()
+      end
+    end
+
+    context "with invalid file path" do
+      it "raises an error" do
+        expect { subject.load_db('no_such_987_file_path') }.to raise_error(Errno::ENOENT)
+        subject.unload_db()
+      end
+    end
+  end
+
 end