NAME
Net::Firewall::BlockerHelper::backends::panos - Palo Alto Networks PAN-OS backend via the User-ID XML API.
VERSION
Version 0.1.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'panos',
name => 'ssh',
options => {
host => 'fw.example.org',
key => $panos_api_key,
tag => 'blocklist',
},
);
$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 Palo Alto Networks PAN-OS firewall by registering them with a tag through the User-ID XML API. A Dynamic Address Group (DAG) on the firewall is configured to match that tag, and a security policy references the DAG. Banning an IP is then a matter of registering the IP-to-tag mapping; the DAG membership, and therefore the enforcement, updates without a commit.
This backend manages only the IP registrations. The Dynamic Address Group matching the tag and the security policy referencing it must already exist on the firewall.
Auth is via a PAN-OS API key (the key option), which you generate out of band (the type=keygen API call or the web UI). The same tag holds both IPv4 and IPv6 registrations.
Blocking is per IP; ports and protocols belong on the referencing policy, so specifying them here 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 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 :: PAN-OS host, optionally host:port. Required.
- Default :: undef
- key :: PAN-OS API key. Required.
- Default :: undef
- tag :: The tag registered IPs are given, matched by the Dynamic Address
Group.
- Default :: <prefix>_<name>
- vsys :: Optional vsys the registrations are scoped to (eg vsys1).
- Default :: undef
- scheme :: 'https' or 'http'.
- Default :: https
- insecure :: If true, skip TLS certificate verification.
- 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 key and connectivity with an op command.
ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then registered with the tag by POSTing a User-ID register uid-message to the XML API. 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 unregistered from the tag by POSTing a User-ID unregister uid-message to the XML API. Unbanning an IP that is not banned is a noop.
$backend->unban(ban => $ip);ban_cidr
Bans a CIDR range by registering it with the tag via a User-ID register uid-message. PAN-OS User-ID accepts a network prefix in the same manner as a single address. 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 unregistering it from the tag via a User-ID unregister uid-message. 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-registers all previously added bans. Registrations are runtime state on the firewall, so this is how they are restored after a reboot or a User-ID cache flush.
teardown
Tears down the setup by unregistering each currently banned IP. The internal list of bans is kept, so a following re_init will re-add them.
stop
Alias for "teardown".
check
Verifies the key and connectivity are still usable with an op command. Returns a true value if so and a false value otherwise.
flush
Removes all currently banned IPs at once by unregistering them 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 API with an op command failed.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, portsNotSupported
Ports were specified, but the backend does not support ports.
27, protocolsNotSupported
Protocols were specified, but the backend does not support protocols.
30, hostNotDefined
The option host is undef or blank.
31, keyNotDefined
The option key is undef or blank.
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