NAME
Masscan::Client - A Perl module which helps in using the masscan port scanner.
VERSION
version 0.2
SYNOPSIS
use Masscan::Client;
my @hosts = qw(::1 127.0.0.1);
my @ports = qw(22 80 443 1-100);
my @arguments = qw(--banners);
my $mas = Masscan::Client -> new(
hosts => \@hosts,
ports => \@ports,
arguments => \@arguments
);
$mas -> add_host('10.0.0.1');
$mas -> add_host('10.0.0.0/24');
$mas -> add_port(25);
$mas -> add_port(110);
$mas -> add_port('1024-2048');
$mas -> add_port('3000-65535');
$mas -> add_host('averna.id.au');
$mas -> add_host('duckduckgo.com');
$mas -> sudo(1);
$mas -> verbose(1);
$mas -> add_argument('--rate 100000');
$mas -> binary('/usr/bin/masscan');
$mas -> name_servers(['192.168.0.100', '192.168.0.101']);
my $scan = $mas -> scan;
my $res;
if ($scan) {
$res = $mas -> scan_results;
}DESCRIPTION
Masscan::Client provides an object-oriented interface for building, running, and parsing masscan scans from Perl code.
SUBROUTINES/METHODS
add_host
This method allows the addition of a host to the host list to be scaned.
my $mas = Masscan::Client -> 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::Client -> 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::Client -> 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::Client -> 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::Client -> 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'
}
};DIAGNOSTICS
The module logs warnings and errors through Log::Log4perl. Typical diagnostics include invalid host or port input, missing masscan binary, and JSON parsing failures in scan output.
CONFIGURATION AND ENVIRONMENT
The module discovers the masscan binary from the `PATH` environment variable when not explicitly set. DNS lookups use configurable name servers through the `name_servers` attribute.
DEPENDENCIES
Core dependencies include Moose, JSON, Net::DNS, Data::Validate::IP, Data::Validate::Domain, Try::Catch, and Log::Log4perl.
INCOMPATIBILITIES
No known incompatibilities are documented.
BUGS AND LIMITATIONS
Scan execution depends on the external masscan binary and required execution privileges in the runtime environment.
AUTHOR
Heitor Gouvea <hgouvea@cpan.org>
LICENSE AND COPYRIGHT
This software is copyright (c) 2026 by Heitor Gouvea.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.