NAME
Net::Firewall::BlockerHelper::backends::opnsense - OPNsense firewall alias backend for Net::Firewall::BlockerHelper.
VERSION
Version 0.2.0
SYNOPSIS
use Net::Firewall::BlockerHelper::backends::opnsense;
my $backend;
eval {
$backend = Net::Firewall::BlockerHelper::backends::opnsense->new(
name => 'ssh',
options => {
host => 'fw.example.org',
key => 'someAPIkey',
secret => 'someAPIsecret',
alias => 'kur_ssh',
},
);
};
if ($@) {
print 'Error: '
. $Error::Helper::error
. "\nError String: "
. $Error::Helper::errorString
. "\nError Flag: "
. $Error::Helper::errorFlag . "\n";
}
$backend->init;
$backend->ban(ban => '1.2.3.4');
$backend->ban(ban => '4.3.2.1');
use Data::Dumper;
print Dumper($backend->list);
$backend->unban(ban => '4.3.2.1');
$backend->teardown;DESCRIPTION
This backend blocks IPs by adding them to an OPNsense firewall alias via the os-firewall alias_util REST API, talked to via LWP::UserAgent.
A single alias holds all of the banned IPs. Both IPv4 and IPv6 addresses are added to the same alias as OPNsense host/network aliases are family agnostic.
The alias must already exist in OPNsense. It is created in the OPNsense web UI (Firewall -> Aliases) and referenced by a firewall rule that does the actual blocking. This backend only manages the contents of the alias, not the alias itself nor the rule referencing it.
LWP::UserAgent is only loaded at run time, so it is only required if this backend is actually used. For https, LWP::Protocol::https must be present as well.
METHODS
new
Initiates the the object.
- options :: Backend specific options. See below for further info.
- Default :: {}
- ports :: Not used by this backend but is accepted for parity with
Net::Firewall::BlockerHelper.
- Default :: []
- protocols :: Not used by this backend but is accepted for parity with
Net::Firewall::BlockerHelper.
- Default :: []
- prefix :: Prefix to use when building the default alias name.
- default :: kur
- name :: Name of this specific instance. This must be specified.
- default :: undefThe options hash accepts the following.
- host :: OPNsense hostname or IP the API is reached at. May include a
port, eg 'fw.example.org:8443'. This must be specified and can
not be blank.
- Default :: undef
- key :: The OPNsense API key. This must be specified and can not be
blank.
- Default :: undef
- secret :: The OPNsense API secret. This must be specified and can not
be blank.
- Default :: undef
- alias :: The name of the alias the IPs are added to. The alias must
already exist in OPNsense.
- Default :: <prefix>_<name>
- timeout :: HTTP timeout in seconds.
- Default :: 30
- insecure :: If true, certificate verification is disabled so
self-signed certs are accepted.
- Default :: 0
- scheme :: The scheme used when building the URL, either 'https' or
'http'.
- Default :: httpsAll errors are considered fatal, meaning if new fails it will die.
my $backend;
eval {
$backend = Net::Firewall::BlockerHelper::backends::opnsense->new(
name => 'ssh',
options => {
host => 'fw.example.org',
key => 'someAPIkey',
secret => 'someAPIsecret',
},
);
};
if ($@) {
print 'Error: '
. $Error::Helper::error
. "\nError String: "
. $Error::Helper::errorString
. "\nError Flag: "
. $Error::Helper::errorFlag . "\n";
}init
Initiates the backend. This lists the alias via the API, with any connection or HTTP level failure, bad credentials included, raising an error.
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 added to the alias via a POST to the alias_util/add API endpoint. 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 alias via a POST to the alias_util/delete API endpoint. 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 alias via the alias_util/add API endpoint. OPNsense aliases accept a network in the same manner as a single address. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased. Banning an already banned range is a noop.
$backend->ban_cidr(ban => '1.2.3.0/24');unban_cidr
Unbans a CIDR range by removing it from the alias via the alias_util/delete API endpoint. 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.
$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.
This will call teardown and init again. After that it will re-add all previously added bans.
$backend->re_init;teardown
Tears down the setup for the backend.
This flushes the alias, removing all of the banned IPs from it. The alias itself and the rule referencing it are left in place.
$backend->teardown;stop
Alias for "teardown", provided for parity with the fail2ban actionstop concept.
$backend->stop;check
Verifies the alias is still reachable by listing it via the API. A successful request is treated as healthy. This is the equivalent of fail2ban's actioncheck.
if ( !$backend->check ) {
$backend->re_init;
}flush
Removes all currently banned IPs at once by flushing the alias, leaving the alias and the rule referencing it 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.
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.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
30, hostNotDefined
The option host is undef or blank.
31, apiKeyNotDefined
The option key is undef or blank.
32, apiSecretNotDefined
The option secret is undef or blank.
33, banCidrFailed
Failed to ban the CIDR range.
34, unbanCidrFailed
Failed to unban the CIDR range.
35, 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.
36, cidrNotSupported
The backend does not support CIDR bans.
37, 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::BlockerHelperYou can also look for information at:
RT: CPAN's request tracker (report bugs here)
https://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Firewall-BlockerHelper
Search CPAN
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