NAME
Net::Firewall::BlockerHelper::backends::nsupdate - Dynamic DNS blocklist backend for Net::Firewall::BlockerHelper.
VERSION
Version 0.2.0
SYNOPSIS
All this backend does is add and remove TXT records, so two bits of external setup are required for bans to actually mean anything. First the zone the records live under must exist on the DNS server and allow dynamic updates authenticated via the TSIG key, the like of the following in named.conf for BIND, with the key also declared there via a key statement matching the keyfile.
zone "rbl.foo.bar" {
type primary;
file "rbl.foo.bar.db";
allow-update { key "nsupdate-key"; };
};Second, a DNS record on its own blocks nothing. Whatever should be turning away the banned IPs must be configured to consult the resulting blocklist. Also worth noting is that only TXT records are created, while the usual DNSBL style lookup checks for an A record, so the consumer needs to be something that can be pointed at TXT records.
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'nsupdate',
name => 'ssh',
options => {
domain => 'rbl.foo.bar',
keyfile => '/etc/nsupdate.key',
},
);
$fw_helper->init_backend;
$fw_helper->ban(ban => '1.2.3.4');
$fw_helper->unban(ban => '1.2.3.4');DESCRIPTION
Maintains a DNS based blocklist (RBL style) by using nsupdate(1) to dynamically add and remove TXT records under a BIND zone, equivalent to the fail2ban nsupdate action. Banning 1.2.3.4 adds a TXT record at 4.3.2.1.<domain>.
nsupdate speaks the DNS update protocol authenticated via a TSIG key, not HTTP, so this backend runs the nsupdate command rather than using LWP::UserAgent.
Only IPv4 is supported, matching the fail2ban action; banning an IPv6 IP is an error. Ports and protocols are not supported and specifying them is an error. check has nothing it can probe cheaply and always reports healthy.
METHODS
new
Initiates the the object.
- options :: Backend specific options. See below.
- Default :: {}
- 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 :: undefPorts and protocols are not supported by this backend and specifying either is an error.
The options hash accepts the following. domain and keyfile must be specified.
- domain :: DNS domain the records are managed under.
- Default :: undef
- keyfile :: Full path to the TSIG key file used to authenticate to
BIND. Verified to exist at init.
- Default :: undef
- ttl :: TTL in seconds for the created TXT records.
- Default :: 60
- rdata :: Data of the created TXT records.
- Default :: banned
- nsupdate :: The nsupdate command to use.
- Default :: nsupdateAll errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. Verifies the keyfile exists.
Note that the zone must allow updates via the key and something must be consuming the blocklist for bans to have an effect. See "SYNOPSIS".
$backend->init;ban
Bans an IP. The value of ban is validated as being a IPv4 address; IPv6 is not supported and is an error. The octets are reversed and a TXT record is added at that name under the domain, eg banning 1.2.3.4 adds a TXT record at 4.3.2.1.<domain>, by piping an update with a nxrrset prereq into nsupdate authenticated via the TSIG keyfile. 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 address; IPv6 is not supported and is an error. The TXT record for the IP is deleted by piping an update delete for its record name into nsupdate. Unbanning an IP that is not banned is a noop.
$backend->unban(ban => $ip);ban_cidr
CIDR bans are not supported by this backend; this always sets the cidrNotSupported error.
$backend->ban_cidr(ban => '1.2.3.0/24');unban_cidr
CIDR bans are not supported by this backend; this always sets the cidrNotSupported error.
$backend->unban_cidr(ban => '1.2.3.0/24');list_cidr
CIDR bans are not supported by this backend, so this always returns an empty list.
my @banned_cidrs = $backend->list_cidr;list
List banned IPs. Returns an array of the currently banned IPs from the internal ban list.
my @banned = $backend->list;re_init
Tells the backend to re-init it's self.
This will call teardown, which deletes the record for each banned IP, then init, and then re-add the TXT record for every retained ban via nsupdate.
$backend->re_init;teardown
Tears down the setup for the backend by deleting the record for each currently banned IP. The internal list of bans is kept, so a following re_init will re-add them.
$backend->teardown;stop
Alias for "teardown", provided for parity with the fail2ban actionstop concept.
$backend->stop;check
There is nothing this backend can cheaply probe, so this always reports healthy. This is the equivalent of fail2ban's actioncheck.
my $healthy = $backend->check;flush
Removes all currently banned IPs at once by deleting their records and forgetting them. 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.
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 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.
23, initFailed
init failed. The keyfile does not exist or is not a file.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, portsNotSupported
Ports were specified, but the backend does not support ports.
27, protocolsNotSupported
Protocols were specified, but the backend does not support protocols.
28, optionInvalid
One of the specified options failed validation.
29, ipv6NotSupported
The backend only supports IPv4 and the item is an IPv6 IP.
30, banCidrFailed
Failed to ban the CIDR range.
31, unbanCidrFailed
Failed to unban the CIDR range.
32, 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.
33, cidrNotSupported
The backend does not support CIDR bans.
34, 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.
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