Nmap::Parser

What Is This Library For?

This library provides a Ruby interface to the Nmap Security Scanner and its XML formatted scan data. It can run Nmap and parse its XML output directly from the scan, parse a file or string of XML scan data, or parse XML scan data from an object via its read() method. This information is presented in an easy-to-use and intuitive fashion for further storage and manipulation.

Note that while Anthony Persaud’s Perl Nmap::Parser was certainly an inspiration when designing this library, there are a number of distinguishing characteristics. Very briefly, this library contains more classes, many more methods, and has blocks extensively available.

The Nmap Security Scanner is an awesome utility written and maintained by Fyodor (fyodor(a)insecure.org). Its main function is port scanning, but it also has service and operating system detection, its own scripting engine and a whole lot more. One of its many available output formats is XML, which allows machines to handle all of the information instead of us slowly sifting through tons of output.

Conventions

Depending on the data type, unavailable information is presented differently:

• Arrays are empty
• Non-arrays are nil, unless it’s a method that returns the size of one of the previously mentioned empty arrays. In this case they still return the size (which would be 0).

All information available as arrays are presented via methods. These methods not only return the array, but they also yield each element to a block if one is given.

Module Hierarchy

  Nmap::Parser
  |
  + Session           <- Scan session information
  |
  + Host              <- General host information
    |
    + ExtraPorts      <- Ports consolidated in an "ignored" state
    |
    + Port            <- General port information
    | |
    | + Service       <- Port Service information
    |
    + Script          <- NSE Script information (both host and port)
    |
    + Times           <- Timimg information (round-trip time, etc)
    |
    + Traceroute      <- General Traceroute information
    | |
    | + Hop           <- Individual Hop information
    |
    + OS              <- OS Detection information
      |
      + OSClass       <- OS Class information
      |
      + OSMatch       <- OS Match information

Examples

There are two ways to go about getting a new Parser object and actually parsing Nmap’s XML output:

• Call one of the Nmap::Parser class methods to parse the XML and return a new Parser object all in one step.
• Call Nmap::Parser.new to get a new object and then call one of the instance parsing methods (e.g. parsefile()). The main reason to go this route is that new() takes a hash of options; for example, this is how the callback feature is implemented.

Parsing XML Data Already Available as a String

This method is not limited to only String objects, but rather any object which responsds to to_str().

        require 'nmap/parser'

        parser = Nmap::Parser.new
        parser.parsestring(xml)

or

        parser = Nmap::Parser.parsestring(xml)

Reading and Parsing From a File

        require 'nmap/parser'

        parser = Nmap::Parser.parsefile("log.xml")

Reading and Parsing From an Object

This method can read from any object responding to a read() method that returns a String (or something else responding to to_str())

        require 'nmap/parser'

        parser = Nmap::Parser.parseread($stdin)

Scanning and Parsing

This is the only Parser method that requires Nmap to be available.

        require 'nmap/parser'

        parser = Nmap::Parser.parsescan("sudo nmap", "-sVC 192.168.1.0/24")

Registering a Callback

To use a callback you create a new Parser object and register a proc or method to call each time a new host is parsed, as soon as it’s parsed. The callback is then run in a new thread and is passed the newly created Nmap::Parser::Host object.

        require 'nmap/parser'

        callback = proc do |host|
                return if host.status != "up"
                puts "Found #{host.addr}"
        end

        parser = Nmap::Parser.new(:callback => callback)
        parser.parsefile("nmaplog.xml")

        # Found 192.168.10.1
        # Found 192.168.10.2
        # Found 192.168.10.7
        # [...]

Doing a Bit More

After printing a little session information, this example will cycle through all of the up hosts, printing state and service information on the open TCP and UDP ports. See the examples directory that comes with this library for more examples.

        puts "Nmap args: #{parser.session.scan_args}"
        puts "Runtime: #{parser.session.scan_time} seconds"
        puts

        parser.hosts("up") do |host|
                puts "#{host.addr} is up:"
                puts

                [:tcp, :udp].each do |type|
                        host.getports(type, "open") do |port|
                                srv = port.service

                                puts "Port ##{port.num}/#{port.proto} is open (#{port.reason})"
                                puts "\tService: #{srv.name}" if srv.name
                                puts "\tProduct: #{srv.product}" if srv.product
                                puts "\tVersion: #{srv.version}" if srv.version
                                puts
                        end
                end

                puts
        end

Credits

Author & Maintainer:

• Kris Katterjohn (katterjohn(a)gmail.com)

Contributors (in chronological order of first contribution):

• Stefan Friedli (stfr(a)scip.ch)
• Daniel Roethlisberger (daniel(a)roe.ch)
• Dustin Webber (dustinw(a)aos5.com)
• Tom Sellers (nmap(a)fadedcode.net)
• Rory McCune (rorym(a)nmrconsult.net)
• Russell Fulton (r.fulton(a)auckland.ac.nz)

Thanks a lot for taking the time and helping out, everybody!

For information on what each contributor actually did, please take a look at the project’s ChangeLog and Subversion logs.