NAME

Nmap::Parser::XML - frontend to parse the Nmap scan data from the XML output (-oX).

SYNOPSIS

  use Nmap::Parser::XML;

  my $p = new Nmap::Parser::XML;
  $p->parse($fh); #filehandle or nmap xml output string
  #or $p->parsefile('nmap_output.xml');
  my @hosts = $p->get_host_list('up');#only get if they are active

  print "Hosts scanned:\n";
  for (@hosts) {print "Address: ".$_->addr()."\t".$_->hostnames()."\n";}

  "\n\nUnix Flavor Machines:\n";
  for ($p->filter_by_generic_os('linux','solaris','unix')){print;}

  print "\n\nAnd for those who like Windows:\n";
  for ($p->filter_by_generic_os('win')){print;}

  $p->clean(); #frees memory

DESCRIPTION

This is an XML parser for nmap XML reports. This uses the XML::Twig library which is fast and more memory efficient than using the XML::SAX::PurePerl that comes with Nmap::Scanner::Scanner. This module, in the authors opinion, is easier to use for basic information gathering of hosts.

METHODS

Easy Steps

1. Using this module is very simple. (hopefully). You use $obj->parse() or $obj->parsefile(), to parse the nmap xml information. This information is parsed and constructed internally.

2.a Use the $s = $obj->get_scaninfo() to obtain the Nmap::Parser::XML::ScanInfo object. Then you can call any of the ScanInfo methods on this object to retrieve the information. See Nmap::Parser::XML::ScanInfo below.

2.b Use the $h = $obj->get_host($addr) to obtain the Nmap::Parser::XML::Host object of the current address. Using this object you can call any methods in the Host object to retrieve the information taht nmap obtained from this scan.

3. You can use any of the other methods to filter or obtain different lists. Example: get_host_list() returns all ip addresses that were scanned filter_by_generic_os($os) returns all ip addresses that have generic_os = $os See get_os_list() and set_os_list() etc. (see other methods)

4. After you are done with everything, you should do a $obj->clean() to free up the memory used by maintaining the scan and hosts information from the scan. A much more efficient way to do is, once you are done using a host object, delete it from the main tree.

 Example:
 for my $host ($obj->get_host_list())
        {
        my $h = $obj->get_host($host);
        print "Addr: $host  OS: ".(join ',',$h->os_matches())."\n";
        $obj->del_host($host); #frees memory    
        }
        
 Of course a much better way would be:
 for ($obj->get_host_objects())
 {
 print "Addr: ".$_->addr()." OS: ".$_->os_matches()."\n";
 delete $_;
 }

new()

parse($source [, opt => opt_value [...]])

Same as XML::Twig::parse().

This method is inherited from XML::Parser. The "SOURCE" parameter should either be a string containing the whole XML document, or it should be an open "IO::Handle". Constructor options to "XML::Parser::Expat" given as keyword-value pairs may follow the"SOURCE" parameter. These override, for this call, any options or attributes passed through from the XML::Parser instance.

A die call is thrown if a parse error occurs. Otherwise it will return the twig built by the parse. Use "safe_parse" if you want the parsing to return even when an error occurs.

parsefile($filename [, opt => opt_value [...]])

Same as XML::Twig::parsefile().

This method is inherited from XML::Parser. Open "$filename" for reading, then call "parse" with the open handle. The file is closed no matter how "parse" returns.

A die call is thrown if a parse error occurs. Otherwise it willreturn the twig built by the parse. Use "safe_parsefile" if you want the parsing to return even when an error occurs.

safe_parse($source [, opt => opt_value [...]])

Same as XML::Twig::safe_parse().

This method is similar to "parse" except that it wraps the parsing in an "eval" block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig). $@ contains the error message on failure.

Note that the parsing still stops as soon as an error is detected, there is no way to keep going after an error.

safe_parsefile($source [, opt => opt_value [...]])

Same as XML::Twig::safe_parsefile().

This method is similar to "parsefile" except that it wraps the parsing in an "eval" block. It returns the twig on success and 0 on failure (the twig object also contains the parsed twig) . $@ con- tains the error message on failure

Note that the parsing still stops as soon as an error is detected, there is no way to keep going after an error.

clean()

Frees up memory by cleaning the current tree hashes and purging the current information in the XML::Twig object.

only_active()

only_inactive()

set_generic_os_list($hashref)

Decides what is the generic OS name of the given system.

Takes in a hash refernce that referes to pairs of generic os names to their keyword list. Shown here is the default. Calling this method will overwrite the whole list, not append to it. Use get_generic_os_list() first to get the current listing.

  $obj->set_generic_os_list({
        solaris => [qw(solaris sparc sunos)],
        linux => [qw(linux mandrake redhat slackware)],
        unix => [qw(unix hpux bsd immunix)],
        windows  => [qw(win microsoft crap)],
        mac => [qw(mac osx)],
        switch => [qw(ethernet cisco netscout)]
            });

example: generic_os_name = solaris if the os string being matched matches (solaris, sparc or sunos) keywords

get_generic_os_list()

Returns a hashre containing the current generic os names (keys) and an arrayref pointing to the list of corresponding keywords (values). See set_generic_os_list() for an example.

get_host_list([$status])

Returns all the ip addresses that were run in the nmap scan. $status is optional and can be either 'up' or 'down'. If $status is given, then only IP addresses that have that corresponding state will be returned. Example: setting $status = 'up', then will return all IP addresses that were found to be up. (network talk for active)

get_host_tree($ip_addr)

Returns the complete tree of the corresponding IP address.

del_host_tree($ip_addr)

Deletes the corresponding host tree from the main forest. (Frees up memory of unwanted host structures).

get_host_objects()

Returns all the host objects of all the IP addresses that nmap had run against. See Nmap::Parser::XML::Host.

filter_by_generic_os(@generic_os_names)

This returns all the IP addresses that have match any of the keywords in @generic_os_names that is set in their generic_names field. See os_list() for example on generic_os_name. This makes it easier to sift through the lists of IP if you are trying to split up IP addresses depending on platform (window and unix machines for example).

filter_by_status($status)

This returns an array of hosts addresses that are in the $status state. $status can be either 'up' or 'down'. Default is 'up'.

get_scaninfo_tree()

Returns the the current Nmap::Parser::XML::ScanInfo. Methods can be called on this object to retrieve information about the parsed scan. See Nmap::Parser::XML::ScanInfo below.

Nmap::Parser::XML::ScanInfo

The scaninfo tree object. This package contains methods to easily access all the parameters and values of the Nmap scan ran by the currently parsed xml file or filehandle.

num_of_services([$scan_type]);

If given a corresponding scan type, it returns the number of services that was scan by nmap for that scan type. If $scan_type is omitted, then num_of_services() returns the total number of services scan by all scan_types.

start_time()

Returns the start time of the nmap scan.

finish_time()

Returns the finish time of the nmap scan.

nmap_version()

Returns the version of nmap that ran.

args()

Returns the command line parameters that were run with nmap

scan_types()

In list context, returns an array containing the names of the scan types that were selected. In scalar context, returns the total number of scan types that were selected.

proto_of_scan_type($scan_type)

Returns the protocol of the specific scan type.

Nmap::Parser::XML::Host

The host tree object. This package contains methods to access easily all the parameters in the host tree.

status()

Returns the status of the host system. Either 'up' or 'down'

addr()

Returns the IP address of the system

addrtype()

Returns the address type of the IP address returned by addr(). Ex. 'ipv4'

hostnames()

In a list context, returns an array of all the hostnames names that the given system has. In a scalar context, the first hostname is returned.

tcp_ports()

In a list context, returns an array containing the open tcp ports on the system. In a scalar context, a hash reference of the tree branch is returned.

udp_ports()

In a list context, returns an array containing the open udp ports on the system. In a scalar context, a hash reference of the tree branch is returned.

tcp_service_name($port)

Returns the name of the service running on the given tcp $port. (if any)

udp_service_name($port)

Returns the name of the service running on the given udp $port. (if any)

os_matches()

In a list context, returns an array containing all of the OS strings that matched the given host. In a scalar context, the first OS string is returned.

os_port_used()

Returns the port number that was used in determining the OS of the system.

os_generic()

Returns the generic_name that was matched to the given host. (see set_os_list()).

uptime_seconds()

Returns the number of seconds the host has been up (since boot).

uptime_lastboot()

Returns the time and date the given host was last rebooted.

AUTHOR

Anthony G Persaud <ironstar@iastate.edu>

SEE ALSO

nmap(1), XML::Twig(3), Nmap::Scanner::Basic

  http://www.insecure.org/nmap/
  http://www.xmltwig.com

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html