Configuring Google Cloud Armor security policies

Use these instructions to create Google Cloud Armor security policies to filter incoming traffic that is destined to external HTTP(S) load balancers. 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, make sure that you are familiar with HTTP(S) Load Balancing concepts.

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

  • Creating, 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

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.

Setting 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

Configuring 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 external HTTP(S) load balancers:

  1. Create a Google Cloud Armor security policy.
  2. Add rules to the security policy based on IP address lists, custom expressions, or preconfigured expression sets.
  3. Attach the security policy to a backend service of the external HTTP(S) load balancer for which you want to control access.
  4. 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.

Example in which two security policies are applied to different backend services.
Example in which two security policies are applied to different backend services (click to enlarge)

In the example, these are the Google Cloud Armor security policies:

  • mobile-clients-policy applies to external users of your games services.
  • internal-users-policy applies to your organization's test-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.

Creating the example

Use these instructions to create the example configuration discussed in the previous section.

Console

Configure the security policy for external users:

  1. In the Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  2. On the Policies page, click Create policy.

  3. In the Name field, enter mobile-clients-policy.

  4. In the Description field, enter Policy for external users.

  5. For Default rule action, select Deny.

  6. For Deny status, select 404 (Not Found).

  7. Click Next step.

Add more rules:

  1. Click Add rule.
  2. In the Description field, enter allow traffic from 192.0.2.0/24.
  3. For Mode, select Basic mode (IP addresses/ranges only).
  4. In the Match field, enter 192.0.2.0/24.
  5. For Action, select Allow.
  6. In the Priority field, enter 1000.
  7. Click Done.
  8. Click Next step.

Apply policy to targets:

  1. Click Add Target.
  2. In the Target list, select a target.
  3. Click Done.
  4. Click Create policy.

Optionally, enable Adaptive Protection:

  1. To enable Adaptive Protection, check the Enable check box.

Configure the security policy for internal users:

  1. On the Policies page, click Create policy.
  2. In the Name field, enter internal-users-policy.
  3. In the Description field, enter Policy for internal test users.
  4. For Default rule action, select Deny.
  5. For Deny status, select 502 (Bad Gateway).
  6. Click Next step.

Add more rules:

  1. Click Add rule.
  2. In the Description field, enter allow traffic from 198.51.100.0/24.
  3. For Mode, select Basic mode (IP addresses/ranges only).
  4. In the Match field, enter 198.51.100.0/24.
  5. For Action, select Allow.
  6. For Preview only, select the Enable checkbox.
  7. In the Priority field, enter 1000.
  8. Click Done.
  9. Click Next step.

Apply policy to targets:

  1. Click Add Target.
  2. In the Target list, select a target.
  3. Click Done.
  4. Click Create policy.

gcloud

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

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

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

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

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

Creating security policies, rules, and expressions

You can create Google Cloud Armor security policies, rules, and expressions by using the Google Cloud Console, the gcloud command-line tool, or the REST API.

The following are sample expressions. For more information about expressions, see the Google Cloud Armor custom rules language reference.

If you are creating 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 Godzilla 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 match against SQLi attacks:

    evaluatePreconfiguredExpr('sqli-stable')

The following instructions assume that you are creating security policies to apply to an existing external HTTP(S) load balancer 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:

  1. In the Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  2. On the Policies page, click Create policy.

  3. In the Name field, enter the name of your policy.

  4. Optional: Enter a description of the policy.

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

  6. If you are creating 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.

  7. Regardless of the type of rule that you are creating, click Next step.

Add more rules:

  1. Click Add rule.
  2. Optional: Enter a description for the rule.

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

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

  5. For Action, select Allow or Deny to allow or deny traffic if the rule matches.

  6. To enable preview mode, select the Enable checkbox. In preview mode, you can see how the rule behaves, but the rule is not enabled.

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

  8. Click Done.

  9. To add more rules, click Add rule and repeat the previous steps. Otherwise, click Next step.

Apply policy to targets:

  1. Click Add Target.
  2. In the Target list, select a target.
  3. To add more targets, click Add Target.
  4. Click Done.
  5. Click Create policy.

gcloud

  1. To create a new Google Cloud Armor security policy, use the command gcloud compute security-policies create. Replace NAME and DESCRIPTION with the name and description of the security policy:

    gcloud compute security-policies create NAME \
   [--file-format=FILE_FORMAT | --description=DESCRIPTION] \
   [--file-name=FILE_NAME]

    For example:

    gcloud compute security-policies create my-policy \
    --description "block bad traffic"

  2. To add rules to a security policy, use the command gcloud compute security-policies rules create PRIORITY. Replace PRIORITY 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 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('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"

Using Adaptive Protection

Adaptive Protection is applied on a per-security-policy basis.

Console

To activate Adaptive Protection for a security policy:

  1. In the Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  2. On the Policies page, click the name of a security policy.

  3. Click Edit.

  4. Under Adaptive Protection, select Enable.

  5. Click Update.

To deactivate Adaptive Protection for a security policy:

  1. In the Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  2. On the Policies page, click the name of a security policy.

  3. Click Edit.

  4. Under Adaptive Protection, deselect Enable.

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

Listing 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

  1. 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
   expression-set-1-id-1
   expression-set-1-id-2
expression-set-2
   alias-1
   RULE_ID
   expression-set-2-id-1
   expression-set-2-id-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
    owasp-crs-v030001-id942110-sqli
    owasp-crs-v030001-id942120-sqli
    …
xss-canary
    RULE_ID
    owasp-crs-v030001-id941110-xss
    owasp-crs-v030001-id941120-xss
…
sourceiplist-fastly
sourceiplist-cloudflare
sourceiplist-imperva

Listing 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 Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  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.

Updating 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 Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  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 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 gcloud command-line tool instructions:

Exporting security policies

You can export a Google Cloud Armor security policy as a YAML or JSON file by using the gcloud command-line tool. Exporting a policy enables you to retrieve a copy of it that you can modify or save in source control.

gcloud

  1. 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 the my-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

  2. You can modify the exported file with any text editor, and then import it back to Google Cloud by using the import command.

Importing security policies

You can import Google Cloud Armor security policies from a YAML or JSON file by using the gcloud command-line tool. 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.

Deleting 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 Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  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

Attaching 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 security policy attached to it.

Console

  1. In the Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  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

Use the gcloud compute backend-services command:

gcloud compute backend-services update my-backend \
    --security-policy my-policy

Removing a security policy from a backend service

Use these instructions to remove a Google Cloud Armor security policy from a backend service.

Console

  1. In the Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  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

Use the gcloud compute backend-services command:

gcloud compute backend-services update my-backend \
    --security-policy ""

Adding rules to a security policy

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

Console

  1. In the Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  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 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 string Godzilla 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')

  8. For Action, select Allow or Deny.

  9. If you are creating 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 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

Listing the rules in a security policy

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

Console

  1. In the Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  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

Updating 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 Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

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

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

  3. 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 \
    --description "allow-listed traffic" \
    --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

Deleting rules from a security policy

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

Console

  1. In the Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  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, 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

Enabling HTTP(S) request logging

Google Cloud Armor logs for security policy name, match rule priority, associated action, and related information are logged as part of logging for HTTP(S) Load Balancing. Logging for new backend services is disabled by default, so you must enable HTTP(S) Load Balancing logging to record complete logging information for Google Cloud Armor.

Using HTTP(S) Load Balancing logging, you can view denied and allowed HTTP(S) requests in detail. For example, to view denied requests, you can use filters such as jsonPayload.enforcedSecurityPolicy.outcome="DENY" or jsonPayload.statusDetails="denied_by_security_policy".

To enable HTTP(S) Load Balancing logging, see HTTP(S) Load Balancing Logging and Monitoring.

Viewing logs

You can view the logs for a Google Cloud Armor security policy only in the Google Cloud Console.

Console

  1. In the Google Cloud Console, go to the Network Security page.

    Go to the Network Security page

  2. On the Security policies page, in the row for a security policy, click Menu for the policy whose logs you want to view.

  3. Select View logs.

What's next