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 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 only for backend services of global external HTTP(S) load balancers, global external HTTP(S) load balancer (classic)s, external TCP proxy load balancers, or external SSL proxy load balancers. 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 Functions services
- Internet NEGs for external backends
- Buckets in Cloud Storage
When you use Google Cloud Armor to protect a hybrid deployment or a multi-cloud 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 TCP/UDP network load balancer, 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 global external HTTP(S) load balancer, global external HTTP(S) load balancer (classic)s, external TCP proxy load balancers, or external SSL proxy load balancers 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 HTTP(S) load balancers, global external HTTP(S) load balancer (classic)s, the Google network, and Google data centers.
These are the requirements for using Google Cloud Armor security policies:
- The load balancer must be an global external HTTP(S) load balancer, global external HTTP(S) load balancer (classic), external TCP proxy load balancer, or external SSL proxy load balancer.
- The backend service's load balancing scheme must be
EXTERNAL_MANAGEDif you are using global external HTTP(S) load balancer.
- The backend service's protocol must be one of
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 do not 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
Google Cloud Armor security policies have the following core features:
You can optionally use the
QUICprotocol 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 security policies with GKE and the default Ingress controller.
Types of security policies
The following table shows 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.
|Frontend Type||Global external HTTP(S) load balancer/Global external HTTP(S) load balancer (classic)||external TCP proxy load balancer/external SSL proxy load balancer||global external HTTP(S) load balancer/global external HTTP(S) load balancer (classic)|
|Attachment point (protected resource)||Backend service||Backend service||
|Source IP address||✔||✔||✔|
|Layer 7 filtering||✔|
|Named IP address lists||✔|
Backend security policies
Backend security policies are used with backend services exposed by an global external HTTP(S) load balancer, global external HTTP(S) load balancer (classic), External TCP Proxy Load Balancing, or External SSL Proxy Load Balancing. They can be used to filter requests and protect backend services that reference instance groups or network endpoint groups (NEGs) including internet, zonal, and serverless NEGs.
When using an external TCP proxy load balancer, Google Cloud Armor enforces the security policy
deny only on new connection requests. The
terminates the TCP connection. In addition, if you provide a status code with
deny action, the status code is ignored.
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 not supported for external TCP proxy load balancers or external SSL proxy load balancers.
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 at 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.
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
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
action. The custom request header action, if matched during the body
processing phase, will not 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
For more information about this limitation, see
POST body inspection limitation.
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
request types with a request body, Google Cloud Armor processes only
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.
In the following example, rules 1, 2, and 3 are evaluated in that order for the
HTTP header fields. However, if an
IP 18.104.22.168 launches an XSS
attack in the
HTTP POST body, only the body is blocked (by rule 2); the
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, '22.214.171.124/24') action: allow priority: 3 Rule-default action: deny(403) priority: INT-MAX
In the following example, the policy allows
IP 126.96.36.199 without scanning against
Rule1 expr: inIPRange(origin.ip, '10.10.10.0/24') action: deny(403) priority: 1 Rule2 expr: inIPRange(origin.ip, '188.8.131.52/24') action: allow priority: 2 Rule3 expr: evaluatePreconfiguredExpr('xss-stable') action: deny(403) priority: 3 Rule-default action: allow priority: INT-MAX
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
Each Google Cloud Armor security policy has a field
fingerprint is a hash of the contents stored in the policy. When you create a
new policy, do not 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
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
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 multiple 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
UScode 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 enables you to block a source IP address or CIDR range from accessing supported load balancers.
Allowlisting for IP address/CIDR enables you to allow a source IP address or CIDR range to access supported load balancers.
IPv4 and IPv6 addresses are supported in allowlist and denylist rules.
IP address rules can block or allow individual source IP addresses or CIDRs. Both IPv4 and IPv6 source addresses are supported.
Deny rules can return an HTTP
404(Access Denied), or
502(Bad Gateway) response.
Exceed action rules can return an HTTP
429(Too Many Requests).
Preconfigured rules for XSS, SQLi, LFI, RFI, and RCE
You can use preconfigured rules to mitigate the following attacks:
- Cross-site scripting (XSS)
- SQL injection (SQLi) attacks
- Local file inclusion (LFI) attacks
- Remote file inclusion (RFI) attacks
- Remote code execution (RCE) attacks
These rules are based on the OWASP Modsecurity core rule set version 3.0.2.
Bot management rules
You can use bot management rules to do the following:
- Redirect requests for reCAPTCHA Enterprise assessment with optional manual challenges.
- Evaluate reCAPTCHA Enterprise 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 external TCP proxy load balancers or external SSL proxy 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
IPare supported for External TCP Proxy Load Balancing and External SSL Proxy Load Balancing.
- If you attempt to use the key type
HTTP-COOKIEwith TCP/SSL load balancers, the key type is interpreted as
ALL, and likewise
XFF-IPis interpreted as
For more information about rate limiting and how it works, see the Rate limiting overview.
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 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, which is not currently
documented. 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.
Google Cloud Armor has extensive logging and lets you define how verbose your logging is. For complete information about logging, see Using request logging.
JSON parsing and verbose logging
By default, Google Cloud Armor does not parse the JSON content of POST bodies
when preconfigured WAF (web application firewall) rules are evaluated. This can
cause the WAF rules to be noisy and potentially generate false positive matches
on incoming requests if the protected workloads serve REST APIs or otherwise
receive requests with JSON in the POST Body
Content-Type = "application/json").
A noisy rule is triggered by requests that you would most likely consider to be
false positives. For example, a JSON request body such as
triggers the SQL injection rule
owasp-crs-v030001-id942431-sqli if JSON
parsing is not enabled.
We recommend that you enable JSON parsing if you expect your workload to receive
Content-Type = "application/json"—for example, if you are
serving REST APIs. By default, this option is disabled. The syntax for the flag
is as follows:
--json-parsing=[STANDARD | DISABLED]
The flag is available only with
gcloud compute security-policies update. You
cannot create a new security policy with this option unless you create a
security policy in a file and then import that file.
To reduce the noise and false positives, you can configure Google Cloud Armor to parse the JSON content of POST bodies. This means that Google Cloud Armor ignores structural characters of the JSON message in the POST body and looks only at the end-user-provided values in the JSON message. For more information about preconfigured WAF rules, see Tuning Google Cloud Armor WAF rules.
Additionally, you might not be able to tell why a preconfigured WAF rule was triggered by a particular request. Google Cloud Armor's default event logs contain the rule that was triggered, as well as the subsignature. However, you might need to identify the details from the incoming request that triggered the rule for troubleshooting, rule validation, or rule tuning purposes.
You can adjust the level of detail recorded in your logs. We recommend that you enable verbose logging only when you first create a policy, make changes to a policy, or troubleshoot a policy. If you enable verbose logging, it is in effect for rules in preview mode as well as active (non-previewed) rules during standard operations.
For more information about verbose logging, see Using request logging.
HTTP(S) Load Balancing 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.
To view Google Cloud Armor logs, see Viewing logs.
External TCP Proxy Load Balancing and External SSL Proxy Load Balancing request logging
You can configure External TCP Proxy Load Balancing and External SSL Proxy Load Balancing logging using the Google Cloud CLI commands as listed in HTTP(S) Load Balancing logging and monitoring. You cannot enable logging for External TCP Proxy Load Balancing and External SSL Proxy Load Balancing using the Google Cloud console.
The following sections detail limitations for security policies.
POST body inspection limitation
evaluatePreconfiguredExpr() 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
The inspection is limited to the first 8 KB of the POST body, which gets decoded like URL query parameters. The remainder of the POST body might contain malicious code, which your application might accept. To mitigate the risk of POST 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 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 HTTP(S) load balancer has 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 do not conform to the HTTP protocol, and Google Cloud Armor does not evaluate any messages after the first request.
- Configure security policies, rules, and expressions
- Learn about the features in Managed Protection tiers
- Learn about named IP address lists
- Troubleshoot issues