/ 
Net-Firewall-BlockerHelper-0.1.0
/ Net::Firewall::BlockerHelper::backends::dummy

NAME

Net::Firewall::BlockerHelper::backends::dummy - Example dummy backend for testing purposes.

VERSION

Version 0.1.0

SYNOPSIS

use Net::Firewall::BlockerHelper::backends::dummy;

# create a backend named ssh with a dummy backend for port 22 tcp
my $backend;
eval {
    $backend = Net::Firewall::BlockerHelper::backends::dummy->new(
            backend => 'dummy',
            ports => ['22'],
            protocols => ['tcp'],
            name => 'ssh',
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

$backend->init;

# ban some IPs
$backend->ban(ban => '1.2.3.4');
$backend->ban(ban => '5.6.7.8');

# unban a IP
$backend->unban(ban => '1.2.3.4');

# get a list of banned IPs
my @banned = $backend->list;
foreach my $ip (@banned) {
    print 'Banned IP: '.$ip."\n";
}

# teardown the backend, re-init, and re-ban everything
$backend->re_init;

# teardown the backend
$backend->teardown;

METHODS

new

Initiates the the object.

- options :: Backend specific options that will be passed to the backend unchecked
        outside of making sure it is a hash ref if defined.
    - Default :: {}

- ports :: A array of ports to block. Checked to make sure they are positive ints or a valid
        service name via getservbyname.
    - Default :: []

- protocols :: A array of protocols to block. By default will block all. This
        is checked against /etc/protocols via the function getprotobyname.
    - Default :: []

- prefix :: Prefix to use. Must match the regex /^[a-zA-Z0-9]+$/
    - default :: kur

- name :: Name of this specific instance.
    - default :: undef

All errors are considered fatal, meaning if new fails it will die.

my $backend;
eval {
    $backend = Net::Firewall::BlockerHelper::backends::dummy->new(
            backend => 'dummy',
            ports => ['22'],
            protocols => ['tcp'],
            name => 'ssh',
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

init

Initiates the backend. As this is the dummy testing backend, nothing external is touched; the backend is just marked as inited and the call is recorded when in testing mode.

No arguments are taken.

$backend->init;

ban

Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then recorded in the internal ban list. As this is the dummy testing backend, nothing external is touched.

$backend->ban(ban => $ip);

unban

Unbans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then removed from the internal ban list. As this is the dummy testing backend, nothing external is touched.

$backend->unban(ban => $ip);

ban_cidr

Bans a CIDR range. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased, then recorded in the internal CIDR ban list. Nothing external is touched.

$backend->ban_cidr(ban => '1.2.3.0/24');

unban_cidr

Unbans a CIDR range. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased, then removed from the internal CIDR ban list. Nothing external is touched.

$backend->unban_cidr(ban => '1.2.3.0/24');

list_cidr

List banned CIDR ranges. Returns an array of the currently banned CIDR ranges. Single IPs are not included; for those see "list".

my @banned_cidrs = $backend->list_cidr;

list

List banned IPs. Returns an array of the currently banned single IPs. CIDR ranges are not included; for those see "list_cidr".

my @banned = $backend->list;

re_init

Tells the backend to re-init it's self. As this is the dummy testing backend, this just marks it as inited again; the internal ban lists are retained.

teardown

Tears down the setup for the backend. As this is the dummy testing backend, there is nothing external to remove; the backend is just marked as not inited. The internal ban lists are kept.

$backend->teardown;

stop

Alias for "teardown", provided for parity with the fail2ban actionstop concept.

$backend->stop;

check

Dummy check. Always reports the setup as intact. This is the equivalent of fail2ban's actioncheck.

my $healthy = $backend->check;

flush

Dummy flush. Clears the internal lists of banned IPs and CIDR ranges. This is the equivalent of fail2ban's actionflush.

$backend->flush;

ERROR CODES / FLAGS

Error handling is provided by Error::Helper. All errors are considered fatal.

1, notInited

The backend has not been inited yet.

2, invalidPortSpecified

Port is either not an int within the range 1 to 65535 or a name that can be resolved by getservbyname.

3, portsNotArray

The data passed to new for ports is not an array.

4, protocolsNotArray

The data passed to new for protocols is not an array.

5, invalidPortSpecified

Port is either not an int within the range 1 to 65535 or a name that can be resolved by getservbyname.

6, invalidPrefixSpecified

The specified prefix did not match /^[a-zA-Z0-9]+$/.

7, invalidName

The name is either undef or does not match /^[a-zA-Z0-9\-]+$/.

8, optionsNotHash

The item passed to new for options is not a hash.

9, noBanItem

No IP or CIDR range specified to ban or unban.

10, banItemNotIP

The item to ban is not an IP. Either wrong ref type or regexp test using Regexp::IPv4 and Regexp::IPv6 failed.

11, invalidBackend

The specified backend failed to pass a basic sanity check of making sure it matches the regexp /^[a-zA-Z0-9\_]+$/.

12, backendInitError

Failed to init the backend.

13, banFailed

Failed to ban the item.

14, unbanFailed

Failed to unban the item.

15, listFailed

Failed to get a list of bans.

16, reInitFailed

Failed to re_init the backend.

17, teardownFailed

Failed to teardown the backend.

18, alreadyInited

init called, but the backend has already been inited.

24, checkFailed

The backend check raised an error.

25, flushFailed

Failed to flush the bans.

26, banCidrFailed

Failed to ban the CIDR range.

27, unbanCidrFailed

Failed to unban the CIDR range.

28, cidrItemNotCidr

The item to ban is not a CIDR range. Either wrong ref type or it is not an IPv4 or IPv6 address followed by a prefix length valid for its family.

29, cidrNotSupported

The backend does not support CIDR bans.

30, listCidrFailed

Failed to get a list of CIDR bans.

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.ent>

BUGS

Please report any bugs or feature requests to bug-net-firewall-blockerhelper at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Firewall-BlockerHelper. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::Firewall::BlockerHelper

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2023 by Zane C. Bowers-Hadley.

This is free software, licensed under:

The GNU Lesser General Public License, Version 2.1, February 1999