Class: Shodanz::API::Streaming

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

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.



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

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.



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

def key
  @key
end

Instance Method Details

#alert(id) ⇒ Object

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



132
133
134
135
136
 
# File 'lib/shodanz/apis/streaming.rb', line 132

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.



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

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



46
47
48
49
50
 
# File 'lib/shodanz/apis/streaming.rb', line 46

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



116
117
118
119
120
 
# File 'lib/shodanz/apis/streaming.rb', line 116

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



101
102
103
104
105
 
# File 'lib/shodanz/apis/streaming.rb', line 101

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



72
73
74
75
76
 
# File 'lib/shodanz/apis/streaming.rb', line 72

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



59
60
61
62
63
 
# File 'lib/shodanz/apis/streaming.rb', line 59

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



86
87
88
89
90
 
# File 'lib/shodanz/apis/streaming.rb', line 86

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) 


29
30
31
 
# File 'lib/shodanz/apis/streaming.rb', line 29

def key?
  return true if @key; false
end