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 can't tell why a preconfigured WAF rule is 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. For this 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 Google Cloud 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 can't 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.

  • inspectedBodySize (integer): the configured inspection limit (number of bytes) for a request body that you set by using the --request-body-inspection-size flag. For more information about this limit, see POST and PATCH body inspection limitation.

For example, you might send the following 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 is similar to the following:

enforcedSecurityPolicy: {
 name: "user-staging-sec-policy"
 priority: 100
 configuredAction: "DENY"
 outcome: "DENY
 inspectedBodySize: 65536
 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. A snippet can contain 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.

When you enable verbose logging, 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