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/.
Some descriptions of methods here are taken directly from the nmap man page.
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"
);
}
}
Register for any of the below events if you wish to use Nmap::Scanner in
event-driven mode.
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 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 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 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 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 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 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 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);
Set this to a non-zero value to see debugging output.
Set this to non-zero to have Nmap::Scanner::Scanner print the nmap command line
and exit when
scan() is called.
specify the network interface that nmap should use for scanning
See the nmap man page for descriptions of all these.
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.'
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().
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().
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.
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()
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.
Try and guess the operating system of each target host using TCP fingerprinting.
Only scan for services listed in nmap's services file.
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.
Specifies how much time nmap spends on scanning each host before giving up. Not
set by default.
Specifies the maximum time nmap should wait for a response to a probe of a port.
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.
Specifies the initial probe timeout. See the nmap man page for more detail.
Specifies the maximum number of scans Nmap is allowed to perform in parallel.
Specifies the minimum amount of time Nmap must wait between probes.
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);
Perform the scan. Returns a populated instance of
Nmap::Scanner::Backend::Results when scanning in batch mode (as opposed to
event-driven mode).
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');
If nmap is not in your PATH, you can specify where it is using this method.
Hey!
The above document had some coding errors, which are explained
below:
- Around line 553:
- '=item' outside of any '=over'
- Around line 611:
- You forgot a '=back' before '=head2'