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

NAME

Net::Firewall::BlockerHelper::backends::juniper_srx - Juniper SRX backend via the Junos REST API.

VERSION

Version 0.2.0

SYNOPSIS

use Net::Firewall::BlockerHelper;

my $fw_helper = Net::Firewall::BlockerHelper->new(
    backend => 'juniper_srx',
    name    => 'ssh',
    options => {
        host        => 'srx.example.org',
        user        => 'blocker',
        password    => $password,
        address_set => '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 Juniper SRX by managing entries in a global address book and a global address-set through the Junos REST API (the /rpc endpoint, which takes XML RPCs). A security policy referencing the address-set must already exist on the device.

For each banned IP an address book entry is created and added to the configured address-set. Changes are applied by loading the configuration in set format and then committing it, both as POSTs to https://<host>/rpc.

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

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

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

- user :: REST API user for basic auth. Required.
    - Default :: undef

- password :: REST API password for basic auth. Required.
    - Default :: undef

- address_set :: Name of the global address-set a security policy
        references and that banned IPs are added to.
    - 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. Verifies the credentials and connectivity with a get-software-information RPC.

ban

Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased. A global address book entry named <prefix>_<name>_<ip> (dots and colons replaced with '-') is created with a /32 or /128 mask as appropriate and added to the configured address-set, via a load-configuration RPC in set format followed by a commit-configuration RPC, both POSTed to the REST 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. The IP's address book object is deleted via a load-configuration RPC followed by a commit-configuration RPC; deleting the address also removes it from the address-set. Unbanning an IP that is not banned is a noop.

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

ban_cidr

Bans a CIDR range. The value of ban is validated as being a IPv4 or IPv6 CIDR and lowercased. An address book object is created the same way as for a single IP, but with the CIDR used verbatim as the address prefix, and is added to the address-set, then the change is committed. Banning an already banned CIDR range is a noop.

$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 and lowercased. The range's address book object is deleted, then the change is committed; deleting the address also removes it from the address-set. Unbanning a CIDR 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 from internal state; the device 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 device 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. Teardown is best effort, as a partially or fully wiped setup is what re_init recovers from. Each retained IP and CIDR range is then re-added via its own load-configuration and commit-configuration RPC pair.

teardown

Tears down the setup by deleting the address book object of each currently banned IP and CIDR range, committing after each deletion. The internal list of bans is kept, so a following re_init will re-add them.

stop

Alias for "teardown".

check

Verifies the credentials and connectivity are still usable with a get-software-information RPC. Returns a true value if so and a false value otherwise.

flush

Removes all currently banned IPs and CIDR ranges at once by deleting their address book objects, committing after each deletion, and clearing the internal ban lists.

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

Probing the API during init failed.

24, checkFailed

The backend check raised an error.

25, flushFailed

Failed to flush the bans.

26, portsNotSupported

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

27, protocolsNotSupported

The juniper_srx 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