Class: Shodanz::API::Streaming

Inherits:
Object
  • Object
show all
Includes:
Utils
Defined in:
lib/shodanz/apis/streaming.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.

Note: Only 1-5% of the data is currently provided to subscription-based API plans. If your company is interested in large-scale, real-time access to all of the Shodan data please contact us for pricing information ([email protected]).

Author:

  • Kent ‘picat’ Gruber

Constant Summary collapse

URL =

The Streaming API is an HTTP-based service that returns a real-time stream of data collected by Shodan.

'https://stream.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']) ⇒ Streaming

Returns a new instance of Streaming.

Parameters:

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

    SHODAN API key, defaulted to the SHODAN_API_KEY enviroment variable.



29
30
31
32
33
34
35
 
# File 'lib/shodanz/apis/streaming.rb', line 29

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) 


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

def key
  @key
end

Instance Method Details

#alert(id) ⇒ Object

Subscribe to banners discovered on the IP range defined in a specific network alert.



142
143
144
145
146
 
# File 'lib/shodanz/apis/streaming.rb', line 142

def alert(id)
  slurp_stream("alert/#{id}") do |data|
    yield data
  end
end

#alerts ⇒ Object

Subscribe to banners discovered on all IP ranges described in the network alerts. Use the REST API methods to create/ delete/ manage your network alerts and use the Streaming API to subscribe to them.



135
136
137
138
139
 
# File 'lib/shodanz/apis/streaming.rb', line 135

def alerts
  slurp_stream('alert') do |data|
    yield data
  end
end

#banners(**params) ⇒ Object

This stream provides ALL of the data that Shodan collects. Use this stream if you need access to everything and/ or want to store your own Shodan database locally. If you only care about specific ports, please use the Ports stream.

Sometimes data may be piped down stream that is weird to parse. You can choose to keep this data optionally; and it will not be parsed for you.

Example

api.banners do |banner|
  # do something with banner as hash
  puts data
end



56
57
58
59
60
 
# File 'lib/shodanz/apis/streaming.rb', line 56

def banners(**params)
  slurp_stream('shodan/banners', **params) do |data|
    yield data
  end
end

#banners_on_port(param) ⇒ Object

Only returns banner data for a specific port. This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in a specific list of ports.

Example

api.banners_on_port(80) do |banner|
  # do something with the banner hash
  puts data
end



126
127
128
129
130
 
# File 'lib/shodanz/apis/streaming.rb', line 126

def banners_on_port(param)
  banners_on_ports(param) do |data|
    yield data
  end
end

#banners_on_ports(*params) ⇒ Object

Only returns banner data for the list of specified ports. This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in a specific list of ports.

Example

api.banners_on_port(80, 443) do |data|
  # do something with the banner hash
  puts data
end



111
112
113
114
115
 
# File 'lib/shodanz/apis/streaming.rb', line 111

def banners_on_ports(*params)
  slurp_stream("shodan/ports/#{params.join(',')}") do |data|
    yield data
  end
end

#banners_within_asn(param) ⇒ Object

This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in devices located in a certain ASN.

Example

api.banners_within_asn(3303) do |data|
  # do something with the banner hash
  puts data
end



82
83
84
85
86
 
# File 'lib/shodanz/apis/streaming.rb', line 82

def banners_within_asn(param)
  banners_within_asns(param) do |data|
    yield data
  end
end

#banners_within_asns(*asns, **params) ⇒ Object

This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in devices located in certain ASNs.

Example

api.banners_within_asns(3303, 32475) do |data|
  # do something with the banner hash
  puts data
end



69
70
71
72
73
 
# File 'lib/shodanz/apis/streaming.rb', line 69

def banners_within_asns(*asns, **params)
  slurp_stream("shodan/asn/#{asns.join(',')}", **params) do |data|
    yield data
  end
end

#banners_within_countries(*params) ⇒ Object

Only returns banner data for the list of specified ports. This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in a specific list of ports.

Example

api.banners_within_countries("US","DE","JP") do |data|
  # do something with the banner hash
  puts data
end



96
97
98
99
100
 
# File 'lib/shodanz/apis/streaming.rb', line 96

def banners_within_countries(*params)
  slurp_stream("shodan/countries/#{params.join(',')}") do |data|
    yield data
  end
end

#key? ⇒ Boolean

Check if there’s an API key.

Returns:

  • (Boolean) 


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

def key?
  return true if @key; false

end