view release on metacpan or  search on metacpan

docs/kurs/cloud_armor.md  view on Meta::CPAN

gcloud compute security-policies rules create 1000 \
    --security-policy kur-policy --action deny-403 \
    --src-ip-ranges 192.0.2.255/32
```

  (the placeholder range gets overwritten at the first mutation).
- `gcloud` authenticated as an account with
  `compute.securityPolicies.get`/`.update` — a service account
  activated for the kur's user, since the kur runs headless.

## Requirements

- `gcloud` in the `PATH` of the kur process (or `gcloud_cmd`),
  pre-authenticated.

## Settings

- `ports` / `protocols` — accepted for parity but **ignored**; a
  Cloud Armor deny rule's scope is the rule's own business.
- `enable_cidr` — supported, but a range takes one of the 10 slots
  same as a single IP.
- `prefix` — unused.

## Options

| option       | default      | what                                     |
|--------------|--------------|-------------------------------------------|
| `policy`     | *(required)* | the security policy name                 |
| `priority`   | `1000`       | the rule (priority) the kur owns         |
| `project`    | *(unset)*    | adds `--project <project>` when set      |
| `gcloud_cmd` | `gcloud`     | the gcloud binary                        |

## What each operation runs

| operation  | command                                                              |
|------------|--------------------------------------------------------------------------|
| `init`     | `gcloud compute security-policies rules describe <priority> --security-policy <policy>` |
| `ban`      | `gcloud compute security-policies rules update <priority> --security-policy <policy> --src-ip-ranges <ip1>/32,<ip2>/128,...` — the full sorted book |
| `unban`    | the same render, minus the IP                                        |
| `list`     | no command — the kur's own ban book                                  |
| `check`    | the same describe as init                                            |
| `flush`    | the update with an empty range list                                  |
| `re_init`  | teardown (best effort), init, update with the full book              |
| `teardown` | update with empty ranges (ban book kept)                             |

## self_heal

`check` verifies the rule exists and gcloud auth works — not the
rule's contents. Hand-edits to the ranges are overwritten at the
next mutation, since every update ships the whole book.

## Gotchas

- The 10-range ceiling, again — it is the design constraint
  everything else here follows from.
- Each mutation is a full `gcloud` invocation (slow — seconds, not
  milliseconds) and Cloud Armor propagation adds more; sentences
  land at cloud pace.
- gcloud auth (service account tokens) can expire out from under a
  long-running kur; a failed ban with an auth error means
  re-activating credentials, not a kur bug.
- Errors carry Error::Helper flags (`policyNotDefined`, …) —
  [`Net::Firewall::BlockerHelper::backends::cloud_armor`](https://metacpan.org/pod/Net::Firewall::BlockerHelper::backends::cloud_armor) has
  the full table.