Custom WAF rule groups

Cloud-Prem deploys regional and global AWS WAF web ACLs to protect inbound traffic to your instance. You can attach your own WAF rule groups to apply your organization’s rules alongside the Superblocks rules. This applies to inbound traffic only. To filter outbound traffic, use AWS Network Firewall.

Rules Superblocks already applies

Every Cloud-Prem WAF includes these rules, so you don’t need to add your own versions of them:

Rule	What it does
Superblocks IP allowlist	Always allows the Superblocks deploy plane NAT egress IPs and support VPN CIDRs, so upgrade pipelines and support access are never rate-limited or blocked
JWKS path carve-out	Allows `/.well-known/jwks.json` from any source IP so CloudFront can validate JWTs for deployed applications. Control plane WAF only
Rate limit	Blocks IPs that send more than 10,000 requests in a 5-minute window
AWS Common Rule Set	The AWS Managed Rules Common Rule Set, which protects against common web exploits such as those in the OWASP Top 10

How your rules are evaluated

AWS WAF evaluates rules in priority order, lowest first. Rules fall into three priority bands:

Priority	Rules
0–19	Superblocks critical rules: the Superblocks IP allowlist (0) and the JWKS path carve-out (10)
20–99	Your rule groups, in the order you list them
100+	Superblocks generic rules: the rate limit (100) and the AWS Common Rule Set (105)

The Superblocks critical rules always run before yours, so your rule groups can’t block Superblocks upgrades, support access, or JWT validation.

Add rule groups

Your rule groups are attached to the regional and global WAFs. AWS only lets a web ACL use rule groups with the same scope, so create each rule group in both scopes:

WAF	Rule group scope	Create it in
Regional	Regional	The same AWS region as your Cloud-Prem control plane
Global	CloudFront	`us-east-1`, whatever region your Cloud-Prem instance runs in

Create your rule groups in AWS WAF, in both scopes and regions. See Managing your own rule groups in the AWS documentation.
Send the rule group ARNs to your Superblocks deployment team, in the order you want them evaluated.
Superblocks attaches them at the next deployment.

You can add rule groups during your initial deployment or at any time after.

Update your rules

To add, change, or remove rules, edit the rules in the rule groups you’ve already given Superblocks. Because your rule groups are attached by ARN, your changes take effect right away, without a Superblocks deployment or a request to your deployment team.

Update both scopes. Make the same change to the Regional and the CloudFront copies of the rule group.
Don’t create your own web ACL. AWS allows only one web ACL per resource, so associating your own web ACL with Cloud-Prem resources replaces the Superblocks web ACL and removes the Superblocks IP allowlist, rate limit, and AWS Common Rule Set.
Don’t edit the Superblocks web ACLs directly. Superblocks manages them, and changes made outside a deployment can be overwritten.

If new rules would exceed the rule group’s capacity, which AWS fixes when the rule group is created, create a new rule group with more capacity and send its ARN to your deployment team.

Change or remove rule groups

To add a new rule group, remove one, or change their order, send the updated list of ARNs to your deployment team. Changes take effect at the next deployment.

Common use cases

Most customers use rule groups to restrict who can reach their instance. The examples below are rules for the AWS WAF console’s rule JSON editor. Replace the IP set ARNs with your own, and create the IP sets in the same scope and region as the rule group.

Allow only known IP addresses

Block every request that doesn’t come from an IP address you trust. Write this as a Block rule for traffic outside your IP set, not an Allow rule for traffic inside it. An Allow rule would skip the Superblocks rate limit and AWS Common Rule Set.

{
  "Name": "block-outside-ip-allowlist",
  "Priority": 0,
  "Action": { "Block": {} },
  "Statement": {
    "NotStatement": {
      "Statement": {
        "IPSetReferenceStatement": { "ARN": "<allowed-ip-set-arn>" }
      }
    }
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "block-outside-ip-allowlist"
  }
}

Your IP set must include every source that reaches your instance, or those requests are blocked. Check for:

Corporate network egress IPs for offices and other locations where builders and app users work.
VPN egress IPs for remote employees and contractors.
Self-hosted data plane egress IPs, if you run data planes outside the Cloud-Prem account.
CI/CD and automation IPs for pipelines and scripts that call the Superblocks APIs, the MCP server, or the CLI.
Identity provider IPs for SCIM provisioning. See Allow SCIM requests from your identity provider.

AWS WAF IP sets hold either IPv4 or IPv6 addresses, not both. If any of these sources use IPv6, create a second IP set and reference both.

Allow SCIM requests from your identity provider

If you use SCIM, your identity provider sends provisioning requests to https://{tenant}.superblocks.com/scim/v2 from its own servers, not from your network. An IP allowlist blocks them unless you allow your identity provider’s IP ranges. AWS WAF can’t match requests by source domain, so allow your identity provider by IP range instead, and only for the SCIM path:

Identity provider	Published IP ranges
Okta	Okta IP address ranges for your Okta cell
Microsoft Entra ID	The `AzureActiveDirectory` service tag

Put those ranges in their own IP set and add a SCIM exception to your IP allowlist rule. This version blocks a request unless it comes from your allowed IPs, or it’s a SCIM request from your identity provider:

{
  "Name": "block-outside-ip-allowlist",
  "Priority": 0,
  "Action": { "Block": {} },
  "Statement": {
    "AndStatement": {
      "Statements": [
        {
          "NotStatement": {
            "Statement": {
              "IPSetReferenceStatement": { "ARN": "<allowed-ip-set-arn>" }
            }
          }
        },
        {
          "NotStatement": {
            "Statement": {
              "AndStatement": {
                "Statements": [
                  {
                    "ByteMatchStatement": {
                      "SearchString": "/scim/v2",
                      "FieldToMatch": { "UriPath": {} },
                      "PositionalConstraint": "STARTS_WITH",
                      "TextTransformations": [{ "Priority": 0, "Type": "NONE" }]
                    }
                  },
                  {
                    "IPSetReferenceStatement": { "ARN": "<identity-provider-ip-set-arn>" }
                  }
                ]
              }
            }
          }
        }
      ]
    }
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "block-outside-ip-allowlist"
  }
}

Identity providers update their IP ranges over time. Keep the IP set current, or provisioning starts failing.

Restrict access by country

Block requests from outside the countries where your organization operates. List the allowed countries as two-letter ISO 3166 country codes:

{
  "Name": "block-outside-allowed-countries",
  "Priority": 1,
  "Action": { "Block": {} },
  "Statement": {
    "NotStatement": {
      "Statement": {
        "GeoMatchStatement": { "CountryCodes": ["US", "CA"] }
      }
    }
  },
  "VisibilityConfig": {
    "SampledRequestsEnabled": true,
    "CloudWatchMetricsEnabled": true,
    "MetricName": "block-outside-allowed-countries"
  }
}

Country matching is based on the request’s IP address, so it also blocks your identity provider, CI/CD pipelines, and travelling users when their traffic comes from another country. Account for the same sources as an IP allowlist. Superblocks support and upgrade traffic isn’t affected, because the Superblocks IP allowlist runs first.

Enterprise deployment

Security

Support

Rules Superblocks already applies

How your rules are evaluated

Add rule groups

Update your rules

Change or remove rule groups

Common use cases

Allow only known IP addresses

Allow SCIM requests from your identity provider

Restrict access by country

​Rules Superblocks already applies

​How your rules are evaluated

​Add rule groups

​Update your rules

​Change or remove rule groups

​Common use cases

​Allow only known IP addresses

​Allow SCIM requests from your identity provider

​Restrict access by country

​Related

Rules Superblocks already applies

How your rules are evaluated

Add rule groups

Update your rules

Change or remove rule groups

Common use cases

Allow only known IP addresses

Allow SCIM requests from your identity provider

Restrict access by country

Related