/ 
Net-Firewall-BlockerHelper-0.0.1
River stage zero No dependents
/ Net::Firewall::BlockerHelper

NAME

Net::Firewall::BlockerHelper - Helps with managing firewalls for banning IPs.

VERSION

Version 0.0.1

SYNOPSIS

use Net::Firewall::BlockerHelper;

# create a instance named ssh with a ipfw backend for port 22 tcp
my $fw_helper;
eval {
    $fw_helper = Net::Firewall::BlockerHelper->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";
}

# start the backend
$fw_helper->init_backend;

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

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

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

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

# teardown the backend
$fw_helper->teardown;

METHODS

new

Initiates the the object.

- backend :: The backend to use. This must be specified.
    - Default :: undef

- 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 $fw_helper;
eval {
    $fw_helper = Net::Firewall::BlockerHelper->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_backend

Initiates the backend.

No arguments are taken.

$fw_helper->init_backend;

ban

Bans the IP.

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

unban

Unbans the an IP.

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

list

List banned IPs.

my @banned = $fw_helper->list;

re_init

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

teardown

Tears down the setup for the backend.

ERROR CODES / FLAGS

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

1, noBackendSpecified

No backend was specified to use.

2, invalidPortSpecified

Port is either not a positive int 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 a positive int 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 specified to ban.

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 get a list of bans.

16, reInitFailed

Failed to re_init the backend.

17, teardownFailed

Failed to teardown the backend.

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