shodan

class shodan.Shodan(key, proxies=None)[source]

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)[source]
count(query, facets=None)[source]

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)[source]

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.

add_alert_notifier(aid, nid)[source]

Enable the given notifier for an alert that has triggers enabled.

alert_triggers()[source]

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

Returns:

A list of triggers

alerts(aid=None, include_expired=True)[source]

List all of the active alerts that the user created.

count(query, facets=None)[source]

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)[source]

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)[source]

Delete the alert with the given ID.

disable_alert_trigger(aid, trigger)[source]

Disable the given trigger on the alert.

edit_alert(aid, ip)[source]

Edit the IPs that should be monitored by the alert.

Parameters:
  • aid – Alert ID

  • ip (str OR list of str) – Network range(s) to monitor

Returns:

A dict describing the alert

enable_alert_trigger(aid, trigger)[source]

Enable the given trigger on the alert.

host(ips, history=False, minify=False)[source]

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.

ignore_alert_trigger_notification(aid, trigger, ip, port, vulns=None)[source]

Ignore trigger notifications for the provided IP and port.

info()[source]

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()[source]

Get a list of ports that Shodan crawls

Returns:

An array containing the ports that Shodan crawls for.

protocols()[source]

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')[source]

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)[source]

Search the directory of saved search queries in Shodan.

Parameters:

size (int) – The number of tags to return

Returns:

A list of tags.

remove_alert_notifier(aid, nid)[source]

Remove the given notifier for an alert that has triggers enabled.

scan(ips, force=False)[source]

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)[source]

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)[source]

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)[source]

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, fields=None)[source]

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

  • fields (str) – (optional) List of properties that should get returned. This option is mutually exclusive with the “minify” parameter

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, fields=None)[source]

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 (bool) – (optional) Whether to minify the banner and only return the important data

  • retries (int) – (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_facets()[source]

Returns a list of search facets that can be used to get aggregate information about a search query.

Returns:

A list of strings where each is a facet name

search_filters()[source]

Returns a list of search filters that are available.

Returns:

A list of strings where each is a filter name

search_tokens(query)[source]

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()[source]

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.

unignore_alert_trigger_notification(aid, trigger, ip, port)[source]

Re-enable trigger notifications for the provided IP and port

Exceptions

exception shodan.APIError(value)[source]

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