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, 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).
- 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).
- 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.