Use these instructions to create Google Cloud Armor security policies to filter incoming traffic that is destined to global external HTTP(S) load balancers or global external HTTP(S) load balancer (classic)s. For conceptual information about security policies, see the Google Cloud Armor security policy overview.
For information about configuring Google Cloud Armor on Google Kubernetes Engine (GKE), see Google Cloud Armor security policy in the section Configuring Ingress features through BackendConfig parameters.
Before you begin
Before you configure security policies, do the following:
Make sure that you are familiar with HTTP(S) Load Balancing concepts.
Examine your existing backend services to determine which do not already have a security policy attached. These backend services and their associated backends are not protected by Google Cloud Armor. To add the protection that Google Cloud Armor provides, use the instructions in this document to attach a newly-created or existing security policy to the backend service.
Set up IAM permissions for Google Cloud Armor security policies
The following operations require the Identity and Access Management (IAM) role Compute Security Admin (roles/compute.securityAdmin):
- configuring, modifying, updating, and deleting a Google Cloud Armor security policy
- API methods allowed:
SecurityPolicies insert
SecurityPolicies delete
SecurityPolicies patch
SecurityPolicies addRule
SecurityPolicies patchRule
SecurityPolicies removeRule
A user with the Compute Network Admin role (roles/compute.networkAdmin) can perform the following operations:
- Setting a Google Cloud Armor security policy for a backend service
- API methods allowed:
BackendServices setSecurityPolicy
BackendServices list
(gcloud
only)
Users with the roles Security Admin and Network Admin can view
Google Cloud Armor security policies using the API methods
SecurityPolicies get
, list
, and getRule
.
Set up IAM permissions for custom roles
The following table lists the IAM roles' base permissions and their associated API methods.
IAM permission | API methods |
---|---|
compute.securityPolicies.create |
SecurityPolicies insert |
compute.securityPolicies.delete |
SecurityPolicies delete |
compute.securityPolicies.get |
SecurityPolicies get SecurityPolicies getRule |
compute.securityPolicies.list |
SecurityPolicies list |
compute.securityPolicies.use |
BackendServices setSecurityPolicy |
compute.securityPolicies.update |
SecurityPolicies patch SecurityPolicies addRule SecurityPolicies patchRule SecurityPolicies removeRule |
compute.backendServices.setSecurityPolicy |
BackendServices setSecurityPolicy |
Configure security policies for HTTP(S) Load Balancing
The following are the high-level steps for configuring Google Cloud Armor security policies to enable rules that allow or deny traffic to global external HTTP(S) load balancers or global external HTTP(S) load balancer (classic)s:
- Create a Google Cloud Armor security policy.
- Add rules to the security policy based on IP address lists, custom expressions, or preconfigured expression sets.
- Attach the security policy to a backend service of the global external HTTP(S) load balancer or global external HTTP(S) load balancer (classic) for which you want to control access.
- Update the security policy as needed.
In the following example, you create two Google Cloud Armor security policies and apply them to different backend services.
In the example, these are the Google Cloud Armor security policies:
mobile-clients-policy
applies to external users of yourgames
services.internal-users-policy
applies to your organization'stest-network
team.
You apply mobile-clients-policy
to the games
service, whose backend service
is called games
, and you apply internal-users-policy
to the internal test
service for the testing team, whose corresponding backend service is called
test-network
.
If the backend instances for a backend service are in multiple regions,
the Google Cloud Armor security policy associated with the service is
applicable to instances in all regions. In the preceding example, the
security policy mobile-clients-policy
is applicable
to instances 1, 2, 3, and 4 in us-central
and to instances 5 and 6 in
us-east
.
Create the example
Use these instructions to create the example configuration discussed in the previous section.
Console
Configure the security policy for external users:
In the Google Cloud console, go to the Network Security page.
On the Policies page, click Create policy.
In the Name field, enter
mobile-clients-policy
.In the Description field, enter
Policy for external users
.For Default rule action, select Deny.
For Deny status, select 404 (Not Found).
Click Next step.
Add more rules:
- Click Add rule.
- In the Description field, enter
allow traffic from 192.0.2.0/24
. - For Mode, select Basic mode (IP addresses/ranges only).
- In the Match field, enter
192.0.2.0/24
. - For Action, select Allow.
- In the Priority field, enter
1000
. - Click Done.
- Click Next step.
Apply policy to targets:
- Click Add Target.
- In the Target list, select a target.
- Click Done.
- Click Create policy.
Optionally, enable Adaptive Protection:
- To enable Adaptive Protection, check the Enable check box.
Configure the security policy for internal users:
- On the Policies page, click Create policy.
- In the Name field, enter
internal-users-policy
. - In the Description field, enter
Policy for internal test users
. - For Default rule action, select Deny.
- For Deny status, select 502 (Bad Gateway).
- Click Next step.
Add more rules:
- Click Add rule.
- In the Description field, enter
allow traffic from 198.51.100.0/24
. - For Mode, select Basic mode (IP addresses/ranges only).
- In the Match field, enter
198.51.100.0/24
. - For Action, select Allow.
- For Preview only, select the Enable checkbox.
- In the Priority field, enter
1000
. - Click Done.
- Click Next step.
Apply policy to targets:
- Click Add Target.
- In the Target list, select a target.
- Click Done.
- Click Create policy.
gcloud
Create the Google Cloud Armor security policies:
gcloud compute security-policies create mobile-clients-policy \ --description "policy for external users"
gcloud compute security-policies create internal-users-policy \ --description "policy for internal test users"
Update the default rules to the security policies to deny traffic:
gcloud compute security-policies rules update 2147483647 \ --security-policy mobile-clients-policy \ --action "deny-404"
gcloud compute security-policies rules update 2147483647 \ --security-policy internal-users-policy \ --action "deny-502"
Add rules to the security policies:
gcloud compute security-policies rules create 1000 \ --security-policy mobile-clients-policy \ --description "allow traffic from 192.0.2.0/24" \ --src-ip-ranges "192.0.2.0/24" \ --action "allow"
gcloud compute security-policies rules create 1000 \ --security-policy internal-users-policy \ --description "allow traffic from 198.51.100.0/24" \ --src-ip-ranges "198.51.100.0/24" \ --action "allow"
Attach the security policies to the backend services:
gcloud compute backend-services update games \ --security-policy mobile-clients-policy
gcloud compute backend-services update test-network \ --security-policy internal-users-policy
Optionally, enable Adaptive Protection:
gcloud compute security-policies update mobile-clients-policy \ --enable-layer7-ddos-defense
gcloud compute security-policies update internal-users-policy \ --enable-layer7-ddos-defense
Configure security policies, rules, and expressions
You can configure Google Cloud Armor security policies, rules, and expressions
by using the Google Cloud console, the Google Cloud CLI, or the REST API. When you
use the gcloud CLI to create security policies, use the --type
flag to specify whether the security policy is a backend security policy or an
edge security policy.
Test security policies
We recommend that you deploy all new rules in preview mode, then examine your request logs, to verify that the policies and rules are behaving as expected.
Sample expressions
The following are sample expressions. For more information about expressions, see the Google Cloud Armor custom rules language reference.
If you are configuring a rule or expression that uses ISO 3166-1 alpha 2 country or region codes, Google Cloud Armor treats each code independently. Google Cloud Armor rules and expressions explicitly use those region codes to allow or deny requests.
The following expression matches against requests from the IP address
1.2.3.4
and contains the stringGodzilla
in the user-agent header:inIpRange(origin.ip, '1.2.3.4/32') && has(request.headers['user-agent']) && request.headers['user-agent'].contains('Godzilla')
The following expression matches against requests that have a cookie with a specific value:
has(request.headers['cookie']) && request.headers['cookie'].contains('cookie_name=cookie_value')
The following expression matches against requests from the region
AU
:origin.region_code == 'AU'
The following expression matches against requests from the region
AU
that are not in the specified IP range:origin.region_code == "AU" && !inIpRange(origin.ip, '1.2.3.0/24')
The following expression matches against requests with a numbered variable path to a specific file if the URI matches a regular expression:
request.path.matches('/path/[0-9]+/target_file.html')
The following expression matches against requests if the Base64 decoded value of the
user-id
header contains a specific value:has(request.headers['user-id']) && request.headers['user-id'].base64Decode().contains('myValue')
The following expression uses a preconfigured expression set match against SQLi attacks:
evaluatePreconfiguredExpr('sqli-stable')
Use JSON parsing
You can enable or disable parsing of the JSON body content of POST requests for
each security policy. When the Content-Type
header is set to
application/json
, use the --json-parsing
flag in the Google Cloud CLI.
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. For more information, see
Importing security policies.
For more information about JSON parsing, see JSON parsing and verbose logging.
Use verbose logging
You can configure the Google Cloud Armor logging level to enable more detailed
logging for each security policy by using the --log-level
flag in the
gcloud CLI.
By default, this option is disabled. The syntax for the flag is as follows:
--log-level=[NORMAL | VERBOSE]
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. For more information, see
Importing security policies.
For more information about verbose logging, see JSON parsing and verbose logging.
Configure rules for rate limiting
This section contains information about configuring Google Cloud Armor rules to enforce per-client rate limits by configuring a throttle or rate-based ban action.
Rules for rate-based throttling
Rules for rate-based throttling have the following format in the gcloud CLI:
gcloud compute security-policies rules create PRIORITY --security-policy=SECURITY_POLICY (--expression=EXPRESSION | --src-ip-ranges=SRC_IP_RANGE) --action "throttle" --rate-limit-threshold-count=RATE_LIMIT_THRESHOLD_COUNT --rate-limit-threshold-interval-sec=RATE_LIMIT_THRESHOLD_INTERVAL_SEC --conform-action=[allow] --exceed-action=[deny-403|deny-404|deny-429|deny-502|redirect] --exceed-redirect-type=[google-recaptcha|external-302] --exceed-redirect-target=REDIRECT_URL --enforce-on-key=[IP | ALL | HTTP-HEADER | XFF-IP | HTTP-COOKIE | HTTP-PATH | SNI | REGION-CODE] --enforce-on-key-name=[HTTP_HEADER_NAME|HTTP_COOKIE_NAME]
For example, the following gcloud
command creates a throttle
rule at
priority 105
with a rate limit of 100 requests each 60 seconds for each IP
address in 1.2.3.0/24
. Requests that exceed the throttling limit return a
429
error code.
gcloud compute security-policies rules create 105 \ --security-policy sec-policy \ --src-ip-ranges="1.2.3.0/24" \ --action=throttle \ --rate-limit-threshold-count=100 \ --rate-limit-threshold-interval-sec=60 \ --conform-action=allow \ --exceed-action=deny-429 \ --enforce-on-key=IP
For example, the following gcloud
command creates a throttle
rule at
priority 110
with a rate limit of 10 requests each 60 seconds for each unique
value of the HTTP header User-Agent
across all requests coming from IP
addresses in 1.2.3.0/24
. Requests that exceed the throttling limit return a
429
error code.
gcloud compute security-policies rules create 110 \ --security-policy sec-policy \ --src-ip-ranges="1.2.3.0/24" \ --action=throttle \ --rate-limit-threshold-count=10 \ --rate-limit-threshold-interval-sec=60 \ --conform-action=allow \ --exceed-action=deny-429 \ --enforce-on-key=HTTP-HEADER \ --enforce-on-key-name='User-Agent'
You can also issue rate-based bans for users who have a valid reCAPTCHA
exemption cookie. For example, the following gcloud
command creates a
throttle
rule at priority 115
with a rate limit of 20 requests per 5 minutes
for each unique reCAPTCHA exemption cookie across all requests that have a
valid reCAPTCHA exemption cookie. Requests that exceed the throttling limit are
redirected for reCAPTCHA Enterprise assessment. For more information about
exemption cookies and reCAPTCHA Enterprise assessment, see the
bot management overview.
gcloud compute security-policies rules create 115 \ --security-policy sec-policy \ --expression="token.recaptcha_exemption.valid" \ --action=throttle \ --rate-limit-threshold-count=20 \ --rate-limit-threshold-interval-sec=300 \ --conform-action=allow \ --exceed-action=redirect \ --exceed-redirect-type=google-recaptcha \ --enforce-on-key=HTTP-COOKIE \ --enforce-on-key-name="recaptcha-ca-e"
Rules for rate-based bans
Rules for rate-based bans have the following format in the gcloud CLI:
gcloud compute security-policies rules create PRIORITY \ --security-policy=SECURITY_POLICY \ (--expression=EXPRESSION | --src-ip-ranges=SRC_IP_RANGE) \ --action "rate-based-ban" \ --rate-limit-threshold-count=RATE_LIMIT_THRESHOLD_COUNT \ --rate-limit-threshold-interval-sec=RATE_LIMIT_THRESHOLD_INTERVAL_SEC \ --ban-duration-sec=BAN_DURATION_SEC \ --ban-threshold-count=BAN_THRESHOLD_COUNT \ --ban-threshold-interval-sec=BAN_THRESHOLD_INTERVAL_SEC \ --conform-action=[allow] \ --exceed-action=[deny-403|deny-404|deny-429|deny-502|redirect] --exceed-redirect-type=[google-recaptcha|external-302] --exceed-redirect-target=REDIRECT_URL --enforce-on-key=[IP | ALL | HTTP-HEADER | XFF-IP | HTTP-COOKIE | HTTP-PATH | SNI | REGION-CODE] --enforce-on-key-name=[HTTP_HEADER_NAME|HTTP_COOKIE_NAME]
For example, the following gcloud
command creates a rate-based ban rule at
priority 100 for each IP address whose requests match a header fish
with value
tuna
and ban it for 300 seconds when its rate exceeds a limit of 50 requests
for each 120 seconds. Banned requests return an error code of 404
.
gcloud compute security-policies rules create 100 \ --security-policy=sec-policy \ --expression="request.headers['fish'] == 'tuna'" \ --action=rate-based-ban \ --rate-limit-threshold-count=50 \ --rate-limit-threshold-interval-sec=120 \ --ban-duration-sec=300 \ --conform-action=allow \ --exceed-action=deny-404 \ --enforce-on-key=IP
For example, the following gcloud
command creates a rate-based ban rule at
priority 101 to limit all requests whose region code matches US
to 10 requests
per 60 seconds. The rule also bans requests from the US
region for 300 seconds
when their rate exceeds a limit of 1000 requests per 600 seconds. Banned
requests return an error code of 403
.
gcloud compute security-policies rules create 101 \ --security-policy sec-policy \ --expression "origin.region_code == 'US'" \ --action rate-based-ban \ --rate-limit-threshold-count 10 \ --rate-limit-threshold-interval-sec 60 \ --ban-duration-sec 300 \ --ban-threshold-count 1000 \ --ban-threshold-interval-sec 600 \ --conform-action allow \ --exceed-action deny-403 \ --enforce-on-key ALL
For example, the following gcloud
command creates a rate-based ban rule at
priority 102 to limit all requests from any source IP address range to 20 requests per
60 seconds. The rule also bans requests from any source IP address range for 600 seconds
when their rate exceeds a limit of 500 requests per 400 seconds. Banned requests
return an error code of 429
.
gcloud compute security-policies rules create 102 \ --security-policy sec-policy \ --src-ip-ranges="*" \ --action rate-based-ban \ --rate-limit-threshold-count 20 \ --rate-limit-threshold-interval-sec 60 \ --ban-duration-sec 600 \ --ban-threshold-count 500 \ --ban-threshold-interval-sec 400 \ --conform-action allow \ --exceed-action deny-429 \ --enforce-on-key ALL
Use the Google Cloud console and the gcloud CLI to create security policies
The instructions in this section assume that you are configuring security policies to apply to an existing global external HTTP(S) load balancer or global external HTTP(S) load balancer (classic) and backend service. For an example of how to complete the fields, see Creating the example.
Console
Create Google Cloud Armor security policies and rules and attach a security policy to a backend service:
In the Google Cloud console, go to the Network Security page.
On the Policies page, click Create policy.
In the Name field, enter the name of your policy.
Optional: Enter a description of the policy.
For Policy type choose Backend security policy or Edge security policy.
For Default rule action, select Allow for a default rule that permits access, or select Deny for a default rule that forbids access to an IP address or IP address range.
The default rule is the lowest priority rule that takes effect only if no other rule applies.
If you are configuring a Deny rule, select a Deny status message. This is the error message that Google Cloud Armor displays if a user without access tries to gain access.
Regardless of the type of rule that you are configuring, click Next step.
Add more rules:
- Click Add rule.
- Optional: Enter a description for the rule.
Select the mode:
- Basic mode: allow or deny traffic based on IP addresses or IP ranges.
- Advanced mode: allow or deny traffic based on rule expressions.
In the Match field, specify the conditions under which the rule applies:
- Basic mode: enter IP addresses or IP ranges to match in the rule.
- Advanced mode: enter an expression or subexpressions to evaluate against incoming requests. For information about how to write the expressions, see the custom rules language reference.
For Action, select Allow or Deny to allow or deny traffic if the rule matches.
To enable preview mode, select the Enable checkbox. In preview mode, you can see how the rule behaves, but the rule is not enabled.
Enter the rule's Priority. This can be any positive integer from 0 to 2,147,483,646 inclusive. For more information about the evaluation order, see Rule evaluation order.
Click Done.
To add more rules, click Add rule and repeat the previous steps. Otherwise, click Next step.
Apply policy to targets:
- Click Add Target.
- In the Target list, select a target.
- To add more targets, click Add Target.
- Click Done.
- Click Create policy.
gcloud
To create a new Google Cloud Armor security policy, use the command
gcloud compute security-policies create
. ReplaceNAME
andDESCRIPTION
with the name and description of the security policy. In thetype
field, useCLOUD_ARMOR
to create a backend security policy orCLOUD_ARMOR_EDGE
to create an edge security policy. Thetype
flag is not a required flag; if no type is specified, a backend security policy is created by default:gcloud compute security-policies create NAME \ [--type=CLOUD_ARMOR|CLOUD_ARMOR_EDGE] \ [--file-format=FILE_FORMAT | --description=DESCRIPTION] \ [--file-name=FILE_NAME]
The following command updates a policy that you previously created, turns JSON parsing on, and changes the log level to
VERBOSE
:gcloud compute security-policies update my-policy \ --json-parsing=STANDARD --log-level=VERBOSE
To add rules to a security policy, use the command
gcloud compute security-policies rules create PRIORITY
. ReplacePRIORITY
with the priority assigned to the rule in the policy. For information about how rule priority works, see Rule evaluation order.gcloud compute security-policies rules create PRIORITY \ [--security-policy POLICY_NAME] \ [--description DESCRIPTION] \ --src-ip-ranges IP_RANGE,... | --expression EXPRESSION \ --action=[ allow | deny-403 | deny-404 | deny-502 ] \ [--preview]
For example, the following command adds a rule to block traffic from IP address ranges 192.0.2.0/24 and 198.51.100.0/24. The rule has priority 1000, and it is a rule in a policy called
my-policy
.gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --description "block traffic from 192.0.2.0/24 and 198.51.100.0/24" \ --src-ip-ranges "192.0.2.0/24","198.51.100.0/24" \ --action "deny-403"
With the
--preview
flag added, the rule is added to the policy, but not enforced, and any traffic that triggers the rule is only logged.gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --description "block traffic from 192.0.2.0/24 and 198.51.100.0/24" \ --src-ip-ranges "192.0.2.0/24","198.51.100.0/24" \ --action "deny-403" \ --preview
Use the
--expression
flag to specify a custom condition in the custom rules language reference. The following command adds a rule to allow traffic from the IP address1.2.3.4
and contains the stringGodzilla
in the user-agent header:gcloud beta compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "inIpRange(origin.ip, '1.2.3.4/32') && has(request.headers['user-agent']) && request.headers['user-agent'].contains('Godzilla')" \ --action allow \ --description "Block User-Agent 'Godzilla'"
The following command adds a rule to block requests if the request's cookie contains a specific value:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "has(request.headers['cookie']) && request.headers['cookie'].contains('cookie_name=cookie_value')" \ --action "deny-403" \ --description "Cookie Block"
The following command adds a rule to block requests from the region
AU
:gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "origin.region_code == 'AU'" \ --action "deny-403" \ --description "AU block"
The following command adds a rule to block requests from the region
AU
that are not in the specified IP range:gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "origin.region_code == 'AU' && !inIpRange(origin.ip, '1.2.3.0/24')" \ --action "deny-403" \ --description "country and IP block"
The following command adds a rule to block requests with a URI that matches a regular expression:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "request.path.matches('/bad_path/')" \ --action "deny-403" \ --description "regex block"
The following command adds a rule to block requests if the Base64 decoded value of the
user-id
header contains a specific value:gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "has(request.headers['user-id']) && request.headers['user-id'].base64Decode().contains('myValue')" \ --action "deny-403" \ --description "country and IP block"
The following command adds a rule that uses a preconfigured expression set to mitigate SQLi attacks:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "evaluatePreconfiguredExpr('sqli-stable')" \ --action "deny-403"
The following command adds a rule that uses a preconfigured expression to allow access from all IP addresses on a named IP address list:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "evaluatePreconfiguredExpr('sourceiplist-fastly')" \ --action "allow"
Configure rules for bot management
This section contains information about configuring Google Cloud Armor security policy rules for bot management. For more information, see the bot management overview.
Use a reCAPTCHA Enterprise manual challenge to distinguish between human or automated clients
To associate or disassociate your own reCAPTCHA WAF site key with a security policy, use the following command, replacing the security policy name (SECURITY_POLICY) and reCAPTCHA WAF challenge site key (SITE_KEY) as appropriate.
gcloud compute security-policies update SECURITY_POLICY \ --recaptcha-redirect-site-key SITE_KEY
The following example associates a reCAPTCHA WAF site key with a security policy. The associated site key applies to all the rules using the manual challenge feature under the given security policy.
gcloud compute security-policies update my-policy \ --recaptcha-redirect-site-key "SITE_KEY"
You can also disassociate a reCAPTCHA WAF site key with a security policy as follows:
gcloud compute security-policies update my-policy \ --recaptcha-redirect-site-key ""
To create a rule to internally redirect traffic for reCAPTCHA Enterprise
assessment, use the following format in gcloud
:
gcloud compute security-policies rules create PRIORITY \ --security-policy SECURITY_POLICY \ (--expression EXPRESSION | --src-ip-ranges SRC_IP_RANGE) \ --action redirect \ --redirect-type google-recaptcha
The following example creates a rule that redirects traffic attempting to reach
/login.html
for reCAPTCHA Enterprise manual challenge.
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "request.path.matches(\"/login.html\")" \ --action redirect \ --redirect-type google-recaptcha
Enforce reCAPTCHA Enterprise frictionless assessment
Before you proceed, see the bot management overview for prerequisites on using reCAPTCHA Enterprise action-tokens or session-tokens.
You can use token.recaptcha_action.ATTRIBUTE
(replacing ATTRIBUTE with a valid token
attribute in the Google Cloud Armor
rules language) to extract
attributes from a reCAPTCHA Enterprise action-token. Similarly, you can use
token.recaptcha_session.ATTRIBUTE
for a
reCAPTCHA Enterprise session-token. For more information on the syntax of
available reCAPTCHA Enterprise token attributes, see the
rules language reference.
The following example creates a rule that allows traffic targeting for
/login.html
and with a reCAPTCHA Enterprise action-token whose score is
no less than 0.8
.
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "request.path.matches(\"/login.html\") && token.recaptcha_action.score >= 0.8" \ --action allow
Redirect (302 response)
To create a rule to redirect traffic to a user-configured URL, use the
following format in gcloud
.
gcloud compute security-policies rules create PRIORITY \ --security-policy SECURITY_POLICY \ (--expression EXPRESSION | --src-ip-ranges SRC_IP_RANGE) \ --action redirect \ --redirect-type external-302 \ --redirect-target REDIRECT_URL
The following example creates a rule that redirects traffic coming from 10.10.10.0/24 to https://www.example.com.
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --src-ip-ranges "10.10.10.0/24" \ --action redirect \ --redirect-type external-302 \ --redirect-target "https://www.example.com"
Decorate request
To create a rule that allows traffic but adds custom headers and user-defined
static values before proxying them to protected backends, use the following
format in gcloud
:
gcloud compute security-policies rules create PRIORITY \ --security-policy SECURITY_POLICY \ (--expression EXPRESSION | --src-ip-ranges SRC_IP_RANGE) \ --action allow \ --request-headers-to-add HEADER_1=VALUE_1,HEADER_2=VALUE_2,...
The following example creates a rule that allows but adds a custom header for
traffic targeting for /login.html
and with a reCAPTCHA Enterprise
action-token score lower than 0.2
.
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "request.path.matches("/login.html") && token.recaptcha_action.score < 0.2" \ --action allow \ --request-headers-to-add "reCAPTCHA-Warning=high"
Use Adaptive Protection
Adaptive Protection is applied on a per-security-policy basis.
Console
To activate Adaptive Protection for a security policy:
In the Google Cloud console, go to the Network Security page.
On the Policies page, click the name of a security policy.
Click Edit.
Under Adaptive Protection, select Enable.
Click Update.
To deactivate Adaptive Protection for a security policy:
In the Google Cloud console, go to the Network Security page.
On the Policies page, click the name of a security policy.
Click Edit.
Under Adaptive Protection, deselect Enable.
Click Update.
gcloud
To activate Adaptive Protection for a security policy:
gcloud compute security-policies update MY-SECURITY-POLICY \ --enable-layer7-ddos-defense
To deactivate Adaptive Protection for a security policy:
gcloud compute security-policies update MY-SECURITY-POLICY \ --no-enable-layer7-ddos-defense
List available preconfigured rules
List preconfigured rules to view the predefined application protection rules and signatures such as the ModSecurity Core Rule Set that Google Cloud Armor provides. These preconfigured rules contain multiple built-in signatures that Google Cloud Armor uses to evaluate against incoming requests. You add these preconfigured rules to new or existing rules by using the custom rules language reference.
For more information, see preconfigured rules.
gcloud
Run the
gcloud compute security-policies list-preconfigured-expression-sets
command:gcloud compute security-policies list-preconfigured-expression-sets
The follow example shows the form of the output from the command:
EXPRESSION_SET expression-set-1 RULE_ID SENSITIVITY expression-set-1-id-1 sensitivity-value-1 expression-set-1-id-2 sensitivity-value-2 expression-set-2 alias-1 RULE_ID SENSITIVITY expression-set-2-id-1 sensitivity-value-1 expression-set-2-id-2 sensitivity-value-2
The follow example includes a sample of the actual output from the command. Note that the actual output would include all of the rules that are listed in Tuning Google Cloud Armor WAF rules.
gcloud compute security-policies list-preconfigured-expression-sets
EXPRESSION_SET sqli-canary RULE_ID SENSITIVITY owasp-crs-v030001-id942110-sqli 2 owasp-crs-v030001-id942120-sqli 2 … xss-canary RULE_ID SENSITIVITY owasp-crs-v030001-id941110-xss 1 owasp-crs-v030001-id941120-xss 1 … sourceiplist-fastly sourceiplist-cloudflare sourceiplist-imperva
List security policies
Use these instructions to list all Google Cloud Armor security policies in the current project or in a project that you specify.
Console
In the Google Cloud console, go to the Network Security page.
To view a particular policy, on the Security policies page, in the list of policies, click its name.
gcloud
gcloud compute security-policies list
For example:
gcloud compute security-policies list
NAME my-policy
For more information, see
gcloud compute security-policies list
.
Update security policies
Use these instructions to update a Google Cloud Armor security policy. For example, you can modify the policy's description, modify the default rule's behavior, change the target backend service, or add new rules.
Console
In the Google Cloud console, go to the Network Security page.
To update a particular policy, on the Security policies page, in the list of policies, click
Menu for the policy that you want to update.- To update the policy description of the default rule action, select Edit, make the desired changes, and then click Update.
- To add a rule, select Add rule, and then follow the instructions in Adding rules to a security policy.
- To change the target backend service for the policy, select Apply policy to target, click Add Target, select a target, and then click Add.
gcloud
To update a security policy, use the following Google Cloud CLI instructions:
- To update a rule in a security policy, see Updating a single rule in a security policy.
- To add a rule to a security policy, see Adding rules to a security policy.
- To delete a rule from a security policy, see Deleting rules from a security policy.
- To update multiple rules in a single update (atomic update), see Atomically updating multiple rules in a security policy.
- To update non-rule fields in a security policy (such as the description field), see Exporting security policies and Importing security policies.
Export security policies
You can export a Google Cloud Armor security policy as a YAML or JSON file by using the Google Cloud CLI. Exporting a policy enables you to retrieve a copy of it that you can modify or save in source control.
gcloud
In the following command,
NAME
is the name of the security policy. Valid file formats are YAML and JSON. If you do not provide the file format, Google Cloud Armor uses the default YAML.gcloud compute security-policies export NAME \ --file-name FILE_NAME \ --file-format FILE_FORMAT
The following example exports the
my-policy
security policy to themy-file
file in the YAML format:gcloud compute security-policies export my-policy \ --file-name my-file \ --file-format yaml
The following example shows an exported security policy:
description: my description fingerprint: PWfLGDWQDLY= id: '123' name: my-policy rules: - action: allow description: default rule match: config: srcIpRanges: - '*' versionedExpr: SRC_IPS_V1 preview: false priority: 2147483647 selfLink: https://www.googleapis.com/compute/v1/projects/my-project/global/securityPolicies/my-policy
You can modify the exported file with any text editor, and then import it back to Google Cloud by using the
import
command.
Import security policies
You can import Google Cloud Armor security policies from a YAML or JSON file
by using the Google Cloud CLI. You can't use the import
command to update an
existing policy's rules. Instead, you must update rules one-by-one by using the
Updating a single rule in a security policy procedure, or all
at once by using the
Atomically updating multiple rules in a security policy procedure.
gcloud
To import security policies, use the
gcloud compute security-policies import NAME
command.
Replace NAME
with the name of the security policy that
you are importing. If you do not provide the file format, the correct format
is assumed based on the file structure. If the structure is invalid, you
see an error.
gcloud compute security-policies import NAME \ --file-name FILE_NAME \ [--file-format FILE_FORMAT]
For example, the following command updates the policy my-policy
by
importing the file my-file
.
gcloud compute security-policies import my-policy \ --file-name my-file \ --file-format json
If the policy's
fingerprint is out of
date when you import it, Google Cloud Armor shows an error. This means
that the policy has been modified since you last exported it. To fix this,
use the describe
command on the policy to get the latest fingerprint.
Merge any differences between the described policy and your policy, and
then replace the outdated fingerprint with the latest one.
Delete security policies
Use these instructions to delete a Google Cloud Armor security policy. You must remove all backend services from the policy before you can delete it.
Console
In the Google Cloud console, go to the Network Security page.
On the Security policies page, next to the name of the security policy that you want to delete, select the checkbox.
In the upper-right corner of the page, click
Delete.
gcloud
Use gcloud compute security-policies delete NAME
.
Replace NAME
with the name of the security policy:
gcloud compute security-policies delete NAME
Attach a security policy to a backend service
Use these instructions to attach a Google Cloud Armor security policy to a backend service. A security policy can be attached to more than one backend service, but a backend service can have only one of each type of security policy attached to it.
Console
In the Google Cloud console, go to the Network Security page.
On the Security policies page, click the name of the security policy. The Policy details page is displayed.
In the middle of the page, click the Targets tab.
Click Apply policy to new target.
Click Add Target.
In the Target list, select a target, and then click Add.
gcloud
When you attach a backend security policy to a backend service, use the
gcloud compute backend-services
command and the --security-policy
flag:
gcloud compute backend-services update my-backend \ --security-policy my-policy
When you attach an edge security policy to a backend service, use the
gcloud compute backend-services
command and the
--edge-security-policy
flag:
gcloud compute backend-services update my-backend \ --edge-security-policy my-policy
Remove a security policy from a backend service
Use these instructions to remove a Google Cloud Armor backend security policy or edge security policy from a backend service.
Console
In the Google Cloud console, go to the Network Security page.
On the Security policies page, click the name of the security policy. The Policy details page is displayed.
In the middle of the page, click the Targets tab.
Select the target backend service from which you are removing the policy.
Click Remove.
In the Remove target message, click Remove.
gcloud
When you remove a backend security policy, use the gcloud compute
backend-services
command and the --security-policy
flag:
gcloud compute backend-services update my-backend \ --security-policy ""
When you remove an edge security policy, use the gcloud compute
backend-services
command and the --edge-security-policy
flag:
gcloud compute backend-services update my-backend \ --edge-security-policy ""
Attach a security policy to a backend bucket
Use these instructions to attach a Google Cloud Armor edge security policy to a backend bucket. An edge security policy can be attached to more than one backend bucket.
Console
In the Google Cloud console, go to the Network Security page.
On the Security policies page, click the name of the security policy. The Policy details page is displayed.
In the middle of the page, click the Targets tab.
Click Apply policy to new target.
Click Add Target.
In the Target list, select a target, and then click Add.
gcloud
When you attach an edge security policy to a backend bucket, use the
cloud compute backend-buckets
command and the
--edge-security-policy
flag:
gcloud compute backend-services update my-bucket \ --edge-security-policy my-edge-policy
Remove a security policy from a backend bucket
Use these instructions to remove a Google Cloud Armor edge security policy from a backend bucket.
Console
In the Google Cloud console, go to the Network Security page.
On the Security policies page, click the name of the security policy. The Policy details page is displayed.
In the middle of the page, click the Targets tab.
Select the target backend service from which you are removing the policy.
Click Remove.
In the Remove target message, click Remove.
gcloud
When you remove an edge security policy from a backend bucket, use the
cloud compute backend-buckets
command and the
--edge-security-policy
flag:
gcloud compute backend-services update my-bucket \ --edge-security-policy ""
Add rules to a security policy
Use these instructions to add rules to a Google Cloud Armor security policy.
Console
In the Google Cloud console, go to the Network Security page.
On the Security policies page, click the name of the security policy. The Policy details page is displayed.
In the middle of the page, click the Rules tab.
Click Add rule.
Optional: Enter a description of the rule.
Select the mode:
- Basic mode: allow or deny traffic based on IP addresses or IP ranges.
- Advanced mode: allow or deny traffic based on rule expressions.
In the Match field, specify the conditions under which the rule applies:
- Basic mode: enter from one (1) to five (5) IP address ranges to match in the rule.
Advanced mode: enter an expression or subexpressions to evaluate against incoming requests. For information about how to write the expressions and read the following examples, see the custom rules language reference.
The following expression matches against requests from the IP address
1.2.3.4
and contains the stringGodzilla
in the user-agent header:inIpRange(origin.ip, '1.2.3.4/32') && has(request.headers['user-agent']) && request.headers['user-agent'].contains('Godzilla')
The following expression matches against requests that have a cookie with a specific value:
has(request.headers['cookie']) && request.headers['cookie'].contains('cookie_name=cookie_value')
The following expression matches against requests from the region
AU
:origin.region_code == 'AU'
The following expression matches against requests from the region
AU
that are not in the specified IP range:origin.region_code == "AU" && !inIpRange(origin.ip, '1.2.3.0/24')
The following expression matches against requests if the URI matches a regular expression:
request.path.matches('/bad_path/')
The following expression matches against requests if the Base64 decoded value of the
user-id
header contains a specific value:has(request.headers['user-id']) && request.headers['user-id'].base64Decode().contains('myValue')
The following expression uses a preconfigured expression set to match against SQLi attacks:
evaluatePreconfiguredExpr('sqli-stable')
For Action, select Allow or Deny.
If you are configuring a deny rule, select a Deny status message.
If you want to enable preview mode for the rule, select the Enable checkbox.
In the Priority field, enter a positive integer.
Click Add.
gcloud
Use the command
gcloud compute security-policies rules create PRIORITY
.
Replace PRIORITY
with the priority of the rule in the
policy:
gcloud compute security-policies rules create PRIORITY \ --security-policy POLICY_NAME \ --description DESCRIPTION \ --src-ip-ranges IP_RANGES | --expression EXPRESSION \ --action=[ allow | deny-403 | deny-404 | deny-502 ] \ --preview
For example, the following command adds a rule to block traffic from IP
address ranges 192.0.2.0/24 and 198.51.100.0/24. The rule has priority
1000 and is a rule in a policy called my-policy
:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --description "block traffic from 192.0.2.0/24 and 198.51.100.0/24" \ --src-ip-ranges "192.0.2.0/24","198.51.100.0/24" \ --action "deny-403"
Use the --expression
flag to specify a condition in the
custom rules language reference.
The following command adds a rule to allow traffic from the IP address
1.2.3.4
and contains the string Godzilla
in the user-agent header:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "inIpRange(origin.ip, '1.2.3.4/32') && has(request.headers['user-agent']) && request.headers['user-agent'].contains('Godzilla')" \ --action allow \ --description "Block User-Agent 'Godzilla'"
The following command adds a rule to block requests if the request's cookie contains a specific value:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "has(request.headers['cookie']) && request.headers['cookie'].contains('80=BLAH')" \ --action deny-403 \ --description "Cookie Block"
The following command adds a rule to block requests from the region AU
:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "origin.region_code == 'AU'" \ --action deny-403 \ --description "AU block"
The following command adds a rule to block requests from the region AU
that are not in the specified IP range:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "origin.region_code == "AU" && !inIpRange(origin.ip, '1.2.3.0/24')" \ --action deny-403 \ --description "country and IP block"
The following command adds a rule to block requests with a URI that matches a regular expression:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "request.path.matches('/bad_path/')" \ --action deny-502 \ --description "regex block"
The following command adds a rule to block requests if the Base64
decoded value of the user-id
header contains a specific value:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "has(request.headers['user-id']) && request.headers['user-id'].base64Decode().contains('myValue')" \ --action deny-403 \ --description "country and IP block"
The following command adds a rule that uses a preconfigured expression set to mitigate SQLi attacks:
gcloud compute security-policies rules create 1000 \ --security-policy my-policy \ --expression "evaluatePreconfiguredExpr('sqli-stable')" \ --action deny-403
List the rules in a security policy
Use these instructions to list the rules in a Google Cloud Armor security policy.
Console
In the Google Cloud console, go to the Network Security page.
On the Security policies page, click the name of the security policy. The Policy details page is displayed, and the policy rules are listed on the Rules tab in the middle of the page.
gcloud
Use the following gcloud
command to list all rules in a single security
policy along with a description of the policy:
gcloud compute security-policies describe NAME \
Use the following gcloud
command to describe a rule with the specified
priority in the specified security policy:
gcloud compute security-policies rules describe PRIORITY \ --security-policy POLICY_NAME
For example, the following command describes the rule with priority 1000 in
the security policy my-policy
:
gcloud compute security-policies rules describe 1000 \ --security-policy my-policy
Output:
action: deny(403) description: block traffic from 192.0.2.0/24 and 198.51.100.0/24 kind: compute#securityPolicyRule match: srcIpRanges: - '192.0.2.0/24' - '198.51.100.0/24' preview: false priority: 1000
Update a single rule in a security policy
Use these instructions to update a single rule in a Google Cloud Armor security policy. To atomically update multiple rules, see Atomically updating multiple rules in a security policy.
Console
In the Google Cloud console, go to the Network Security page.
On the Security policies page, click the name of the security policy. The Policy details page is displayed.
In the middle of the page, click the Rules tab.
Next to the rule that you want to update, click
Edit. The Edit rule page is displayed.Make the desired changes, and then click Update.
gcloud
Use this command to update a rule with the specified priority in a designated security policy. You can only update one security policy at a time using this command:
gcloud compute security-policies rules update PRIORITY [ \ --security-policy POLICY_NAME \ --description DESCRIPTION \ --src-ip-ranges IP_RANGES | --expression EXPRESSION \ --action=[ allow | deny-403 | deny-404 | deny-502 ] \ --preview ]
For example, the following command updates a rule with priority 1111 to allow traffic from the IP address range 192.0.2.0/24:
gcloud compute security-policies rules update 1111 \ --security-policy my-policy \ --description "allow traffic from 192.0.2.0/24" \ --src-ip-ranges "192.0.2.0/24" \ --action "allow"
For more information about this command, see
gcloud compute security-policies rules update
.
To update the priority of a rule, you must use the REST API. For more
information, see
securityPolicies.patchRule
.
Atomically update multiple rules in a security policy
An atomic update applies changes to multiple rules in a single update. If you were to update rules one-by-one, you might see some unintended behavior because old and new rules might be working together for a short period of time.
To atomically update multiple rules, export the current security policy to a JSON or YAML file, and then modify it. Use the modified file to create a new security policy, and then switch the security policy for the relevant backend services.
gcloud
Export the policy to update, as shown in the following example:
gcloud compute security-policies export my-policy \ --file-name my-file \ --file-format yaml
The exported policy will look similar to the following example:
description: my description fingerprint: PWfLGDWQDLY= id: '123' name: my-policy rules: - action: deny(404) description: my-rule-1 match: expr: expression: evaluatePreconfiguredExpr('xss-stable') versionedExpr: SRC_IPS_V1 preview: false priority: 1 - action: allow description: my-rule-2 match: config: srcIpRanges: - '1.2.3.4' versionedExpr: SRC_IPS_V1 preview: false priority: 2 - action: deny description: default rule kind: compute#securityPolicyRule match: config: srcIpRanges: - '*' versionedExpr: SRC_IPS_V1 preview: false priority: 2147483647 selfLink: https://www.googleapis.com/compute/v1/projects/my-project/global/securityPolicies/my-policy
Use any text editor to modify the policy. For example, you can modify the the priorities of the existing rules and add a new rule:
description: my description fingerprint: PWfLGDWQDLY= id: '123' name: my-policy rules: - action: deny(404) description: my-rule-1 match: expr: expression: evaluatePreconfiguredExpr('xss-stable') versionedExpr: SRC_IPS_V1 preview: false priority: 1 - action: allow description: my-new-rule match: config: srcIpRanges: - '1.2.3.1' versionedExpr: SRC_IPS_V1 preview: false priority: 10 - action: allow description: my-rule-2 match: config: srcIpRanges: - '1.2.3.4' versionedExpr: SRC_IPS_V1 preview: false priority: 11 - action: deny description: default rule kind: compute#securityPolicyRule match: config: srcIpRanges: - '*' versionedExpr: SRC_IPS_V1 preview: false priority: 2147483647 selfLink: https://www.googleapis.com/compute/v1/projects/my-project/global/securityPolicies/my-policy
Create a new Google Cloud Armor security policy and specify the modified file name and format, as shown in the following example:
gcloud compute security-policies create new-policy \ --file-name modified-policy \ --file-format yaml
Remove the old security policy from the relevant backend service, as shown in the following example:
gcloud compute backend-services update my-backend \ --security-policy ""
Add the new security policy to the backend service, as shown in the following example:
gcloud compute backend-services update my-backend \ --security-policy new-policy
If the old policy is unused, delete it:
gcloud compute security-policies delete my-policy
Delete rules from a security policy
Use these instructions to delete rules from a Google Cloud Armor security policy.
Console
In the Google Cloud console, go to the Network Security page.
On the Security policies page, click the name of the security policy. The Policy details page is displayed.
In the middle of the page, on the Rules tab, select the checkbox next to the rule that you want to delete.
Click
Delete.
gcloud
Use this command to remove a rule with the specified priority from a designated security policy. You can modify only one security policy at a time, but you can delete multiple rules at once:
gcloud compute security-policies rules delete PRIORITY [...] [ --security-policy POLICY_NAME \ ]
For example:
gcloud compute security-policies rules delete 1000 \ --security-policy my-policy
What's next
- Tune web application firewall (WAF) rules
- Troubleshoot issues
- Use the custom rules language reference