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
-
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
-
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)[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).
-
queries_search(query, page=1)[source]¶ 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
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)[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
- 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)[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
skip (int) – (optional) Number of results to skip
- 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.