/ 
Net-Firewall-BlockerHelper-0.1.0
/ Net::Firewall::BlockerHelper::backends::f5_bigip

NAME

Net::Firewall::BlockerHelper::backends::f5_bigip - F5 BIG-IP backend using the iControl REST API.

VERSION

Version 0.1.0

SYNOPSIS

use Net::Firewall::BlockerHelper;

my $fw_helper = Net::Firewall::BlockerHelper->new(
    backend => 'f5_bigip',
    name    => 'ssh',
    options => {
        host     => 'bigip.example.org',
        user     => 'blocker',
        password => $password,
    },
);

$fw_helper->init_backend;
$fw_helper->ban( ban => '1.2.3.4' );
$fw_helper->unban( ban => '1.2.3.4' );

DESCRIPTION

Blocks IPs on an F5 BIG-IP via its iControl REST API, managing the membership of a single firewall address-list. The full membership of the address-list is rendered from this backend's internal state on every change, so the address list contains exactly the currently banned IPs and nothing else.

The managed address-list is identified by its name option (defaulting to <prefix>_<name>) within a partition (defaulting to Common). The address-list object, and any firewall rule referencing it, must already exist on the BIG-IP.

Blocking is per IP; ports and protocols are not supported and specifying them is an error.

Auth is via HTTP basic auth using the user and password options.

LWP::UserAgent is loaded at run time, so it is only required when 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.
- 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.

- host :: BIG-IP host, optionally host:port. Required.
    - Default :: undef

- user :: iControl REST user. Required.
    - Default :: undef

- password :: iControl REST password. Required.
    - Default :: undef

- name :: The firewall address-list name to manage.
    - Default :: <prefix>_<name>

- partition :: The partition the address-list lives in.
    - Default :: Common

- insecure :: If true, skip TLS certificate verification (BIG-IP ships a
        self-signed certificate).
    - Default :: 0

- timeout :: HTTP timeout in seconds.
    - Default :: 30

All errors are considered fatal, meaning if new fails it will die.

init

Initiates the backend. Verifies the credentials, reachability, and that the address-list object exists by fetching it.

ban

Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then added to the internal ban list and the full rendered membership is pushed to the address-list via a PUT. Banning an already banned IP is a noop. If the PUT fails, the IP is removed from the internal list again.

$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 internal ban list and the full rendered membership is pushed to the address-list via a PUT. Unbanning an IP that is not banned is a noop. If the PUT fails, the IP is re-added to the internal list.

$backend->unban(ban => $ip);

ban_cidr

Bans a CIDR range by adding it to the internal list and pushing the full rendered membership to the address-list via a PUT. 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 removing it from the internal list and pushing the full rendered membership to the address-list via a PUT. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased. 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

Tears down and re-inits, then re-renders the full membership in a single PUT.

teardown

Tears down the setup by rendering an empty membership to the address-list. The internal list of bans is kept, so a following re_init will re-add them.

stop

Alias for "teardown".

check

Verifies the endpoint and credentials are still usable by fetching the address-list object. Returns a true value if so and a false value otherwise.

flush

Removes all currently banned IPs at once by rendering an empty membership to the address-list and forgetting them.

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 address-list object failed.

24, checkFailed

The backend check raised an error.

25, flushFailed

Failed to flush the bans.

26, portsNotSupported

The f5_bigip backend blocks whole IPs and does not support ports.

27, protocolsNotSupported

The f5_bigip backend blocks whole IPs and does not support protocols.

30, hostNotDefined

The option host is undef or blank.

31, userNotDefined

The option user is undef or blank.

32, passwordNotDefined

The option password is undef or blank.

33, banCidrFailed

Failed to ban the CIDR range.

34, unbanCidrFailed

Failed to unban the CIDR range.

35, 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.

36, cidrNotSupported

The backend does not support CIDR bans.

37, 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