class Shodanz::API::REST
The REST
API
provides methods to search Shodan, look up hosts, get summary information on queries and a variety of other utilities. This requires you to have an API
key which you can get from Shodan.
@author Kent 'picat' Gruber
Constants
Attributes
@return [String]
Public Class Methods
@param key [String] SHODAN API
key, defaulted to the SHODAN_API_KEY enviroment variable.
# File lib/shodanz/apis/rest.rb, line 23 def initialize(key: ENV['SHODAN_API_KEY']) @url = URL @client = Async::HTTP::Client.new(Async::HTTP::Endpoint.parse(@url)) self.key = key warn 'No key has been found or provided!' unless key? end
Public Instance Methods
Use this method to obtain a list of search queries that users have saved in Shodan.
# File lib/shodanz/apis/rest.rb, line 135 def community_queries(**params) get('shodan/query', **params) end
Use this method to request Shodan to crawl the Internet for a specific port.
This method is restricted to security researchers and companies with a Shodan Data license. To apply for access to this method as a researcher, please email jmath@shodan.io with information about your project. Access is restricted to prevent abuse.
Example¶ ↑
rest_api.crawl_for(port: 80, protocol: "http")
# File lib/shodanz/apis/rest.rb, line 123 def crawl_for(**params) params[:query] = '' params = turn_into_query(**params) post('shodan/scan/internet', **params) end
Calculates a honeypot probability score ranging from 0 (not a honeypot) to 1.0 (is a honeypot).
# File lib/shodanz/apis/rest.rb, line 182 def honeypot_score(ip) get("labs/honeyscore/#{ip}") end
Returns all services that have been found on the given host IP. @param ip [String] @option params [Hash] @return [Hash]
Examples¶ ↑
# Typical usage. rest_api.host("8.8.8.8") # All historical banners should be returned. rest_api.host("8.8.8.8", history: true) # Only return the list of ports and the general host information, no banners. rest_api.host("8.8.8.8", minify: true)
# File lib/shodanz/apis/rest.rb, line 51 def host(ip, **params) get("shodan/host/#{ip}", **params) end
This method behaves identical to “/shodan/host/search” with the only difference that this method does not return any host results, it only returns the total number of results that matched the query and any facet information that was requested. As a result this method does not consume query credits.
Examples¶ ↑
rest_api.host_count("apache") rest_api.host_count("apache", country: "US") rest_api.host_count("apache", country: "US", state: "MI") rest_api.host_count("apache", country: "US", state: "MI", city: "Detroit")
# File lib/shodanz/apis/rest.rb, line 65 def host_count(query = '', facets: {}, **params) params[:query] = query params = turn_into_query(**params) facets = turn_into_facets(**facets) get('shodan/host/count', **params.merge(**facets)) end
Search Shodan using the same query syntax as the website and use facets to get summary information for different properties.
Example¶ ↑
rest_api.host_search("apache", country: "US", facets: { city: "Detroit" }, page: 1, minify: false)
# File lib/shodanz/apis/rest.rb, line 76 def host_search(query = '', facets: {}, page: 1, minify: true, **params) params[:query] = query params = turn_into_query(**params) facets = turn_into_facets(**facets) params[:page] = page params[:minify] = minify get('shodan/host/search', **params.merge(**facets)) end
This method lets you determine which filters are being used by the query string and what parameters were provided to the filters.
# File lib/shodanz/apis/rest.rb, line 87 def host_search_tokens(query = '', **params) params[:query] = query params = turn_into_query(**params) get('shodan/host/search/tokens', **params) end
Shows the HTTP headers that your client sends when connecting to a webserver.
# File lib/shodanz/apis/rest.rb, line 171 def http_headers get('tools/httpheaders') end
Check if there's an API
key.
# File lib/shodanz/apis/rest.rb, line 32 def key? return true if @key false end
Get your current IP address as seen from the Internet.
# File lib/shodanz/apis/rest.rb, line 176 def my_ip get('tools/myip') end
This method returns a list of port numbers that the crawlers are looking for.
# File lib/shodanz/apis/rest.rb, line 94 def ports get('shodan/ports') end
Returns information about the Shodan account linked to this API
key.
# File lib/shodanz/apis/rest.rb, line 154 def profile get('account/profile') end
List all protocols that can be used when performing on-demand Internet scans via Shodan.
# File lib/shodanz/apis/rest.rb, line 99 def protocols get('shodan/protocols') end
Look up the IP address for the provided list of hostnames.
# File lib/shodanz/apis/rest.rb, line 159 def resolve(*hostnames) get('dns/resolve', hostnames: hostnames.join(',')) end
Look up the hostnames that have been defined for the given list of IP addresses.
# File lib/shodanz/apis/rest.rb, line 165 def reverse_lookup(*ips) get('dns/reverse', ips: ips.join(',')) end
Use this method to request Shodan to crawl a network.
This method uses API
scan credits: 1 IP consumes 1 scan credit. You must have a paid API
plan (either one-time payment or subscription) in order to use this method.
IP, IPs or netblocks (in CIDR notation) that should get crawled.
# File lib/shodanz/apis/rest.rb, line 110 def scan(*ips) post('shodan/scan', ips: ips.join(',')) end
Check the progress of a previously submitted scan request.
# File lib/shodanz/apis/rest.rb, line 130 def scan_status(id) get("shodan/scan/#{id}") end
Use this method to search the directory of search queries that users have saved in Shodan.
# File lib/shodanz/apis/rest.rb, line 140 def search_for_community_query(query, **params) params[:query] = query params = turn_into_query(**params) get('shodan/query/search', **params) end