NAME
Net::Firewall::BlockerHelper::backends::fortigate - Fortinet FortiGate backend via the REST API.
VERSION
Version 0.1.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'fortigate',
name => 'ssh',
options => {
host => 'fw.example.org',
token => $fortigate_api_token,
group4 => 'blocklist',
group6 => 'blocklist6',
},
);
$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 Fortinet FortiGate via the FortiOS REST API. For each banned IP a firewall address object is created and added as a member of a firewall address group; a firewall policy referencing that group then drops the traffic. IPv4 addresses use firewall/address and firewall/addrgrp, IPv6 use firewall/address6 and firewall/addrgrp6.
This backend manages the address objects and their group membership. The address group(s) and the policy referencing them must already exist on the FortiGate.
Auth is via a REST API token (the token option), sent as a bearer token. An optional vdom scopes the calls to a virtual domain.
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. Takes the following.
- 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 :: FortiGate host, optionally host:port. Required.
- Default :: undef
- token :: REST API token, sent as a bearer token. Required.
- Default :: undef
- group4 :: IPv4 firewall address group the banned addresses are added to.
- Default :: <prefix>_<name>
- group6 :: IPv6 firewall address group the banned addresses are added to.
- Default :: <prefix>_<name>
- vdom :: Optional virtual domain to scope the calls to.
- 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 token and reachability by fetching the IPv4 address group.
ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased. A firewall address object named <prefix>_<name>_<ip> (dots and colons replaced with dashes) is created via a POST to firewall/address (IPv4) or firewall/address6 (IPv6) and then added as a member of the family's address group via a POST to the group's member endpoint. 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 object is removed from the family's address group via a DELETE on the group's member endpoint and then the address object itself is deleted via a DELETE on firewall/address (IPv4) or firewall/address6 (IPv6). 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. A subnet firewall address object named <prefix>_<name>_<cidr> (dots, colons, and slashes replaced with dashes) is created via a POST to firewall/address (IPv4) or firewall/address6 (IPv6) and then added as a member of the family's address group. Banning an already banned CIDR 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 CIDR's address object is removed from the family's address group via a DELETE on the group's member endpoint and then the address object itself is deleted. Unbanning a CIDR 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 CIDRs from internal state; the FortiGate 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 FortiGate 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 ban is then re-applied by recreating its address object and group membership.
teardown
Tears down the setup by removing the group membership and address object for each currently banned IP and CIDR. 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 IPv4 address group. Returns a true value if so and a false value otherwise.
flush
Removes all currently banned IPs and CIDRs at once by removing their group membership and address objects 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 address group failed.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, portsNotSupported
The fortigate backend blocks whole IPs and does not support ports.
27, protocolsNotSupported
The fortigate backend blocks whole IPs and does not support protocols.
30, hostNotDefined
The option host is undef or blank.
31, tokenNotDefined
The option token 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