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

NAME

Net::Firewall::BlockerHelper::backends::routeros_api - MikroTik RouterOS backend using the REST API.

VERSION

Version 0.2.0

SYNOPSIS

use Net::Firewall::BlockerHelper;

my $fw_helper = Net::Firewall::BlockerHelper->new(
    backend => 'routeros_api',
    name    => 'ssh',
    options => {
        host     => '10.0.0.1',
        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 a MikroTik RouterOS device via its REST API (RouterOS 7.1+), adding and removing entries in a firewall address-list. IPv4 addresses go in the /ip/firewall/address-list and IPv6 in /ipv6/firewall/address-list, under the list names given by the list4/list6 options (both defaulting to <prefix>_<name>).

This backend manages only the address-list membership. A firewall filter (or raw) rule that drops traffic matching the address-list must already exist on the router. If you would rather have the referencing rules created for you, or you are on RouterOS 6 without the REST API, use the ssh driven routeros backend instead.

Blocking is per IP; ports and protocols belong on the referencing rule, 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.

NOTES

This backend was written going off the API docs and actual testing is needed to double check a few things as the exact behavior is not clear.

teardown currently only removes the single IP address-list entries, leaving CIDR entries on the router, while flush removes both. A re_init after a teardown will re-add the CIDR entries, and whether RouterOS then errors or ends up with duplicate entries needs checking.

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

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

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

- scheme :: 'https' or 'http'.
    - Default :: https

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

- list4 :: IPv4 address-list name.
    - Default :: <prefix>_<name>

- list6 :: IPv6 address-list name.
    - Default :: <prefix>_<name>

- 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 reachability by performing a GET against the IPv4 address-list endpoint. Nothing is created on the router; the referencing firewall rule must already exist.

$backend->init;

ban

Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then added to the relevant address-list via a PUT to /rest/ip/firewall/address-list or /rest/ipv6/firewall/address-list. 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 address-list entry is looked up via a GET to find its .id and then removed via a DELETE. An entry that can not be found is treated as already unbanned. Unbanning an IP that is not banned is a noop.

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

ban_cidr

Bans a CIDR range by adding it to the relevant address-list via a PUT. RouterOS address-lists accept 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. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased. Its address-list entry is looked up via a GET to find its .id and then removed via a DELETE. An entry that can not be found is treated as already unbanned. 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-adds all previously added bans. teardown is best effort, as a partially or fully wiped setup is what this needs to recover from. Each retained single IP and CIDR ban is re-added via a PUT to the relevant address-list endpoint.

$backend->re_init;

teardown

Tears down the setup by removing the address-list entry for 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 endpoint and credentials are still usable by fetching the address-list. Returns a true value if so and a false value otherwise.

flush

Removes all currently banned IPs and CIDR ranges at once by removing their address-list entries and forgetting them.

$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 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 endpoint failed.

24, checkFailed

The backend check raised an error.

25, flushFailed

Failed to flush the bans.

26, portsNotSupported

Ports were specified, but this backend manages whole IPs and does not support ports.

27, protocolsNotSupported

Protocols were specified, but this backend manages 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