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

NAME

Net::Firewall::BlockerHelper::backends::routeros - MikroTik RouterOS backend for Net::Firewall::BlockerHelper.

VERSION

Version 0.1.0

SYNOPSIS

use Net::Firewall::BlockerHelper;

my $fw_helper;
eval {
    $fw_helper = Net::Firewall::BlockerHelper->new(
            backend=>'routeros',
            name=>'ssh',
            options=>{
                      host     => '192.0.2.1',
                      user     => 'admin',
                      identity => '/home/user/.ssh/id_ed25519',
                      },
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

$fw_helper->init_backend;

$fw_helper->ban(ban => '5.6.7.8');
$fw_helper->ban(ban => '1.2.3.4');

$fw_helper->unban(ban => '5.6.7.8');

$fw_helper->teardown;

DESCRIPTION

This backend blocks IPs on a MikroTik RouterOS device by driving its CLI over SSH.

For each instance two address-lists are used, one for IPv4 (default <prefix>_<name> under the /ip firewall menu) and one for IPv6 (default <prefix>_<name> under the /ipv6 firewall menu). A filter rule in the input chain references each address-list and applies the configured action. Banning an IP is then simply a matter of adding it to the relevant address-list.

The filter rules are created via a plain add, which appends them to the end of the input chain. As RouterOS filter rules are evaluated first match wins, any earlier rule accepting the traffic will win out over them, so on a router with the likes of a broad accept rule in input the rules will need to be moved up the chain for bans to actually take effect. Also, being in the input chain, they only cover traffic to the router itself and not traffic forwarded through it.

Requires an SSH client in the PATH of the process and credentials that allow the configured user to run firewall commands on the router.

METHODS

new

Initiates the the object.

- options :: A hash of options to pass to the backend.
    Default :: {}

- ports :: Not used by this backend.
    Default :: []

- protocols :: Not used by this backend.
    Default :: []

- prefix :: Prefix to use.
    - default :: kur

- name :: Name of this specific instance.
    - default :: undef

The options hash accepts the following.

- host :: Router hostname or IP. This must be specified.
    - Default :: undef

- user :: SSH user to connect as.
    - Default :: admin

- ssh_cmd :: SSH binary plus any base arguments.
    - Default :: ssh

- ssh_port :: Optional SSH port. When set, '-p <port>' is added.
    - Default :: undef

- identity :: Optional path to a SSH private key. When set, '-i <identity>'
        is added.
    - Default :: undef

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

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

- action :: Firewall action for the drop rules.
    - Default :: drop

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

my $fw_helper;
eval {
    $fw_helper = Net::Firewall::BlockerHelper->new(
            backend=>'routeros',
            name=>'ssh',
            options=>{ host => '192.0.2.1' },
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

init

Initiates the backend. Over SSH this runs /ip firewall filter add and /ipv6 firewall filter add to create a filter rule in the input chain for each family, matching its address-list and applying the configured action.

Note that the rules are appended to the end of the input chain, so they may need moving up past any earlier accept rules to have an effect. See "DESCRIPTION".

No arguments are taken.

May called a second time, it will error.

$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 by running /ip firewall address-list add or /ipv6 firewall address-list add over SSH. Banning an already banned IP is a noop.

$fw_helper->ban(ban => $ip);

unban

Unbans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then its address-list entry is removed by running /ip firewall address-list remove [find ...] or the IPv6 equivalent over SSH. Unbanning an IP that is not banned is a noop.

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

ban_cidr

Bans a CIDR range by adding it to the relevant address-list. 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.

$fw_helper->ban_cidr(ban => '1.2.3.0/24');

unban_cidr

Unbans a CIDR range by removing it from the relevant address-list via address-list remove [find ...] over SSH. 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.

$fw_helper->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 = $fw_helper->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 = $fw_helper->list;

re_init

Tells the backend to re-init it's self.

This will call teardown and init again. After that it will re-add all previously added bans.

$fw_helper->re_init;

teardown

Tears down the setup for the backend.

This will remove the filter rules and all address-list entries for both families.

$fw_helper->teardown;

stop

Alias for "teardown", provided for parity with the fail2ban actionstop concept.

$fw_helper->stop;

check

Runs a remote /ip firewall filter print for the IPv4 address-list. A zero exit code is treated as healthy. This is the equivalent of fail2ban's actioncheck.

if ( !$fw_helper->check ) {
    $fw_helper->re_init;
}

flush

Removes all currently banned IPs at once by removing every entry from both address-lists, leaving the filter rules in place. This is the equivalent of fail2ban's actionflush.

$fw_helper->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.

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.

24, checkFailed

The backend check raised an error.

25, flushFailed

Failed to flush the bans.

30, hostNotDefined

The option host is undef or blank.

31, banCidrFailed

Failed to ban the CIDR range.

32, unbanCidrFailed

Failed to unban the CIDR range.

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

34, cidrNotSupported

The backend does not support CIDR bans.

35, listCidrFailed

Failed to get a list of CIDR bans.

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.ent>

BUGS

Please report any bugs or feature requests to bug-net-firewall-blockerhelper at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Firewall-BlockerHelper. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::Firewall::BlockerHelper

You can also look for information at:

ACKNOWLEDGEMENTS

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