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

URL

The path to the REST API endpoint.

Attributes

key[RW]

@return [String]

Public Class Methods

new(key: ENV['SHODAN_API_KEY']) click to toggle source

@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

community_queries(**params) click to toggle source

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
crawl_for(**params) click to toggle source

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
honeypot_score(ip) click to toggle source

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
host(ip, **params) click to toggle source

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
host_count(query = '', facets: {}, **params) click to toggle source

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
host_search_tokens(query = '', **params) click to toggle source

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
http_headers() click to toggle source

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
info() click to toggle source

Returns information about the API plan belonging to the given API key.

# File lib/shodanz/apis/rest.rb, line 187
def info
  get('api-info')
end
key?() click to toggle source

Check if there's an API key.

# File lib/shodanz/apis/rest.rb, line 32
def key?
  return true if @key

  false
end
my_ip() click to toggle source

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
ports() click to toggle source

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
profile() click to toggle source

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
protocols() click to toggle source

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
resolve(*hostnames) click to toggle source

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
reverse_lookup(*ips) click to toggle source

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
scan(*ips) click to toggle source

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
scan_status(id) click to toggle source

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
search_for_community_query(query, **params) click to toggle source

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