ruby-nmap 0.1.1 → 0.2.0

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title 'Ruby Nmap Documentation' --protected --files ChangeLog.md,LICENSE.txt

data/ChangeLog.md

@@ -0,0 +1,25 @@
+### 0.2.0 / 2010-10-29
+
+* Require nokogiri >= 1.3.0.
+* Require rprogram ~> 0.2.0.
+* Added {Nmap::XML#tasks}.
+* Added {Nmap::Scanner#start_time}.
+* Added {Nmap::ScanTask#duration}.
+* Added {Nmap::Host#start_time}.
+* Added {Nmap::Host#end_time}.
+* Allow `Nmap::Tasks#ports=` to accept port ranges.
+* Omit the `-p` option if no ports are given to {Nmap::Task}.
+* Have the `Nmap::Host#each_*` methods return an `Enumerator` object if no
+  block is given.
+
+### 0.1.1 / 2010-01-02
+
+* Require RProgram >= 0.1.8.
+  * Adds `sudo` and `sudo=` instance methods to {Nmap::Task}.
+
+### 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/LICENSE.txt

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2009-2010 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/README.md

@@ -0,0 +1,63 @@
+# ruby-nmap
+
+* [Source](http://github.com/sophsec/ruby-nmap/)
+* [Issues](http://github.com/sophsec/ruby-nmap/issues)
+* [Documentation](http://rubydoc.info/gems/ruby-nmap/file/README.md)
+* 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.sudo = true
+
+      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.3.0
+* [rprogram](http://github.com/postmodern/rprogram) ~> 0.2.0
+
+## Install
+
+    $ sudo gem install ruby-nmap
+
+## License
+
+See {file:LICENSE.txt} for license information.
+

data/Rakefile

@@ -1,28 +1,35 @@
-# -*- 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')
+require 'rake'
 
-  self.readme_file = 'README.rdoc'
-  self.history_file = 'History.rdoc'
-  self.remote_rdoc_dir = '/'
+begin
+  gem 'ore-tasks', '~> 0.1.2'
+  require 'ore/tasks'
 
-  self.extra_deps = [
-    ['nokogiri', '>=1.4.0'],
-    ['rprogram', '>=0.1.8']
-  ]
+  Ore::Tasks.new
+rescue LoadError => e
+  STDERR.puts e.message
+  STDERR.puts "Run `gem install ore-tasks` to install 'ore/tasks'."
+end
 
-  self.extra_dev_deps = [
-    ['rspec', '>=1.1.12'],
-    ['yard', '>=0.2.3.5']
-  ]
+begin
+  gem 'rspec', '~> 2.0.0'
+  require 'rspec/core/rake_task'
 
-  self.spec_extras = {:has_rdoc => 'yard'}
+  RSpec::Core::RakeTask.new
+rescue LoadError => e
+  task :spec do
+    abort "Please run `gem install rspec` to install RSpec."
+  end
 end
+task :default => :spec
 
-# vim: syntax=ruby
+begin
+  gem 'yard', '~> 0.6.0'
+  require 'yard'
+
+  YARD::Rake::YardocTask.new  
+rescue LoadError => e
+  task :yard do
+    abort "Please run `gem install yard` to install YARD."
+  end
+end

data/gemspec.yml

@@ -0,0 +1,23 @@
+name: ruby-nmap
+summary: A Ruby interface to Nmap.
+description:
+  A Ruby interface to Nmap, the exploration tool and security / port
+  scanner.
+
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: http://github.com/sophsec/ruby-nmap
+has_yard: true
+
+requirements: nmap, 4.xx or greater
+
+dependencies:
+  nokogiri: >= 1.3.0
+  rprogram: ~> 0.2.0
+
+development_dependencies:
+  ore: ~> 0.2.1
+  ore-tasks: ~> 0.1.2
+  rspec: ~> 2.0.0
+  yard: ~> 0.6.0

data/lib/nmap/host.rb

@@ -30,6 +30,30 @@ module Nmap
       block.call(self) if block
     end
 
+    #
+    # The time the host was first scanned.
+    #
+    # @return [Time]
+    #   The time the host was first scanned.
+    #
+    # @since 0.1.2
+    #
+    def start_time
+      Time.at(@node['starttime'].to_i)
+    end
+
+    #
+    # The time the host was last scanned.
+    #
+    # @return [Time]
+    #   The time the host was last scanned.
+    #
+    # @since 0.1.2
+    #
+    def end_time
+      Time.at(@node['endtime'].to_i)
+    end
+
     #
     # Parses the status of the host.
     #
@@ -54,17 +78,20 @@ module Nmap
     # @yieldparam [Address] addr
     #   A address of the host.
     #
-    # @return [Host]
+    # @return [Host, Enumerator]
     #   The host.
+    #   If no block was given, an enumerator will be returned.
     #
-    def each_address(&block)
+    def each_address
+      return enum_for(:each_address) unless block_given?
+
       @node.xpath("address[@addr]").each do |addr|
         address = Address.new(
           addr['addrtype'].to_sym,
           addr['addr']
         )
 
-        block.call(address) if block
+        yield address
       end
 
       return self
@@ -77,7 +104,7 @@ module Nmap
     #   The addresses of the host.
     #
     def addresses
-      Enumerator.new(self,:each_address).to_a
+      each_address.to_a
     end
 
     #
@@ -157,12 +184,15 @@ module Nmap
     # @yieldparam [String] host
     #   A hostname of the host.
     #
-    # @return [Host]
+    # @return [Host, Enumerator]
     #   The host.
+    #   If no block was given, an enumerator will be returned.
     #
-    def each_hostname(&block)
+    def each_hostname
+      return enum_for(:each_hostname) unless block_given?
+
       @node.xpath("hostnames/hostname[@name]").each do |host|
-        block.call(host['name']) if block
+        yield host['name']
       end
 
       return self
@@ -175,7 +205,7 @@ module Nmap
     #   The hostnames of the host.
     #
     def hostnames
-      Enumerator.new(self,:each_hostname).to_a
+      each_hostname.to_a
     end
 
     #
@@ -205,12 +235,15 @@ module Nmap
     # @yieldparam [Port] port
     #   A scanned port of the host.
     #
-    # @return [Host]
+    # @return [Host, Enumerator]
     #   The host.
+    #   If no block was given, an enumerator will be returned.
     #
-    def each_port(&block)
+    def each_port
+      return enum_for(:each_port) unless block_given?
+
       @node.xpath("ports/port").each do |port|
-        block.call(create_port(port)) if block
+        yield create_port(port)
       end
 
       return self
@@ -223,7 +256,7 @@ module Nmap
     #   The scanned ports of the host.
     #
     def ports
-      Enumerator.new(self,:each_port).to_a
+      each_port.to_a
     end
 
     #
@@ -235,12 +268,15 @@ module Nmap
     # @yieldparam [Port] port
     #   An open scanned port of the host.
     #
-    # @return [Host]
+    # @return [Host, Enumerator]
     #   The host.
+    #   If no block was given, an enumerator will be returned.
     #
     def each_open_port(&block)
+      return enum_for(:each_open_port) unless block_given?
+
       @node.xpath("ports/port[state/@state='open']").each do |port|
-        block.call(create_port(port)) if block
+        yield create_port(port)
       end
 
       return self
@@ -253,7 +289,7 @@ module Nmap
     #   The open ports of the host.
     #
     def open_ports
-      Enumerator.new(self,:each_open_port).to_a
+      each_open_port.to_a
     end
 
     #
@@ -265,12 +301,15 @@ module Nmap
     # @yieldparam [Port] port
     #   An TCP scanned port of the host.
     #
-    # @return [Host]
+    # @return [Host, Enumerator]
     #   The host.
+    #   If no block was given, an enumerator will be returned.
     #
-    def each_tcp_port(&block)
+    def each_tcp_port
+      return enum_for(:each_tcp_port) unless block_given?
+
       @node.xpath("ports/port[@protocol='tcp']").each do |port|
-        block.call(create_port(port)) if block
+        yield create_port(port)
       end
 
       return self
@@ -283,7 +322,7 @@ module Nmap
     #   The TCP ports of the host.
     #
     def tcp_ports
-      Enumerator.new(self,:each_tcp_port).to_a
+      each_tcp_port.to_a
     end
 
     #
@@ -295,12 +334,15 @@ module Nmap
     # @yieldparam [Port] port
     #   An UDP scanned port of the host.
     #
-    # @return [Host]
+    # @return [Host, Enumerator]
     #   The host.
+    #   If no block was given, an enumerator will be returned.
     #
-    def each_udp_port(&block)
+    def each_udp_port
+      return enum_for(:each_udp_port) unless block_given?
+
       @node.xpath("ports/port[@protocol='udp']").each do |port|
-        block.call(create_port(port)) if block
+        yield create_port(port)
       end
 
       return self
@@ -313,7 +355,7 @@ module Nmap
     #   The UDP ports of the host.
     #
     def udp_ports
-      Enumerator.new(self,:each_udp_port).to_a
+      each_udp_port.to_a
     end
 
     #

data/lib/nmap/program.rb

@@ -8,7 +8,7 @@ module Nmap
     name_program 'nmap'
 
     #
-    # Finds the +nmap+ program and performs a scan.
+    # Finds the `nmap` program and performs a scan.
     #
     # @param [Hash{Symbol => Object}] options
     #   Additional options for nmap.

data/lib/nmap/scan_task.rb

@@ -0,0 +1,65 @@
+module Nmap
+  class ScanTask
+
+    # The name of the scan task
+    attr_reader :name
+
+    # The time the scan task begun
+    attr_reader :start_time
+
+    # The time the scan task ended
+    attr_reader :end_time
+
+    # Extra information on the scan task
+    attr_reader :extrainfo
+
+    #
+    # Creates a new ScanTask object.
+    #
+    # @param [String] name
+    #   The name of the scan task.
+    #
+    # @param [Time] start_time
+    #   The time the scan task begun.
+    #
+    # @param [Time] end_time
+    #   The time the scan task ended.
+    #
+    # @param [String] extrainfo
+    #   Any extra information relating to the scan task.
+    #
+    # @since 0.1.2
+    #
+    def initialize(name,start_time,end_time,extrainfo=nil)
+      @name = name
+      @start_time = start_time
+      @end_time = end_time
+      @extrainfo = extrainfo
+    end
+
+    #
+    # The duration of the scan task.
+    #
+    # @return [Integer]
+    #   The number of seconds it took the scan task to complete.
+    #
+    # @since 0.1.2
+    #
+    def duration
+      (@end_time - @start_time)
+    end
+
+    #
+    # Converts the scan task to a String.
+    #
+    # @return [String]
+    #   The String form of the scan task.
+    #
+    # @since 0.1.2
+    #
+    def to_s
+      "#{@start}: #{@name} (#{@extrainfo})"
+    end
+
+  end
+end