/ 
Net-Firewall-BlockerHelper-0.2.0
/ Net::Firewall::BlockerHelper::backends::shorewall

NAME

Net::Firewall::BlockerHelper::backends::shorewall - Shorewall backend for Net::Firewall::BlockerHelper.

VERSION

Version 0.2.0

SYNOPSIS

use Net::Firewall::BlockerHelper;

my $fw_helper;
eval {
    $fw_helper = Net::Firewall::BlockerHelper->new(
            backend => 'shorewall',
            name    => 'derp',
            options => {
                      type => 'drop',
                      },
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

$fw_helper->init_backend;

$fw_helper->ban(ban => '5.6.7.8');
$fw_helper->ban(ban => '1.2.3.4');

$fw_helper->unban(ban => '5.6.7.8');

$fw_helper->teardown;

DESCRIPTION

This backend blocks IPs using Shorewall's dynamic blacklisting via the shorewall(8) and shorewall6(8) commands. IPv4 addresses are handled by the shorewall command and IPv6 addresses by the shorewall6 command.

Dynamic blacklisting is part of Shorewall itself, so there is nothing to create at init time. Banning an IP is a matter of running shorewall <type> <ip> and unbanning is a matter of running shorewall allow <ip>.

This does require the firewall to actually be in the started state and DYNAMIC_BLACKLIST to not have been set to No in shorewall.conf(5). It is enabled by default, so unless it has been explicitly disabled there is nothing to configure.

Requires shorewall and, for IPv6 support, shorewall6 to be installed and in the PATH of the process, which must have sufficient privileges to run them.

METHODS

new

Initiates the the object.

- options :: A hash of options to pass to the backend. See below for further info.
    Default :: {}

- ports :: Not used by this backend but accepted for parity with the others.
    Default :: []

- protocols :: Not used by this backend but accepted for parity with the others.
    Default :: []

- prefix :: Prefix to use.
    Default :: kur

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

The options hash accepts the following.

- shorewall_cmd :: Path to the shorewall binary, used for IPv4 addresses.
    Default :: shorewall

- shorewall6_cmd :: Path to the shorewall6 binary, used for IPv6 addresses.
    Default :: shorewall6

- type :: The block method to use. One of 'drop' or 'reject'.
            - drop   :: Silently drop the packet.
            - reject :: Send an ICMP port-unreachable back.
    Default :: drop

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

my $fw_helper;
eval {
    $fw_helper = Net::Firewall::BlockerHelper->new(
            backend => 'shorewall',
            name    => 'ssh',
            options => { type => 'drop' },
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

init

Initiates the backend.

Dynamic blacklisting is part of Shorewall itself, so there is nothing to create.

Note that for bans to have an effect the firewall must be started and DYNAMIC_BLACKLIST must not have been disabled in shorewall.conf. See "DESCRIPTION".

No arguments are taken.

May called a second time, it will error.

$backend->init;

ban

Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then shorewall <type> <ip> is run, using shorewall6 for IPv6 addresses. Banning an already banned IP is a noop.

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

unban

Unbans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then shorewall allow <ip> is run, using shorewall6 for IPv6 addresses. Unbanning an IP that is not banned is a noop.

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

ban_cidr

Bans a CIDR range. Shorewall's dynamic blacklisting accepts a network prefix in the same manner as a single address, so this runs shorewall <type> <cidr>, using shorewall6 for IPv6 ranges. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased. Banning an already banned range is a noop.

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

unban_cidr

Unbans a CIDR range by running shorewall allow <cidr>, using shorewall6 for IPv6 ranges. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased. Unbanning a range that is not banned is a noop.

$fw_helper->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 = $fw_helper->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 = $fw_helper->list;

re_init

Tells the backend to re-init it's self.

This will call teardown and init again. After that it will re-add all previously added bans.

$fw_helper->re_init;

teardown

Tears down the setup for the backend.

This will allow every currently banned IP and CIDR range. The internal list of bans is kept, so a following re_init will re-add them.

$fw_helper->teardown;

stop

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

$fw_helper->stop;

check

Runs shorewall show dynamic, and, when anything IPv6 is currently banned, shorewall6 show dynamic as well. A zero exit code from each is treated as healthy. The IPv6 side is only checked when in use so setups without shorewall6 installed are not flagged as unhealthy. This is the equivalent of fail2ban's actioncheck.

if ( !$fw_helper->check ) {
    $fw_helper->re_init;
}

flush

Removes all currently banned IPs and CIDR ranges at once by allowing each of them and forgetting them. This is the equivalent of fail2ban's actionflush.

$fw_helper->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.

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.

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.

20, typeInvalid

The option type is not 'drop' or 'reject'.

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