NAME
Net::Firewall::BlockerHelper::backends::dns_rpz - DNS RPZ blocklist backend via nsupdate.
VERSION
Version 0.2.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'dns_rpz',
name => 'resolver',
options => {
zone => 'rpz.example.org',
keyfile => '/etc/rpz.key',
},
);
$fw_helper->init_backend;
$fw_helper->ban( ban => '1.2.3.4' );
$fw_helper->unban( ban => '1.2.3.4' );DESCRIPTION
Blocks IPs at the DNS layer using a BIND Response Policy Zone (RPZ). By default the rpz-client-ip trigger is used, so a banned IP is prevented from resolving anything through the resolver (the policy action is NXDOMAIN via a CNAME . record). Set the trigger option to ip to instead use the rpz-ip trigger, which rewrites answers that contain the banned IP.
Records are added and removed with nsupdate(1) (the DNS update protocol, TSIG authenticated), so this backend runs the nsupdate command rather than speaking HTTP. The RPZ zone must already exist and be referenced from the resolver's response-policy configuration.
The owner name is the RPZ IP format: for IPv4 1.2.3.4 it is 32.4.3.2.1.rpz-client-ip.<zone>, and for IPv6 the eight groups are reversed with the longest zero run replaced by zz, prefixed with the 128 length.
Blocking is per IP; ports and protocols are not supported and specifying either is an error.
METHODS
new
Initiates the object.
- options :: Backend specific options. See below.
- name :: Required by Net::Firewall::BlockerHelper, otherwise unused.The options hash accepts the following. zone and keyfile are required.
- zone :: The RPZ zone name.
- Default :: undef
- keyfile :: Full path to the TSIG key file authenticating to the server.
- Default :: undef
- trigger :: 'client-ip' (block the querying client) or 'ip' (rewrite
answers containing the IP).
- Default :: client-ip
- server :: Optional server to send the updates to; adds a server line.
- Default :: undef
- ttl :: TTL in seconds for the created records.
- Default :: 60
- nsupdate :: The nsupdate command to use.
- Default :: nsupdateAll errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. Nothing is created on the server; the configured keyfile is just verified to exist and be a file.
ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then a CNAME . record is added at the RPZ owner name for the IP by running nsupdate. 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 the CNAME . record at the RPZ owner name for the IP is deleted by running nsupdate. Unbanning an IP that is not banned is a noop.
$fw_helper->unban( ban => $ip );list
List banned IPs. Returns an array of the currently banned IPs.
my @banned = $fw_helper->list;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;re_init
Tears down and re-initiates. teardown is called best effort, init is run again, and then the RPZ record for every retained banned IP is re-added via nsupdate.
teardown
Removes the RPZ record for each currently banned IP. The internal ban list is kept so a following re_init restores them.
stop
Alias for "teardown".
check
Verifies the keyfile still exists and is a file. Returns a true value if so and a false value otherwise.
flush
Removes all currently banned IPs at once by running a nsupdate delete for each RPZ record and clearing the ban list.
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 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, triggerInvalid
The option trigger is not "client-ip" or "ip".
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
The dns_rpz backend blocks whole IPs and does not support ports.
27, protocolsNotSupported
The dns_rpz backend blocks whole IPs and does not support protocols.
30, zoneInvalid
The option zone is undef or not a valid zone name.
31, keyfileInvalid
The option keyfile is undef or contains whitespace or single quotes.
32, banCidrFailed
Failed to ban the CIDR range.
33, unbanCidrFailed
Failed to unban the CIDR range.
34, 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.
35, cidrNotSupported
The backend does not support CIDR bans.
36, listCidrFailed
Failed to get a list of CIDR bans.
37, serverInvalid
The option server does not match /^[a-zA-Z0-9.:\-]+$/.
38, ttlInvalid
The option ttl is not an int.
39, nsupdateInvalid
The option nsupdate does not match /^[a-zA-Z0-9.\/_\-]+$/.
AUTHOR
Zane C. Bowers-Hadley, <vvelox at vvelox.ent>
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