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).
-
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).
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.
- ips (str or dict) –
-
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.