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.

alert_triggers()

Return a list of available triggers that can be enabled for alerts.

Returns:A list of triggers

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)

Create a network alert/ private firehose for the specified IP range(s)

Parameters:

• name (str) – Name of the alert
• ip (str OR list of str) – Network range(s) to monitor

Returns:

A dict describing the alert

delete_alert(aid)

Delete the alert with the given ID.

disable_alert_trigger(aid, trigger)

Disable the given trigger on the alert.

enable_alert_trigger(aid, trigger)

Enable the given trigger on the alert.

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).

queries_search(query, page=1)

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:size (int) – 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.

scans(page=1)

Get a list of scans submitted

Parameters:page (int) – Page through the list of scans 100 results at a time

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.