NAME
Net::Firewall::BlockerHelper::backends::cloudflare - Cloudflare IP access rules backend for Net::Firewall::BlockerHelper.
VERSION
Version 0.2.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'cloudflare',
name => 'ssh',
options => {
token => $cf_api_token,
zone => $cf_zone_id,
},
);
$fw_helper->init_backend;
$fw_helper->ban(ban => '1.2.3.4');
$fw_helper->unban(ban => '1.2.3.4');DESCRIPTION
Blocks IPs remotely via the Cloudflare v4 API using IP access rules, equivalent to the fail2ban cloudflare and cloudflare-token actions, but using LWP::UserAgent rather than curl.
Auth is via either a API token (preferred, the token option) or the legacy email plus global API key (the email and key options). If the zone option is set the rules are managed zone level, otherwise user level.
Blocking is per IP; ports and protocols are not supported and specifying them is an error.
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.
NOTES
This backend was written going off the API docs and actual testing is needed to double check a few things as the exact behavior is not clear.
teardown currently only removes the single IP access rules, leaving CIDR bans in place remotely, while flush removes both. A re_init after a teardown will re-add the CIDR bans, and how the API handles creating a rule that already exists needs checking.
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. Either token or both email and key must be specified.
- token :: Cloudflare API token, used as a bearer token. Ideally
restricted to just the needed permissions.
- Default :: undef
- email :: Account email for legacy global API key auth.
- Default :: undef
- key :: Legacy global API key.
- Default :: undef
- zone :: Zone ID to manage the rules under. If not set, the rules are
managed at the user level.
- Default :: undef
- mode :: What Cloudflare should do with matching requests. One of
'block', 'challenge', 'js_challenge', or 'managed_challenge'.
- Default :: block
- notes :: Note attached to created rules, also used to find them again
for removal.
- Default :: <prefix>_<name>
- timeout :: HTTP timeout in seconds.
- Default :: 30All errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. Verifies the credentials and endpoint by listing a few rules.
$backend->init;ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then an access rule is created for it via a POST to the access rules endpoint, using the configured mode and notes. 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. The matching access rule is then found via a GET filtering on mode, notes, and the IP, and deleted by its ID. A rule that can not be found is treated as already unbanned. Unbanning an IP that is not banned is a noop.
$backend->unban(ban => $ip);ban_cidr
Bans a CIDR range by creating an access rule for it. Cloudflare access rules accept a network prefix as the configuration value 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 finding and deleting its access rule, the same way "unban" does for a single IP. A rule that can not be found is treated as already unbanned. 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-added all previously added bans.
$backend->re_init;teardown
Tears down the setup for the backend by removing the access rule 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
Verifies the endpoint and credentials are still usable by listing a few rules. Returns a true value if so and a false value otherwise. 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 removing their access rules 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 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.
20, modeInvalid
The option mode is not 'block', 'challenge', 'js_challenge', or 'managed_challenge'.
23, initFailed
init failed. Probing the access rules endpoint failed.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, portsNotSupported
The cloudflare backend blocks whole IPs and does not support ports.
27, protocolsNotSupported
The cloudflare backend blocks whole IPs and does not support protocols.
28, optionInvalid
An option is invalid. Auth requires either the option token or both the options email and key, zone must be a zone ID, and timeout must be an int.
29, banCidrFailed
Failed to ban the CIDR range.
30, unbanCidrFailed
Failed to unban the CIDR range.
31, 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.
32, cidrNotSupported
The backend does not support CIDR bans.
33, 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