Shodan Search - Metasploit


This page contains detailed information about how to use the auxiliary/gather/shodan_search metasploit module. For list of all metasploit modules, visit the Metasploit Module Library.

Table Of Contents
hide

Module Overview

Name: Shodan Search
Module: auxiliary/gather/shodan_search
Source code: modules/auxiliary/gather/shodan_search.rb
Disclosure date: -
Last modification time: 2021-05-21 20:46:23 +0000
Supported architecture(s): -
Supported platform(s): -
Target service / protocol: http, https
Target network port(s): 80, 443, 3000, 8000, 8008, 8080, 8443, 8880, 8888
List of CVEs: -

This module uses the Shodan API to search Shodan. Accounts are free and an API key is required to use this module. Output from the module is displayed to the screen and can be saved to a file or the MSF database. NOTE: SHODAN filters (i.e. port, hostname, os, geo, city) can be used in queries, but there are limitations when used with a free API key. Please see the Shodan site for more information. Shodan website: https://www.shodan.io/ API: https://developer.shodan.io/api

Module Ranking and Traits

Module Ranking:

  • normal: The exploit is otherwise reliable, but depends on a specific version and can't (or doesn't) reliably autodetect. More information about ranking can be found here.

Basic Usage

msf > use auxiliary/gather/shodan_search
msf auxiliary(shodan_search) > show targets
    ... a list of targets ...
msf auxiliary(shodan_search) > set TARGET target-id
msf auxiliary(shodan_search) > show options
    ... show and set options ...
msf auxiliary(shodan_search) > exploit

Required Options

  • SHODAN_APIKEY: The SHODAN API key

  • QUERY: Keywords you want to search for

Go back to menu.

Msfconsole Usage

Here is how the gather/shodan_search auxiliary module looks in the msfconsole:

msf6 > use auxiliary/gather/shodan_search

msf6 auxiliary(gather/shodan_search) > show info

       Name: Shodan Search
     Module: auxiliary/gather/shodan_search
    License: Metasploit Framework License (BSD)
       Rank: Normal

Provided by:
  John H Sawyer <[email protected]>
  sinn3r <[email protected]>

Check supported:
  No

Basic options:
  Name           Current Setting  Required  Description
  ----           ---------------  --------  -----------
  DATABASE       false            no        Add search results to the database
  MAXPAGE        1                yes       Max amount of pages to collect
  OUTFILE                         no        A filename to store the list of IPs
  QUERY                           yes       Keywords you want to search for
  REGEX          .*               yes       Regex search for a specific IP/City/Country/Hostname
  SHODAN_APIKEY                   yes       The SHODAN API key

Description:
  This module uses the Shodan API to search Shodan. Accounts are free 
  and an API key is required to use this module. Output from the 
  module is displayed to the screen and can be saved to a file or the 
  MSF database. NOTE: SHODAN filters (i.e. port, hostname, os, geo, 
  city) can be used in queries, but there are limitations when used 
  with a free API key. Please see the Shodan site for more 
  information. Shodan website: https://www.shodan.io/ API: 
  https://developer.shodan.io/api

Module Options

This is a complete list of options available in the gather/shodan_search auxiliary module:

msf6 auxiliary(gather/shodan_search) > show options

Module options (auxiliary/gather/shodan_search):

   Name           Current Setting  Required  Description
   ----           ---------------  --------  -----------
   DATABASE       false            no        Add search results to the database
   MAXPAGE        1                yes       Max amount of pages to collect
   OUTFILE                         no        A filename to store the list of IPs
   QUERY                           yes       Keywords you want to search for
   REGEX          .*               yes       Regex search for a specific IP/City/Country/Hostname
   SHODAN_APIKEY                   yes       The SHODAN API key

Advanced Options

Here is a complete list of advanced options supported by the gather/shodan_search auxiliary module:

msf6 auxiliary(gather/shodan_search) > show advanced

Module advanced options (auxiliary/gather/shodan_search):

   Name                  Current Setting                                     Required  Description
   ----                  ---------------                                     --------  -----------
   DOMAIN                WORKSTATION                                         yes       The domain to use for Windows authentication
   DigestAuthIIS         true                                                no        Conform to IIS, should work for most servers. Only set to false for non-IIS servers
   FingerprintCheck      true                                                no        Conduct a pre-exploit fingerprint verification
   HttpClientTimeout                                                         no        HTTP connection and receive timeout
   HttpPassword                                                              no        The HTTP password to specify for authentication
   HttpRawHeaders                                                            no        Path to ERB-templatized raw headers to append to existing headers
   HttpTrace             false                                               no        Show the raw HTTP requests and responses
   HttpTraceColors       red/blu                                             no        HTTP request and response colors for HttpTrace (unset to disable)
   HttpTraceHeadersOnly  false                                               no        Show HTTP headers only in HttpTrace
   HttpUsername                                                              no        The HTTP username to specify for authentication
   SSLVersion            Auto                                                yes       Specify the version of SSL/TLS to be used (Auto, TLS and SSL23 are auto-negotiate) (Accepted: Auto, TLS, SSL23, SSL3, TLS1, TLS1.1, TLS1.2)
   UserAgent             Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)  no        The User-Agent header to use for all requests
   VERBOSE               false                                               no        Enable detailed status messages
   WORKSPACE                                                                 no        Specify the workspace for this module

Auxiliary Actions

This is a list of all auxiliary actions that the gather/shodan_search module can do:

msf6 auxiliary(gather/shodan_search) > show actions

Auxiliary actions:

   Name  Description
   ----  -----------

Evasion Options

Here is the full list of possible evasion options supported by the gather/shodan_search auxiliary module in order to evade defenses (e.g. Antivirus, EDR, Firewall, NIDS etc.):

msf6 auxiliary(gather/shodan_search) > show evasion

Module evasion options:

   Name                          Current Setting  Required  Description
   ----                          ---------------  --------  -----------
   HTTP::header_folding          false            no        Enable folding of HTTP headers
   HTTP::method_random_case      false            no        Use random casing for the HTTP method
   HTTP::method_random_invalid   false            no        Use a random invalid, HTTP method for request
   HTTP::method_random_valid     false            no        Use a random, but valid, HTTP method for request
   HTTP::pad_fake_headers        false            no        Insert random, fake headers into the HTTP request
   HTTP::pad_fake_headers_count  0                no        How many fake headers to insert into the HTTP request
   HTTP::pad_get_params          false            no        Insert random, fake query string variables into the request
   HTTP::pad_get_params_count    16               no        How many fake query string variables to insert into the request
   HTTP::pad_method_uri_count    1                no        How many whitespace characters to use between the method and uri
   HTTP::pad_method_uri_type     space            no        What type of whitespace to use between the method and uri (Accepted: space, tab, apache)
   HTTP::pad_post_params         false            no        Insert random, fake post variables into the request
   HTTP::pad_post_params_count   16               no        How many fake post variables to insert into the request
   HTTP::pad_uri_version_count   1                no        How many whitespace characters to use between the uri and version
   HTTP::pad_uri_version_type    space            no        What type of whitespace to use between the uri and version (Accepted: space, tab, apache)
   HTTP::uri_dir_fake_relative   false            no        Insert fake relative directories into the uri
   HTTP::uri_dir_self_reference  false            no        Insert self-referential directories into the uri
   HTTP::uri_encode_mode         hex-normal       no        Enable URI encoding (Accepted: none, hex-normal, hex-noslashes, hex-random, hex-all, u-normal, u-all, u-random)
   HTTP::uri_fake_end            false            no        Add a fake end of URI (eg: /%20HTTP/1.0/../../)
   HTTP::uri_fake_params_start   false            no        Add a fake start of params to the URI (eg: /%3fa=b/../)
   HTTP::uri_full_url            false            no        Use the full URL for all HTTP requests
   HTTP::uri_use_backslashes     false            no        Use back slashes instead of forward slashes in the uri
   HTTP::version_random_invalid  false            no        Use a random invalid, HTTP version for request
   HTTP::version_random_valid    false            no        Use a random, but valid, HTTP version for request

Go back to menu.

Error Messages

This module may fail with the following error messages:

Error Messages

Check for the possible causes from the code snippets below found in the module source code. This can often times help in identifying the root cause of the problem.

401 Unauthorized. Your SHODAN_APIKEY is invalid

Here is a relevant code snippet related to the "401 Unauthorized. Your SHODAN_APIKEY is invalid" error message:

61:	        'page' => page.to_s
62:	      }
63:	    })
64:	
65:	    if res && res.code == 401
66:	      fail_with(Failure::BadConfig, '401 Unauthorized. Your SHODAN_APIKEY is invalid')
67:	    end
68:	
69:	    # Check if we can resolve host, got a response,
70:	    # then parse the JSON, and return it
71:	    if res

server_response_error

Here is a relevant code snippet related to the "server_response_error" error message:

70:	    # then parse the JSON, and return it
71:	    if res
72:	      results = ActiveSupport::JSON.decode(res.body)
73:	      return results
74:	    else
75:	      return 'server_response_error'
76:	    end
77:	  end
78:	
79:	  # save output to file
80:	  def save_output(data)

Shodan API key should be 32 characters a-z,A-Z,0-9.

Here is a relevant code snippet related to the "Shodan API key should be 32 characters a-z,A-Z,0-9." error message:

96:	  end
97:	
98:	  def run
99:	    # check our API key is somewhat sane
100:	    unless /^[a-z\d]{32}$/i.match?(datastore['SHODAN_APIKEY'])
101:	      fail_with(Failure::BadConfig, 'Shodan API key should be 32 characters a-z,A-Z,0-9.')
102:	    end
103:	
104:	    # check to ensure api.shodan.io is resolvable
105:	    unless shodan_resolvable?
106:	      print_error("Unable to resolve api.shodan.io")

Unable to resolve api.shodan.io

Here is a relevant code snippet related to the "Unable to resolve api.shodan.io" error message:

101:	      fail_with(Failure::BadConfig, 'Shodan API key should be 32 characters a-z,A-Z,0-9.')
102:	    end
103:	
104:	    # check to ensure api.shodan.io is resolvable
105:	    unless shodan_resolvable?
106:	      print_error("Unable to resolve api.shodan.io")
107:	      return
108:	    end
109:	
110:	    # create our Shodan request parameters
111:	    query = datastore['QUERY']

error

Here is a relevant code snippet related to the "error" error message:

116:	    results = []
117:	    results[0] = shodan_query(apikey, query, 1)
118:	
119:	    if results[0]['total'].nil? || results[0]['total'] == 0
120:	      msg = "No results."
121:	      if results[0]['error'].to_s.length > 0
122:	        msg << " Error: #{results[0]['error']}"
123:	      end
124:	      print_error(msg)
125:	      return
126:	    end

Error: <VALUE>

Here is a relevant code snippet related to the "Error: <VALUE>" error message:

117:	    results[0] = shodan_query(apikey, query, 1)
118:	
119:	    if results[0]['total'].nil? || results[0]['total'] == 0
120:	      msg = "No results."
121:	      if results[0]['error'].to_s.length > 0
122:	        msg << " Error: #{results[0]['error']}"
123:	      end
124:	      print_error(msg)
125:	      return
126:	    end
127:

Go back to menu.

Go back to menu.

See Also

Check also the following modules related to this module:

Authors

  • John H Sawyer <john[at]sploitlab.com>
  • sinn3r

Version

This page has been produced using Metasploit Framework version 6.1.27-dev. For more modules, visit the Metasploit Module Library.

Go back to menu.