DESCRIPTION

This is the primary class of this module; it is the driver for the Nmap::Scanner hierarchy. To use it, create an instance of Nmap::Scanner, possibly set the path to Nmap with nmap_location() (the default behaviour of this class is to search for nmap in the PATH variable.

my $nmap = new Nmap::Scanner(); $nmap->nmap_location('/usr/local/bin/nmap');

Set any options you wish to use in order to run the scan in either batch or event mode, and then call scan() to start scanning. The results are return in an Nmap::Scanner::Backend::Results object.

my $results = $nmap->scan();

For information on the options presented below, see the man page for nmap or go to http://www.insecure.org/nmap/.

NOTE

Some descriptions of methods here are taken directly from the nmap man page.

EXAMPLE

See examples/ directory in the distribution for many more)

use Nmap::Scanner;
my $scan = Nmap::Scanner->new();

$scan->add_target('localhost');
$scan->add_target('host.i.administer');
$scan->add_scan_port('1-1024');
$scan->add_scan_port('31337');
$scan->tcp_syn_scan();
$scan->noping();

my $results = $scan->scan();

my $hosts = $results->gethostlist();

while (my $host = $hosts->get_next()) {

    print "On " . $host->hostname() . ": \n";

    my $ports = $host->get_port_list();

    while (my $port = $ports->get_next()) {
        print join(' ',
            'Port',
            $port->service() . '/' . $port->portid(),
            'is in state',
            $port->state(),
            "\n"
        );
    }

}

SCAN EVENTS

Register for any of the below events if you wish to use Nmap::Scanner in event-driven mode.

register_scan_complete_event(\&host_done)

Register for this event to be notified when a scan of a host is complete. Pass in a function reference that can accept a $self object reference and a reference to an Nmap::Scanner::Host object.

host_done($self, $host);

register_scan_started_event(\&scan_started);

Register for this event to be notified when nmap has started to scan one of the targets specified in add_target. Pass in a function reference that can accept a $self object reference, and a reference to an Nmap::Scanner::Host object.

scan_started($self, $host);

register_host_closed_event(\&host_closed);

Register to be notified if a scanned host is found to be closed (no open ports). Pass in a function reference that can take an $self object reference and a reference to a Host object.

XXX --- TBD (not implemented yet).

host_closed($self, $host);

register_port_found_event(\&port_found);

Register to be notified when a port is scanned on a host. The port may be in any state ... closed, open, filtered. Pass a reference to a function that takes a $self object reference, a Host reference, and a Port reference.

port_found($self, $host, $port);

register_no_ports_open_event(\&port_found);

Register to be notified in the event that no ports are found to be open on a host. Pass in a reference to a function that takes a $self object reference, a Host reference, and a reference to an ExtraPorts object. The ExtraPorts object describes ports that are in a state other than open (e.g. flitered, closed).

port_found($self, $host, $extra_ports);

register_task_started_event(\&task_begin);

Register to be notified when an internal nmap task starts. Pass in a reference to a function that takes a $self object reference and an Nmap::Scanner::Task reference. Note that end_time() will be undefined in the Task instance as this is a begin event.

task_begin($self, $task);

register_task_ended_event(\&task_end);

Register to be notified when an internal nmap task ends. Pass in a reference to a function that takes a $self object reference and an Nmap::Scanner::Task reference.

task_end($self, $task);

register_task_progress_event(\&task_progress);

Register to be notified when an internal nmap task progress event is fired; this happens when a task takes more than a few seconds to complete (good for GUIs).

Pass in a reference to a function that takes a $self object reference and an Nmap::Scanner::TaskProgress reference.

task_progress($self, $task_progress);

debug()

Set this to a non-zero value to see debugging output.

norun()

Set this to non-zero to have Nmap::Scanner::Scanner print the nmap command line and exit when scan() is called.

use_interface()

specify the network interface that nmap should use for scanning

SCAN TYPES

See the nmap man page for descriptions of all these.

tcp_connect_scan()

tcp_syn_scan()

fin_scan()

xmas_scan()

null_scan()

ping_scan()

udp_scan()

protocol_scan()

If this scan is used, the protocols can be retrieved from the Nmap::Scanner::Host objects using the method get_protocol_list(); this method returns a list of Nmap::Scanner::Port object references of type 'ip.'

idle_scan($zombie_host, $probe_port)

ack_scan()

window_scan()

version_scan($intestity)

rpc_scan()

SPECIFYING PORTS TO SCAN

Use add_scan_port($port_spec) to add one or more ports to scan. $port_spec can be a single port or a range: $n->add_scan_port(80) or $n->add_scan_port('80-1023');

Use delete_scan_port($portspec) to delete a port or range of ports.

Use reset_scan_ports() to cancel any adds done with add_scan_port().

Use getports to get a hash reference in which the keys are the ports you specified with add_scan_port().

SPECIFYING TARGETS TO SCAN

See the nmap documentation for the full syntax nmap supports for specifying hosts / subnets / networks to scan.

Use add_target($hostspec) to add a target to scan.

Use delete_target($hostspec) to delete a target from the list of hosts/networks to scan (must match text used in add_target($hostspec)).

Use reset_targets() to cancel any targets you specified with add_target().

PING OPTIONS

nmap has a very flexible mechanism for setting how a ping is interpreted for hosts during a scan. See the nmap documentation for more details.

Use no_ping() to not ping hosts before scanning them.

Use ack_ping($port) to use a TCP ACK packet as a ping to the port specified on each host to be scanned.

Use syn_ping($port) to use a TCP SYN packet as a ping to the port specified on each host to be scanned.

Use icmp_ping() to use a true ICMP ping for each host to be scanned.

Use ack_icmp_ping($port) to use an ICMP ping, then a TCP ACK packet as a ping (if the ICMP ping fails) to the port specified on each host to be scanned. This is the default behaviour if no ping options are specified.

TIMING OPTIONS

Use these methods to set how quickly or slowly nmap scans a host. For more detail on these methods, see the nmap documentation.

From slowest to fastest:

• paranoid_timing()

• sneaky_timing()

• polite_timing()

• normal_timing()

• aggressive_timing()

• insane_timing()

OTHER OPTIONS

There are many other nmap options. I have done my best to to represent them all. I welcome patches from users for any that I have missed.

For details on any of these methods see the nmap documentation.

guess_os()

Try and guess the operating system of each target host using TCP fingerprinting.

fast_scan()

Only scan for services listed in nmap's services file.

ident_check() [DEPRECATED]

Attempts to find the user that owns each open port by querying the ident damon of the remote host. See the nmap man page for more details. Support for ident checking is being removed from nmap as so few hosts allow or utilize IDENT anymore.

host_timeout($milliseconds)

Specifies how much time nmap spends on scanning each host before giving up. Not set by default.

max_rtt_timeout($milliseconds)

Specifies the maximum time nmap should wait for a response to a probe of a port.

max_rtt_timeout($milliseconds)

Specifies the minimum time nmap should wait for a response to a probe of a port. Nmap reduces the amoutn of time per response if the scanned machines respond quickly; it will not go below this threshold.

initial_rtt_timeout($milliseconds)

Specifies the initial probe timeout. See the nmap man page for more detail.

max_parallelism($number)

Specifies the maximum number of scans Nmap is allowed to perform in parallel.

scan_delay($milliseconds)

Specifies the minimum amount of time Nmap must wait between probes.

open_nmap()

This method sets up a scan, but instead of actually performing the scan, it returns the PID, read filehandle, write file handle, and error file handle of the opened nmap process. Use this if you wish to just use Nmap::Scanner::Scanner as your front end to set up a scan but you wish to process it in some way not supported by Nmap::Scanner.

Example:

my $scan = Nmap::Scanner->new();

my $opts = '-sS -P0 -p 1-1024 192.168.32.1-255';

my ($pid, $in, $out, $err) = $scan->open_nmap($opts);

scan()

Perform the scan. Returns a populated instance of Nmap::Scanner::Backend::Results when scanning in batch mode (as opposed to event-driven mode).

scan_from_file()

Recreate a scan from an existing nmap XML-formatted output file. Pass this method in the name of an XML file created by a previously performed nmap scan done in XML output mode and the file will be processed in the same manner as a live scan would be processed. If the passed in file looks like a URI, the module will attempt to retrieve the file using an HTTP GET simple (LWP::UserAgent).

Examples:

my $scanner = Nmap::Scanner->new();
my $results = $scanner->scan_from_file('/path/to/scan_output.xml');
my $results = $scanner->scan_from_file('http://example.com/results.xml');

nmap_location($path)

If nmap is not in your PATH, you can specify where it is using this method.

cpanm Nmap::Scanner

perl -MCPAN -e shell
install Nmap::Scanner