# 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, skip=0)

    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
    - skip (int) – (optional) Number of results to skip

    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.