NAME
Net::Firewall::BlockerHelper::backends::netscaler - Citrix NetScaler/ADC backend for Net::Firewall::BlockerHelper.
VERSION
Version 0.1.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'netscaler',
name => 'ssh',
options => {
host => 'netscaler.foo.bar',
user => 'nsroot',
pass => $password,
dataset => 'fail2ban',
},
);
$fw_helper->init_backend;
$fw_helper->ban(ban => '1.2.3.4');
$fw_helper->unban(ban => '1.2.3.4');DESCRIPTION
Blocks IPs remotely by binding them into a policy dataset on a Citrix NetScaler/ADC via the NITRO REST API, equivalent to the fail2ban netscaler action, but using LWP::UserAgent rather than curl. The dataset can then be used to block the IPs via responder policies at a vserver or global level.
The dataset must already exist on the NetScaler, as must a responder or similar policy referencing it, as binding IPs into the dataset does nothing by itself; init and check only verify the API is reachable and auth works.
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.
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. host must be specified, as must either auth or both user and pass.
- host :: Hostname or IP of the NetScaler appliance.
- Default :: undef
- user :: Username for basic auth.
- Default :: undef
- pass :: Password for basic auth.
- Default :: undef
- auth :: Pre-base64ed basic auth value to use instead of user/pass,
for parity with the fail2ban ns_auth option.
- Default :: undef
- dataset :: The policy dataset holding the blocked IPs.
- Default :: <prefix>_<name>
- scheme :: http or https.
- Default :: https
- ssl_verify :: Verify the TLS certificate. The fail2ban action uses
curl -k, so this defaults to off; set to 1 if the appliance has
a valid certificate.
- Default :: 0
- timeout :: HTTP timeout in seconds.
- Default :: 30All errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. Verifies the NITRO API is reachable and auth works via a GET of /nitro/v1/config. Nothing is created on the NetScaler; the dataset is expected to already exist.
$backend->init;ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then bound into the policy dataset via a PUT to /nitro/v1/config/policydataset_value_binding. 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 its binding is removed from the policy dataset via a DELETE of /nitro/v1/config/policydataset_value_binding/<dataset>?args=value:<ip>. 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; the NetScaler is not queried.
my @banned = $backend->list;re_init
Tells the backend to re-init it's self.
This will call teardown, best effort as a partially wiped setup is what it is recovering from, then init again. After that every IP in the retained ban list is re-banned by PUTing its dataset binding back.
$backend->re_init;teardown
Tears down the setup for the backend by removing the binding 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 NITRO API is still reachable and auth still works. 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 removing their bindings 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
Probing the NITRO API during init failed.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, portsNotSupported
The netscaler backend blocks whole IPs and does not support ports.
27, protocolsNotSupported
The netscaler backend blocks whole IPs and does not support protocols.
28, optionInvalid
One of the options, such as host, auth, dataset, scheme, or timeout, is invalid or missing.
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