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

  add_alert_notifier(aid, nid)

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

  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.

  edit_alert(aid, ip)

    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)

    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.

  ignore_alert_trigger_notification(aid, trigger, ip, port)

    Ignore trigger notifications for the provided IP and port.

  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.

  remove_alert_notifier(aid, nid)

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

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

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

    Returns a list of search filters that are available.

    Returns

      A list of strings where each is a filter name

  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.

  unignore_alert_trigger_notification(aid, trigger, ip, port)

    Re-enable trigger notifications for the provided IP and port

## Exceptions

exception shodan.APIError(value)

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