NAME
Net::Firewall::BlockerHelper::backends::akamai - Akamai Network Lists backend for Net::Firewall::BlockerHelper.
VERSION
Version 0.1.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'akamai',
name => 'ssh',
options => {
host => 'akab-xxxx.luna.akamaiapis.net',
client_token => $client_token,
client_secret => $client_secret,
access_token => $access_token,
network_list_id => $network_list_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 Akamai Network Lists API v2, adding and removing elements of an existing network list. Requests are authenticated using Akamai's EdgeGrid (EG1-HMAC-SHA256) request signing scheme.
The network list identified by the network_list_id option must already exist. This backend only manages the membership of that list.
Blocking is per IP or CIDR range; ports and protocols are not supported and specifying them is an error.
Note: Changes to a network list made via the API do not take effect until the list is activated (staging and/or production). Activation is out of scope for this backend and must be performed separately, either via the Akamai control center or the activation endpoints of the Network Lists API. Similarly, membership in the list does not block anything on its own; the list must actually be used by a security policy, eg as the block list of a IP/Geo firewall rule. Wiring the list into a policy is likewise out of scope for this backend.
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 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. The host, client_token, client_secret, access_token, and network_list_id options are all required.
- host :: Akamai API hostname, eg akab-xxxx.luna.akamaiapis.net .
- Default :: undef
- client_token :: EdgeGrid client token.
- Default :: undef
- client_secret :: EdgeGrid client secret.
- Default :: undef
- access_token :: EdgeGrid access token.
- Default :: undef
- network_list_id :: ID of the network list to manage.
- Default :: undef
- timeout :: HTTP timeout in seconds.
- Default :: 30
- insecure :: If true, skip TLS certificate verification.
- Default :: 0All errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. Verifies the credentials and endpoint by GETing the network list at /network-list/v2/network-lists/$network_list_id. Nothing is created remotely; the list must already exist.
Note that for bans to have an effect the list must also be activated and in use by a security policy. See "DESCRIPTION".
$backend->init;ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then appended to the network list via a POST to the list's /append 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 network list via a DELETE of its element at the list's /elements endpoint. Unbanning an IP that is not banned is a noop.
$backend->unban(ban => $ip);ban_cidr
Bans a CIDR range. The value of ban is validated as being a IPv4 or IPv6 CIDR and lowercased, then appended to the network list via a POST to the list's /append endpoint; Akamai network lists accept a CIDR range as a list element in the same manner as a single address. Banning an already banned range is a noop.
$backend->ban_cidr(ban => '1.2.3.0/24');unban_cidr
Unbans a CIDR range. The value of ban is validated as being a IPv4 or IPv6 CIDR and lowercased, then removed from the network list via a DELETE of its element at the list's /elements endpoint. 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 from internal state; the network list is not fetched. 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 from internal state; the network list is not fetched. CIDR ranges are not included; for those see "list_cidr".
my @banned = $backend->list;re_init
Tears down and re-initiates the backend. teardown is called best effort, then init, after which every previously banned single IP and CIDR range is re-added to the network list via POSTs to the list's /append endpoint.
$backend->re_init;teardown
Tears down the setup for the backend by DELETEing the element for each currently banned single IP from the network list. Banned CIDR ranges are left in place. 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 fetching the network list. 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 DELETEing their elements from the network list 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.
23, initFailed
init failed. Probing the network list endpoint failed.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, portsNotSupported
The akamai backend blocks whole IPs and does not support ports.
27, protocolsNotSupported
The akamai backend blocks whole IPs and does not support protocols.
30, hostNotDefined
The option host is undef or blank.
31, clientTokenNotDefined
The option client_token is undef or blank.
32, clientSecretNotDefined
The option client_secret is undef or blank.
33, accessTokenNotDefined
The option access_token is undef or blank.
34, networkListIdNotDefined
The option network_list_id is undef or blank.
35, banCidrFailed
Failed to ban the CIDR range.
36, unbanCidrFailed
Failed to unban the CIDR range.
37, 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.
38, cidrNotSupported
The backend does not support CIDR bans.
39, 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