diff --git a/documentation/modules/auxiliary/gather/shodan_honeyscore.md b/documentation/modules/auxiliary/gather/shodan_honeyscore.md new file mode 100644 index 0000000000..ad9c4c989f --- /dev/null +++ b/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 ` + 4. Do: `set SHODAN_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 + ``` diff --git a/modules/auxiliary/gather/shodan_honeyscore.rb b/modules/auxiliary/gather/shodan_honeyscore.rb new file mode 100644 index 0000000000..d792d6029d --- /dev/null +++ b/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