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

NAME

Net::Firewall::BlockerHelper::backends::ipfw - IPFW backend for Net::Firewall::BlockerHelper.

VERSION

Version 0.2.0

SYNOPSIS

The block rules this backend creates are added straight into the main ruleset at the configured rule number, the rule option, default 150, so no additional wiring is needed for them to be evaluated. What does need minding is placement, as ipfw is first match wins. The rule number needs to be lower than that of any rule that would pass the traffic in question, such as a check-state or an allow rule, otherwise the bans will never match anything.

use Net::Firewall::BlockerHelper::backends::ipfw;

my $backend1;
my $backend2;
eval {
    $backend1 = Net::Firewall::BlockerHelper::backends::ipfw->new(
            backend => 'ipfw',
            name => 'all',
            options=>{ rule=>150, kill=>1 },
        );
    $backend2 = Net::Firewall::BlockerHelper::backends::ipfw->new(
            backend => 'ipfw',
            ports => ['143'],
            protocols => ['tcp'],
            name => 'imap',
            options=>{ rule=>151 },
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

print `ipfw list`

$backend1->init;
$backend2->init;

print `ipfw list`

$backend1->ban(ban=>'1.2.3.4');
$backend1->ban(ban=>'4.3.2.1');
$backend2->ban(ban=>'4.3.2.1');

use Data::Dumper;
print Dumper($backend1->list);
print Dumper($backend2->list);

$backend1->unban(ban=>'4.3.2.1');

use Data::Dumper;
print Dumper($backend1->list);
print Dumper($backend2->list);

$backend1->teardown;

print `ipfw list`

$backend2->teardown;

print `ipfw list`

METHODS

new

Initiates the object. Takes the arguments below.

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

- ports :: A array of ports to block. Checked to make sure they are positive ints or a valid
        service name via getservbyname. All ports will be blocked if non are specified. If
        duplicates are removed.
    - Default :: []

- protocols :: A array of protocols to block. This is checked against
        /etc/protocols via the function getprotobyname. Duplicates will be
        discarded. If no protocols are given, all IPv4 and IPv6 traffic is
        blocked ('ip4' and 'ip6'), unless ports are given, in which case it
        defaults to tcp and udp. Ports are only attached to port-capable
        protocols (tcp/udp/sctp); other protocols are blocked without a
        port. As the ipfw 'me' keyword only matches IPv4 addresses and
        'me6' only IPv6 ones, family neutral protocols such as tcp/udp
        get one rule per family while family specific ones such as icmp or
        ip6 get a single rule for their family.
    - Default :: ['ip4','ip6'], or ['tcp','udp'] when ports are given

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

- name :: Name of this specific instance. This must be specified.
    - default :: undef

The options hash accepts the following.

- rule :: The rule number to use for the IPFW rules. This should not
        be re-used or it will result in the other rules at that number
        being removed when init is called.
    - Default :: 150

- type :: The drop method to use. 'deny' silently drops. 'unreach' and
        'unreach6' both mean reject, and are treated as synonyms: the
        family of each generated rule decides whether an IPv4 unreach or
        an IPv6 unreach6 is sent, using the unreach and unreach6 codes
        below. See ipfw(8) for more info.
    - Default :: deny

- unreach :: The IPv4 unreach code to use when type is a reject. Applied
        to IPv4 protocols. See ipfw(8) for more info.
    - Default :: port

- unreach6 :: The IPv6 unreach6 code to use when type is a reject. Applied
        to IPv6 protocols. See ipfw(8) for more info.
    - Default :: port

- kill :: Use tcpdrop to kill TCP connections for that IP. Handles both
        IPv4 and IPv6, picking the sockstat family and parsing per the
        family of the banned IP. TCP only, as FreeBSD has no tcpdrop
        equivalent for UDP; since the generated rules are stateless, UDP
        from the banned IP is blocked immediately regardless, so there is
        no lingering flow state to clear. If protocols are configured and
        tcp is not among them, nothing is killed, so blocking only udp
        never drops TCP connections.
    - Default :: 0

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

my $backend;
eval {
    $backend = Net::Firewall::BlockerHelper::backends::ipfw->new(
            backend => 'ipfw',
            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. First any old remnants are removed on a best effort basis, deleting the configured rule number and then destroying the table <prefix>_<name>, with failures ignored. The rule goes first as ipfw will not destroy a table a rule still references. The table is then created via ipfw table ... create and a block rule is added at the configured rule number for each configured protocol, matching from table(...) to me or me6 depending on the family, with the configured ports appended for port-capable protocols (tcp/udp/sctp). The action is deny or, for reject types, unreach/unreach6 per the family of the rule.

Note that as ipfw is first match wins, the configured rule number needs to come before any rules that would pass the traffic. See "SYNOPSIS".

No arguments are taken.

If 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 added to the IPFW table via ipfw table <prefix>_<name> add. If the kill option is set and tcp is among the blocked protocols, established TCP connections from the IP are found via sockstat and killed via tcpdrop. Banning an already banned IP is a noop.

$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 IPFW table via ipfw table <prefix>_<name> delete. Unbanning an IP that is not banned is a noop.

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

ban_cidr

Bans a CIDR range by adding it to the IPFW table. IPFW tables accept a network prefix in the same manner as a single address.

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

unban_cidr

Unbans a CIDR range by deleting it from the IPFW table.

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

list_cidr

List banned CIDR ranges.

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 itself.

Calls teardown, with errors ignored as a partially wiped setup is what re_init recovers from, then init to recreate the table and rules. All previously banned IPs and CIDR ranges are then re-added to the table via ipfw table ... add.

$backend->re_init;

teardown

Tears down the setup for the backend, deleting the configured rule number and then destroying the table <prefix>_<name>.

The ordering matters. ipfw will not destroy a table that is still in use by a rule, so the rule is removed first; doing it the other way round leaves the table behind.

Both commands are always attempted, and a failure of either is raised only once both have run, so a rule that has already been removed does not stop the table from being destroyed.

It does not check if it has been inited or not, so if called prior to calling init, it will error as the commands will fail.

$backend->teardown;

stop

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

$backend->stop;

check

Verifies that the IPFW table is still present and that the rule number still exists. Returns a true value if the setup is intact and a false value if any part of it appears to have been removed. This is the equivalent of fail2ban's actioncheck.

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

flush

Removes all currently banned IPs and CIDR ranges at once by flushing the IPFW table, leaving the table and rule in place. 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.

19, ruleInvalid

The option rule is not an int of 1 or greater.

20, typeInvalid

The option type is not "deny", "unreach", or "unreach6".

21, unreachInvalid

The option unreach is not a value understood by ipfw(8) for unreach.

22, unreach6Invalid

The option unreach6 is not a value understood by ipfw(8) for unreach6.

23, initFailed

One of the required commands for init failed.

24, checkFailed

The backend check raised an error.

25, flushFailed

Failed to flush the bans.

26, nameTooLong

The combined prefix and name is longer than 63 characters, the max ipfw table name length.

27, banCidrFailed

Failed to ban the CIDR range.

28, unbanCidrFailed

Failed to unban the CIDR range.

29, 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.

30, cidrNotSupported

The backend does not support CIDR bans.

31, 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