Security policy overview

This page describes how you can use Google Cloud Armor security policies to protect your Google Cloud deployments.

Google Cloud Armor security policies protect your application by providing Layer 7 filtering and by scrubbing incoming requests for common web attacks or other Layer 7 attributes to potentially block traffic before it reaches your load-balanced backend services or backend buckets. Each security policy is made up of a set of rules that can be configured on attributes from Layer 3 through Layer 7. The rules can filter traffic based on conditions such as an incoming request's IP address, IP range, region code, or request headers.

Google Cloud Armor security policies are available for the following load balancer and endpoint types:

Global external Application Load Balancer (HTTP/HTTPS)
Classic Application Load Balancer (HTTP/HTTPS)
Regional external Application Load Balancer (HTTP/HTTPS)
Regional internal Application Load Balancer (HTTP/HTTPS)
Global external proxy Network Load Balancer (TCP/SSL)
Classic proxy Network Load Balancer (TCP/SSL)
External passthrough Network Load Balancer (TCP/UDP)
Protocol forwarding
VMs with public IP addresses

The load balancer can be in Premium Tier or Standard Tier.

The backends to the backend service can be any of the following:

Instance groups
Zonal network endpoint groups (NEGs)
Serverless NEGs: One or more App Engine, Cloud Run, or Cloud Run functions services
Internet NEGs for external backends
Buckets in Cloud Storage

When you use Google Cloud Armor to protect a hybrid deployment or a multicloud architecture, the backends must be internet NEGs. Google Cloud Armor also protects serverless NEGs when traffic is routed through a load balancer. To ensure that only traffic that has been routed through your load balancer reaches your serverless NEG, see Ingress controls.

Google Cloud Armor also provides advanced network DDoS protection for external passthrough Network Load Balancers, protocol forwarding, and VMs with public IP addresses. For more information about advanced DDoS protection, see Configure advanced network DDoS protection.

Protect your Google Cloud deployments with Google Cloud Armor security policies

External load balancing is implemented at the edge of Google's network in Google's points of presence (PoPs) around the world. In Premium Tier, user traffic directed to an external load balancer enters the PoP closest to the user. It is then load balanced over Google's global network to the closest backend that has sufficient capacity available. In Standard Tier, user traffic enters Google's network through peering, ISP, or transit networks in the region where you have deployed your Google Cloud resources.

Google Cloud Armor security policies enable you to allow, deny, rate-limit, or redirect requests to your backend services at the Google Cloud edge, as close as possible to the source of incoming traffic. This prevents unwelcome traffic from consuming resources or entering your Virtual Private Cloud (VPC) networks.

The following diagram illustrates the location of global external Application Load Balancers, classic Application Load Balancers, the Google network, and Google data centers.

Google Cloud Armor policy at network edge. — Google Cloud Armor policy at network edge (click to enlarge).

Requirements

These are the requirements for using Google Cloud Armor security policies:

The backend service's load balancing scheme must be EXTERNAL, EXTERNAL_MANAGED, or INTERNAL_MANAGED.
The backend service's protocol must be one of HTTP, HTTPS, HTTP/2, UDP, TCP, SSL, or UNSPECIFIED.

About Google Cloud Armor security policies

Google Cloud Armor security policies are sets of rules that match on attributes from Layer 3 to Layer 7 to protect externally facing applications or services. Each rule is evaluated with respect to incoming traffic.

A Google Cloud Armor security policy rule consists of a match condition and an action to take when that condition is met. Conditions can be as simple as whether the incoming traffic's source IP address matches a specific IP address or CIDR range (also known as IP address allowlist and denylist rules). Alternatively, by using the Google Cloud Armor custom rules language reference, you can create custom conditions that match on various attributes of the incoming traffic, such as the URL path, request method, or request header values.

When an incoming request matches a condition in a security policy rule, Google Cloud Armor allows, denies, or redirects the request, based on whether the rule is an allow rule, a deny rule, or a redirect rule. There can be additional action parameters to apply, like inserting request headers; this feature is part of Google Cloud Armor bot management. For more information about bot management, see the bot management overview.

You can associate a Google Cloud Armor security policy with one or more backend services. A backend service can have only one security policy associated with it, but your backend services don't all need to be associated with the same security policy.

If a Google Cloud Armor security policy is associated with any backend service, it can't be deleted. A backend service can be deleted regardless of whether it has an associated security policy.

If multiple forwarding rules point to a backend service that has an associated security policy, the policy rules are enforced for all traffic coming in to each of the forwarding rule IP addresses.

In the following illustration, the Google Cloud Armor security policy internal-users-policy is associated with the backend service test-network.

Google Cloud Armor security policy at network edge. — Google Cloud Armor security policy at network edge (click to enlarge).

Google Cloud Armor security policies have the following features:

You can optionally use the QUIC protocol with load balancers that use Google Cloud Armor.
You can use Google Cloud Armor with load balancers that are in either of the following Network Service Tiers:
- Premium Tier
- Standard Tier
You can use backend security policies with GKE and the default Ingress controller.
You can use a default security policy that throttles traffic over a user-specified threshold when you configure one of the following load balancers:
- Global external Application Load Balancer
- Classic Application Load Balancer
- Regional external Application Load Balancer
- Regional internal Application Load Balancer
- Global external proxy Network Load Balancer
- Classic proxy Network Load Balancer
- External passthrough Network Load Balancer

In addition, you can configure Google Cloud Armor preconfigured WAF rules, which are complex web application firewall (WAF) rules with dozens of signatures that are compiled from open source industry standards. Each signature corresponds to an attack detection rule in the rule set. Google offers these rules as-is. The rules allow Google Cloud Armor to evaluate dozens of distinct traffic signatures by referring to conveniently named rules, rather than requiring you to define each signature manually. For more information about preconfigured WAF rules, see the preconfigured WAF rules overview.

Types of security policies

The following tables show the types of security policies and what you can do with them. A check mark () indicates that the type of security policy supports the feature.

Globally scoped security policies

	Backend security policy		Edge security policy
Frontend type	Global external Application Load Balancer Classic Application Load Balancer	Global external proxy Network Load Balancer Classic proxy Network Load Balancer	Global external Application Load Balancer Classic Application Load Balancer
Attachment point (protected resource)	Backend service	Backend service	Backend service Backend bucket
Rule actions	Allow Deny Redirect (`GOOGLE_RECAPTCHA` and `EXTERNAL_302`) Throttle Rate-based ban	Allow Deny Throttle Rate-based ban	Allow Deny
Source IP address
Source geography
Source ASN
Rate limiting
JA3 fingerprints
Bot management
Layer 7 filtering			Media CDN only
WAF
Adaptive Protection
Address Group
Threat Intelligence
Security Command Center
Cloud Monitoring
Request logging

Regionally scoped security policies

	Regional backend security policy		Network edge security policy
Frontend Type	Regional external Application Load Balancer	Regional internal Application Load Balancer	External passthrough Network Load Balancer Protocol forwarding VMs with public IP addresses
Attachment point (protected resource)	Backend service (Regional)	Backend service (Regional)	Target pool Target instance Backend service (regional) Instance
Rule actions	Allow Deny Throttle Rate-based ban	Allow Deny Throttle Rate-based ban	Allow Deny
Source IP address
Source geography
Source ASN
Rate limiting
JA3 fingerprints
Bot management
Layer 7 filtering
WAF
Adaptive Protection
Address Group
Threat Intelligence
Byte offset filtering
Security Command Center
Cloud Monitoring
Request logging

Backend security policies

Backend security policies are used with backend services exposed by the following load balancer types:

Global external Application Load Balancer
Classic Application Load Balancer
Regional external Application Load Balancer
Regional internal Application Load Balancer
Global external proxy Network Load Balancer
Classic proxy Network Load Balancer

They can be used to filter requests and protect backend services that reference instance groups or network endpoint groups (NEGs) including Internet, Zonal, Hybrid, and Serverless NEGs. Not all load balancers support all types of NEG. For more information about the NEGs that your load balancer supports, see the Network endpoint groups overview.

When using global external proxy Network Load Balancers or classic proxy Network Load Balancers, Google Cloud Armor enforces the security policy rule deny action only on new connection requests. The deny action terminates the TCP connection. In addition, if you provide a status code with your deny action, the status code is ignored.

Backend security policies have the optional type flag value CLOUD_ARMOR. If you don't set the type flag, the default value is CLOUD_ARMOR.

Edge security policies

Edge security policies enable users to configure filtering and access control policies for content that is stored in cache; this includes endpoints like Cloud CDN-enabled backend services and Cloud Storage buckets. Edge security policies support filtering based on a subset of parameters compared to backend security policies. You cannot set an edge security policy as a backend policy. Edge security policies are supported for the following endpoints:

Global external Application Load Balancer
Classic Application Load Balancer

Edge security policies can be configured to filter requests before the request is served from Google's cache. Edge security policies are deployed and enforced near the outermost perimeter of Google's network, upstream of where the Cloud CDN cache resides. Edge security policies can coexist with backend security policies to provide two layers of protection. They can be simultaneously applied to a backend service regardless of the resources that the backend service points to (for example, instance groups or network endpoint groups). Only edge security policies can be applied to backend buckets.

When edge security policies and backend security policies are attached to the same backend service, backend security policies are enforced only for cache miss requests that have passed edge security policies.

Edge security policies are evaluated and enforced before Identity-Aware Proxy (IAP). A request blocked by an edge security policy is denied before IAP evaluates the identity of the requestor. Blocking a request with a rule at the edge security policy prevents IAP from serving a sign-in page or otherwise attempting to authenticate the user.

Edge security policies have the type flag value CLOUD_ARMOR_EDGE.

Network edge security policies

Network edge security policies let you configure rules to block traffic at the edge of Google's network. Enforcing network edge security policies does not consume VM or host resources, which helps prevent high volume traffic from exhausting resources on the target workload or otherwise causing a denial of service. You can configure network edge security policies for the following resources:

External passthrough Network Load Balancers
Protocol forwarding
VMs with public IP addresses

Network edge security policies support filtering based on some of the same parameters as backend security policies, and are the only security policy type to support byte offset filtering. Refer to the Types of security policies table for a complete list of available parameters.

Network edge security policies have the type flag value CLOUD_ARMOR_NETWORK. To configure network edge security policies, you must first configure advanced network DDoS protection in the region in which you intend to create the policies. For more information about advanced DDoS protection, see Configure advanced network DDoS protection.

Rule evaluation order

Rule evaluation order is determined by rule priority, from the lowest number to the highest number. The rule with the lowest numeric value assigned has the highest logical priority and is evaluated prior to rules with lower logical priorities. The minimum numeric priority is 0. The priority of a rule decreases as its number increases (1, 2, 3, N+1). You cannot configure two or more rules with the same priority. The priority for each rule must be set to a number from 0 to 2147483646 inclusive. The priority value 2147483647, also known as INT-MAX, is reserved for the default rule.

Priority numbers can have gaps, which enable you to add or remove rules in the future without affecting the rest of the rules. For example, 1, 2, 3, 4, 5, 9, 12, 16 is a valid series of priority numbers to which you could add rules numbered from 6 to 8, 10 to 11, and 13 to 15 in the future. You don't need to change the existing rules except for the order of execution.

Typically, the highest priority rule that matches the request is applied. However, there is an exception when HTTP POST requests are evaluated against preconfigured rules that use evaluatePreconfiguredExpr(). The exception is as follows.

For HTTP POST requests, Google Cloud Armor receives the request's header before the body (payload). Because Google Cloud Armor receives the header information first, it evaluates rules that match against the header, but it does not match any preconfigured rules on the body. If there are multiple header-based rules, Google Cloud Armor evaluates them based on their priority as expected. Note that redirect actions and inserting custom header actions work only during the header processing phase. The redirect action, if matched during the following body processing phase, is translated to a deny action. The custom request header action, if matched during the body processing phase, doesn't take effect.

After Google Cloud Armor receives the HTTP POST body, it evaluates rules that apply to both the request headers and body. As a result, it's possible that lower priority rules that allow a request's header are matched before higher priority rules that block the request's body. In such cases, it is possible that the HTTP header portion of the request is sent to the target backend service, but the POST body containing potentially malicious content is blocked. Google Cloud Armor inspects the first 8KB of the POST body. For more information about this limitation, see POST body inspection limitation.

The evaluatePreconfiguredExpr() expression for preconfigured rules is the only expression that is evaluated against the request body. All other expressions are evaluated against the request header only. Among the HTTP request types with a request body, Google Cloud Armor processes only POST requests. The inspection is limited to the first 8 KB of the POST body and gets decoded like URL query parameters. Google Cloud Armor can parse and apply preconfigured WAF rules for JSON-formatted POST bodies (Content-Type = "application/json"). However, Google Cloud Armor does not support other HTTP Content-Type/Content-Encoding-based decoders such as XML, Gzip, or UTF-16.

Examples

In the following example, rules 1, 2, and 3 are evaluated in that order for the IP and HTTP header fields. However, if an IP 9.9.9.1 launches an XSS attack in the HTTP POST body, only the body is blocked (by rule 2); the HTTP header passes through to the backend (by rule 3).

Rule1
expr: inIPRange(origin.ip, '10.10.10.0/24')
action: deny(403)
priority: 1
Rule2
expr: evaluatePreconfiguredExpr('xss-stable')
action: deny(403)
priority: 2
Rule3
expr: inIPRange(origin.ip, '9.9.9.0/24')
action: allow
priority: 3
Rule-default
action: deny(403)
priority: INT-MAX

In the following example, the policy allows IP 9.9.9.1 without scanning against XSS attacks:

Rule1
expr: inIPRange(origin.ip, '10.10.10.0/24')
action: deny(403)
priority: 1
Rule2
expr: inIPRange(origin.ip, '9.9.9.0/24')
action: allow
priority: 2
Rule3
expr: evaluatePreconfiguredExpr('xss-stable')
action: deny(403)
priority: 3
Rule-default
action: allow
priority: INT-MAX

Default rule

Each Google Cloud Armor security policy contains a default rule that is matched if none of the higher priority rules are matched or if there are no other rules in the policy. The default rule is automatically assigned a priority of 2147483647 (INT-MAX), and it is always present in the security policy.

You cannot delete the default rule, but you can modify it. The default action for the default rule is deny, but you can change the action to allow.

Fingerprint

Each Google Cloud Armor security policy has a field fingerprint. The fingerprint is a hash of the contents stored in the policy. When you create a new policy, don't provide the value of this field. If you provide a value, it is ignored. However, when you update a security policy, you must specify the current fingerprint, which you get when you export or describe the policy (using EXPORT or DESCRIBE, respectively).

The fingerprint protects you from overriding another user's update. If the fingerprint that you provide is out of date, it means that the security policy was updated since you last retrieved the fingerprint. To check for any differences and to retrieve the latest fingerprint, run the DESCRIBE command.

Rules language and enforcement engine

The rules language and enforcement engine provide the following:

The ability to write custom rule expressions that can match on various Layer 3 through Layer 7 attributes of incoming requests. Google Cloud Armor provides a flexible language for writing custom match conditions.
The ability to combine up to 5 subexpressions in a single rule.
The ability to deny or allow requests based on the incoming request's region code. The region codes are based on the ISO 3166-1 alpha 2 codes. The region codes sometimes correspond to specific countries, but some encompass a country plus its associated areas. For example, the US code includes all states of the United States, one district, and six outlying areas.

Types of rules

Google Cloud Armor has the following types of rules.

IP address allowlist and denylist rules

You can create IP address allowlist and denylist rules within a security policy. Some examples include the following:

Denylisting for IP address/CIDR lets you block a source IP address or CIDR range from accessing supported load balancers.
Allowlisting for IP address/CIDR lets you allow a source IP address or CIDR range to access supported load balancers.
IPv4 and IPv6 addresses are supported in allowlist and denylist rules.
Deny rules can return an HTTP 403 (Unauthorized), 404 (Access Denied), or 502 (Bad Gateway) response.
Exceed action rules can return an HTTP 429 (Too Many Requests).

Source geography rules

You can allow or deny requests that originated from selected geographical areas that are defined by the Unicode country code.

Google Cloud Armor uses our own IP geolocation database to identify the request geography location. The database is updated regularly. While we can't guarantee a particular update cadence, during normal operations the mappings that Google Cloud Armor uses are updated approximately once a week.

Updated mappings must be propagated to Google's infrastructure globally. The rollout process happens gradually, usually over several days, across multiple zones and regions that Google Cloud Armor is deployed on. Because of this gradual rollout process, it's possible to see requests from the same source IP address being handled inconsistently during a rollout when the source IP address has a change on the geo-location mapping.

Preconfigured WAF rules

Google Cloud Armor provides a comprehensive list of preconfigured WAF rules based on the OWASP ModSecurity Core Rule Set (CRS) to help you detect the following:

SQL injection attacks
Cross-site scripting attacks
Local file inclusion attacks
Remote file inclusion attacks
Remote code execution attacks
Method enforcement attacks
Scanner detection attacks
Protocol attacks
PHP injection attacks
Session fixation attacks
Java attacks
NodeJS attacks

For details, see the Google Cloud Armor preconfigured WAF rules overview.

Bot management rules

You can use bot management rules to do the following:

Redirect requests for reCAPTCHA assessment with optional manual challenges.
Evaluate reCAPTCHA tokens attached with a request and apply the configured action based on token attributes.
Redirect requests to your configured alternative URL with a 302 response.
Insert custom headers to requests before proxying them to your backends.

For more information about bot management, see the bot management overview.

Preconfigured rules for named IP address lists

Preconfigured rules for named IP address lists provide the following:

Integrate third-party providers' named IP address lists with Google Cloud Armor.
Simplify maintenance of allowed or denied IP address ranges.
Synchronize third-party providers' lists daily.
Increase your capacity for configuring IP addresses and ranges in security policies because named IP address lists are not subject to limits on the number of IP addresses per rule.

Rate limiting rules

You can use rate limiting rules to do the following:

Throttle requests per client based on a threshold you configure.
Temporarily ban clients that exceed a request threshold that you set for a configured duration.

When you use rate limiting with global external proxy Network Load Balancers or classic proxy Network Load Balancers, the following restrictions apply:

Google Cloud Armor only enforces rate limiting actions like throttling or banning on new connection requests from clients.
Only the key types ALL and IP are supported.
If you attempt to use the key type HTTP-HEADER or HTTP-COOKIE with TCP/SSL load balancers, the key type is interpreted as ALL, and likewise XFF-IP is interpreted as IP.

For more information about rate limiting and how it works, see the Rate limiting overview.

Preview mode

You can preview the effects of a rule without enforcing it. In preview mode, actions are noted in Cloud Monitoring. You can choose to preview individual rules in a security policy, or you can preview every rule in the policy. You are charged the normal per-request fee for rules in preview mode.

You can enable preview mode for a rule by using the Google Cloud CLI and the --preview flag of gcloud compute security-policies rules update.

To disable preview mode, use the --no-preview flag. You can also use the Google Cloud console.

If a request triggers a preview, Google Cloud Armor will continue to evaluate other rules until finding a match. Both the matched and preview rule will be available in the logs.

Custom error responses

When you use a global external Application Load Balancer, you can configure custom error responses for HTTP status codes for errors that load balancers or backend instances generate. In addition, you can configure custom error codes for traffic that Google Cloud Armor denies by configuring custom response pages for the same 4xx series or 5xx series error codes that your existing security policy rules use.

For more information about custom error responses, see the Custom error response overview. For configuration steps, see Configure custom error responses.

Logging

Google Cloud Armor has extensive logging and lets you define how verbose your logging is. Google Cloud Armor logs are generated based on the first (highest priority) rule that matches an incoming request, whether or not the security policy is in preview mode. This means that logs are not generated for non-matching rules, nor for matching rules at lower priorities.

For complete information about logging, see Use request logging. For more information about verbose logging, see Verbose logging. To view Google Cloud Armor logs, see Viewing logs.

External Application Load Balancer request logging

Each HTTP(S) request that is evaluated against a Google Cloud Armor security policy is logged through Cloud Logging. The logs provide details such as the name of the applied security policy, the matching rule, and whether the rule was enforced. Request logging for new backend service resources is disabled by default. To ensure that Google Cloud Armor requests are logged, you must enable HTTP(S) logging for each backend service protected by a security policy.

For more information, see External Application Load Balancer logging and monitoring.

External proxy Network Load Balancer request logging

You can configure logging for external proxy Network Load Balancers by using the Google Cloud CLI commands as listed in TCP/SSL proxy load balancing logging and monitoring. You cannot enable logging for external proxy Network Load Balancers using the Google Cloud console.

Limitations

The following sections detail limitations for security policies.

POST and PATCH body inspection limitation

The evaluatePreconfiguredWaf() expression for preconfigured rules is the only expression that Google Cloud Armor evaluates against the request body. Among the HTTP request types with a request body, Google Cloud Armor processes only POST and PATCH requests.

The inspection is limited to the first 8 KB of the POST or PATCH body, which gets decoded like URL query parameters. The remainder of the request body might contain malicious code, which your application might accept. To mitigate the risk of request bodies whose size exceeds 8 KB, see the troubleshooting guide.

Google Cloud Armor can parse and apply preconfigured WAF rules for default URL-encoded and JSON-formatted POST and PATCH bodies (Content-Type = "application/json"), in which case rules are independently applied on the decoded names and values in the data. For other content types and encoding types, Google Cloud Armor does not decode the data, but applies the preconfigured rules on raw data.

How WebSocket connections are handled

Global external Application Load Balancers have built-in support for the WebSocket protocol. WebSocket channels are initiated from HTTP(S) requests. Google Cloud Armor can block a WebSocket channel from being established, for example, if an IP address denylist blocks the originating IP address. However, subsequent transactions in the channel don't conform to the HTTP protocol, and Google Cloud Armor does not evaluate any messages after the first request.