Configure Google Cloud Armor security policies

Use these instructions to create Google Cloud Armor security policies to filter incoming traffic to your application. For conceptual information about security policies, see the Google Cloud Armor security policy overview.

Before you begin

Before you configure security policies, do the following:

  • Make sure that you are familiar with external Application Load Balancer concepts.

  • Examine your existing backend services to determine which don't 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) Compute Security Admin role (roles/compute.securityAdmin):

  • Configuring, modifying, updating, and deleting a Google Cloud Armor security policy
  • Using the following API methods:
    • 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
  • Using the following API methods:
    • BackendServices setSecurityPolicy
    • BackendServices list (gcloud only)

Users with the Security Admin role (roles/iam.securityAdmin) and the Compute Network Admin role can view Google Cloud Armor security policies by using the SecurityPolicies API methods 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

Create security policies

You can configure Google Cloud Armor security policies, rules, and expressions by using the Trusted 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.

If you are unfamiliar with security policy configuration, we recommend that you view example security policies.

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 string example in the user-agent header:

    inIpRange(origin.ip, '1.2.3.4/32') && has(request.headers['user-agent']) && request.headers['user-agent'].contains('example')

    Alternatively, you can match on the IP address range of a custom client IP address header by using the origin.user_ip attribute:

    inIpRange(origin.user_ip, '1.2.3.4/32') && has(request.headers['user-agent']) && request.headers['user-agent'].contains('example')

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

    evaluatePreconfiguredWaf('sqli-stable')

Manage security policies

Use the following sections to list the security policies in your project, update your security policies, delete your security policies, or test your security policies.

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

  1. In the Trusted Cloud console, go to the Google Cloud Armor policies page.

    Go to Google Cloud Armor policies

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

  1. In the Trusted Cloud console, go to the Google Cloud Armor policies page.

    Go to Google Cloud Armor policies

  2. 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 your 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:

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

  1. In the Trusted Cloud console, go to the Google Cloud Armor policies page.

    Go to Google Cloud Armor policies

  2. On the Security policies page, next to the name of the security policy that you want to delete, select the checkbox.

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

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.

Manage security policy rules

Use the following sections to list security policy rules, add rules, update rules, or delete rules.

List the rules in a security policy

Use these instructions to list the rules in a Google Cloud Armor security policy.

Console

  1. In the Trusted Cloud console, go to the Google Cloud Armor policies page.

    Go to Google Cloud Armor policies

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

Add rules to a security policy

Use these instructions to add rules to a Google Cloud Armor security policy.

Console

  1. In the Trusted Cloud console, go to the Google Cloud Armor policies page.

    Go to Google Cloud Armor policies

  2. On the Security policies page, click the name of the security policy. The Policy details page is displayed.

  3. In the middle of the page, click the Rules tab.

  4. Click Add rule.

  5. Optional: Enter a description of the rule.

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

  7. In the Match field, specify the conditions under which the rule applies:

    • Basic mode: enter from one (1) to 10 IP address ranges to match in the rule. You can add a maximum of 10 IP address ranges. For limits, see Google Cloud Armor quotas and limits.

    • 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 string example in the user-agent header:

        inIpRange(origin.ip, '1.2.3.4/32') && has(request.headers['user-agent']) && request.headers['user-agent'].contains('example')

      • 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('/example_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:

        evaluatePreconfiguredWaf('sqli-stable')

  8. For Action, select Allow or Deny.

  9. If you are configuring a deny rule, select a Deny status message.

  10. If you want to enable preview mode for the rule, select the Enable checkbox.

  11. In the Priority field, enter a positive integer.

  12. 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 example 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('example')" \
    --action allow \
    --description "Block User-Agent 'example'"

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('/example_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 "evaluatePreconfiguredWaf('sqli-stable')" \
    --action deny-403

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

  1. In the Trusted Cloud console, go to the Google Cloud Armor policies page.

    Go to Google Cloud Armor policies

  2. On the Security policies page, click the name of the security policy. The Policy details page is displayed.

  3. In the middle of the page, click the Rules tab.

  4. Next to the rule that you want to update, click Edit. The Edit rule page is displayed.

  5. Make your 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

  1. 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: evaluatePreconfiguredWaf('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

  2. 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: evaluatePreconfiguredWaf('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

  3. Create a new Google Cloud Armor security policy and specify the modified filename and format, as shown in the following example:

    gcloud compute security-policies create new-policy \
    --file-name modified-policy \
    --file-format yaml

  4. 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 ""

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

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

  1. In the Trusted Cloud console, go to the Google Cloud Armor policies page.

    Go to Google Cloud Armor policies

  2. Click the name of the security policy. The Policy details page is displayed.

  3. In the middle of the page, on the Rules tab, select the checkbox next to the rule that you want to delete.

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

Attach and remove security policies

Use the following sections to attach and remove security policies from backend services and backend buckets.

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

  1. In the Trusted Cloud console, go to the Google Cloud Armor policies page.

    Go to Google Cloud Armor policies

  2. On the Security policies page, click the name of the security policy. The Policy details page is displayed.

  3. In the middle of the page, click the Targets tab.

  4. Click Apply policy to new target.

  5. Click Add Target.

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

  1. In the Trusted Cloud console, go to the Google Cloud Armor policies page.

    Go to Google Cloud Armor policies

  2. On the Security policies page, click the name of the security policy. The Policy details page is displayed.

  3. In the middle of the page, click the Targets tab.

  4. Select the target backend service from which you are removing the policy.

  5. Click Remove.

  6. 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 ""