Class: Shodanz::API::REST

Inherits:
Object
  • Object
show all
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.

Constant Summary collapse

URL =

The path to the REST API endpoint.

"https://api.shodan.io/"

Instance Attribute Summary collapse

Instance Method Summary collapse

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.



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

def initialize(key: ENV['SHODAN_API_KEY'])
  self.key = key
  warn "No key has been found or provided!" unless self.key?
end

Instance Attribute Details

#key ⇒ Object

Returns the value of attribute key.



10
11
12
 
# File 'lib/shodanz/apis/rest.rb', line 10

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.



124
125
126
 
# File 'lib/shodanz/apis/rest.rb', line 124

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



112
113
114
115
116
 
# File 'lib/shodanz/apis/rest.rb', line 112

def crawl_for(**params)
  params[:query] = ""
  params = turn_into_query(params)
  post("shodan/scan/internet", params)
end

#get(path, **params) ⇒ Object

Perform a direct GET HTTP request to the REST API.



178
179
180
181
182
 
# File 'lib/shodanz/apis/rest.rb', line 178

def get(path, **params)
  resp = Unirest.get "#{URL}#{path}?key=#{@key}", parameters: params
  raise resp if resp.code != 200 #and resp.body.has_key?("error")
  resp.body
end

#honeypot_score(ip) ⇒ Object

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



168
169
170
 
# File 'lib/shodanz/apis/rest.rb', line 168

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) 


39
40
41
 
# File 'lib/shodanz/apis/rest.rb', line 39

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



53
54
55
56
57
58
 
# File 'lib/shodanz/apis/rest.rb', line 53

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)



64
65
66
67
68
69
70
71
 
# File 'lib/shodanz/apis/rest.rb', line 64

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.



75
76
77
78
79
 
# File 'lib/shodanz/apis/rest.rb', line 75

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.



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

def http_headers
  get("tools/httpheaders")
end

#info ⇒ Object

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



173
174
175
 
# File 'lib/shodanz/apis/rest.rb', line 173

def info
  get('api-info')
end

#key? ⇒ Boolean

Check if there’s an API key.

Returns:

  • (Boolean) 


22
23
24
 
# File 'lib/shodanz/apis/rest.rb', line 22

def key?
  return true if @key; false
end

#my_ip ⇒ Object

Get your current IP address as seen from the Internet.



163
164
165
 
# File 'lib/shodanz/apis/rest.rb', line 163

def my_ip
  get("tools/my_ip")
end

#popular_query_tags(size = 10) ⇒ Object

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



136
137
138
139
140
 
# File 'lib/shodanz/apis/rest.rb', line 136

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.



82
83
84
 
# File 'lib/shodanz/apis/rest.rb', line 82

def ports
  get("shodan/ports")
end

#post(path, **params) ⇒ Object

Perform a direct POST HTTP request to the REST API.



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

def post(path, **params)
  resp = Unirest.post "#{URL}#{path}?key=#{@key}", parameters: params
  raise resp.body["error"] if resp.code != 200 and resp.body.has_key?("error")
  resp.body
end

#profile ⇒ Object

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



143
144
145
 
# File 'lib/shodanz/apis/rest.rb', line 143

def profile
  get("account/profile")
end

#protocols ⇒ Object

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



87
88
89
 
# File 'lib/shodanz/apis/rest.rb', line 87

def protocols 
  get("shodan/protocols")
end

#resolve(*hostnames) ⇒ Object

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



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

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.



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

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.



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

def scan(*ips)
  raise "Not enough scan credits!" unless self.info["scan_credits"] >= 1
  post("shodan/scan", ips: ips.join(","))
end

#scan_status(id) ⇒ Object

Check the progress of a previously submitted scan request.



119
120
121
 
# File 'lib/shodanz/apis/rest.rb', line 119

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.



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

def search_for_community_query(query, **params)
  params[:query] = query
  params = turn_into_query(params)
  get("shodan/query/search", params) 
end