NAME
Net::Firewall::BlockerHelper::backends::cloud_armor - Google Cloud Armor backend via the gcloud CLI.
VERSION
Version 0.1.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'cloud_armor',
name => 'ssh',
options => {
policy => 'my-policy',
priority => 1000,
},
);
$fw_helper->init_backend;
$fw_helper->ban( ban => '1.2.3.4' );
$fw_helper->unban( ban => '1.2.3.4' );DESCRIPTION
Blocks IPs with Google Cloud Armor by maintaining the --src-ip-ranges of a single deny rule (identified by its priority) in a security policy, using the gcloud CLI. The full set of currently banned IPs is rendered into the rule on every change, so ban/unban are idempotent. Both IPv4 and IPv6 share the one rule.
Cloud Armor caps the source ranges of a rule, ten per match condition at the time of writing, so bans past that limit will fail. A failed ban is rolled back out of the local ban list so it can not wedge later bans by being re-rendered into every subsequent update. A failed unban is not rolled back; the range is already gone locally and the next successful update converges the rule.
This backend manages only the rule's source ranges. The security policy, the deny rule at the given priority, and the policy's attachment to a backend service or load balancer must already exist.
Requires gcloud in the PATH, authenticated (eg via an activated service account) with rights to update the policy.
METHODS
new
Initiates the object.
- options :: Backend specific options. See below.
- name :: Required by Net::Firewall::BlockerHelper, otherwise unused.The options hash accepts the following.
- gcloud_cmd :: Path to the gcloud binary.
- Default :: gcloud
- policy :: Name of the security policy. Required.
- Default :: undef
- priority :: Priority of the deny rule whose source ranges are managed.
- Default :: 1000
- project :: Optional GCP project; appended as --project when set.
- Default :: undefAll errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend, verifying the deny rule at the configured priority exists via gcloud compute security-policies rules describe.
ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then added to the ban list. The rule's source ranges are then rewritten via gcloud compute security-policies rules update, the IP included as a /32 (IPv4) or /128 (IPv6) range. 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 removed from the ban list. The rule's source ranges are rewritten without it via gcloud compute security-policies rules update. Unbanning an IP that is not banned is a noop.
$fw_helper->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 added to the rule's source ranges via gcloud compute security-policies rules update. Banning an already banned range is a noop.
$fw_helper->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, then the rule's source ranges are rewritten without it. 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
Tears down and re-initiates, then re-applies the full retained banned set (single IPs and CIDR ranges) to the rule's source ranges with a single gcloud update.
teardown
Empties the rule's source ranges. The internal ban list is kept so a following re_init restores them.
stop
Alias for "teardown".
check
Verifies the rule still exists via gcloud compute security-policies rules describe. Returns a true value on a zero exit and a false value otherwise.
flush
Removes all currently banned IPs and CIDR ranges at once by clearing the ban lists and rewriting the rule's source ranges empty with a single gcloud update.
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, policyNotDefined
The option policy 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>
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