/ 
Net-Firewall-BlockerHelper-0.2.0
/ Net::Firewall::BlockerHelper::backends::cisco_fmc

NAME

Net::Firewall::BlockerHelper::backends::cisco_fmc - Cisco Firepower Management Center backend via the REST API.

VERSION

Version 0.2.0

SYNOPSIS

use Net::Firewall::BlockerHelper;

my $fw_helper = Net::Firewall::BlockerHelper->new(
    backend => 'cisco_fmc',
    name    => 'ssh',
    options => {
        host     => 'fmc.example.org',
        user     => 'apiuser',
        password => $fmc_password,
        group_id => $network_group_object_id,
    },
);

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

DESCRIPTION

Blocks IPs on a Cisco Firepower Management Center (FMC) via its REST API. A single Network Group object is managed; its literals list is rendered from the internal set of banned IPs and CIDR ranges and PUT to the FMC in full on each change. Both IPv4 and IPv6 addresses are rendered as Host literals and CIDR ranges as Network literals.

A firewall access control policy referencing the Network Group must already exist, and after any change a policy deployment is required on the FMC for the new literal set to actually be enforced. This backend does not trigger the deployment.

Auth is via a username and password, POSTed to the token generation endpoint; the returned X-auth-access-token header is then sent on every subsequent request. The credentials and token are carried as headers only.

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

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 backend object. Arguments are taken as a hash.

- 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 :: FMC host, optionally host:port. Required.
    - Default :: undef

- user :: API username. Required.
    - Default :: undef

- password :: API password. Required.
    - Default :: undef

- domain :: FMC domain UUID.
    - Default :: e276abec-e0f2-11e3-8169-6d9ed49b625f

- group_id :: UUID of the Network Group object to manage. Required.
    - Default :: undef

- group_name :: Name of the Network Group object.
    - Default :: <prefix>_<name>

- insecure :: If true, skip TLS certificate verification.
    - 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. POSTs the configured user and password via HTTP Basic auth to the token generation endpoint, /api/fmc_platform/v1/auth/generatetoken, and stores the returned X-auth-access-token header for use on all subsequent requests. Nothing is done to the Network Group object itself.

ban

Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then added to the ban list. The full Network Group object, containing every current ban as a Host literal, is rendered and PUT to the networkgroups endpoint. Banning an already banned IP is a noop. If the PUT fails, the IP is removed from the ban 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 ban list. The full Network Group object is re-rendered without it and PUT to the networkgroups endpoint. Unbanning an IP that is not banned is a noop. If the PUT fails, the IP is restored to the ban list.

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

ban_cidr

Bans a CIDR range. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased, then added to the CIDR ban list. The full Network Group object, with the range as a Network literal, is rendered and PUT to the networkgroups endpoint. Banning an already banned range is a noop. If the PUT fails, the range is removed from the ban list again.

$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 range and lowercased, then removed from the CIDR ban list. The full Network Group object is re-rendered without it and PUT to the networkgroups endpoint. Unbanning a range that is not banned is a noop. If the PUT fails, the range is restored to the ban list.

$backend->unban_cidr(ban => '1.2.3.0/24');

list_cidr

List banned CIDR ranges. Returns an array of the currently banned ranges from internal state; the FMC is not queried. 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 FMC is not queried. CIDR ranges are not included; for those see "list_cidr".

my @banned = $backend->list;

re_init

Tears down and re-inits, then re-adds all previously added bans by rendering and PUTing the full Network Group object.

teardown

Tears down the setup by PUTing the Network Group object with an empty literal set. 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 token are still usable by fetching the Network Group object. Returns a true value if so and a false value otherwise.

flush

Removes all currently banned IPs and CIDR ranges at once by PUTing the Network Group object with an empty literal set 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. Generating an auth token failed.

24, checkFailed

The backend check raised an error.

25, flushFailed

Failed to flush the bans.

26, portsNotSupported

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

27, protocolsNotSupported

The cisco_fmc 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, groupIdNotDefined

The option group_id is undef or blank.

34, banCidrFailed

Failed to ban the CIDR range.

35, unbanCidrFailed

Failed to unban the CIDR range.

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

37, cidrNotSupported

The backend does not support CIDR bans.

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