ruby-nmap 0.6.0 → 0.7.0

data/lib/nmap/uptime.rb

@@ -0,0 +1,20 @@
+module Nmap
+  #
+  # Wraps a `uptime` XML element.
+  #
+  # @since 0.7.0
+  #
+  class Uptime < Struct.new(:seconds, :last_boot)
+
+    #
+    # Converts the uptime object to a String.
+    #
+    # @return [String]
+    #   The String form of the Uptime.
+    #
+    def to_s
+      "uptime: #{self.seconds} (#{self.last_boot})"
+    end
+
+  end
+end

data/lib/nmap/version.rb

@@ -1,4 +1,4 @@
 module Nmap
   # ruby-nmap version
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

data/lib/nmap/xml.rb

@@ -2,6 +2,7 @@ require 'nmap/scanner'
 require 'nmap/scan_task'
 require 'nmap/scan'
 require 'nmap/host'
+require 'nmap/run_stat'
 
 require 'nokogiri'
 
@@ -19,8 +20,8 @@ module Nmap
     #
     # Creates a new XML object.
     #
-    # @param [String] path
-    #   The path to the Nmap XML scan file.
+    # @param [Nokogiri::XML::Document, IO, String] document
+    #   The path to the Nmap XML scan file or Nokogiri::XML::Document.
     #
     # @yield [xml]
     #   If a block is given, it will be passed the new XML object.
@@ -28,13 +29,56 @@ module Nmap
     # @yieldparam [XML] xml
     #   The newly created XML object.
     #
-    def initialize(path)
-      @path = File.expand_path(path)
-      @doc = Nokogiri::XML(open(@path))
+    def initialize(document)
+      case document
+      when Nokogiri::XML::Document
+        @doc = document
+      when IO, StringIO
+        @doc = Nokogiri::XML(document)
+      else
+        @path = File.expand_path(document)
+        @doc  = Nokogiri::XML(open(@path))
+      end
 
       yield self if block_given?
     end
 
+    #
+    # Creates a new XML object from XML text.
+    #
+    # @param [String] text
+    #   XML text of the scan file
+    #
+    # @yield [xml]
+    #   If a block is given, it will be passed the new XML object.
+    #
+    # @yieldparam [XML] xml
+    #   The newly created XML object.
+    #
+    # @since 0.7.0
+    #
+    def self.load(text,&block)
+      new(Nokogiri::XML(text), &block)
+    end
+
+    #
+    # Creates a new XML object from the file.
+    #
+    # @param [String] path
+    #   The path to the XML file.
+    #
+    # @yield [xml]
+    #   If a block is given, it will be passed the new XML object.
+    #
+    # @yieldparam [XML] xml
+    #   The newly created XML object.
+    #
+    # @since 0.7.0
+    #
+    def self.open(path,&block)
+      new(path,&block)
+    end
+
     #
     # Parses the scanner information.
     #
@@ -82,6 +126,47 @@ module Nmap
       end
     end
 
+    #
+    # Parses the essential runstats information.
+    #
+    # @yield [run_stat]
+    #   The given block will be passed each runstat.
+    #
+    # @yieldparam [RunStat] run_stat
+    #   A runstat.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an enumerator will be returned.
+    #
+    # @since 0.7.0
+    #
+    def each_run_stat
+      return enum_for(__method__) unless block_given?
+
+      @doc.xpath('/nmaprun/runstats/finished').each do |run_stat|
+        yield RunStat.new(
+          Time.at(run_stat['time'].to_i),
+          run_stat['elapsed'],
+          run_stat['summary'],
+          run_stat['exit']
+        )
+      end
+
+      return self
+    end
+
+    #
+    # Parses the essential runstats information.
+    #
+    # @return [Array<RunStat>]
+    #   The runstats.
+    #
+    # @since 0.7.0
+    #
+    def run_stats
+      each_run_stat.to_a
+    end
+
     #
     # Parses the verbose level.
     #
@@ -105,22 +190,44 @@ module Nmap
     #
     # Parses the tasks of the scan.
     #
-    # @return [Array<ScanTask>]
-    #   The tasks of the scan.
+    # @yield [task]
+    #   The given block will be passed each scan task.
     #
-    # @since 0.1.2
+    # @yieldparam [ScanTask] task
+    #   A task from the scan.
     #
-    def tasks
-      @doc.xpath('/nmaprun/taskbegin').map do |task_begin|
+    # @return [Enumerator]
+    #   If no block is given, an enumerator will be returned.
+    #
+    # @since 0.7.0
+    #
+    def each_task
+      return enum_for(__method__) unless block_given?
+
+      @doc.xpath('/nmaprun/taskbegin').each do |task_begin|
         task_end = task_begin.xpath('following-sibling::taskend').first
 
-        ScanTask.new(
+        yield ScanTask.new(
           task_begin['task'],
           Time.at(task_begin['time'].to_i),
           Time.at(task_end['time'].to_i),
           task_end['extrainfo']
         )
       end
+
+      return self
+    end
+
+    #
+    # Parses the tasks of the scan.
+    #
+    # @return [Array<ScanTask>]
+    #   The tasks of the scan.
+    #
+    # @since 0.1.2
+    #
+    def tasks
+      each_task.to_a
     end
 
     #
@@ -136,11 +243,11 @@ module Nmap
     #   The XML object. If no block was given, an enumerator object will
     #   be returned.
     #
-    def each_host(&block)
-      return enum_for(__method__) unless block
+    def each_host
+      return enum_for(__method__) unless block_given?
 
       @doc.xpath('/nmaprun/host').each do |host|
-        Host.new(host,&block)
+        yield Host.new(host)
       end
 
       return self
@@ -169,11 +276,11 @@ module Nmap
     #   The XML parser. If no block was given, an enumerator object will
     #   be returned.
     #
-    def each_up_host(&block)
-      return enum_for(__method__) unless block
+    def each_up_host
+      return enum_for(__method__) unless block_given?
 
       @doc.xpath("/nmaprun/host[status[@state='up']]").each do |host|
-        Host.new(host,&block)
+        yield Host.new(host)
       end
 
       return self
@@ -208,5 +315,15 @@ module Nmap
       @path.to_s
     end
 
+    #
+    # Inspects the XML file.
+    #
+    # @return [String]
+    #   The inspected XML file.
+    #
+    def inspect
+      "#<#{self.class}: #{self}>"
+    end
+
   end
 end

data/spec/address_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+require 'nmap/address'
+
+describe Address do
+  describe "#to_s" do
+    let(:addr) { '127.0.0.1' }
+
+    subject { described_class.new(:ipv4, addr) }
+
+    it "should return the address" do
+      subject.to_s.should == addr
+    end
+  end
+end

data/spec/cpe/url_spec.rb

@@ -0,0 +1,99 @@
+require 'spec_helper'
+
+describe CPE::URL do
+  describe "parse" do
+    context "when the URL does not start with 'cpe:'" do
+      it "should raise an ArgumentError" do
+        lambda {
+          described_class.parse('foo:')
+        }.should raise_error(ArgumentError)
+      end
+    end
+
+    context "when blank fields are omitted" do
+      let(:vendor)  { :linux        }
+      let(:product) { :linux_kernel }
+      let(:version) { '2.6.39'      }
+
+      subject do
+        described_class.parse("cpe:/o:#{vendor}:#{product}:#{version}")
+      end
+
+      it "should leave them nil" do
+        subject.vendor.should == vendor
+        subject.product.should == product
+        subject.version.should == version
+
+        subject.update.should be_nil
+        subject.edition.should be_nil
+        subject.language.should be_nil
+      end
+    end
+
+    context "when part is /h" do
+      subject { described_class.parse("cpe:/h:foo:bar:baz") }
+
+      it "should parse it as :hardware" do
+        subject.part.should == :hardware
+      end
+    end
+
+    context "when part is /a" do
+      subject { described_class.parse("cpe:/a:foo:bar:baz") }
+
+      it "should parse it as :application" do
+        subject.part.should == :application
+      end
+    end
+
+    context "when part is /o" do
+      subject { described_class.parse("cpe:/o:foo:bar:baz") }
+
+      it "should parse it as :os" do
+        subject.part.should == :os
+      end
+    end
+  end
+
+  describe "#to_s" do
+    let(:vendor)  { :linux        }
+    let(:product) { :linux_kernel }
+    let(:version) { '2.6.39'      }
+
+    it "should add the scheme 'cpe:'" do
+      subject.to_s.should start_with('cpe:')
+    end
+
+    context "when fields are nil" do
+      subject { described_class.new(:os,vendor,product,version) }
+
+      it "should omit them" do
+        subject.to_s.should == "cpe:/o:#{vendor}:#{product}:#{version}"
+      end
+    end
+
+    context "when part is :hardware" do
+      subject { described_class.new(:hardware) }
+
+      it "should map it to /h" do
+        subject.to_s.should == "cpe:/h"
+      end
+    end
+
+    context "when part is :application" do
+      subject { described_class.new(:application) }
+
+      it "should map it to /h" do
+        subject.to_s.should == "cpe:/a"
+      end
+    end
+
+    context "when part is :os" do
+      subject { described_class.new(:os) }
+
+      it "should map it to /h" do
+        subject.to_s.should == "cpe:/o"
+      end
+    end
+  end
+end

data/spec/cpe_examples.rb

@@ -0,0 +1,11 @@
+require 'rspec'
+
+shared_examples_for "CPE" do
+  subject { super().cpe }
+
+  it { should_not be_empty }
+
+  it "should contain CPE URLs" do
+    subject.should all_be_kind_of(CPE::URL)
+  end
+end

data/spec/hop_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+require 'nmap/hop'
+
+describe Hop do
+  describe "#to_s" do
+    subject do
+      described_class.new('10.0.0.1', nil, '1', '3.38')
+    end
+
+    it "should return the addr" do
+      subject.to_s.should == subject.addr
+    end
+  end
+end

data/spec/host_spec.rb

@@ -1,12 +1,11 @@
 require 'spec_helper'
+require 'scripts_examples'
 
 require 'nmap/xml'
 require 'nmap/host'
 
 describe Host do
-  let(:xml) { XML.new(Helpers::SCAN_FILE) }
-
-  subject { xml.hosts.first }
+  subject { @xml.hosts.first }
 
   it "should parse the start_time" do
     subject.start_time.should > Time.at(0)
@@ -17,91 +16,175 @@ describe Host do
     subject.end_time.should > subject.start_time
   end
 
-  it "should parse the status" do
-    status = subject.status
-    
-    status.state.should == :up
-    status.reason.should == 'arp-response'
+  describe "#uptime" do
+    subject { super().uptime }
+
+    it "should return an Uptime object" do
+      subject.should be_kind_of(Uptime)
+    end
+
+    it "should parse the seconds attribute" do
+      subject.seconds.should be > 0
+    end
+
+    it "should parse the lastboot attribute" do
+      subject.last_boot.should be_kind_of(Time)
+    end
   end
 
-  it "should parse the addresses" do
-    addresses = subject.addresses
-    
-    addresses.length.should == 2
+  describe "#tcp_sequence" do
+    subject { super().tcp_sequence }
 
-    addresses[0].type.should == :ipv4
-    addresses[0].addr.should == '192.168.5.1'
+    it { should be_kind_of(TcpSequence) }
+  end
+
+  describe "#ip_ip_sequence" do
+    subject { super().ip_id_sequence }
 
-    addresses[1].type.should == :mac
-    addresses[1].addr.should == '00:1D:7E:EF:2A:E5'
+    it { should be_kind_of(IpIdSequence) }
   end
 
-  it "should parse the MAC address" do
-    subject.mac.should == '00:1D:7E:EF:2A:E5'
+  describe "#tcp_ts_sequence" do
+    subject { super().tcp_ts_sequence }
+
+    it { should be_kind_of(TcpTsSequence) }
   end
 
-  it "should parse the IPv4 address" do
-    subject.ipv4.should == '192.168.5.1'
+  describe "#status" do
+    subject { super().status }
+
+    it "should parse the state" do
+      subject.state.should be_one_of(:up, :down)
+    end
+
+    it "should parse the reason" do
+      subject.reason.should be_one_of(
+        'syn-ack',
+        'timestamp-reply',
+        'echo-reply',
+        'reset'
+      )
+    end
+  end
+
+  describe "#addresses" do
+    subject { super().addresses.first }
+
+    it "should parse the type" do
+      subject.type.should == :ipv4
+    end
+
+    it "should parser the addr" do
+      subject.addr.should == '74.207.244.221'
+    end
   end
 
-  it "should parse the IPv6 address" do
-    pending "generate a Nmap XML scan file including IPv6 addresses"
+  describe "#mac" do
+    it "should parse the first MAC address" do
+      pending "need a host with address[@addrtype='mac']"
+    end
   end
 
-  it "should have an IP" do
-    subject.ip.should == '192.168.5.1'
+  describe "#ipv6" do
+    it "should parse the first IPv6 address" do
+      pending "need a host with address[@addrtype='ipv6']"
+    end
   end
 
-  it "should have an address" do
-    subject.address.should == '192.168.5.1'
+  describe "#ipv4" do
+    it "should parse the IPv4 address" do
+      subject.ipv4.should == '74.207.244.221'
+    end
   end
 
-  it "should parse the hostnames" do
-    pending "generate a Nmap XML scan file including hostnames"
+  describe "#ip" do
+    it "should have an IP" do
+      subject.ip.should == '74.207.244.221'
+    end
   end
 
-  it "should parse the OS guessing information" do
-    subject.os.should_not be_nil
+  describe "#address" do
+    it "should have an address" do
+      subject.address.should == '74.207.244.221'
+    end
   end
 
-  it "should parse the ports" do
-    ports = subject.ports
-    
-    ports.length.should == 3
+  describe "#hostnames" do
+    subject { super().hostnames }
+
+    it { should_not be_empty }
+
+    it "should parse the type" do
+      subject.all? { |hostname| hostname.type }.should be_true
+    end
+
+    it "should parse the name" do
+      subject.all? { |hostname| hostname.name }.should be_true
+    end
+
+    it "should include a user hostname" do
+      subject.any? { |hostname| hostname.type == 'user' }.should be_true
+    end
+
+    it "should include a PTR hostname" do
+      subject.any? { |hostname| hostname.type == 'PTR' }.should be_true
+    end
   end
 
-  it "should list the open ports" do
-    ports = subject.open_ports
-    
-    ports.length.should == 1
-    ports.all? { |port| port.state == :open }.should == true
+  describe "#os" do
+    subject { super().os }
+
+    it { should_not be_nil }
+    it { should be_kind_of(OS) }
   end
 
-  it "should list TCP ports" do
-    ports = subject.tcp_ports
-    
-    ports.length.should == 3
-    ports.all? { |port| port.protocol == :tcp }.should == true
+  describe "#ports" do
+    subject { super().ports }
+
+    it { should_not be_empty }
   end
 
-  it "should list the UDP ports" do
-    pending "generate a Nmap XML scan file including scanned UDP ports"
+  describe "#open_ports" do
+    subject { super().open_ports }
+
+    it { should_not be_empty }
+
+    it "should list the open ports" do
+      subject.all? { |port| port.state == :open }.should be_true
+    end
   end
 
-  it "should convert to a String" do
-    subject.to_s.should == '192.168.5.1'
+  describe "#tcp_ports" do
+    subject { super().tcp_ports }
+
+    it { should_not be_empty }
+
+    it "should contain TCP ports" do
+      subject.all? { |port| port.protocol == :tcp }.should be_true
+    end
   end
 
-  context "when NSE scripts are ran" do
-    let(:xml) { XML.new(Helpers::NSE_FILE) }
+  describe "#udp_ports" do
+    subject { super().udp_ports }
+
+    it { should_not be_empty }
 
-    subject { xml.hosts.first }
+    it "should contain UDP ports" do
+      subject.all? { |port| port.protocol == :udp }.should be_true
+    end
+  end
 
-    it "should list output of the scripts" do
-      subject.scripts.should_not be_empty
+  it "should convert to a String" do
+    subject.to_s.should == '74.207.244.221'
+  end
 
-      subject.scripts.keys.should_not include(nil)
-      subject.scripts.values.should_not include(nil)
+  describe "#inspect" do
+    it "should include the address" do
+      subject.inspect.should include(subject.address)
     end
   end
+
+  pending "scan.xml does not currently include any hostscripts" do
+    include_examples "#scripts"
+  end
 end