shodanz 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7a5b350b66032bb9e169a2adf65271c7841d8e0f
+  data.tar.gz: 2b57aabeeec1acf297a96e171710f15a0758dbd1
+SHA512:
+  metadata.gz: d580381f2f606eb7c59ba1ee9019086c526d0f4a750de8317ecf8e2b3d1098201c52fffc30e6543adec32c4dc9d96b880d0b0af7315ddb47cf5b54f791fae68d
+  data.tar.gz: 25d2ffa6642f68d92a394be99fa16f63668777b13e9eb8198f21190443237791251eee5e0b4f3cd7bd6d8df1b8cc99bc54c76b42b30bbdaebf0579586d28f170

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.1
+before_install: gem install bundler -v 1.15.3

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at kgruber1@emich.edu. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in shodanz.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Kent Gruber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,280 @@
+# Shodanz
+
+A modern Ruby [gem](https://rubygems.org/) for [Shodan](https://www.shodan.io/), the world's first search engine for Internet-connected devices.
+
+## Installation
+
+    $ gem install shodanz
+
+## Usage
+
+```ruby
+require "shodanz"
+
+client = Shodanz.client.new
+```
+
+## REST API
+
+The REST API provides methods to search Shodan, look up hosts, get summary information on queries and a variety of utility methods to make developing easier. Refer to the [REST API](https://developer.shodan.io/api) documentation for more ideas on how to use it.
+
+### Shodan Search Methods
+
+Search'n for stuff, are 'ya?
+
+#### Host Information
+
+Returns all services that have been found on the given host IP.
+
+```ruby
+client.rest_api.host("8.8.8.8")                # Default
+client.rest_api.host("8.8.8.8", history: true) # All historical banners should be returned.
+client.rest_api.host("8.8.8.8", minify: true)  # Only return the list of ports and the general host information, no banners. 
+```
+
+#### Host Search
+
+Search Shodan using the same query syntax as the website and use facets to get summary information for different properties.
+
+```ruby
+client.rest_api.host_search("mongodb")
+client.rest_api.host_search("nginx")
+client.rest_api.host_search("apache", after: "1/12/16")
+client.rest_api.host_search("ssh", port: 22, page: 1)
+client.rest_api.host_search("ssh", port: 22, page: 2)
+client.rest_api.host_search("ftp", port: 21, facets: { link: "Ethernet or modem" })
+```
+
+#### Search Shodan without Results
+
+This method behaves identical to `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.
+
+```ruby
+client.rest_api.host_count("apache")
+client.rest_api.host_count("apache", country: "US")
+client.rest_api.host_count("apache", country: "US", state: "MI")
+client.rest_api.host_count("apache", country: "US", state: "MI", city: "Detroit") 
+client.rest_api.host_count("apache", country: "US", state: "MI", city: "Detroit") 
+client.rest_api.host_count("nginx".  facets: { country: 5 })
+client.rest_api.host_count("apache". facets: { country: 5 })
+```
+
+#### Scan Targets
+
+Use this method to request Shodan to crawl an IP or netblock.
+
+```ruby
+client.rest_api.scan("8.8.8.8")
+```
+
+#### Crawl Internet for Port
+
+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.
+
+```ruby
+client.rest_api.crawl_for(port: 80, protocol: "http")
+```
+
+#### List Community Queries
+
+Use this method to obtain a list of search queries that users have saved in Shodan.
+
+```ruby
+client.rest_api.community_queries
+client.rest_api.community_queries(page: 2)
+client.rest_api.community_queries(sort: "votes")
+client.rest_api.community_queries(sort: "votes", page: 2)
+client.rest_api.community_queries(order: "asc")
+client.rest_api.community_queries(order: "desc")
+```
+
+#### Search Community Queries
+
+Use this method to search the directory of search queries that users have saved in Shodan.
+
+```ruby
+client.rest_api.search_for_community_query("the best")
+client.rest_api.search_for_community_query("the best", page: 2)
+```
+
+#### Popular Community Query Tags
+
+Use this method to obtain a list of popular tags for the saved search queries in Shodan.
+
+```ruby
+client.rest_api.popular_query_tags
+client.rest_api.popular_query_tags(20)
+```
+
+#### Protocols
+
+This method returns an object containing all the protocols that can be used when launching an Internet scan.
+
+```ruby
+client.rest_api.protocols
+```
+
+#### Ports
+
+This method returns a list of port numbers that the Shodan crawlers are looking for.
+
+```ruby
+client.rest_api.ports
+```
+
+#### Account Profile
+
+Returns information about the Shodan account linked to this API key.
+
+```ruby
+client.rest_api.profile
+```
+
+#### DNS Lookup
+
+Look up the IP address for the provided list of hostnames.
+
+```ruby
+client.rest_api.resolve("google.com")
+client.rest_api.resolve("google.com", "bing.com")
+```
+
+#### Reverse DNS Lookup
+
+Look up the hostnames that have been defined for the given list of IP addresses.
+
+```ruby
+client.rest_api.reverse_lookup("74.125.227.230")
+client.rest_api.reverse_lookup("74.125.227.230", "204.79.197.200")
+```
+
+#### HTTP Headers
+
+Shows the HTTP headers that your client sends when connecting to a webserver.
+
+```ruby
+client.rest_api.http_headers
+```
+
+#### Your IP Address
+
+Get your current IP address as seen from the Internet.
+
+```ruby
+client.rest_api.my_ip
+```
+
+#### Honeypot Score
+
+Calculates a honeypot probability score ranging from 0 (not a honeypot) to 1.0 (is a honeypot).
+
+```ruby
+client.rest_api.honeypot_score('8.8.8.8')
+```
+
+#### API Plan Information
+
+```ruby
+client.rest_api.info
+```
+
+### Streaming API
+
+The Streaming API is an HTTP-based service that returns a real-time stream of data collected by Shodan. Refer to the [Streaming API](https://developer.shodan.io/api/stream) documentation for more ideas on how to use it.
+#### Banners
+
+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.
+
+```ruby
+client.streaming_api.banners do |data|
+  # do something with banner data
+  puts data
+end
+```
+
+#### Banners Filtered by ASN
+
+This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in devices located in certain ASNs.
+
+```ruby
+client.streaming_api.banners_within_asns(3303, 32475) do |data|
+  # do something with banner data
+  puts data
+end
+```
+
+#### Banners Filtered by Country
+
+This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in devices located in certain countries.
+
+```ruby
+client.streaming_api.banners_within_countries("DE", "US", "JP") do |data|
+  # do something with banner data
+  puts data
+end
+```
+
+#### Banners Filtered by Ports 
+
+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.
+
+```ruby
+client.streaming_api.banners_on_ports(21, 22, 80) do |data| 
+  # do something with banner data
+  puts data
+end
+```
+
+#### Banners by Network Alerts
+
+Subscribe to banners discovered on all IP ranges described in the network alerts.
+
+```ruby
+client.streaming_api.alerts do |data|
+  # do something with banner data
+  puts data
+end
+```
+
+#### Banner Filtered by Alert ID
+
+Subscribe to banners discovered on the IP range defined in a specific network alert.
+
+```ruby
+client.streaming_api.alert("HKVGAIRWD79Z7W2T") do |data|
+  # do something with banner data
+  puts data
+end
+```
+
+### Exploits API
+
+The Exploits API provides access to several exploit/ vulnerability data sources. Refer to the [Exploits API](https://developer.shodan.io/api/exploits/rest) documentation for more ideas on how to use it.
+
+#### Search
+
+Search across a variety of data sources for exploits and use facets to get summary information.
+
+```ruby
+client.exploits_api.search("python")             # Search for Snek vulns.
+client.exploits_api.search(post: 22)             # Port number for the affected service if the exploit is remote.
+client.exploits_api.search(type: "shellcode")    # A category of exploit to search for.
+client.exploits_api.search(osvdb: "100007")      # Open Source Vulnerability Database ID for the exploit.
+```
+
+#### Count
+
+This method behaves identical to the Exploits API `search` method with the difference that it doesn't return any results.
+
+```ruby
+client.exploits_api.count("python")             # Count Snek vulns.
+client.exploits_api.count(port: 22)             # Port number for the affected service if the exploit is remote.
+client.exploits_api.search(type: "shellcode")   # A category of exploit to search for.
+client.exploits_api.count(osvdb: "100007")      # Open Source Vulnerability Database ID for the exploit.
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/examples/debug.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'shodanz'
+require 'pry'
+
+rest_api      = Shodanz.api.rest.new
+streaming_api = Shodanz.api.streaming.new
+exploits_api  = Shodanz.api.exploits.new
+
+binding.pry

data/examples/top_10_countries_running.rb

@@ -0,0 +1,66 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'shodanz'
+require 'command_lion'
+require 'yaml'
+require 'pry'
+
+module Top10
+  
+  @rest_api = Shodanz.api.rest.new
+  
+  def self.check(product)
+    begin
+      @rest_api.host_count(product: product, facets: { country: 10 })["facets"]["country"].collect { |x| x.values }.to_h.invert
+    rescue
+      puts "Unable to succesffully check the Shodan API."
+      exit 1
+    end
+  end
+
+end
+
+CommandLion::App.run do
+  name "Top 10 Countires Running a Product Using Shodan"
+
+  command :product do
+    description "Search for this given product."
+    type :string
+    flag "--product"
+
+    # Check is Shodan Enviroemnt Variable Set
+    before do
+      unless ENV['SHODAN_API_KEY'] 
+        puts "Need to set the 'SHODAN_API_KEY' enviroment variable before using this app!"
+        exit 1 # [ ╯´･ω･]╯︵┸━┸) 
+      end
+      if argument.empty?
+        puts "What kind of nonsense is this?! You need to provide some argument..."
+        exit 1 # [ ╯ ﾟ▽ﾟ]╯︵┻━┻)
+      end
+    end
+
+    # Do stuff.
+    action do
+      result = Top10.check(argument)
+      if options[:json].given?
+        puts JSON.pretty_generate(result)
+      elsif options[:yaml].given?
+        puts result.to_yaml
+      else
+        result.each do |country, count|
+          puts "#{country}\t#{count}"
+        end
+      end
+    end
+
+    option :json do
+      description "Use JSON as the format to output to STDOUT."
+      flag "--json"
+    end
+
+    option :yaml do
+      description "Use YAML as the format to output to STDOUT."
+      flag "--yaml"
+    end
+  end
+end

data/lib/shodanz/api.rb

@@ -0,0 +1,32 @@
+require_relative "apis/rest.rb"
+require_relative "apis/streaming.rb"
+require_relative "apis/exploits.rb"
+
+module Shodanz
+  # There are 2 APIs for accessing Shodan: the REST API 
+  # and the Streaming API. The REST API provides methods 
+  # to search Shodan, look up hosts, get summary information 
+  # on queries and a variety of utility methods to make 
+  # developing easier. The Streaming API provides a raw, 
+  # real-time feed of the data that Shodan is currently 
+  # collecting. There are several feeds that can be subscribed 
+  # to, but the data can't be searched or otherwise interacted 
+  # with; it's a live feed of data meant for large-scale 
+  # consumption of Shodan's information.
+  module API
+    # REST API class.
+    def self.rest
+      REST
+    end
+    
+    # Streaming API class.
+    def self.streaming
+      Streaming
+    end
+    
+    # Exploits API class.
+    def self.exploits
+      Exploits
+    end
+  end
+end

data/lib/shodanz/apis/exploits.rb

@@ -0,0 +1,85 @@
+module Shodanz
+
+  module API
+    # The Exploits API provides access to several exploit 
+    # and vulnerability data sources. At the moment, it 
+    # searches across the following:
+    #  - Exploit DB
+    #  - Metasploit
+    #  - Common Vulnerabilities and Exposures (CVE)
+    #
+    # @author Kent 'picat' Gruber
+    class Exploits
+      attr_accessor :key
+      
+      # The path to the REST API endpoint.
+      URL = "https://exploits.shodan.io/api/"
+
+      # @param key [String] SHODAN API key, defaulted to the *SHODAN_API_KEY* enviroment variable.
+      def initialize(key: ENV['SHODAN_API_KEY'])
+        self.key = key
+        warn "No key has been found or provided!" unless self.key?
+      end
+
+      # Check if there's an API key.
+      def key?
+        return true if @key; false
+      end
+
+      # Search across a variety of data sources for exploits and 
+      # use facets to get summary information.
+      # == Example
+      #   api.search("SQL", port: 443)
+      #   api.search(port: 22)
+      #   api.search(type: "dos")
+      def search(query = "", facets: {}, page: 1, **params)
+        params[:query] = query
+        params = turn_into_query(params)
+        facets = turn_into_facets(facets)
+        params[:page] = page
+        get("search", params.merge(facets))
+      end
+
+      # This method behaves identical to the "/search" method with 
+      # the difference that it doesn't return any results.
+      # == Example
+      #   api.count(type: "dos")
+      def count(query = "", facets: {}, page: 1, **params)
+        params[:query] = query
+        params = turn_into_query(params)
+        facets = turn_into_facets(params)
+        params[:page] = page
+        get("count", params.merge(facets))
+      end
+
+      # Perform a direct GET HTTP request to the REST API.
+      def get(path, **params)
+        resp = Unirest.get "#{URL}#{path}?key=#{@key}", parameters: params
+        raise resp.body["error"] if resp.code != 200 and resp.body.has_key?("error")
+        resp.body
+      end
+
+      private
+
+      def turn_into_query(params)
+        filters = params.reject { |key, value| key == :query }
+        filters.each do |key, value|
+          params[:query] << " #{key}:#{value}"
+        end
+        params.select { |key, value| key == :query }
+      end
+
+      def turn_into_facets(facets)
+        filters = facets.reject { |key, value| key == :facets }
+        facets[:facets] = []
+        filters.each do |key, value|
+          facets[:facets] << "#{key}:#{value}"
+        end
+        facets[:facets] = facets[:facets].join(",")
+        facets.select { |key, value| key == :facets }
+      end
+
+    end
+
+  end
+end

data/lib/shodanz/apis/rest.rb

@@ -0,0 +1,214 @@
+module Shodanz
+
+  module API
+    # 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
+    class REST
+      attr_accessor :key
+
+      # The path to the REST API endpoint.
+      URL = "https://api.shodan.io/"
+
+      # @param key [String] SHODAN API key, defaulted to the *SHODAN_API_KEY* enviroment variable.
+      def initialize(key: ENV['SHODAN_API_KEY'])
+        self.key = key
+        warn "No key has been found or provided!" unless self.key?
+      end
+
+      # Check if there's an API key.
+      def key?
+        return true if @key; false
+      end
+
+      # 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)  
+      def host(ip, **params)
+        get("shodan/host/#{ip}", params)
+      end
+
+      # 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")
+      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
+
+      # 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)
+      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
+
+      # This method lets you determine which filters are being used by 
+      # the query string and what parameters were provided to the filters.
+      def host_search_tokens(query = "", **params)
+        params[:query] = query
+        params = turn_into_query(params)
+        get("shodan/host/search/tokens", params)
+      end
+
+      # This method returns a list of port numbers that the crawlers are looking for.
+      def ports
+        get("shodan/ports")
+      end
+
+      # List all protocols that can be used when performing on-demand Internet scans via Shodan.
+      def protocols 
+        get("shodan/protocols")
+      end
+
+      # 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.
+      def scan(*ips)
+        raise "Not enough scan credits!" unless self.info["scan_credits"] >= 1
+        post("shodan/scan", ips: ips.join(","))
+      end
+
+      # 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")
+      def crawl_for(**params)
+        params[:query] = ""
+        params = turn_into_query(params)
+        post("shodan/scan/internet", params)
+      end
+
+      # Check the progress of a previously submitted scan request. 
+      def scan_status(id)
+        get("shodan/scan/#{id}")
+      end
+
+      # Use this method to obtain a list of search queries that users have saved in Shodan.
+      def community_queries(**params)
+        get("shodan/query", params)
+      end
+
+      # Use this method to search the directory of search queries that users have saved in Shodan.
+      def search_for_community_query(query, **params)
+        params[:query] = query
+        params = turn_into_query(params)
+        get("shodan/query/search", params) 
+      end
+
+      # Use this method to obtain a list of popular tags for the saved search queries in Shodan.
+      def popular_query_tags(size = 10)
+        params = {}
+        params[:size] = size
+        get("shodan/query/tags", params)
+      end
+
+      # Returns information about the Shodan account linked to this API key.
+      def profile
+        get("account/profile")
+      end
+
+      # Look up the IP address for the provided list of hostnames.
+      def resolve(*hostnames)
+        get("dns/resolve", hostnames: hostnames.join(","))
+      end
+
+      # Look up the hostnames that have been defined for the given list of IP addresses.
+      def reverse_lookup(*ips)
+        get("dns/reverse", ips: ips.join(","))
+      end
+
+      # Shows the HTTP headers that your client sends when connecting to a webserver.
+      def http_headers
+        get("tools/httpheaders")
+      end
+
+      # Get your current IP address as seen from the Internet.
+      def my_ip
+        get("tools/my_ip")
+      end
+
+      # Calculates a honeypot probability score ranging from 0 (not a honeypot) to 1.0 (is a honeypot).
+      def honeypot_score(ip)
+        get("labs/honeyscore/#{ip}")
+      end
+
+      # Returns information about the API plan belonging to the given API key.
+      def info
+        get('api-info')
+      end
+
+      # Perform a direct GET HTTP request to the REST API.
+      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
+
+      # Perform a direct POST HTTP request to the REST API.
+      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
+
+      private
+
+      def turn_into_query(params)
+        filters = params.reject { |key, value| key == :query }
+        filters.each do |key, value|
+          params[:query] << " #{key}:#{value}"
+        end
+        params.select { |key, value| key == :query }
+      end
+
+      def turn_into_facets(facets)
+        filters = facets.reject { |key, value| key == :facets }
+        facets[:facets] = []
+        filters.each do |key, value|
+          facets[:facets] << "#{key}:#{value}"
+        end
+        facets[:facets] = facets[:facets].join(",")
+        facets.select { |key, value| key == :facets }
+      end
+
+    end
+
+  end
+end

data/lib/shodanz/apis/streaming.rb

@@ -0,0 +1,187 @@
+module Shodanz
+
+  module API
+    # 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 (sales@shodan.io).
+    # 
+    # @author Kent 'picat' Gruber
+    class Streaming
+      attr_accessor :key
+      
+      # The Streaming API is an HTTP-based service that returns 
+      # a real-time stream of data collected by Shodan.
+      URL = "https://stream.shodan.io/"
+
+      # @param key [String] SHODAN API key, defaulted to the *SHODAN_API_KEY* enviroment variable.
+      def initialize(key: ENV['SHODAN_API_KEY'])
+        self.key = key
+        warn "No key has been found or provided!" unless self.key?
+      end
+
+      # Check if there's an API key.
+      def key?
+        return true if @key; false
+      end
+
+      # 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
+      def banners(**params)
+        slurp_stream("shodan/banners", params) do |data|
+          yield data
+        end
+      end
+
+      # 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
+      def banners_within_asns(*asns, **params)
+        slurp_stream("shodan/asn/#{asns.join(",")}", params) do |data|
+          yield data
+        end
+      end
+
+      # 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
+      def banners_within_asn(param)
+        banners_within_asns(param) do |data|
+          yield data
+        end
+      end
+
+      # 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
+      def banners_within_countries(*params)
+        slurp_stream("shodan/countries/#{params.join(",")}") do |data|
+          yield data
+        end
+      end
+
+      # 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
+      def banners_on_ports(*params)
+        slurp_stream("shodan/ports/#{params.join(",")}") do |data|
+          yield data
+        end
+      end
+
+      # 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
+      def banners_on_port(param)
+        banners_on_ports(param) do |data|
+          yield data
+        end
+      end
+
+      # 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.
+      def alerts
+        slurp_stream("alert") do |data|
+          yield data
+        end
+      end
+
+      # Subscribe to banners discovered on the IP range defined in a specific network alert.
+      def alert(id)
+        slurp_stream("alert/#{id}") do |data|
+          yield data
+        end
+      end
+
+      private
+
+      # Perform the main function of consuming the streaming API. 
+      def slurp_stream(path, **params)
+        uri = URI("#{URL}#{path}?key=#{@key}")
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+          request = Net::HTTP::Get.new uri
+          begin
+            http.request request do |resp|
+              raise "Unable to connect to Streaming API" if resp.code != "200"
+              # Buffer for Shodan's bullshit.
+              raw_body = ""
+              resp.read_body do |chunk| 
+                if /^\{"product":.*\}\}\n/.match(chunk)
+                  begin
+                    yield Oj.load(chunk)
+                  rescue
+                    # yolo
+                  end
+                elsif /.*\}\}\n$/.match(chunk)
+                  next if raw_body.empty?
+                  raw_body << chunk
+                  raw_body
+                elsif /^\{.*\b/.match(chunk) 
+                  raw_body << chunk
+                end
+                if m = /^\{"product":.*\}\}\n/.match(raw_body)
+                  index = 0
+                  while matched = m[index]
+                    index += 1
+                    raw_body = raw_body.gsub(/^\{"product":.*\}\}\n/, "")
+                    begin
+                      yield Oj.load(matched)
+                    rescue
+                      # yolo
+                    end
+                  end
+                end
+              end
+            end
+          ensure
+            http.finish
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/shodanz/client.rb

@@ -0,0 +1,22 @@
+module Shodanz
+  class Client
+    # Create a new client to connect to any of the APIs.
+    def initialize
+      @rest_api      = Shodanz.api.rest.new
+      @streaming_api = Shodanz.api.streaming.new
+      @exploits_api  = Shodanz.api.exploits.new  
+    end
+
+    def rest_api
+      @rest_api
+    end
+
+    def streaming_api
+      @streaming_api
+    end
+
+    def exploits_api
+      @exploits_api
+    end
+  end
+end

data/lib/shodanz/version.rb

@@ -0,0 +1,3 @@
+module Shodanz
+  VERSION = "1.0.0"
+end

data/lib/shodanz.rb

@@ -0,0 +1,14 @@
+require "oj"
+require "unirest"
+require "shodanz/version"
+require "shodanz/api"
+require "shodanz/client"
+
+module Shodanz
+  def self.api
+    API
+  end
+  def self.client
+    Client
+  end
+end

data/shodanz.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "shodanz/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "shodanz"
+  spec.version       = Shodanz::VERSION
+  spec.authors       = ["Kent 'picatz' Gruber"]
+  spec.email         = ["kgruber1@emich.edu"]
+
+  spec.summary       = %q{A modern Ruby gem for Shodan, the world's first search engine for Internet-connected devices.}
+  spec.description   = %q{Featuring full support for the REST, Streaming and Exploits API}
+  spec.homepage      = "https://github.com/picatz/shodanz"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.require_paths = ["lib"]
+  
+  spec.add_dependency "unirest"
+  spec.add_dependency "oj"
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: shodanz
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Kent 'picatz' Gruber
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-10-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: unirest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Featuring full support for the REST, Streaming and Exploits API
+email:
+- kgruber1@emich.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/debug.rb
+- examples/top_10_countries_running.rb
+- lib/shodanz.rb
+- lib/shodanz/api.rb
+- lib/shodanz/apis/exploits.rb
+- lib/shodanz/apis/rest.rb
+- lib/shodanz/apis/streaming.rb
+- lib/shodanz/client.rb
+- lib/shodanz/version.rb
+- shodanz.gemspec
+homepage: https://github.com/picatz/shodanz
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: A modern Ruby gem for Shodan, the world's first search engine for Internet-connected
+  devices.
+test_files: []