This document explains how to automatically deploy
suggested rules generated by Google Cloud Armor Adaptive Protection. To enable automatic
deployment, create a placeholder rule with the following values:

- **Match expression** : `evaluateAdaptiveProtectionAutoDeploy()`
- **Action**: Any
- **Priority** : Any. We recommend that you include the `evaluateAdaptiveProtectionAutoDeploy()` placeholder rule at a lower priority than any of your static allow or deny rules to ensure that your known traffic restrictions are always evaluated.

If you use an upstream proxy in front of your external Application Load Balancer, such as a
third-party CDN, you can configure the placeholder rule to match requests based
on the original client's IP address from a specified header or headers. To use
this preview feature, configure the `userIpRequestHeaders[]` option in the
`advancedOptionsConfig` field. For more information, see the
[ComputeSecurityPolicy](https://docs.cloud.google.com/compute/docs/reference/rest/beta/securityPolicies)
resource reference.

## Example placeholder rules

The following commands are example placeholder rules for security policies
called `POLICY_NAME`, each of which features a different rule action.
You can add these rules to an existing security policy or create a new policy. For
more information about creating security policies, see
[Create and view Cloud Armor security policies](https://docs.cloud.google.com/armor/docs/create-security-policies).

### Block malicious traffic

This example rule evaluates to `true` for requests that Adaptive Protection
identifies as attack traffic. Cloud Armor applies the blocking
action to the attacking request:

```
gcloud compute security-policies rules create 1000 \
    --security-policy POLICY_NAME \
    --expression "evaluateAdaptiveProtectionAutoDeploy()" \
    --action deny-403
```

### Redirect malicious traffic to a reCAPTCHA challenge

This example rule redirects traffic that Adaptive Protection identifies as
malicious to a reCAPTCHA challenge:

```
gcloud compute security-policies rules create 1000 \
    --security-policy POLICY_NAME \
    --expression "evaluateAdaptiveProtectionAutoDeploy()" \
    --action redirect \
    --redirect-type google-recaptcha
```

### Rate limit malicious traffic

This example applies Cloud Armor rate limiting to traffic that
Adaptive Protection identifies as malicious:

```
gcloud compute security-policies rules create 1000 \
    --security-policy POLICY_NAME \
    --expression "evaluateAdaptiveProtectionAutoDeploy()" \
    --action throttle \
    --rate-limit-threshold-count 500 \
    --rate-limit-threshold-interval-sec 120 \
    --conform-action allow \
    --exceed-action deny-404 \
    --enforce-on-key ip
```

## Configure Adaptive Protection auto-deploy parameters

You can configure the thresholds for automatic deployment of rules by tuning the
following parameters. If you don't specify a value for a parameter,
Cloud Armor uses the default value.

- **Load threshold**: during an alerted attack, Adaptive Protection identifies
  new attackers only when the load to the backend service that is under attack
  exceeds this threshold. In addition, rules are only automatically deployed for
  alerts when the load to the backend service that is under attack exceeds this
  threshold.

  - **Default value** : `0.8`

    > [!CAUTION]
    > **Caution**: Setting the load threshold field has no effect on
    > serverless backends. The load threshold value isn't used for detecting an
    > attack nor for triggering auto-deployment for backend services that are
    > configured with the following network endpoint groups (NEGs):
    > - A serverless NEG sending traffic to [App Engine](https://docs.cloud.google.com/appengine), [Cloud Run](https://docs.cloud.google.com/run), or [Cloud Run functions](https://docs.cloud.google.com/functions).
    > - An internet NEG sending traffic to an external origin.

- **Confidence threshold**: rules are only automatically deployed for alerts on
  potential attacks with confidence scores greater than this threshold.

  - Default value: `0.5`
- Impacted baseline threshold: rules are *only* automatically deployed when the
  estimated impact to baseline traffic from the suggested mitigation is
  lower than this threshold. `impactedBaselineProportion` and
  `impactedBaselinePolicyProportion` should be lower than the impacted baseline
  threshold.

  - Default value: `0.01` (1%)
- Expiration set: Cloud Armor stops applying the action in the
  automatically deployed rule to an identified attacker after this duration.
  The rule continues to operate against new requests.

  - **Default value** : `7200` seconds

> [!NOTE]
> **Note:** The auto-deploy action triggers only when all three thresholds (load threshold, confidence threshold, and impacted baseline threshold) are met. For example, even if Adaptive Protection confidently detects an attack and generates a targeted attack signature with minimal baseline impact, auto-deploy still does not act if the backend service under attack is significantly over-provisioned such that the load balancer sees its load below the configured load threshold during the attack.

The following command adds Layer 7 DDoS defense threshold configurations to
security policies.

```
gcloud compute security-policies add-layer7-ddos-defense-threshold-config NAME
[FLAG = VALUE]
```

Replace the following:

- `NAME`: the name of the security policy.
- `FLAG`: the defense threshold parameter.
- `VALUE`: the value of the defense threshold parameter.

For more information, see [Configure granular traffic units](https://docs.cloud.google.com/armor/docs/configure-adaptive-protection#configure-traffic-units).

The following command updates the security policy to use non-default,
automatically deployed thresholds. You can set at most one of the
`auto_deploy_config` and `threshold_config` parameters. Setting more than one
flag causes an error.

```
gcloud beta compute security-policies update NAME [
    --layer7-ddos-defense-auto-deploy-PARAMETER VALUE
]
```

Replace the following:

- `NAME`: the name of the security policy.
- `PARAMETER`: the auto-deploy parameter. It is one of the following:
  - `load-threshold`
  - `confidence-threshold`
  - `impacted-baseline-threshold`
  - `expiration-sec`
- `VALUE`: the value of the auto-deploy parameter.

## Logging

Logs generated by rules automatically deployed with Adaptive Protection have
the following additional fields:

- `autoDeployed`: after you configure automatic rule deployment, each alert log that Adaptive Protection generates has the boolean field `autoDeployed`, which indicates whether an automatic defense was triggered. When `autoDeployed` is set to `true`, it indicates that the `evaluateAdaptiveProtectionAutoDeploy()` placeholder rule has already evaluated that the attack Confidence and Impacted baseline thresholds have exceeded the configured auto-deploy parameters. The system then begins to monitor the dynamic load. Once the load surpasses the configured load threshold, the rule is automatically deployed to mitigate the attack.
- `adaptiveProtection.autoDeployAlertId`: whenever Adaptive Protection takes an action on a request as part of an automatic defense, the request log has the additional `adaptiveProtection.autoDeployAlertId` field, which records the alert ID. This field appears under `enforcedSecurityPolicy` or `previewSecurityPolicy`, depending on whether the security policy is in preview mode.

To view request logs, see [Use request logging](https://docs.cloud.google.com/armor/docs/request-logging). The
following screenshot shows an example of an Adaptive Protection log entry,
with the `autoDeployed` and `adaptiveProtection.autoDeployAlertId` fields.
[![An Adaptive Protection example log.](https://docs.cloud.google.com/static/armor/images/caap-example-log.png)](https://docs.cloud.google.com/static/armor/images/caap-example-log.png) An Adaptive Protection example log (click to enlarge).

## Limitations

- Adaptive Protection is only available for backend security policies attached to backend services that are exposed through an external Application Load Balancer. Adaptive Protection is not available for external proxy Network Load Balancers.