Security policy overview

This page describes how you can use Google Cloud Armor security policies to protect your Trusted Cloud by S3NS 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. 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.

Cloud Armor security policies are available for regional external Application Load Balancers.

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

When you use Cloud Armor to protect a hybrid deployment or a multicloud architecture, the backends must be internet NEGs or hybrid NEGs. Cloud Armor also protects serverless NEGs when traffic is routed through a load balancer. For information about how to route traffic through your load balancer before it reaches your serverless NEG, see Ingress controls.

Protect your Trusted Cloud deployments with Cloud Armor security policies

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.

Cloud Armor security policies enable you to allow, deny, rate-limit, or redirect requests to your backend services at the Trusted 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.

Requirements

These are the requirements for using Cloud Armor security policies:

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

About Cloud Armor security policies

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

A Cloud Armor security policy rule consists of a match condition and an action to take when that condition is met. For example, a condition can be 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 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, Cloud Armor allows, denies, or redirects the request, based on whether the rule is an allow rule, a deny rule, or a redirect rule.

Cloud Armor provides two categories of security policies: hierarchical security policies and service-level security policies. Hierarchical security policies are attached at the organization, folder, or project level, while service-level security policies are associated with one or more backend services. For more information about hierarchical security policies, see Hierarchical security policies overview.

A backend service can have two service-level security policies associated with it at the same time, but it can't have two backend security policies or two edge security policies at the same time. However, your backend services don't all need to be associated with the same security policies. To attach and remove security policies from supported backend services and features, see Attach and remove security policies.

If a 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 diagram, the Cloud Armor security policy internal-users-policy is associated with the backend service test-network.

Cloud Armor security policy at network edge.
Cloud Armor security policy at network edge (click to enlarge).
Cloud Armor security policies have the following features:

  • You can optionally use the QUIC protocol with load balancers that use Cloud Armor.

  • 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 regional external Application Load Balancers.

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 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 service-level security policies and what you can do with them. A check mark () indicates that the type of security policy supports the feature.

Backend security policies

Backend security policies are used with backend services exposed by Regional external Application Load Balancer.

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.

Internal service security policies

Internal service security policies let you configure fairshare rate limiting with Cloud Service Mesh. Rather than attaching an internal service security policy to a backend service or backend bucket, you attach it to a Cloud Service Mesh endpoint policy. To learn more about internal service security policies, see Configure rate limiting with Cloud Armor in the Cloud Service Mesh documentation.

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. These gaps let you 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 can 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 with a body are evaluated against preconfigured rules that use evaluatePreconfiguredWaf. The exception is as follows:

For HTTP POST requests, Cloud Armor receives the request's header before the body (payload). Because Cloud Armor receives the header information first, it evaluates rules that match against the header, but it doesn't match any preconfigured rules on the body. If there are multiple header-based rules, 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 Cloud Armor receives the HTTP POST request with a 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 body containing potentially malicious content is blocked. Cloud Armor inspects up to the first 64 kB (according to the configured inspection limit of either 8 kB, 16 kB, 32 kB, 48 kB, or 64 kB) of the request body. For more information about this limitation, see POST and PATCH body inspection limitation.

The evaluatePreconfiguredWaf() 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, Cloud Armor processes only POST and PATCH requests. The inspection is limited to the configured inspection limit, up to the first 64 kB (either 8 kB, 16 kB, 32 kB, 48 kB, or 64 kB) of the request body and gets decoded like URL query parameters. Cloud Armor can parse and apply preconfigured WAF rules for JSON-formatted POST bodies (Content-Type = "application/json"). However, Cloud Armor doesn't 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 address 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: evaluatePreconfiguredWaf('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: evaluatePreconfiguredWaf('xss-stable')
action: deny(403)
priority: 3
Rule-default
action: allow
priority: INT-MAX

Default rule

Each 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 can't 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 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. Cloud Armor provides a custom rules language attributes 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

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:

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

  • Adding an IP address or CIDR range to a denylist lets you block a source IP address or CIDR range from accessing supported load balancers.

  • Adding an IP address or CIDR range to an allowlist 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 status code.

  • Exceed action rules can return an HTTP 429 Too Many Requests status code.

Source geography rules

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

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 Cloud Armor uses are updated about once per 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 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 geolocation mapping for the source IP address has changed.

Preconfigured WAF rules

Cloud Armor provides a comprehensive list of preconfigured WAF rules based on the OWASP 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 Cloud Armor preconfigured WAF rules overview.

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:

  • 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.

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 the gcloud compute security-policies rules update command.

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

If a request triggers a preview, Cloud Armor continues to evaluate other rules until finding a match. Both the matched and preview rule are 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 Cloud Armor denies by configuring custom response pages for the same 4xx series or 5xx series status 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

Cloud Armor has extensive logging and lets you define how verbose your logging is. 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 aren't 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 Cloud Armor logs, see Viewing logs.

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 Cloud Armor evaluates against the request body. Among the HTTP request types with a request body, Cloud Armor processes only POST and PATCH requests.

The inspection is limited to the configured inspection limit, up to the first 64 kB (either 8 kB, 16 kB, 32 kB, 48 kB, or 64 kB) of the POST or PATCH body. To learn more about configuring the inspection limit for the request body when using preconfigured WAF rules, see Update inspection limit for pre-configured WAF rules.

The remainder of the request body might contain payloads that would match a WAF rule signature, which your application might accept. To mitigate the risk of request bodies whose size exceeds the configured inspection limit, up to the first 64 kB (either 8 kB, 16 kB, 32 kB, 48 kB, or 64 kB), see Mitigate risk on request body that exceeds configured inspection limit.

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, Cloud Armor doesn't 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. 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 Cloud Armor doesn't evaluate any messages after the first request.

What's next