feat: Add Cloud Armor security policy to block abusive IP ranges from API at load balancer

Author: mjumbewu

infra/gcp-domains/.auto.tfvars.example

@@ -36,3 +36,9 @@ domain_mappings = {
 #   mycity-gov    = ["suggest.mycity.gov", "suggest-staging.mycity.gov"]
 #   bikeshare-com = ["suggest.bikeshare.com"]
 # }
+
+# Optional: List of IP CIDR ranges to block at the load balancer level via Cloud Armor
+# blocked_ip_ranges = [
+#   "192.0.2.0/24",
+# ]
+

infra/gcp-domains/backend.tf

@@ -24,6 +24,7 @@ resource "google_compute_backend_service" "default" {
   name                  = "${each.key}-backend"
   protocol              = "HTTP"
   load_balancing_scheme = "EXTERNAL_MANAGED"
+  security_policy       = length(google_compute_security_policy.ip_blocklist) > 0 ? google_compute_security_policy.ip_blocklist[0].id : null
 
   backend {
     group = google_compute_region_network_endpoint_group.serverless_neg[each.key].id

infra/gcp-domains/security.tf

@@ -0,0 +1,37 @@
+# ------------------------------------------------------------------------------
+# Cloud Armor Security Policy
+# Blocks traffic from specified IP CIDR ranges at the Load Balancer level
+# ------------------------------------------------------------------------------
+
+resource "google_compute_security_policy" "ip_blocklist" {
+  count       = length(var.blocked_ip_ranges) > 0 ? 1 : 0
+  name        = "${var.load_balancer_name}-ip-blocklist"
+  description = "Cloud Armor security policy to block abusive IP ranges"
+
+  dynamic "rule" {
+    for_each = length(var.blocked_ip_ranges) > 0 ? [1] : []
+    content {
+      action   = "deny(403)"
+      priority = "1000"
+      match {
+        versioned_expr = "SRC_IPS_V1"
+        config {
+          src_ip_ranges = var.blocked_ip_ranges
+        }
+      }
+      description = "Deny access to specified IP ranges"
+    }
+  }
+
+  rule {
+    action   = "allow"
+    priority = "2147483647"
+    match {
+      versioned_expr = "SRC_IPS_V1"
+      config {
+        src_ip_ranges = ["*"]
+      }
+    }
+    description = "Default rule, allow all traffic"
+  }
+}

infra/gcp-domains/variables.tf

@@ -53,3 +53,10 @@ variable "ssl_certs" {
   description = "A map of custom SSL certificate groups. Any domains not in this map will be grouped into a default certificate."
   default     = {}
 }
+
+variable "blocked_ip_ranges" {
+  type        = list(string)
+  description = "List of IP CIDR ranges to block at the load balancer level via Cloud Armor security policy"
+  default     = []
+}
+

openspec/changes/archive/2026-08-01-block-abusive-ip-ranges/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-01

openspec/changes/archive/2026-08-01-block-abusive-ip-ranges/design.md

@@ -0,0 +1,34 @@
+## Context
+
+The service infrastructure in `infra/gcp-domains/` manages a central GCP Global External Application Load Balancer using OpenTofu/Terraform. Backend services are defined as `google_compute_backend_service` connected to Cloud Run instances via Serverless Network Endpoint Groups (`google_compute_region_network_endpoint_group`). See `proposal.md` for motivation.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add a GCP Cloud Armor Security Policy (`google_compute_security_policy`) in `infra/gcp-domains/`.
+- Configure rule priorities to deny requests matching blocked IP CIDR ranges with a 403 response.
+- Attach the security policy to `google_compute_backend_service.default`.
+- Allow specifying blocked CIDR ranges via OpenTofu variables (`blocked_ip_ranges`).
+
+**Non-Goals:**
+- Application-level IP filtering in Django middleware.
+- Dynamic IP blocking database/admin interfaces.
+- Advanced Cloud Armor WAF rules (e.g., OWASP top 10 rulesets, reCAPTCHA enterprise) - focus specifically on IP range blocklists.
+
+## Decisions
+
+### Decision 1: GCP Cloud Armor Security Policy over Django Middleware
+- **Rationale**: Cloud Armor drops traffic at GCP edge forwarding rules before requests reach Cloud Run, protecting compute resources, memory, and database connections.
+- **Alternatives Considered**: Django middleware was rejected because requests would still trigger Cloud Run container invocations and consume backend resources.
+
+### Decision 2: Managed via OpenTofu variables in `infra/gcp-domains/`
+- **Rationale**: `infra/gcp-domains/` centralizes domain routing and load balancing backend services. Adding the security policy here keeps infrastructure definitions cohesive and version-controlled.
+- **Implementation**:
+  - Add `blocked_ip_ranges` variable (`list(string)`) in `infra/gcp-domains/variables.tf` (default `[]`).
+  - Declare `google_compute_security_policy` in `infra/gcp-domains/security.tf` (or `main.tf`).
+  - Attach `security_policy = google_compute_security_policy.ip_blocklist[0].id` to `google_compute_backend_service.default`.
+
+## Risks / Trade-offs
+
+- **[Risk] Accidental blocking of legitimate users in shared IP ranges** → **Mitigation**: Specify tight CIDR masks where possible, and document how to update or remove CIDR blocks in `.auto.tfvars`.
+- **[Risk] Cloud Armor rule limit (standard tier limits rules per policy)** → **Mitigation**: Use CIDR ranges (`src_ip_ranges`) to group multiple IPs into concise rule blocks.

openspec/changes/archive/2026-08-01-block-abusive-ip-ranges/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+Abusive HTTP traffic originating from specific IP subnet ranges (e.g., `X.X.X.0/25`) is hitting the service, taking up resources. We need to block abusive IP ranges at the GCP Load Balancer level using Cloud Armor security policies so that unwanted requests are rejected immediately at the edge with a 403 Forbidden status code, protecting Cloud Run compute and database resources.
+
+## What Changes
+
+- Add a GCP Cloud Armor security policy resource in OpenTofu/Terraform (`infra/gcp-domains/`) to block designated IP ranges with a 403 HTTP response.
+- Attach the Cloud Armor security policy to the GCP Load Balancer's backend services (`google_compute_backend_service.default`).
+- Expose configurable variables for the blocked IP CIDR ranges in `infra/gcp-domains/variables.tf` and `.auto.tfvars`.
+
+## Capabilities
+
+### New Capabilities
+
+- `ip-range-blocking`: Support configuring and enforcing IP range blocklists at the load balancer level via Terraform.
+
+### Modified Capabilities
+
+(None)
+
+## Impact
+
+- **Infrastructure**: Updates OpenTofu/Terraform state and configuration in `infra/gcp-domains/`.
+- **GCP Resources**: Provisions a `google_compute_security_policy` in GCP and links it to `google_compute_backend_service`.
+- **Traffic**: Requests originating from IPs within blocked CIDR ranges will receive HTTP 403 Forbidden responses at the GCP edge load balancer prior to reaching Cloud Run.

openspec/changes/archive/2026-08-01-block-abusive-ip-ranges/specs/ip-range-blocking/spec.md

@@ -0,0 +1,23 @@
+## Purpose
+
+Configures IP range blocklists at the GCP load balancer level to reject abusive network traffic before it reaches backend services.
+
+## ADDED Requirements
+
+### Requirement: Block Traffic from Specified IP Ranges
+The load balancer security policy SHALL deny HTTP requests originating from client IP addresses matching configured CIDR ranges with a 403 Forbidden status code.
+
+#### Scenario: Request from a blocked IP CIDR range
+- **WHEN** an HTTP request is received from an IP address within a configured blocked CIDR range
+- **THEN** the load balancer immediately responds with HTTP status 403 Forbidden without forwarding the request to Cloud Run
+
+#### Scenario: Request from an unblocked IP address
+- **WHEN** an HTTP request is received from an IP address outside the configured blocked CIDR ranges
+- **THEN** the load balancer evaluates default rules and forwards legitimate traffic to Cloud Run
+
+### Requirement: Configurable IP Blocklist Ranges via Infrastructure Code
+The infrastructure module SHALL accept a configurable list of IP CIDR strings for the load balancer security policy.
+
+#### Scenario: Adding a new IP range to the blocklist
+- **WHEN** a new IP CIDR range is added to the Terraform variable `blocked_ip_ranges` and applied
+- **THEN** Cloud Armor updates the security policy rule set to block requests from that CIDR range

openspec/changes/archive/2026-08-01-block-abusive-ip-ranges/tasks.md

@@ -0,0 +1,10 @@
+## 1. Terraform Configuration for Security Policy
+
+- [x] 1.1 Declare the `blocked_ip_ranges` input variable in `infra/gcp-domains/variables.tf`.
+- [x] 1.2 Create `infra/gcp-domains/security.tf` defining `google_compute_security_policy` with rules to deny blocked IP CIDR ranges with HTTP 403.
+- [x] 1.3 Update `google_compute_backend_service.default` in `infra/gcp-domains/backend.tf` to reference the Cloud Armor security policy.
+
+## 2. Validation & Deployment Setup
+
+- [x] 2.1 Add example blocked IP configuration to `infra/gcp-domains/.auto.tfvars.example` and `.auto.tfvars`.
+- [x] 2.2 Validate Terraform / OpenTofu syntax and formatting using `tofu fmt` / `tofu validate` or `terraform validate`.

openspec/specs/ip-range-blocking/spec.md

@@ -0,0 +1,23 @@
+## Purpose
+
+Configures IP range blocklists at the GCP load balancer level to reject abusive network traffic before it reaches backend services.
+
+## Requirements
+
+### Requirement: Block Traffic from Specified IP Ranges
+The load balancer security policy SHALL deny HTTP requests originating from client IP addresses matching configured CIDR ranges with a 403 Forbidden status code.
+
+#### Scenario: Request from a blocked IP CIDR range
+- **WHEN** an HTTP request is received from an IP address within a configured blocked CIDR range
+- **THEN** the load balancer immediately responds with HTTP status 403 Forbidden without forwarding the request to Cloud Run
+
+#### Scenario: Request from an unblocked IP address
+- **WHEN** an HTTP request is received from an IP address outside the configured blocked CIDR ranges
+- **THEN** the load balancer evaluates default rules and forwards legitimate traffic to Cloud Run
+
+### Requirement: Configurable IP Blocklist Ranges via Infrastructure Code
+The infrastructure module SHALL accept a configurable list of IP CIDR strings for the load balancer security policy.
+
+#### Scenario: Adding a new IP range to the blocklist
+- **WHEN** a new IP CIDR range is added to the Terraform variable `blocked_ip_ranges` and applied
+- **THEN** Cloud Armor updates the security policy rule set to block requests from that CIDR range