shodan

class shodan.Shodan(key, proxies=None)

Wrapper around the Shodan REST and Streaming APIs

Parameters:

key (str) – The Shodan API key that can be obtained from your account page (https://account.shodan.io)
Variables:
  • exploits – An instance of shodan.Shodan.Exploits that provides access to the Exploits REST API.
  • stream – An instance of shodan.Shodan.Stream that provides access to the Streaming API.
class Exploits(parent)
count(query, facets=None)

Search the entire Shodan Exploits archive but only return the total # of results, not the actual exploits.

Parameters:
  • query (str) – The exploit search query; same syntax as website.
  • facets (str) – A list of strings or tuples to get summary information on.
Returns:

dict – a dictionary containing the results of the search.
search(query, page=1, facets=None)

Search the entire Shodan Exploits archive using the same query syntax as the website.

Parameters:
  • query (str) – The exploit search query; same syntax as website.
  • facets (str) – A list of strings or tuples to get summary information on.
  • page (int) – The page number to access.
Returns:

dict – a dictionary containing the results of the search.
alerts(aid=None, include_expired=True)

List all of the active alerts that the user created.

count(query, facets=None)

Returns the total number of search results for the query.

Parameters:
  • query (str) – Search query; identical syntax to the website
  • facets (str) – (optional) A list of properties to get summary information on
Returns:

A dictionary with 1 main property: total. If facets have been provided then another property called “facets” will be available at the top-level of the dictionary. Visit the website for more detailed information.
create_alert(name, ip, expires=0)

Search the directory of saved search queries in Shodan.

Parameters:query – The number of tags to return
Returns:A list of tags.
delete_alert(aid)

Delete the alert with the given ID.

host(ips, history=False, minify=False)

Get all available information on an IP.

Parameters:
  • ip (str) – IP of the computer
  • history (bool) – (optional) True if you want to grab the historical (non-current) banners for the host, False otherwise.
  • minify (bool) – (optional) True to only return the list of ports and the general host information, no banners, False otherwise.
info()

Returns information about the current API key, such as a list of add-ons and other features that are enabled for the current user’s API plan.

ports()

Get a list of ports that Shodan crawls

Returns:An array containing the ports that Shodan crawls for.
protocols()

Get a list of protocols that the Shodan on-demand scanning API supports.

Returns:A dictionary containing the protocol name and description.
queries(page=1, sort='timestamp', order='desc')

List the search queries that have been shared by other users.

Parameters:
  • page (int) – Page number to iterate over results; each page contains 10 items
  • sort (str) – Sort the list based on a property. Possible values are: votes, timestamp
  • order (str) – Whether to sort the list in ascending or descending order. Possible values are: asc, desc
Returns:

A list of saved search queries (dictionaries).

Search the directory of saved search queries in Shodan.

Parameters:
  • query (str) – The search string to look for in the search query
  • page (int) – Page number to iterate over results; each page contains 10 items
Returns:

A list of saved search queries (dictionaries).
queries_tags(size=10)

Search the directory of saved search queries in Shodan.

Parameters:query – The number of tags to return
Returns:A list of tags.
scan(ips, force=False)

Scan a network using Shodan

Parameters:
  • ips (str or dict) –

    A list of IPs or netblocks in CIDR notation or an object structured like: {

    ”9.9.9.9”: [
    (443, “https”), (8080, “http”)

    ], “1.1.1.0/24”: [

    (503, “modbus”)

    ]

    }

  • force (bool) – Whether or not to force Shodan to re-scan the provided IPs. Only available to enterprise users.
Returns:

A dictionary with a unique ID to check on the scan progress, the number of IPs that will be crawled and how many scan credits are left.
scan_internet(port, protocol)

Scan a network using Shodan

Parameters:
  • port (str) – The port that should get scanned.
  • port – The name of the protocol as returned by the protocols() method.
Returns:

A dictionary with a unique ID to check on the scan progress.
scan_status(scan_id)

Get the status information about a previously submitted scan.

Parameters:id (str) – The unique ID for the scan that was submitted
Returns:A dictionary with general information about the scan, including its status in getting processed.
search(query, page=1, limit=None, offset=None, facets=None, minify=True)

Search the SHODAN database.

Parameters:
  • query (str) – Search query; identical syntax to the website
  • page (int) – (optional) Page number of the search results
  • limit (int) – (optional) Number of results to return
  • offset (int) – (optional) Search offset to begin getting results from
  • facets (str) – (optional) A list of properties to get summary information on
  • minify (bool) – (optional) Whether to minify the banner and only return the important data
Returns:

A dictionary with 2 main items: matches and total. If facets have been provided then another property called “facets” will be available at the top-level of the dictionary. Visit the website for more detailed information.
search_cursor(query, minify=True, retries=5)

Search the SHODAN database.

This method returns an iterator that can directly be in a loop. Use it when you want to loop over all of the results of a search query. But this method doesn’t return a “matches” array or the “total” information. And it also can’t be used with facets, it’s only use is to iterate over results more easily.

Parameters:
  • query (str) – Search query; identical syntax to the website
  • minify (int) – (optional) Whether to minify the banner and only return the important data
  • retries – (optional) How often to retry the search in case it times out
Returns:

A search cursor that can be used as an iterator/ generator.
search_tokens(query)

Returns information about the search query itself (filters used etc.)

Parameters:query (str) – Search query; identical syntax to the website
Returns:A dictionary with 4 main properties: filters, errors, attributes and string.
services()

Get a list of services that Shodan crawls

Returns:A dictionary containing the ports/ services that Shodan crawls for. The key is the port number and the value is the name of the service.

Exceptions

exception shodan.APIError(value)

This exception gets raised whenever a non-200 status code was returned by the Shodan API.