shodan 0.6.1 → 1.0.0

data/README.md

@@ -1,6 +1,6 @@
 Visit the official Shodan API documentation at:
 
-[http://docs.shodanhq.com](http://docs.shodanhq.com)
+[https://developer.shodan.io](https://developer.shodan.io)
 
 ## Installation
 
@@ -14,19 +14,32 @@ Before you can use the API, you need to have an API key.
 
 [Get your API key here](http://www.shodanhq.com/api_doc)
 
-Setup the SHODAN WebAPI:
+Setup the Shodan wrapper object:
 
 	require 'shodan'
 	
-	api = Shodan::WebAPI.new(MY_API_KEY)
+	api = Shodan::Shodan.new(MY_API_KEY)
 
 Print a list of cisco-ios devices:
 
 	result = api.search("cisco-ios")
 	result['matches'].each{ |host|
-		puts host['ip']
+		puts host['ip_str']
 	}
 
+Print the 2nd page of results for the cisco-ios query:
+
+	result = api.search("cisco-ios", :page => 2)
+	result['matches'].each{ |host|
+		puts host['ip_str']
+	}
+
+Find out how many results there are for "apache" and also return the top 5 organizations for the results:
+
+	result = api.count("apache", :facets => 'org:5')
+	puts "Total number of results: #{result['total']}"
+	puts result['facets']
+
 Get all the information SHODAN has on the IP 217.140.75.46:
 
 	host = api.host('217.140.75.46')
@@ -41,7 +54,3 @@ To properly handle potential errors, you should wrap all requests in a try/excep
 	else
 		puts "Unknown error"
 	end
-
-## Articles
-
-* [Perl, Python and Ruby API libraries](http://www.surtri.com/2010/10/20/perl-python-ruby-api/)

data/lib/shodan.rb

@@ -1,3 +1,4 @@
 # Import all the SHODAN classes
 require 'shodan/api'
+require 'shodan/shodan'
 require 'shodan/version'

data/lib/shodan/shodan.rb

@@ -0,0 +1,147 @@
+require 'rubygems'
+require 'cgi'
+require 'json'
+require 'openssl'
+require 'net/http'
+
+module Shodan
+  
+  # The Shodan class interfaces with the official Shodan API.
+  # For more information on the API, please visit https://developer.shodan.io
+  #
+  # Author:: achillean (mailto:jmath@shodan.io)
+  #
+  # :title:Shodan::Shodan
+  class Shodan
+    attr_accessor :api_key
+    attr_accessor :base_url
+    attr_accessor :exploits
+    
+    def initialize(api_key)
+      @api_key = api_key
+      @base_url = "https://api.shodan.io/"
+      @base_url_exploits = "https://exploits.shodan.io/api/"
+
+      @exploits = Exploits.new(self)
+    end
+    
+    # Internal method that sends out the HTTP request.
+    # Expects a webservice function (ex. 'search') name and a hash of arguments.
+    def request(type, func, args)
+      if type == "exploits"
+        base_url = @base_url_exploits
+      else
+        base_url = @base_url
+      end
+
+      # Convert the argument hash into a string
+      args_string = args.map{|k, v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}"}.join("&")
+        
+      # Craft the final request URL
+      url = "#{base_url}#{func}?key=#{@api_key}&#{args_string}"
+      
+      # Send the request
+      puts url
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      response = http.get(uri.request_uri)
+      
+      # Convert the JSON data into a native Ruby hash
+      data = JSON.parse(response.body)
+      
+      # Raise an error if something went wrong
+      if data.has_key? 'error'
+        raise data['error']
+      end
+      
+      return data
+    end
+    
+    # Get all available information on an IP.
+    #
+    # Arguments:
+    # ip  - host IP (string)
+    #
+    # Returns a hash containing the host information
+    def host(ip)
+      return request('shodan', "shodan/host/#{ip}", {})
+    end
+    
+    # Perform a search on Shodan.
+    #
+    # Arguments:
+    # query - search query; same format as the website (string)
+    #
+    # Returns a hash containing the search results
+    def search(query, params={})
+      params[:query] = query
+      return request('shodan', 'shodan/host/search', params)
+    end
+    
+    # Find how many results there are for a search term.
+    #
+    # Arguments:
+    # query - search query; same format as the website (string)
+    #
+    # Returns a hash containing the total number of search results
+    def count(query, params={})
+      params[:query] = query
+      return request('shodan', 'shodan/host/count', params)
+    end
+    
+    # Returns information about the current API key.
+    def info()
+      return request('shodan', 'api-info', {})
+    end
+  end
+  
+  # The Exploits class shouldn't be used independently,
+  # as it depends on the Shodan class.
+  #
+  # Author:: achillean (mailto:jmath@shodan.io)
+  #
+  # :title:Shodan::Exploits
+  class Exploits
+    attr_accessor :api
+    
+    def initialize(api)
+      @api = api
+    end
+    
+    # Search the Shodan Exploits archive for exploits.
+    #    
+    # Arguments:
+    # query     -- Search terms
+    #
+    # Optional arguments:
+    # facets    -- A comma-separated list of properties to get summary information on.
+    # page      -- The page number to page through results 100 exploits at a time.
+    #
+    # Returns:
+    # A dictionary with 2 main items: matches (list) and total (int).
+    # Please visit https://developer.shodan.io/api/exploit-specification for up-to-date information on what an Exploit result contains.
+    def search(query, params={})
+      params[:query] = query
+      return @api.request('exploits', 'search', params)
+    end
+    
+    # Search the Shodan Exploits archive for exploits but don't return results, only the number of matches.
+    #    
+    # Arguments:
+    # query     -- Search terms
+    #
+    # Optional arguments:
+    # facets    -- A comma-separated list of properties to get summary information on.
+    #
+    # Returns:
+    # A dictionary with 1 main item: total (int).
+    def count(query, params={})
+      params[:query] = query
+      return @api.request('exploits', 'count', params)
+    end
+    
+  end
+  
+end

data/lib/shodan/version.rb

@@ -1,3 +1,3 @@
 module Shodan
-  Version = VERSION = '0.6.1'
+  Version = VERSION = '1.0.0'
 end

data/lib/test.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+#
+# shodan_ips.py
+# Search SHODAN and print a list of IPs matching the query
+#
+# Author: achillean
+$:.unshift File.dirname(__FILE__)
+
+require 'rubygems'
+require 'shodan'
+
+# Configuration
+API_KEY = "eMLZhC7qt42If0U8ndfZTlCWSSxFYass"
+
+# Input validation
+if ARGV.length == 0
+        puts "Usage: ./shodan_ips.rb <search query>"
+        exit 1
+end
+
+begin
+        # Setup the API
+        api = Shodan::Shodan.new(API_KEY)
+
+        # Perform the search
+        query = ARGV.join(" ")
+
+        puts "\n--- shodan.info ---"
+        result = api.info()
+        puts result
+
+        puts '--- shodan.search ---'
+        result = api.search(query, :page => 2, :facets => 'port')
+
+        # Loop through the matches and print the IPs
+        puts "Total: #{result['total']}"
+        result['matches'][0..10].each{ |host|
+                puts host['ip_str']
+        }
+
+        puts "\nTop 10 Ports"
+        result['facets']['port'].each{ |facet|
+                puts "#{facet['value']}: #{facet['count']}"
+        }
+
+        puts "\n--- shodan.count ---"
+        result = api.count(query, :facets => 'port')
+
+        # Loop through the matches and print the IPs
+        puts "Total: #{result['total']}"
+        result['matches'][0..10].each{ |host|
+                puts host['ip_str']
+        }
+
+        puts "\nTop 10 Ports"
+        result['facets']['port'].each{ |facet|
+                puts "#{facet['value']}: #{facet['count']}"
+        }
+
+        puts "\n--- shodan.host ---"
+        result = api.host('217.140.75.46')
+        puts result
+rescue Exception => e
+        puts "Error: #{e.to_s}"
+        exit 1
+end

data/lib/test_exploits.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+#
+# shodan_ips.py
+# Search SHODAN and print a list of IPs matching the query
+#
+# Author: achillean
+$:.unshift File.dirname(__FILE__)
+
+require 'rubygems'
+require 'shodan'
+
+# Configuration
+API_KEY = "eMLZhC7qt42If0U8ndfZTlCWSSxFYass"
+
+# Input validation
+if ARGV.length == 0
+        puts "Usage: ./shodan_ips.rb <search query>"
+        exit 1
+end
+
+begin
+        # Setup the API
+        api = Shodan::Shodan.new(API_KEY)
+
+        # Perform the search
+        query = ARGV.join(" ")
+
+        puts "\n--- shodan.exploits.search ---"
+        result = api.exploits.search(query, :page => 2, :facets => 'author')
+
+        # Loop through the matches and print the IPs
+        puts "Total: #{result['total']}"
+        result['matches'][0..10].each{ |exploit|
+                puts exploit
+        }
+
+        puts result['facets']
+
+        puts "\n--- shodan.exploits.search ---"
+        result = api.exploits.count(query, :facets => 'author')
+
+        # Loop through the matches and print the IPs
+        puts "Total: #{result['total']}"
+        result['matches'][0..10].each{ |exploit|
+                puts exploit
+        }
+
+        puts result['facets']
+rescue Exception => e
+        puts "Error: #{e.to_s}"
+        exit 1
+end

metadata

@@ -1,88 +1,75 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: shodan
-version: !ruby/object:Gem::Version 
-  hash: 5
-  prerelease: false
-  segments: 
-  - 0
-  - 6
-  - 1
-  version: 0.6.1
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - John Matherly
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-08-26 00:00:00 -07:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2014-02-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: json
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 11
-        segments: 
-        - 1
-        - 4
-        - 6
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 1.4.6
   type: :runtime
-  version_requirements: *id001
-description: "  A Ruby library to interact with the SHODAN API.\n"
-email: jmath@surtri.com
-executables: []
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.6
+description: ! '  A Ruby library to interact with the Shodan API.
 
+'
+email: jmath@shodan.io
+executables: []
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - LICENSE
 - README.md
-files: 
+files:
 - README.md
 - LICENSE
 - HISTORY.md
+- lib/test_exploits.rb
+- lib/test.rb
+- lib/shodan.rb
 - lib/shodan/version.rb
+- lib/shodan/shodan.rb
 - lib/shodan/api.rb
-- lib/shodan.rb
-has_rdoc: true
 homepage: http://github.com/achillean/shodan-ruby
 licenses: []
-
 post_install_message: 
-rdoc_options: 
+rdoc_options:
 - --charset=UTF-8
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: A Ruby library to interact with the SHODAN API.
+summary: A Ruby library to interact with the Shodan API.
 test_files: []
-
+has_rdoc: