WAF Component
Provisions a Web Application Firewall and associates it with a linked website (CloudFront) and/or api-gateway. Its primary use is edge geographic detection and country-based access control: detect the visitor's country at the edge, allow / block / count traffic by country, and forward the resolved country to downstream services so every service shares one authoritative country signal.
Configuration Fields
Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | string | required | — | Must be "waf" |
name | string | required | — | Unique component name. |
geoRestriction | object | optional | — | Geo-match rule. See the geo restriction fields below. |
countryHeader | string | optional | — | Request header name (e.g. x-fp-country) inserted on matched requests so downstream functions/api-gateway receive the resolved country signal. Must be a valid HTTP header name. |
rateLimit | object | optional | — | Rate-based rule: limit (positive int) and window (positive int, seconds). |
ipAllowList | array | optional | — | IPv4 addresses/CIDR blocks to allow. |
ipBlockList | array | optional | — | IPv4 addresses/CIDR blocks to block. |
rules | array | optional | — | Custom rules; each needs name, positive unique priority, and action (ALLOW|BLOCK|COUNT). |
managedRuleGroups | array | optional | — | Names of managed rule groups to enable (e.g. AWSManagedRulesCommonRuleSet). |
logging | object | optional | — | enabled (boolean); when true, destination (non-blank string) is required. |
Geo Restriction Fields
Field | Type | Required | Description |
|---|---|---|---|
type | string | required | "blocklist" (block the listed countries; allow the rest) or "allowlist" (allow only the listed countries; block the rest). |
countries | array | required | ISO 3166-1 alpha-2 country codes (e.g. US, GB, CU). |
action | string | optional | ALLOW, BLOCK, or COUNT. Overrides the action derived from type. Use COUNT to observe geo matches without enforcing them (useful when rolling out a rule). |
Cloud Resources Created
- WAFv2 Web ACL — with a geo-match rule built from geoRestriction. The rule action is ALLOW, BLOCK, or COUNT; the web ACL default action is ALLOW for a blocklist and BLOCK for an allowlist.
- Custom request header — if countryHeader is set, the geo rule inserts that header on matched requests (WAFv2 custom request handling) so downstream services receive the country signal.
- Association — for a WAF_TO_WEBSITE link, a CLOUDFRONT-scope Web ACL is created in us-east-1 and set on the CloudFront distribution config (webACLId) via UpdateDistribution; for a WAF_TO_API_GATEWAY link, a REGIONAL-scope Web ACL is created in the deploy region and associated with the API's $default stage via AssociateWebACL.
Scope note: A WAF linked to both a website and an api-gateway produces two Web ACLs — one per scope — because AWS forbids associating a CLOUDFRONT-scope ACL with a regional resource and vice-versa.
Deploy ordering: the WAF is provisioned after its linked targets so their ARNs can be resolved for association. On redeploy the Web ACL is updated in place (found by name, updated with its lock token).
- Front Door WAF policy — with geo-filtering rules; associated with the linked Static Web App / API Management.
Note: Provider parity for Azure geo rules is planned; AWS is the reference implementation. Front Door WAF policy creation requires the azure-resourcemanager-cdn module (not yet on the classpath); until then the deployment records the WAF policy resource and is idempotent.
- Cloud Armor security policy — with region/country match rules; attached to the linked Cloud CDN / API Gateway backend.
Note: Provider parity for GCP geo rules is planned; AWS is the reference implementation. Cloud Armor security-policy management requires the google-cloud-compute module (not yet on the classpath); until then the deployment records the policy resource and is idempotent.
JSON Example
{
"type": "waf",
"name": "edge-waf",
"providerSettings": {
"geoRestriction": {
"type": "blocklist",
"countries": ["CU", "IR"],
"action": "BLOCK"
},
"countryHeader": "x-fp-country"
},
"links": [
{ "sourceComponent": "edge-waf", "targetComponent": "marketing-site", "linkType": "WAF_TO_WEBSITE" },
{ "sourceComponent": "edge-waf", "targetComponent": "core-api", "linkType": "WAF_TO_API_GATEWAY" }
]
}
Links
Declare protection using the links array. The plugin infers the relationship from the target component type.
Country access model: hard geo-blocking (blocked geographies never reach the app) is enforced at the WAF. "Not-yet-available" vs "available" redirects can be handled by the app or an edge function using the forwarded countryHeader.