NAME
Net::Firewall::BlockerHelper::backends::checkpoint - Check Point Management (web_api) backend.
VERSION
Version 0.2.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'checkpoint',
name => 'ssh',
options => {
host => 'mgmt.example.org',
user => 'automation',
password => $checkpoint_password,
group => '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 Check Point Security Management server via its web_api. For each banned IP a host object is created and added as a member of a group object; a rule in the policy referencing that group then drops the traffic. The group object (default <prefix>_<name>) and the drop rule referencing it must already exist; this backend creates neither, only the host objects added to the group.
Authentication is session based. "init" POSTs to /web_api/login with the configured user and password and stores the returned session id. Every following call sends that session id in the X-chkp-sid header. All calls are POSTs carrying JSON bodies.
The management server is reached at https://<host> (port 443 by default).
Blocking is per IP; ports and protocols belong on the referencing rule, so specifying them here is an error.
Enforcement note: publish only saves the change to the management database. Actually enforcing the block on the gateways additionally requires an install-policy, which is intentionally out of scope for this backend.
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.
ban_cidr creates a host object with the CIDR as its ip-address and the / is kept in the generated object name, and it is not clear whether the web_api will accept either; a network object may be required instead.
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 :: Check Point management server host. Required.
- Default :: undef
- user :: web_api user to log in as. Required.
- Default :: undef
- password :: password for the web_api user. Required.
- Default :: undef
- group :: group object the host objects are added to.
- Default :: <prefix>_<name>
- timeout :: HTTP timeout in seconds.
- Default :: 30
- insecure :: If true, skip TLS certificate verification.
- Default :: 0All errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. Logs into the web_api by POSTing the configured user and password to /web_api/login and stores the returned session id, which is sent in the X-chkp-sid header on every following call.
Note that nothing is created remotely by this; the group object must already exist. See "DESCRIPTION".
ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased. A host object named <prefix>_<name>_<ip> (dots and colons replaced with -) is created via /web_api/add-host with the group as a member group, then the change is saved via /web_api/publish. 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 host object created by "ban" is deleted via /web_api/delete-host, then the change is saved via /web_api/publish. 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 range and lowercased, then handled the same way as "ban", a host object with the CIDR as its ip-address being created via /web_api/add-host with the group as a member group and the change saved via /web_api/publish. 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 range and lowercased. The host object created by "ban_cidr" is deleted via /web_api/delete-host, then the change is saved via /web_api/publish. 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; nothing is queried from the management server. 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; nothing is queried from the management server. CIDR ranges are not included; for those see "list_cidr".
my @banned = $backend->list;re_init
Tears down and re-inits. "teardown" is called best effort, a new session is logged in via "init", and then the host object and group membership is re-created for every retained single IP and CIDR ban.
teardown
Tears down the setup by deleting the host object for each currently banned IP and CIDR range and publishing. The internal list of bans is kept, so a following re_init will re-add them.
stop
Alias for "teardown".
check
Verifies the session is still usable by POSTing to /web_api/keepalive. 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 host objects and publishing, then 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. Logging into the web_api failed.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, portsNotSupported
The checkpoint backend blocks whole IPs and does not support ports.
27, protocolsNotSupported
The checkpoint 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