Use request logging

Google Cloud Armor per-request logs for security policy name, match rule priority, associated action, and related information are logged as part of logging for external Application Load Balancers and external proxy Network Load Balancers. Logging for new backend services is disabled by default, so you must enable logging to record complete logging information for Google Cloud Armor.

Google Cloud Armor logs are part of the Cloud Load Balancing logs. This means that Google Cloud Armor log generation is subject to the log sampling rate configured for your load balancer. If you reduce the sampling rate for your load balancer, your Google Cloud Armor requests logs are sampled at that reduced rate. In addition, if you use cross-project service referencing, logs are generated under the host or service project that includes your load balancer's frontend and URL map. Therefore, we recommend that administrators in the frontend project grant permissions to read logs and metrics to administrators in the backend project.

Using logging, you can view every request evaluated by a Google Cloud Armor security policy and the outcome or action taken based on the highest priority matching rule. 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 logging for an external Application Load Balancer, see External Application Load Balancer logging and monitoring. For the external proxy Network Load Balancer, you can use the Google Cloud CLI commands as listed in the previous External Application Load Balancer logging and monitoring page. You cannot enable logging for the external proxy Network Load Balancer using the Google Cloud console.

In addition, you can set different logging levels to help you evaluate whether your security policies and their rules are working as intended. For complete information, see Verbose logging.

Security policy log entries

The following log entries in the Logs Explorer are for Google Cloud Armor security policy and rules logging. The entries include the following structure in jsonPayload. HTTP request details appear in the httpRequest message.

  • statusDetails (string): a textual description of the response code.
    • redirected_by_security_policy: the request was redirected by a redirect rule, either GOOGLE_RECAPTCHA or EXTERNAL_302.
    • denied_by_security_policy: a request was denied by the load balancer because of a Google Cloud Armor security policy.
    • body_denied_by_security_policy: a request body was denied by the load balancer because of a Google Cloud Armor security policy.
  • enforcedSecurityPolicy: the security policy rule that was enforced.
    • name (string): the name of the security policy.
    • priority (number): the priority of the matching rule in the security policy.
    • adaptiveProtection: information about the automatically deployed Adaptive Protection rule, if applicable.
      • autoDeployAlertId: the alert ID of the events that Adaptive Protection detected.
    • configuredAction (string): the name of the configured action in the matching rule—for example, ALLOW, DENY, GOOGLE_RECAPTCHA, EXTERNAL_302, THROTTLE (for a throttle rule), RATE_BASED_BAN (for a rate-based ban rule).
    • rateLimitAction: information about the rate limit action when a throttle rule or rate-based ban rule is matched.
      • key (string): rate limit key value (up to 32 bytes). This field is omitted if the key type is ALL, or if the key type is HTTP-HEADER or HTTP-COOKIE and the specified header or cookie is not present in the request.
      • outcome (string): possible values are as follows:
        • "RATE_LIMIT_THRESHOLD_CONFORM" if under the configured rate limit threshold.
        • "RATE_LIMIT_THRESHOLD_EXCEED" if above the configured rate limit threshold.
        • "BAN_THRESHOLD_EXCEED" if above the configured ban threshold.
    • outcome (string): the outcome of executing the configured action—for example, ACCEPT, DENY, REDIRECT, EXEMPT.
    • preconfiguredExprIds (string): the IDs of all preconfigured WAF rule expressions that triggered the rule.
    • threatIntelligence: information about the matched IP address list(s) from Threat Intelligence, if applicable.
      • categories: (string) the matched IP address list name(s).
  • previewSecurityPolicy: populated if a request matches a rule configured for preview (present only when a preview rule would have taken priority over the enforced rule).
    • name (string): the name of the security policy
    • priority (number): the priority of the matching rule in the security policy.
    • configuredAction (string): the name of the configured action in the matching rule—for example, ALLOW, DENY, GOOGLE_RECAPTCHA, EXTERNAL_302, THROTTLE (for a throttle rule), RATE_BASED_BAN (for a rate-based ban rule).
    • rateLimitAction: information about the rate limit action when a throttle rule or rate-based ban rule is matched.
      • key (string): rate limit key value (up to 32 bytes). This field is omitted if the key type is ALL, or if the key type is HTTP-HEADER or HTTP-COOKIE and the specified header or cookie is not present in the request.
      • outcome (string): possible values are as follows:
        • "RATE_LIMIT_THRESHOLD_CONFORM" if under the configured rate limit threshold.
        • "RATE_LIMIT_THRESHOLD_EXCEED" if above the configured rate limit threshold.
        • "BAN_THRESHOLD_EXCEED" if above the configured ban threshold.
    • outcome (string): the outcome of executing the configured.
    • outcome (string): the outcome of executing the configured action—for example, ACCEPT, DENY, REDIRECT, EXEMPT.
    • preconfiguredExprIds (string): the IDs of all preconfigured WAF rule expressions that triggered the rule.
    • threatIntelligence: information about the matched IP address list(s) from Threat Intelligence, if applicable.
      • categories: (string) the matched IP address list name(s).
  • enforcedEdgeSecurityPolicy (Preview): the edge security policy rule that was enforced.
    • name (string): the name of the security policy.
    • priority (number): the priority of the matching rule in the security policy.
    • configuredAction (string): the name of the configured action in the matching rule—for example, ALLOW, DENY.
    • outcome (string): the outcome of executing the configured action—for example, ACCEPT, DENY.
  • previewEdgeSecurityPolicy (Preview): populated if a request matches an edge security policy rule configured for preview (present only when a preview rule would have taken priority over the enforced rule).
    • name (string): the name of the security policy.
    • priority (number): the priority of the matching rule in the security policy.
    • configuredAction (string): the name of the configured action in the matching rule—for example, ALLOW, DENY.
    • outcome (string): the outcome of executing the configured action—for example, ACCEPT, DENY.

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 Google Cloud Armor policies.

    Go to Google Cloud Armor policies

  2. Click Actions.

  3. Select View logs.

Request data logging

When used with Google Cloud Armor, jsonPayload has the following additional field:

  • securityPolicyRequestData: data pertaining to the request while being processed by a security policy, regardless of which rule is matched eventually.
    • recaptchaActionToken: data related to a reCAPTCHA action-token.
      • score (float): a user legitimacy score embedded in a reCAPTCHA action-token. Only present when a reCAPTCHA action-token is attached with the request and it is decoded successfully based on a security policy rule. For more information, see Enforce reCAPTCHA assessment.
    • recaptchaSessionToken: data related to a reCAPTCHA session-token.
      • score (float): a user legitimacy score embedded in a reCAPTCHA session-token. Only present when a reCAPTCHA session-token is attached with the request and it is decoded successfully based on a security policy rule.
    • tlsJa3Fingerprint: a JA3 TTL/SSL fingerprint if the client connects using HTTPS, HTTP/2, or HTTP/3. Only present if the fingerprint is available and there is a security policy that evaluates the request (regardless of whether an expression in the policy matches on the request).

Log examples

The following is an example of log details for a throttle rule that blocks a request:

jsonPayload: {
 enforcedSecurityPolicy: {
  priority: 100
  name: "sample-prod-policy"
  configuredAction: "THROTTLE"
  outcome: "DENY"
  rateLimitAction: {
    key:"sample-key"
    outcome:"RATE_LIMIT_THRESHOLD_EXCEED"
  }
 }
 @type: "type.googleapis.com/google.cloud.loadbalancing.type.LoadBalancerLogEntry"
 statusDetails: "denied_by_security_policy"
}
httpRequest: {8}
resource: {2}
timestamp: "2021-03-17T19:16:48.185763Z"

The following is an example of log details for a rate-based ban rule that blocks a request:

jsonPayload: {
 @type: "type.googleapis.com/google.cloud.loadbalancing.type.LoadBalancerLogEntry"
 enforcedSecurityPolicy: {
  priority: 150
  name: "sample-prod-policy"
  outcome: "DENY"
  configuredAction: "RATE_BASED_BAN"
  rateLimitAction: {
    key:"sample-key"
    outcome:"BAN_THRESHOLD_EXCEED"
  }
 }
 statusDetails: "denied_by_security_policy"
}
httpRequest: {8}
resource: {2}
timestamp: "2021-03-17T19:27:17.393244Z"

What's next

Learn about Troubleshooting Google Cloud Armor issues.