shodan-ruby 0.1.0

data/lib/shodan/extensions.rb

@@ -0,0 +1,21 @@
+#
+# shodan-ruby - A Ruby interface to SHODAN, a computer search engine.
+#
+# Copyright (c) 2009 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#
+
+require 'shodan/extensions/uri'

data/lib/shodan/has_pages.rb

@@ -0,0 +1,231 @@
+#
+# shodan-ruby - A Ruby interface to SHODAN, a computer search engine.
+#
+# Copyright (c) 2009 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#
+
+module Shodan
+  module HasPages
+    include Enumerable
+
+    #
+    # The first page.
+    #
+    # @return [Page]
+    #   The first page.
+    #
+    def first_page
+      page_cache[1]
+    end
+
+    #
+    # The page at a given index.
+    #
+    # @param [Integer] index
+    #   The index to request a page for.
+    #
+    # @return [Page]
+    #   The page at the specified index.
+    #
+    def [](index)
+      page_cache[index]
+    end
+
+    #
+    # The pages at the given indices.
+    #
+    # @param [Range, Array<Integer>]
+    #   The indices to request pages for.
+    #
+    # @return [Array<Page>]
+    #   The pages at the specified indices.
+    #
+    def pages(indices)
+      indices.map { |index| page_cache[index] }
+    end
+
+    #
+    # Iterates over the pages at given indices.
+    #
+    # @param [Range, Array<Integer>]
+    #   The indices to request pages for.
+    #
+    # @yield [page]
+    #   The given block will be passed each page at one of the specified
+    #   indices.
+    #
+    # @yieldparam [Page] page
+    #   The page at one of the specified indices.
+    #
+    # @return [self]
+    #
+    def each_page(indices,&block)
+      indices.map { |index| block.call(page_cache[index]) }
+      return self
+    end
+
+    #
+    # Iterates over every page, until an empty page is encountered.
+    #
+    # @yield [page]
+    #   The given block will receive every non-empty page.
+    #
+    # @yieldparam [Page] page
+    #   A non-empty page.
+    #
+    # @return [self]
+    #
+    def each(&block)
+      index = 1
+
+      until ((next_page = page_cache[index]).empty?) do
+        block.call(next_page)
+        index = index + 1
+      end
+
+      return self
+    end
+
+    #
+    # Iterates over every host.
+    #
+    # @yield [host]
+    #   If a block is given, it will be passed every host from every page.
+    #
+    # @yieldparam [Host] host
+    #   A host.
+    #
+    # @return [self]
+    #
+    def each_host(&block)
+      each { |page| page.each(&block) }
+    end
+
+    #
+    # Iterates over the hosts in a page at a given index.
+    #
+    # @param [Integer] index
+    #   The index of the page to iterate over.
+    #
+    # @yield [host]
+    #   If a block is given, it will be passed every host on the page at
+    #   the specified index.
+    #
+    # @yieldparam [Host] host
+    #   A host on the page at the specified index.
+    #
+    def each_on_page(index,&block)
+      page_cache[index].each(&block)
+    end
+
+    #
+    # Iterates over each host on the pages at the given indices.
+    #
+    # @param [Range, Array<Integer>] indices
+    #   The indices of the pages.
+    #
+    # @yield [host]
+    #   If a block is given, it will be passed ever host on the pages
+    #   at the specified indices.
+    #
+    # @yieldparam [Host] host
+    #   A host on one of the pages at the specified indices.
+    #
+    # @return [self]
+    #
+    def each_on_pages(indices,&block)
+      each_page(indices) { |page| page.each(&block) }
+    end
+
+    #
+    # The first host on the first page.
+    #
+    # @return [Host]
+    #   The first host.
+    #
+    def first_host
+      first_page.first
+    end
+
+    #
+    # Returns the host at a given index.
+    #
+    # @param [Integer] index
+    #   The index to request the host at.
+    #
+    # @return [Host]
+    #   The host at the given index.
+    #
+    def host_at(index)
+      page(page_index_of(index))[result_index_of(index)]
+    end
+
+    protected
+
+    #
+    # Calculates the page index for a given result rank.
+    #
+    # @param [Integer]
+    #   The rank of a result within the total results.
+    #
+    # @return [Integer]
+    #   The index of the page that will contain the result, with the
+    #   specified rank.
+    #
+    def page_index_of(rank)
+      (((rank.to_i - 1) / results_per_page.to_i) + 1)
+    end
+
+    #
+    # Calculates the result rank of the first result on the page at the
+    # given index.
+    #
+    # @param [Integer] page_index
+    #   The index of a page.
+    #
+    # @return [Integer]
+    #   The rank of the first result on the page, with the specified index.
+    #
+    def result_offset_of(page_index)
+      ((page_index.to_i - 1) * results_per_page.to_i)
+    end
+
+    #
+    # Calculates the in-page index of a given result rank.
+    #
+    # @param [Integer] rank
+    #   The result rank.
+    #
+    # @return [Integer]
+    #   The index of the result, within the page that will contain the
+    #   result.
+    #
+    def result_index_of(rank)
+      ((rank.to_i - 1) % results_per_page.to_i)
+    end
+
+    #
+    # The page cache.
+    #
+    # @return [Hash{Integer => Page}]
+    #   A persistant Hash of pages.
+    #
+    def page_cache
+      @page_cache ||= Hash.new { |hash,key| hash[key] = page(key.to_i) }
+    end
+  end
+end

data/lib/shodan/host.rb

@@ -0,0 +1,146 @@
+#
+# shodan-ruby - A Ruby interface to SHODAN, a computer search engine.
+#
+# Copyright (c) 2009 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#
+
+module Shodan
+  class Host
+
+    # The IP of the host
+    attr_reader :ip
+
+    # The date the host was added
+    attr_reader :date
+
+    # The host-name of the host
+    attr_reader :hostname
+
+    # The response returned by the host
+    attr_reader :response
+
+    # The HTTP version supported by the host
+    attr_reader :http_version
+
+    # The HTTP status code in the response
+    attr_reader :http_code
+
+    # The HTTP status string in the response
+    attr_reader :http_status
+
+    # The HTTP headers included in the response
+    attr_reader :http_headers
+
+    # The body of the HTTP response
+    attr_reader :http_body
+
+    #
+    # Creates a new Host object.
+    #
+    # @param [String] ip
+    #   The IP address of the host.
+    #
+    # @param [String] date
+    #   The date the host was added.
+    #
+    # @param [String] response
+    #   The response received from the host.
+    #
+    # @param [String] hostname
+    #   The optional name of the host.
+    #
+    def initialize(ip,date,response,hostname=nil)
+      @ip = ip
+      @date = Date.parse(date)
+      @response = response
+      @hostname = hostname
+
+      @http_version = nil
+      @http_code = nil
+      @http_status = nil
+      @http_headers = {}
+      @http_body = nil
+
+      if response =~ /^HTTP\/?/
+        lines = response.split(/[\r\n]/)
+        match = lines.first.split(/\s+/,3)
+
+        if match[0].include?('/')
+          @http_version = match[0].split('/').last
+        end
+
+        if match[1]
+          @http_code = match[1].to_i
+        end
+
+        @http_status = match[2]
+        @http_body = ''
+
+        lines[1..-1].each_with_index do |line,index|
+          if line.empty?
+            @http_body = lines[(index+2)..-1].join("\n")
+            break
+          end
+
+          name, value = line.chomp.split(/:\s+/,2)
+
+          @http_headers[name] = value
+        end
+      end
+    end
+
+    #
+    # The server software the host runs.
+    #
+    # @return [String]
+    #   The name of the software.
+    #
+    def server_name
+      if (server = @http_headers['Server'])
+        return server.split('/',2).first
+      end
+    end
+
+    #
+    # The server software version.
+    #
+    # @return [String]
+    #   The version of the software.
+    #
+    def server_version
+      if (server = @http_headers['Server'])
+        return server.split('/',2).last
+      end
+    end
+
+    protected
+
+    #
+    # Provides transparent access to the values in +headers+.
+    #
+    def method_missing(sym,*args,&block)
+      if (args.empty? && block.nil?)
+        name = sym.id2name.gsub(/_/,'-').capitalize
+
+        return @http_headers[name] if @http_headers.key?(name)
+      end
+
+      return super(sym,*args,&block)
+    end
+
+  end
+end

data/lib/shodan/page.rb

@@ -0,0 +1,308 @@
+#
+# shodan-ruby - A Ruby interface to SHODAN, a computer search engine.
+#
+# Copyright (c) 2009 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#
+
+require 'shodan/host'
+
+module Shodan
+  class Page < Array
+
+    #
+    # Creates a new Page object.
+    #
+    # @param [Array] hosts
+    #   The initial hosts.
+    #
+    # @yield [page]
+    #   If a block is given, it will be passed the page.
+    #
+    # @yieldparam [Page] page
+    #   The newly created Page object.
+    #
+    def initialize(hosts=[],&block)
+      super(hosts)
+
+      block.call(self) if block
+    end
+
+    #
+    # Maps the hosts within the page.
+    #
+    # @yield [host]
+    #   The given block will be used to map each host in the page.
+    #
+    # @yieldparam [Host] host
+    #   A host within the page.
+    #
+    # @return [Array]
+    #   The resulting mapped Array.
+    #
+    # @example
+    #   page.map
+    #   # => #<Page: ...>
+    #
+    # @example
+    #   page.map { |host| host.ip }
+    #   # => [...]
+    #
+    def map(&block)
+      return self unless block
+
+      mapped = []
+
+      each { |element| mapped << block.call(element) }
+      return mapped
+    end
+
+    #
+    # Selects the hosts within the page.
+    #
+    # @yield [host]
+    #   The given block will be used to select hosts from the page.
+    #
+    # @yieldparam [Host] host
+    #   A host in the page.
+    #
+    # @return [Page]
+    #   A sub-set of the hosts within the page.
+    #
+    # @example
+    #   page.select { |host| host.headers['Server'] =~ /IIS/ }
+    #
+    def select(&block)
+      self.class.new(super(&block))
+    end
+
+    alias hosts_with select
+
+    #
+    # Iterates over the IP addresses of every host in the page.
+    #
+    # @yield [ip]
+    #   If a block is given, it will be passed the IP addresses of every
+    #   host.
+    #
+    # @yieldparam [String] ip
+    #   An IP address of a host.
+    #
+    # @return [self]
+    #
+    def each_ip(&block)
+      each do |host|
+        block.call(host.ip) if block
+      end
+    end
+
+    #
+    # Selects the hosts with the matching IP address.
+    #
+    # @param [Regexp, String] ip
+    #   The IP address to search for.
+    #
+    # @yield [host]
+    #   If a block is also given, it will be passed every matching host.
+    #
+    # @yieldparam [Host] host
+    #   A host with the matching IP address.
+    #
+    # @return [Array<Host>]
+    #   The hosts with the matching IP address.
+    #
+    def hosts_with_ip(ip,&block)
+      hosts_with do |host|
+        if host.ip.match(ip)
+          block.call(host) if block
+          
+          true
+        end
+      end
+    end
+
+    #
+    # The IP addresses of the hosts in the page.
+    #
+    # @return [Array<String>]
+    #   The IP addresses.
+    #
+    def ips
+      Enumerator.new(self,:each_ip).to_a
+    end
+
+    #
+    # Iterates over the host names of every host in the page.
+    #
+    # @yield [hostname]
+    #   If a block is given, it will be passed the host names of every host.
+    #
+    # @yieldparam [String] hostname
+    #   A host name.
+    #
+    # @return [self]
+    #
+    def each_hostname(&block)
+      each do |host|
+        block.call(host.hostname) if (block && host.hostname)
+      end
+    end
+
+    #
+    # Selects the hosts with the matching host name.
+    #
+    # @param [Regexp, String] hostname
+    #   The host name to search for.
+    #
+    # @yield [host]
+    #   If a block is also given, it will be passed every matching host.
+    #
+    # @yieldparam [Host] host
+    #   A host with the matching host name.
+    #
+    # @return [Array<Host>]
+    #   The hosts with the matching host name.
+    #
+    def hosts_with_name(name,&block)
+      hosts_with do |host|
+        if (host.hostname && host.hostname.match(name))
+          block.call(host) if block
+
+          true
+        end
+      end
+    end
+
+    #
+    # The names of the hosts in the page.
+    #
+    # @return [Array<String>]
+    #   The host names.
+    #
+    def hostnames
+      Enumerator.new(self,:each_hostname).to_a
+    end
+
+    #
+    # Iterates over the dates that each host was added.
+    #
+    # @yield [date]
+    #   If a block is given, it will be passed the dates that each host was
+    #   added.
+    #
+    # @yieldparam [Date] date
+    #   A date that a host was added.
+    #
+    # @return [self]
+    #
+    def each_date(&block)
+      each do |host|
+        block.call(host.date) if block
+      end
+    end
+
+    #
+    # The dates that the hosts were added.
+    #
+    # @return [Array<Date>]
+    #   The dates.
+    #
+    def dates
+      Enumerator.new(self,:each_date).to_a
+    end
+
+    #
+    # Iterates over the responses of each host in the page.
+    #
+    # @yield [response]
+    #   If a block is given, it will be passed the responses of each host.
+    #
+    # @yieldparam [String] response
+    #   The initial response of a host.
+    #
+    # @return [self]
+    #
+    def each_response(&block)
+      each do |host|
+        block.call(host.response) if block
+      end
+    end
+
+    #
+    # Selects the hosts with the matching response.
+    #
+    # @param [Regexp, String] pattern
+    #   The response pattern to search for.
+    #
+    # @yield [host]
+    #   If a block is also given, it will be passed every matching host.
+    #
+    # @yieldparam [Host] host
+    #   A host with the matching response.
+    #
+    # @return [Array<Host>]
+    #   The hosts with the matching response.
+    #
+    def responses_with(pattern,&block)
+      hosts_with do |host|
+        if host.response.match(pattern)
+          block.call(host) if block
+
+          true
+        end
+      end
+    end
+
+    #
+    # The responses of the hosts in the page.
+    #
+    # @return [Array<String>]
+    #   The responses.
+    #
+    def responses(&block)
+      Enumerator.new(self,:each_response).to_a
+    end
+
+    #
+    # Itereates over the HTTP headers of each host in the page.
+    #
+    # @yield [headers]
+    #   If a block is given, it will be passed the headers from each host
+    #   in the page.
+    #
+    # @yieldparam [Hash] headers
+    #   The headers from a host in the page.
+    #
+    # @return [self]
+    #
+    def each_http_headers(&block)
+      each do |host|
+        block.call(host.http_headers) if block
+      end
+    end
+
+    #
+    # The HTTP headers from the hosts in the page.
+    #
+    # @return [Array<Hash>]
+    #   The HTTP headers.
+    #
+    def http_headers
+      Enumerator.new(self,:each_http_headers).to_a
+    end
+
+  end
+end