Verbose logging

This page contains information about configuring verbose logging, an optional feature that you can use with your Google Cloud Armor security policies.

You can adjust the level of detail recorded in your logs. We recommend that you enable verbose logging only when you first create a policy, make changes to a policy, or troubleshoot a policy. If you enable verbose logging, it is in effect for rules in preview mode as well as active (non-previewed) rules during standard operations.

Consider an example in which you are not be able to tell why a preconfigured WAF rule was triggered by a particular request. Google Cloud Armor's default event logs contain the rule that was triggered, as well as the subsignature. However, you might need to identify the details from the incoming request that triggered the rule for troubleshooting, rule validation, or rule tuning purposes. This is a example, we recommend that you enable 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 by using the gcloud compute security-policies update command. 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 Import security policies.

For example:

  gcloud compute security-policies update ca-policy-1 \
      --log-level=VERBOSE

We recommend that you enable verbose logging when you first create a policy, make changes to a policy, or troubleshoot a policy.

Values logged when verbose logging is enabled

When verbose logging is enabled, additional information is logged to the load balancing request log that is sent to Cloud Logging. The following additional fields appear in the request log when verbose logging is enabled:

  • matchedFieldType (string): This is the type of field causing the match.

    • ARG_NAMES
    • ARG_VALUES

    • BODY

      • When the BODY field is in the log, it means that the entire post body matches a rule.

    • COOKIE_VALUES

    • COOKIE_NAMES

    • FILENAME

    • HEADER_VALUES

    • RAW_URI

    • REFERER

    • REQUEST_LINE

    • URI

    • USER_AGENT

    • HEADER_NAMES

    • ARGS_GET

    • X_FILENAME

    • ARG_NAME_COUNT

    • TRANSFER_ENCODING

    • REQUEST_METHOD

  • matchedFieldName (string): If this matches the value part of a key-value pair, the key value is stored in this field. Otherwise, it is empty.

  • matchedFieldValue (string): A prefix of up to 16 bytes for the part of the field that causes the match.

  • matchedFieldLength (integer): The total length of the field.

  • matchedOffset (integer): The start offset inside the field that causes the match.

  • matchedLength (integer): The length of the match.

For example, you might send this request to a project where SQL injection WAF rules are enabled:

curl http://IP_ADDR/?sql_table=abc%20pg_catalog%20xyz

The entry in the Logs Explorer would look like the following:

enforcedSecurityPolicy: {
 name: "user-staging-sec-policy"
 priority: 100
 configuredAction: "DENY"
 outcome: "DENY
 preconfiguredExprIds: [
   0: "owasp-crs-v030001-id942140-sqli"
  ]
matchedFieldType: "ARG_VALUES"
matchedFieldName: "sql_table"
matchedFieldValue: "pg_catalog"
matchedFieldLength: 18
matchedOffset: 4
matchedLength: 10
}

Maintaining privacy when verbose logging is turned on

When you use verbose logging, Google Cloud Armor logs snippets of the elements from the incoming requests that triggered a particular preconfigured WAF rule. These snippets might contain pieces of request headers, request parameters, or elements of the POST body. It is possible that a snippet contains sensitive data such as an IP address or other sensitive data from the incoming request, depending on what is in the request headers or body and what triggers the WAF rule.

By enabling verbose logging, be aware that there is a risk of accumulating potentially sensitive data in your logs in Logging. We recommend that you enable verbose logging only during rule creation and validation or for troubleshooting. During normal operations, we recommend that you leave verbose logging disabled.

What's next