--- title: Enabling App and API Protection for Envoy description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: >- Docs > Datadog Security > App and API Protection > Enabling App and API Protection > Enabling App and API Protection for Envoy --- # Enabling App and API Protection for Envoy {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). (). {% /alert %} {% /callout %} You can enable App and API Protection for the Envoy proxy. The Datadog Envoy integration has support for threat detection and blocking. ## Prerequisites{% #prerequisites %} - The [Datadog Agent](https://app.datadoghq.com/account/settings#agent) is installed and configured for your application's operating system or container, cloud, or virtual environment. - [Configure the Agent with Remote Configuration](https://docs.datadoghq.com/tracing/guide/remote_config.md) to block attackers using the Datadog UI. ## Enabling threat detection{% #enabling-threat-detection %} ### Get started{% #get-started %} The App and API Protection Envoy integration uses the Envoy external processing filter. 1. Deploy a new container with the Datadog External Processor Docker image. The image is available on the [Datadog GitHub Registry](https://github.com/DataDog/dd-trace-go/pkgs/container/dd-trace-go%2Fservice-extensions-callout). This service is a gRPC server that Envoy communicates with to have requests and responses analyzed by App and API Protection. The Datadog External Processor exposes some settings: | Environment variable | Default value | Description | | ----------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `DD_SERVICE_EXTENSION_HOST` | `0.0.0.0` | gRPC server listening address. | | `DD_SERVICE_EXTENSION_PORT` | `443` | gRPC server port. | | `DD_SERVICE_EXTENSION_HEALTHCHECK_PORT` | `80` | HTTP server port for health checks. | | `DD_APPSEC_BODY_PARSING_SIZE_LIMIT` | `0` | Maximum size of the bodies to be processed in bytes. If set to `0`, the bodies are not processed. The recommended value is `10000000` (10MB). (To fully enable body processing, the `allow_mode_override` option should also be set in the External Processing filter configuration) | | `DD_SERVICE_EXTENSION_OBSERVABILITY_MODE` | `false` | Enable asynchronous analysis. This also disables blocking capabilities. (To fully enable observability mode, this option should also be set in the External Processing filter configuration) | | `DD_SERVICE` | `serviceextensions` | Service name shown in the Datadog UI. | Configure the Datadog Agent to receive traces from the external processor using the following environment variables: | Environment variable | Default value | Description | | --------------------- | ------------- | ----------------------------------------------- | | `DD_AGENT_HOST` | `localhost` | Hostname or IP of your Datadog Agent. | | `DD_TRACE_AGENT_PORT` | `8126` | Port of the Datadog Agent for trace collection. | 1. Update your Envoy configuration to add the [external processing filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_proc_filter) to your `http_filters` list, and define the corresponding gRPC cluster in your `clusters` section. For example: Http filters section: ```yaml http_filters: # This filter should be the first filter in the filter chain - name: envoy.filters.http.ext_proc typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.ext_proc.v3.ExternalProcessor grpc_service: envoy_grpc: cluster_name: datadog_aap_ext_proc_cluster ## Mandatory: Correctly show the service as an Envoy proxy in the UI. initial_metadata: - key: x-datadog-envoy-integration value: '1' ## A timeout configuration for the grpc connection exist but is not useful in our case. ## This timeout is for all the request lifetime. A timeout on the route is preferred. #timeout: 0s ## Optional: Enable fail open mode. Default is false. ## Normally, if the external processor fails or times out, the filter fails and Envoy ## returns a 5xx error to the downstream client. Setting this to true allows requests ## to continue without error if a failure occurs. failure_mode_allow: true # It won't cause 5xx error if an error occurs. ## Mandatory: Only enable the request and response header modes. ## If you want to enable body processing, please see the section below. processing_mode: request_header_mode: SEND response_header_mode: SEND ## Optional for headers analysis only but **mandatory** for body processing. ## The external processor can dynamically override the processing mode as needed instructing ## Envoy to forward request and response bodies to the external processor. Body processing is ## enabled when DD_APPSEC_BODY_PARSING_SIZE_LIMIT is set on the external processor container. allow_mode_override: true ## Optional: Set a timeout by processing message. Default is 200ms. ## There is a maxium of 2 messages per requests with headers only and 4 messages maximum ## with body processing enabled. ## Note: This timeout also includes the data communication between Envoy and the external processor. ## Optional: When the body processing is enabled, the timeout should be adjusted to accommodate ## the additional possible processing time. Larger payloads will require a longer timeout. #message_timeout: 200ms ## Optional: Enable asynchronous mode analysis. Default is false. ## This mode will disable all blocking capabilities. The external processor should also be ## configured with the DD_SERVICE_EXTENSION_OBSERVABILITY_MODE environment variable. ## Beware, there is no flow control implemented in Envoy ## (cf https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/ext_proc.proto#envoy-v3-api-field-extensions-filters-http-ext-proc-v3-externalprocessor-observability-mode) #observability_mode: true ## Optional: When in asynchronous mode, the message_timeout is not used. This deferred ## timeout starts when the http request is finished, to let the External Processor ## process all processing messages. Default is 5s. #deferred_close_timeout: 5s # ... other filters ``` Clusters section: ```yaml clusters: # ... other clusters - name: datadog_aap_ext_proc_cluster type: STRICT_DNS lb_policy: ROUND_ROBIN http2_protocol_options: {} transport_socket: name: envoy.transport_sockets.tls typed_config: "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext sni: "localhost" load_assignment: cluster_name: datadog_aap_ext_proc_cluster endpoints: - lb_endpoints: - endpoint: address: socket_address: address: 12.0.0.1 # Replace with the host address of the Datadog External Processor docker image (configured in the next step) port_value: 443 ``` **Note**: Please read the provided example configuration carefully and adapt it to match your infrastructure and environment. You can find more configuration options available in the [Envoy external processor documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/ext_proc.proto). 1. Validation. After this configuration is complete, the library collects security data from your application and sends it to the Agent. The Agent sends the data to Datadog, where [out-of-the-box detection rules](https://docs.datadoghq.com/security/default_rules.md#cat-application-security) flag attacker techniques and potential misconfigurations so you can take steps to remediate. 1. To see App and API Protection threat detection in action, send known attack patterns to your application. For example, trigger the [Security Scanner Detected](https://docs.datadoghq.com/security/default_rules/security-scan-detected.md) rule by running a file that contains the following curl script: ``` for ((i=1;i<=250;i++)); do# Target existing service's routescurl https://your-application-url/existing-route -A dd-test-scanner-log;# Target non existing service's routescurl https://your-application-url/non-existing-route -A dd-test-scanner-log;done ``` **Note**: The `dd-test-scanner-log` value is supported in the most recent releases. A few minutes after you enable your application and send known attack patterns to it, threat information appears in the [Application Signals Explorer](https://app.datadoghq.com/security/appsec) and vulnerability information appears in the [Vulnerabilities explorer](https://app.datadoghq.com/security/appsec/vm/). {% video url="https://docs.dd-static.net/images//security/application_security/appsec-getstarted-threat-and-vuln_2.mp4" /%} ## Datadog Go Tracer and Envoy integration{% #datadog-go-tracer-and-envoy-integration %} The External Processor is built on top of the [Datadog Go Tracer](https://github.com/DataDog/dd-trace-go) and inherits all of its environment variables. See [Configuring the Go Tracing Library](https://docs.datadoghq.com/tracing/trace_collection/library_config/go.md) and [App and API Protection Library Configuration](https://docs.datadoghq.com/security/application_security/policies/library_configuration.md). {% alert level="info" %} **Note:** As the Datadog External Processor is built on top of the Datadog Go Tracer, it generally follows the same release process as the tracer, and its Docker images are tagged with the corresponding tracer version (for example, `v2.2.2`). In some cases, early release versions might be published between official tracer releases, and these images are tagged with a suffix such as `-docker.1`. {% /alert %} ## Limitations{% #limitations %} The Envoy integration has the following limitations: - Inspection of request and response bodies is supported when using the Datadog External Processor image version `v2.2.2` or later. For additional details on the Envoy integration compatibilities, refer to the [Envoy integration compatibility page](https://docs.datadoghq.com/security/application_security/setup/compatibility/envoy.md). ## Further Reading{% #further-reading %} - [Envoy integration's source code](https://github.com/DataDog/dd-trace-go/tree/main/contrib/envoyproxy/go-control-plane/cmd/serviceextensions) - [OOTB App and API Protection Rules](https://docs.datadoghq.com/security/default_rules.md?category=cat-application-security) - [Troubleshooting App and API Protection](https://docs.datadoghq.com/security/application_security/troubleshooting.md)