Land #8137 shodan honeyscore module

documentation/modules/auxiliary/gather/shodan_honeyscore.md

@@ -0,0 +1,52 @@
+The `shodan_honeyscore` module utilizes the [Shodan](https://www.shodan.io/) API to determine whether or not a server is a honeypot or not. 
+When setting the module options, we aren't directly requesting `TARGET`, we are requesting the shodan API to analyze `TARGET` and return a honeyscore from 0.0 to 1.0. 0.0 being `not a honeypot` and 1.0 being a `honeypot`. The original website for the honeypot system can be found here: https://honeyscore.shodan.io/. 
+
+#### NOTE: 
+In order for this module to function properly, a Shodan API key is needed. You can register for a free acount here: https://account.shodan.io/register
+
+## Verification Steps
+
+  1. Start `msfconsole`
+  2. Do: `use auxiliary/gather/shodan_honeyscore`
+  3. Do: `set TARGET <targetip>`
+  4. Do: `set SHODAN_APIKEY <your apikey>`
+  5. Do: `run`
+  6. If the API is up, you should recieve a score from 0.0 to 1.0.
+
+## Options
+
+  **TARGET**
+  
+  The remote host to request the API to scan.
+  
+  **SHODAN_APIKEY**
+
+  This is the API key you recieve when signing up for a Shodan account. It should be a 32 character string of random letters and numbers.
+  
+
+## Scenarios
+
+Running the module against a real system (in this case, the Google DNS server):
+
+  ```
+  msf > use auxiliary/gather/shodan_honeyscore
+msf auxiliary(shodan_honeyscore) > options
+
+Module options (auxiliary/gather/shodan_honeyscore):
+
+   Name           Current Setting  Required  Description
+   ----           ---------------  --------  -----------
+   SHODAN_APIKEY                   yes       The SHODAN API key
+   TARGET                          yes       The target to get the score of
+
+msf auxiliary(shodan_honeyscore) > set TARGET 8.8.8.8
+TARGET => 8.8.8.8
+msf auxiliary(shodan_honeyscore) > set SHODAN_APIKEY [redacted]
+SHODAN_APIKEY => [redacted]
+msf auxiliary(shodan_honeyscore) > run
+
+[*] Scanning 8.8.8.8
+[-] 8.8.8.8 is not a honeypot
+[*] 8.8.8.8 honeyscore: 0.0/1.0
+[*] Auxiliary module execution completed
+  ```

modules/auxiliary/gather/shodan_honeyscore.rb

@@ -0,0 +1,96 @@
+##
+# This module requires Metasploit: http://metasploit.com/download
+# Current source: https://github.com/rapid7/metasploit-framework
+##
+
+require 'msf/core'
+
+class MetasploitModule < Msf::Auxiliary
+
+  def initialize(info = {})
+    super(update_info(info,
+      'Name' => 'Shodan Honeyscore Client',
+      'Description' => %q{
+        This module uses the shodan API to check
+        if a server is a honeypot or not. The api
+        returns a score from 0.0 to 1.0. 1.0 being a honeypot.
+        A shodan API key is needed for this module to work properly.
+
+        If you don't have an account, go here to register:
+        https://account.shodan.io/register
+        For more info on how their honeyscore system works, go here:
+        https://honeyscore.shodan.io/
+      },
+      'Author' =>
+        [ 'thecarterb' ],  # Thanks to @rwhitcroft, @h00die and @wvu-r7 for the improvements and review!
+      'License' => MSF_LICENSE,
+      'References' =>
+        [
+          [ 'URL', 'https://honeyscore.shodan.io/']
+        ]
+      )
+    )
+
+    deregister_options('RHOST', 'SSL', 'DOMAIN', 'DigestAuthIIS', 'NTLM::SendLM',
+      'NTLM::SendNTLM', 'VHOST', 'RPORT', 'NTLM::SendSPN', 'NTLM::UseLMKey',
+      'NTLM::UseNTLM2_session', 'NTLM::UseNTLMv2')
+
+    register_options(
+      [
+        OptString.new('TARGET', [true, 'The target to get the score of']),
+        OptString.new('SHODAN_APIKEY', [true, 'The SHODAN API key'])
+      ], self.class)
+  end
+
+  def print_score(score)
+    tgt = datastore['TARGET']
+    print_status("#{tgt} honeyscore: #{score}/1.0")
+  end
+
+  def run
+    key = datastore['SHODAN_APIKEY']
+
+    # Check the length of the key (should be 32 chars)
+    if key.length != 32
+      print_error('Invalid API key (Not long enough)')
+      return
+    end
+
+    tgt = datastore['TARGET']
+    print_status("Scanning #{tgt}")
+    cli = Rex::Proto::Http::Client.new('api.shodan.io', 443, {}, true)
+    cli.connect
+    req = cli.request_cgi({
+      'uri'    => "/labs/honeyscore/#{tgt}?key=#{key}",
+      'method' => 'GET'
+      })
+    res = cli.send_recv(req)
+    cli.close
+    if res.nil?
+      fail_with(Failure::Unknown, 'Unable to connect to shodan')
+    end
+
+    if res.code != 200
+      print_error('Shodan did not respond in an expected way. Check your api key')
+      return
+    end
+
+    score = res.body.to_f  # Change the score to a float to be able to determine value in the checks
+
+    if score == 0
+      print_error("#{tgt} is not a honeypot")
+    elsif score < 0.4 && score != 0.0
+      print_error("#{tgt} is probably not a honeypot")
+    elsif score > 0.4 && score < 0.6
+      print_status("#{tgt} might be a honeypot")
+    elsif score > 0.6 && score < 1.0
+      print_good("#{tgt} is probably a honeypot")
+    elsif score == 1.0
+      print_good("#{tgt} is definitely a honeypot")
+    else  # We shouldn't ever get here as the previous checks should catch an unexpected response
+      print_error('An unexpected error occured.')
+      return
+    end
+    print_score(score)
+  end
+end