ruby-nmap 0.1.0

data/History.txt

@@ -0,0 +1,6 @@
+=== 0.1.0 / 2009-11-13
+
+* Initial release.
+  * Provides a Ruby interface for running Nmap.
+  * Provides a Parser for enumerating Nmap XML scan files.
+

data/Manifest.txt

@@ -0,0 +1,27 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/nmap.rb
+lib/nmap/task.rb
+lib/nmap/program.rb
+lib/nmap/address.rb
+lib/nmap/host.rb
+lib/nmap/os_class.rb
+lib/nmap/os_match.rb
+lib/nmap/os.rb
+lib/nmap/port.rb
+lib/nmap/scanner.rb
+lib/nmap/scan.rb
+lib/nmap/status.rb
+lib/nmap/xml.rb
+lib/nmap/version.rb
+tasks/spec.rb
+tasks/yard.rb
+spec/spec_helper.rb
+spec/helpers/scan.xml
+spec/helpers/xml.rb
+spec/os_spec.rb
+spec/host_spec.rb
+spec/xml_spec.rb
+spec/nmap_spec.rb

data/README.txt

@@ -0,0 +1,80 @@
+= ruby-nmap
+
+* http://github.com/sophsec/ruby-nmap
+* http://github.com/sophsec/ruby-nmap/issues
+* Postmodern (postmodern.mod3 at gmail.com)
+
+== DESCRIPTION:
+
+A Ruby interface to Nmap, the exploration tool and security / port scanner.
+
+== FEATURES:
+
+* Provides a Ruby interface for running Nmap.
+* Provides a Parser for enumerating Nmap XML scan files.
+
+== EXAMPLES:
+
+* Run Nmap from Ruby:
+
+    require 'nmap/program'
+    
+    Nmap::Program.scan do |nmap|
+      nmap.syn_scan = true
+      nmap.service_scan = true
+      nmap.os_fingerprint = true
+      nmap.xml = 'scan.xml'
+      nmap.verbose = true
+
+      nmap.ports = [20,21,22,23,25,80,110,443,512,522,8080,1080]
+      nmap.targets = '192.168.1.*'
+    end
+
+* Parse Nmap XML scan files:
+
+    require 'nmap/xml'
+
+    Nmap::XML.new('scan.xml') do |xml|
+      xml.each_host do |host|
+        puts "[#{host.ip}]"
+    
+        host.each_port do |port|
+          puts "  #{port.number}/#{port.protocol}\t#{port.state}\t#{port.service}"
+        end
+      end
+    end
+
+== REQUIREMENTS:
+
+* {nmap}[http://www.insecure.org/]
+* {nokogiri}[http://nokogiri.rubyforge.org/] >= 1.4.0
+* {rprogram}[http://rprogram.rubyforge.org/] >= 0.1.7
+
+== INSTALL:
+
+  $ sudo gem install ruby-nmap
+
+== LICENSE:
+
+The MIT License
+
+Copyright (c) 2009 Hal Brodigan
+
+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/Rakefile

@@ -0,0 +1,24 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './tasks/spec.rb'
+require './tasks/yard.rb'
+
+Hoe.spec 'ruby-nmap' do
+  self.developer('Postmodern', 'postmodern.mod3@gmail.com')
+  self.remote_rdoc_dir = '/'
+  self.extra_deps = [
+    ['nokogiri', '>=1.4.0'],
+    ['rprogram', '>=0.1.7']
+  ]
+
+  self.extra_dev_deps = [
+    ['rspec', '>=1.1.12'],
+    ['yard', '>=0.2.3.5']
+  ]
+
+  self.spec_extras = {:has_rdoc => 'yard'}
+end
+
+# vim: syntax=ruby

data/lib/nmap/address.rb

@@ -0,0 +1,35 @@
+module Nmap
+  class Address
+
+    # Type of the address
+    attr_reader :type
+
+    # Address
+    attr_reader :addr
+
+    #
+    # Creates a new Address object.
+    #
+    # @param [Symbol] type
+    #   The type of the address.
+    #
+    # @param [String] addr
+    #   The address.
+    #
+    def initialize(type,addr)
+      @type = type
+      @addr = addr
+    end
+
+    #
+    # Converts the address to a String.
+    #
+    # @return [String]
+    #   The address.
+    #
+    def to_s
+      @addr.to_s
+    end
+
+  end
+end

data/lib/nmap/host.rb

@@ -0,0 +1,368 @@
+require 'nmap/status'
+require 'nmap/address'
+require 'nmap/os'
+require 'nmap/port'
+
+require 'nokogiri'
+require 'enumerator'
+
+module Nmap
+  class Host
+
+    include Enumerable
+
+    #
+    # Creates a new Host object.
+    #
+    # @param [Nokogiri::XML::Node] node
+    #   The XML node that contains the host information.
+    #
+    # @yield [host]
+    #   If a block is given, it will be passed the newly created Host
+    #   object.
+    #
+    # @yieldparam [Host] host
+    #   The newly created Host object.
+    #
+    def initialize(node,&block)
+      @node = node
+
+      block.call(self) if block
+    end
+
+    #
+    # Parses the status of the host.
+    #
+    # @return [Status]
+    #   The status of the host.
+    #
+    def status
+      status = @node.at('status')
+
+      return Status.new(
+        status['state'].to_sym,
+        status['reason']
+      )
+    end
+
+    #
+    # Parses each address of the host.
+    #
+    # @yield [addr]
+    #   Each parsed address will be pass to a given block.
+    #
+    # @yieldparam [Address] addr
+    #   A address of the host.
+    #
+    # @return [Host]
+    #   The host.
+    #
+    def each_address(&block)
+      @node.xpath("address[@addr]").each do |addr|
+        address = Address.new(
+          addr['addrtype'].to_sym,
+          addr['addr']
+        )
+
+        block.call(address) if block
+      end
+
+      return self
+    end
+
+    #
+    # Parses the addresses of the host.
+    #
+    # @return [Array<Host>]
+    #   The addresses of the host.
+    #
+    def addresses
+      Enumerator.new(self,:each_address).to_a
+    end
+
+    #
+    # Parses the MAC address of the host.
+    #
+    # @return [String]
+    #   The MAC address of the host.
+    #
+    def mac
+      unless @mac
+        addr = @node.xpath("address[@addr][@addrtype='mac']").first
+
+        @mac = addr['addr'] if addr
+      end
+
+      return @mac
+    end
+
+    #
+    # Parses the IPv4 address of the host.
+    #
+    # @return [String]
+    #   The IPv4 address of the host.
+    #
+    def ipv4
+      unless @ipv4
+        addr = @node.xpath("address[@addr][@addrtype='ipv4']").first
+
+        @ipv4 = addr['addr'] if addr
+      end
+
+      return @ipv4
+    end
+
+    #
+    # Parses the IPv6 address of the host.
+    #
+    # @return [String]
+    #   The IPv6 address of the host.
+    #
+    def ipv6
+      unless @ipv6
+        addr = @node.xpath("address[@addr][@addrtype='ipv6']").first
+
+        @ipv6 = addr['addr'] if addr
+      end
+
+      return @ipv6
+    end
+
+    #
+    # The IP address of the host.
+    #
+    # @return [String]
+    #   The IPv4 or IPv6 address of the host.
+    #
+    def ip
+      ipv6 || ipv4
+    end
+
+    #
+    # The address of the host.
+    #
+    # @return [String]
+    #   The IP or MAC address of the host.
+    #
+    def address
+      ip || mac
+    end
+
+    #
+    # Parses the hostnames of the host.
+    #
+    # @yield [host]
+    #   Each parsed hostname will be passed to the given block.
+    #
+    # @yieldparam [String] host
+    #   A hostname of the host.
+    #
+    # @return [Host]
+    #   The host.
+    #
+    def each_hostname(&block)
+      @node.xpath("hostnames/hostname[@name]").each do |host|
+        block.call(host['name']) if block
+      end
+
+      return self
+    end
+
+    #
+    # Parses the hostnames of the host.
+    #
+    # @return [Array<String>]
+    #   The hostnames of the host.
+    #
+    def hostnames
+      Enumerator.new(self,:each_hostname).to_a
+    end
+
+    #
+    # Parses the OS guessing information of the host.
+    #
+    # @yield [os]
+    #   If a block is given, it will be passed the OS guessing information.
+    #
+    # @yieldparam [OS] os
+    #   The OS guessing information.
+    #
+    # @return [OS]
+    #   The OS guessing information.
+    #
+    def os(&block)
+      os = @node.at('os')
+
+      return OS.new(os,&block) if os
+    end
+
+    #
+    # Parses the scanned ports of the host.
+    #
+    # @yield [port]
+    #   Each scanned port of the host.
+    #
+    # @yieldparam [Port] port
+    #   A scanned port of the host.
+    #
+    # @return [Host]
+    #   The host.
+    #
+    def each_port(&block)
+      @node.xpath("ports/port").each do |port|
+        block.call(create_port(port)) if block
+      end
+
+      return self
+    end
+
+    #
+    # Parses the scanned ports of the host.
+    #
+    # @return [Array<Port>]
+    #   The scanned ports of the host.
+    #
+    def ports
+      Enumerator.new(self,:each_port).to_a
+    end
+
+    #
+    # Parses the open ports of the host.
+    #
+    # @yield [port]
+    #   Each open port of the host.
+    #
+    # @yieldparam [Port] port
+    #   An open scanned port of the host.
+    #
+    # @return [Host]
+    #   The host.
+    #
+    def each_open_port(&block)
+      @node.xpath("ports/port[state/@state='open']").each do |port|
+        block.call(create_port(port)) if block
+      end
+
+      return self
+    end
+
+    #
+    # Parses the open ports of the host.
+    #
+    # @return [Array<Port>]
+    #   The open ports of the host.
+    #
+    def open_ports
+      Enumerator.new(self,:each_open_port).to_a
+    end
+
+    #
+    # Parses the TCP ports of the host.
+    #
+    # @yield [port]
+    #   Each TCP port of the host.
+    #
+    # @yieldparam [Port] port
+    #   An TCP scanned port of the host.
+    #
+    # @return [Host]
+    #   The host.
+    #
+    def each_tcp_port(&block)
+      @node.xpath("ports/port[@protocol='tcp']").each do |port|
+        block.call(create_port(port)) if block
+      end
+
+      return self
+    end
+
+    #
+    # Parses the TCP ports of the host.
+    #
+    # @return [Array<Port>]
+    #   The TCP ports of the host.
+    #
+    def tcp_ports
+      Enumerator.new(self,:each_tcp_port).to_a
+    end
+
+    #
+    # Parses the UDP ports of the host.
+    #
+    # @yield [port]
+    #   Each UDP port of the host.
+    #
+    # @yieldparam [Port] port
+    #   An UDP scanned port of the host.
+    #
+    # @return [Host]
+    #   The host.
+    #
+    def each_udp_port(&block)
+      @node.xpath("ports/port[@protocol='udp']").each do |port|
+        block.call(create_port(port)) if block
+      end
+
+      return self
+    end
+
+    #
+    # Parses the UDP ports of the host.
+    #
+    # @return [Array<Port>]
+    #   The UDP ports of the host.
+    #
+    def udp_ports
+      Enumerator.new(self,:each_udp_port).to_a
+    end
+
+    #
+    # Parses the open ports of the host.
+    #
+    # @see each_open_port
+    #
+    def each(&block)
+      each_open_port(&block)
+    end
+
+    #
+    # Converts the host to a String.
+    #
+    # @return [String]
+    #   The address of the host.
+    #
+    # @see address
+    #
+    def to_s
+      address.to_s
+    end
+
+    protected
+
+    #
+    # Creates a new Port object around a node.
+    #
+    # @param [Nokogiri::XML::Node] node
+    #   The node to create the Port object around.
+    #
+    # @return [Port]
+    #   The port object.
+    #
+    def create_port(node)
+      state = node.at('state')
+
+      if (service = node.at('service/@name'))
+        service = service.inner_text
+      end
+
+      return Port.new(
+        node['protocol'].to_sym,
+        node['portid'].to_i,
+        state['state'].to_sym,
+        state['reason'],
+        service
+      )
+    end
+
+  end
+end

data/lib/nmap/os.rb

@@ -0,0 +1,131 @@
+require 'nmap/os_class'
+require 'nmap/os_match'
+
+require 'enumerator'
+
+module Nmap
+  class OS
+
+    include Enumerable
+
+    #
+    # Creates a new OS object.
+    #
+    # @param [Nokogiri::XML::Node] node
+    #   The node that contains the OS guessing information.
+    #
+    # @yield [os]
+    #   If a block is given, it will passed the newly created OS object.
+    #
+    # @yieldparam [OS] os
+    #   The newly created OS object.
+    #
+    def initialize(node,&block)
+      @node = node
+
+      block.call(self) if block
+    end
+
+    #
+    # Parses the OS class information.
+    #
+    # @yield [class]
+    #   Passes each OS class to the given block.
+    #
+    # @yieldparam [OSClass] class
+    #   The OS class information.
+    #
+    # @return [OS]
+    #   The OS information.
+    #
+    def each_class(&block)
+      @node.xpath("osclass").map do |osclass|
+        os_class = OSClass.new(
+          osclass['type'].to_sym,
+          osclass['vendor'],
+          osclass['osfamily'].to_sym,
+          osclass['accuracy'].to_i
+        )
+
+        block.call(os_class) if block
+      end
+
+      return self
+    end
+
+    #
+    # Parses the OS class information.
+    #
+    # @return [Array<OSClass>]
+    #   The OS class information.
+    #
+    def classes
+      Enumerator.new(self,:each_class).to_a
+    end
+
+    #
+    # Parses the OS match information.
+    #
+    # @yield [match]
+    #   Passes each OS match to the given block.
+    #
+    # @yieldparam [OSMatch] class
+    #   The OS match information.
+    #
+    # @return [OS]
+    #   The OS information.
+    #
+    def each_match(&block)
+      @node.xpath("osmatch").map do |osclass|
+        os_match = OSMatch.new(
+          osclass['name'],
+          osclass['accuracy'].to_i
+        )
+
+        block.call(os_match) if block
+      end
+
+      return self
+    end
+
+    #
+    # Parses the OS match information.
+    #
+    # @return [Array<OSMatch>]
+    #   The OS match information.
+    #
+    def matches
+      Enumerator.new(self,:each_match).to_a
+    end
+
+    #
+    # Parses the ports used for guessing the OS.
+    #
+    # @return [Array<Integer>]
+    #   The ports used.
+    #
+    def ports_used
+      @node.xpath("portused/@portid").map { |port| port.inner_text.to_i }
+    end
+
+    #
+    # Parses the OS fingerprint used by Nmap.
+    #
+    # @return [String]
+    #   The OS fingerprint.
+    #
+    def fingerprint
+      @node.at("osfingerprint/@fingerprint").inner_text
+    end
+
+    #
+    # Parses the OS match information.
+    #
+    # @see each_match
+    #
+    def each(&block)
+      each_match(&block)
+    end
+
+  end
+end

data/lib/nmap/os_class.rb

@@ -0,0 +1,49 @@
+module Nmap
+  class OSClass
+
+    # The OS class
+    attr_reader :type
+
+    # The OS vendor
+    attr_reader :vendor
+
+    # The family of the OS
+    attr_reader :family
+
+    # The accuracy of the OS guess
+    attr_reader :accuracy
+
+    #
+    # Creates a new OSClass object.
+    #
+    # @param [Symbol] type
+    #   The class of the OS.
+    #
+    # @param [String] vendor
+    #   The vendor of the OS.
+    #
+    # @param [String] family
+    #   The family of the OS.
+    #
+    # @param [Integer] accuracy
+    #   The accuracy of the OS guess.
+    #
+    def initialize(type,vendor,family,accuracy)
+      @type = type
+      @vendor = vendor
+      @family = family
+      @accuracy = accuracy
+    end
+
+    #
+    # Converts the OS class to a String.
+    #
+    # @return [String]
+    #   The String form of the OS class.
+    #
+    def to_s
+      "#{@type} #{@vendor} (#{@accuracy}%)"
+    end
+
+  end
+end