Class: Shodanz::API::REST

Inherits:
Object
  • Object
show all
Includes:
Utils
Defined in:
lib/shodanz/apis/rest.rb

Overview

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

Constant Summary collapse

URL =

The path to the REST API endpoint.

'https://api.shodan.io/'

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Utils

#get, #post, #slurp_stream, #turn_into_facets, #turn_into_query

Constructor Details

#initialize(key: ENV['SHODAN_API_KEY']) ⇒ REST

Returns a new instance of REST.

Parameters:

  • key (String) (defaults to: ENV['SHODAN_API_KEY']) —

    SHODAN API key, defaulted to the SHODAN_API_KEY enviroment variable.



23
24
25
26
27
28
29
 
# 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

Instance Attribute Details

#key ⇒ String

Returns:

  • (String) 


17
18
19
 
# File 'lib/shodanz/apis/rest.rb', line 17

def key
  @key
end

Instance Method Details

#community_queries(**params) ⇒ Object

Use this method to obtain a list of search queries that users have saved in Shodan.



135
136
137
 
# File 'lib/shodanz/apis/rest.rb', line 135

def community_queries(**params)
  get('shodan/query', **params)
end

#crawl_for(**params) ⇒ Object

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 [email protected] with information about your project. Access is restricted to prevent abuse.

Example

rest_api.crawl_for(port: 80, protocol: "http")



123
124
125
126
127
 
# 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) ⇒ Object

Calculates a honeypot probability score ranging from 0 (not a honeypot) to 1.0 (is a honeypot).



182
183
184
 
# File 'lib/shodanz/apis/rest.rb', line 182

def honeypot_score(ip)
  get("labs/honeyscore/#{ip}")
end

#host(ip, **params) ⇒ Hash

Returns all services that have been found on the given host IP.

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)

Parameters:

  • ip (String)
  • params (Hash) —

    a customizable set of options

Options Hash (**params):

  • (Hash)

Returns:

  • (Hash) 


51
52
53
 
# File 'lib/shodanz/apis/rest.rb', line 51

def host(ip, **params)
  get("shodan/host/#{ip}", **params)
end

#host_count(query = '', facets: {}, **params) ⇒ Object

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")



65
66
67
68
69
70
 
# 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(query = '', facets: {}, page: 1, minify: true, **params) ⇒ Object

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)



76
77
78
79
80
81
82
83
 
# 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

#host_search_tokens(query = '', **params) ⇒ Object

This method lets you determine which filters are being used by the query string and what parameters were provided to the filters.



87
88
89
90
91
 
# 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 ⇒ Object

Shows the HTTP headers that your client sends when connecting to a webserver.



171
172
173
 
# File 'lib/shodanz/apis/rest.rb', line 171

def http_headers
  get('tools/httpheaders')
end

#info ⇒ Object

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



187
188
189
 
# File 'lib/shodanz/apis/rest.rb', line 187

def info
  get('api-info')
end

#key? ⇒ Boolean

Check if there’s an API key.

Returns:

  • (Boolean) 


32
33
34
35
36
 
# File 'lib/shodanz/apis/rest.rb', line 32

def key?
  return true if @key

  false
end

#my_ip ⇒ Object

Get your current IP address as seen from the Internet.



176
177
178
 
# File 'lib/shodanz/apis/rest.rb', line 176

def my_ip
  get('tools/myip')
end

#popular_query_tags(size = 10) ⇒ Object

Use this method to obtain a list of popular tags for the saved search queries in Shodan.



147
148
149
150
151
 
# File 'lib/shodanz/apis/rest.rb', line 147

def popular_query_tags(size = 10)
  params = {}
  params[:size] = size
  get('shodan/query/tags', **params)
end

#ports ⇒ Object

This method returns a list of port numbers that the crawlers are looking for.



94
95
96
 
# File 'lib/shodanz/apis/rest.rb', line 94

def ports
  get('shodan/ports')
end

#profile ⇒ Object

Returns information about the Shodan account linked to this API key.



154
155
156
 
# File 'lib/shodanz/apis/rest.rb', line 154

def profile
  get('account/profile')
end

#protocols ⇒ Object

List all protocols that can be used when performing on-demand Internet scans via Shodan.



99
100
101
 
# File 'lib/shodanz/apis/rest.rb', line 99

def protocols
  get('shodan/protocols')
end

#resolve(*hostnames) ⇒ Object

Look up the IP address for the provided list of hostnames.



159
160
161
 
# File 'lib/shodanz/apis/rest.rb', line 159

def resolve(*hostnames)
  get('dns/resolve', hostnames: hostnames.join(','))
end

#reverse_lookup(*ips) ⇒ Object

Look up the hostnames that have been defined for the given list of IP addresses.



165
166
167
 
# File 'lib/shodanz/apis/rest.rb', line 165

def reverse_lookup(*ips)
  get('dns/reverse', ips: ips.join(','))
end

#scan(*ips) ⇒ Object

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.



110
111
112
 
# File 'lib/shodanz/apis/rest.rb', line 110

def scan(*ips)
  post('shodan/scan', body: {ips: ips.join(',')})
end

#scan_status(id) ⇒ Object

Check the progress of a previously submitted scan request.



130
131
132
 
# File 'lib/shodanz/apis/rest.rb', line 130

def scan_status(id)
  get("shodan/scan/#{id}")
end

#search_for_community_query(query, **params) ⇒ Object

Use this method to search the directory of search queries that users have saved in Shodan.



140
141
142
143
144
 
# 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