NAME
Net::Firewall::BlockerHelper::backends::abuseipdb - Report banned IPs to AbuseIPDB.
VERSION
Version 0.1.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'abuseipdb',
name => 'ssh',
options => {
key => $abuseipdb_api_key,
categories => [ '18', '22' ],
},
);
$fw_helper->init_backend;
$fw_helper->ban( ban => '1.2.3.4' );DESCRIPTION
Reports banned IPs to AbuseIPDB via its v2 REST API, equivalent to the fail2ban abuseipdb action. This backend blocks nothing itself; it is meant to be used alongside a blocking backend so a ban both blocks locally and reports upstream.
Reports can not be withdrawn, so unban, flush, and teardown are purely internal bookkeeping and touch the API not at all. re_init likewise does not re-report anything, as there is no remote state to restore.
Reporting the same IP again within AbuseIPDB's rate limit window (15 minutes at the time of writing) is answered with a HTTP 429, which this backend treats as already reported rather than as an error, so replaying saved ban state through ban does not error out.
Both IPv4 and IPv6 are supported. Reporting is per IP; ports and protocols are not supported and specifying them is an error.
The comment sent with each report is publicly visible on AbuseIPDB, so do not put anything sensitive in the comment option.
LWP::UserAgent is loaded at run time, so it is only required when this backend is actually used. As the API is https only, LWP::Protocol::https must be present as well.
METHODS
new
Initiates the backend object. No API calls are made until "init".
- options :: Backend specific options. See below.
- prefix :: Prefix to use. Must match /^[a-zA-Z0-9]+$/. Default kur.
- name :: Name of this instance. Required.Ports and protocols are not supported and specifying either is an error.
The options hash accepts the following.
- key :: AbuseIPDB API key. Required.
- Default :: undef
- categories :: Report categories, as either a array ref of category
numbers or a comma separated string of them. See
L<https://www.abuseipdb.com/categories> for the meanings; the
default, 18, is Brute-Force.
- Default :: 18
- comment :: Comment attached to each report. '%%%BAN%%%' is replaced
with the IP being reported. Publicly visible on AbuseIPDB. If
blank, no comment is sent.
- Default :: banned by <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 API key and reachability via a minimal GET to the v2 /check endpoint. Nothing is created remotely; there is no remote state to set up.
ban
Bans the IP by reporting it. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then reported via a POST to the v2 /report endpoint with the configured categories and comment. A HTTP 429, AbuseIPDB's answer to reporting the same IP again inside its rate limit window, is treated as already reported rather than as an error. Banning an already banned IP is a noop.
$backend->ban(ban => $ip);unban
Unbans the IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then removed from the internal ban list. Reports can not be withdrawn, so no API call is made. 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 IPs reported since init, from the internal ban list; no API call is made.
my @banned = $backend->list;re_init
Tears down and re-inits. Unlike the blocking backends nothing is re-added, as reports are fire and forget and there is no remote state to restore.
teardown
Tears down the backend. Reports can not be withdrawn, so no API calls are made. The internal list of bans is kept.
$backend->teardown;stop
Alias for "teardown", provided for parity with the fail2ban actionstop concept.
$backend->stop;check
Verifies the API key and reachability are still usable via a minimal GET to the v2 /check endpoint. 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 at once by forgetting them. Reports can not be withdrawn, so no API calls are made. 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. Probing the check endpoint failed.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, portsNotSupported
The abuseipdb backend reports whole IPs and does not support ports.
27, protocolsNotSupported
The abuseipdb backend reports whole IPs and does not support protocols.
30, keyNotDefined
The option key is undef or blank.
31, categoriesInvalid
The option categories is not an array ref of positive ints or a comma separated string of positive ints.
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.
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