NAME
Masscan::Scanner - A Perl module which helps in using the masscan port scanner.
VERSION
version 20200328.165101
SYNOPSIS
use Masscan::Scanner;
my @hosts = qw(::1 127.0.0.1);
my @ports = qw(22 80 443 1-100);
my @arguments = qw(--banners);
my $mas = Masscan::Scanner->new(hosts => \@hosts, ports => \@ports, arguments => \@arguments);
# Add extra hosts or ports
$mas->add_host('10.0.0.1');
$mas->add_host('10.0.0.0/24');
$mas->add_port(25);
$mas->add_port(110);
# Can add port ranges too
$mas->add_port('1024-2048');
$mas->add_port('3000-65535');
# Can add domains but will incur a performance penalty hence IP(s) and CIDR(s) recommended.
# When a domain is added to the list of hosts to be scanned this module will attempt to
# resolve all of the A records for the domain name provided and then add the IP(s) to the
# scan list.
$mas->add_host('averna.id.au');
$mas->add_host('duckduckgo.com');
# It is usually required that masscan is run as a privilaged user.
# Obviously this module can be successfully run as the root user.
# However, if this is being run by an unprivilaged user then sudo can be enabled.
#
# PLEASE NOTE: This module assumes the user can run the masscan command without
# providing their password. Usually this is achieved by permitting the user to
# run masscan within the /etc/sudoers file like so:a
#
# In /etc/sudoers: user averna = (root) NOPASSWD: /usr/bin/masscan
$mas->sudo(1);
# Turn on verbose mode
# Default is off
$mas->verbose(1);
# Add extra masscan arguments
$mas->add_argument('--rate 100000');
# Set the full path to masscan binary
# Default is the module will automatically find the binary full path if it's
# withing the users environment path.
$mas->binary('/usr/bin/masscan');
# Set the name servers to be used for DNS resolution
# Default is to use a list of public DNS servers.
$mas->name_servers(['192.168.0.100', '192.168.0.101']);
# Will initiate the masscan.
# If the scan is successful returns True otherwise returns False.
my $scan = $mas->scan;
# Returns the scan results
my $res = $mas->scan_results if ($scan);METHODS
add_host
This method allows the addition of a host to the host list to be scaned.
my $mas = Masscan::Scanner->new();
$mas->add_host('127.0.0.1');add_port
This method allows the addition of a port or port range to the port list to be scaned.
my $mas = Masscan::Scanner->new();
$mas->add_port(443);
$mas->add_port('1-65535');add_argument
This method allows the addition of masscan command line arguments.
my $mas = Masscan::Scanner->new(hosts => ['127.0.0.1', '10.0.0.1'], ports => [80. 443]);
$mas->add_argument('--banners');
$mas->add_argument('--rate 100000');scan
Will initiate the scan of what hosts & ports have been provided.
Returns true fi the scan was successful otherwise returns false.
my $mas = Masscan::Scanner->new();
$mas->hosts(['127.0.0.1', '::1']);
$mas->ports(['22', '80', '443']);
$mas->add_port('1024');
$mas->scan;scan_results
Returns the result of the masscan as a Perl data structure.
my $mas = Masscan::Scanner->new();
$mas->hosts(['127.0.0.1', '::1']);
$mas->ports(['22', '80', '443']);
$mas->add_port('1024');
my $scan = $mas->scan;
if ($scan)
{
my $res = $mas->scan_results;
}SCAN RESULTS
The scan_results method returns a data structure like so:
{
'scan_results' => [
{
'timestamp' => '1584816181',
'ip' => '10.0.0.1',
'ports' => [
{
'status' => 'open',
'reason' => 'syn-ack',
'port' => 443,
'proto' => 'tcp',
'ttl' => 60
}
]
},
{
'timestamp' => '1584816181',
'ip' => '10.0.0.2',
'ports' => [
{
'reason' => 'syn-ack',
'status' => 'open',
'port' => 443,
'ttl' => 60,
'proto' => 'tcp'
}
]
},
{
'ports' => [
{
'port' => 80,
'ttl' => 60,
'proto' => 'tcp',
'reason' => 'syn-ack',
'status' => 'open'
}
],
'ip' => '10.0.0.1',
'timestamp' => '1584816181'
},
{
'ip' => '10.0.0.2',
'timestamp' => '1584816181',
'ports' => [
{
'port' => 80,
'ttl' => 60,
'proto' => 'tcp',
'status' => 'open',
'reason' => 'syn-ack'
}
]
},
{
'timestamp' => '1584816181',
'ip' => '10.0.0.3',
'ports' => [
{
'reason' => 'syn-ack',
'status' => 'open',
'proto' => 'tcp',
'ttl' => 111,
'port' => 80
}
]
},
{
'ports' => [
{
'ttl' => 111,
'proto' => 'tcp',
'port' => 443,
'reason' => 'syn-ack',
'status' => 'open'
}
],
'timestamp' => '1584816181',
'ip' => '10.0.0.3'
}
],
'masscan' => {
'scan_stats' => {
'total_hosts' => 4,
'up_hosts' => 3
},
'command_line' => '/usr/bin/masscan --rate 100000 --banners -p 22,80,443,61222,25 10.0.0.2,10.0.0.1,10.0.0.3,10.0.0.4'
}
};AUTHOR
Sarah Fuller <averna@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2020 by Sarah Fuller.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.