Skip to content

Commit fdca741

Browse files
e-n-0e-n-0
committed
Add Envoy doc
1 parent a61efe6 commit fdca741

File tree

5 files changed

+276
-0
lines changed

5 files changed

+276
-0
lines changed

‎config/_default/params.yaml

+2
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,8 @@ code_language_ids:
122122
otel: "OpenTelemetry API"
123123
status_legacy: "Status Page (Legacy)"
124124
status_page: "Status Page"
125+
envoy: "Envoy"
126+
gcp-service-extensions: "GCP Service Extensions"
125127
branch: ""
126128

127129
signupclass: sign-up-trigger

‎content/en/security/application_security/threats/setup/compatibility/envoy.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Evoy Compatibility Requirements
3+
code_lang: envoy
4+
type: multi-code-lang
5+
code_lang_weight: 40
6+
---
7+
8+
## Application Security capabilities support
9+
10+
The following application security capabilities are supported in the Envoy integration, for the
11+
specified tracer version:
12+
13+
| Application Security capability | Minimum Envoy image version |
14+
|----------------------------------------|------------------------------|
15+
| Threat Detection | 1.71.0 |
16+
| Threat Protection | 1.71.0 |
17+
| Customize response to blocked requests | 1.71.0 |
18+
| Software Composition Analysis (SCA) | not applicable |
19+
| Code Security | not applicable |
20+
| Automatic user activity event tracking | not supported |
21+
| API Security | not supported |
22+
23+
Please review Envoy integration version 1.71.0 [limitations][1].
24+
25+
## Envoy support
26+
27+
Only the Linux version and both the arm64 and arm64 architectures are supported.
28+
29+
<div class="alert alert-info">If you would like to see support added for any of
30+
the unsupported capabilities, let us know! Fill out <a
31+
href="https://forms.gle/gHrxGQMEnAobukfn7">this short form to send
32+
details</a>.</div>
33+
34+
[1]: /security/application_security/threats/setup/threat_detection/envoy

‎content/en/security/application_security/threats/setup/threat_detection/envoy.md

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: Enabling ASM for Envoy
3+
code_lang: envoy
4+
type: multi-code-lang
5+
code_lang_weight: 50
6+
aliases:
7+
- /security_platform/application_security/getting_started/envoy
8+
- /security/application_security/getting_started/envoy
9+
- /security/application_security/enabling/tracing_libraries/threat_detection/envoy/
10+
further_reading:
11+
- link: 'https://github.com/DataDog/dd-trace-go/tree/main/contrib/envoyproxy/go-control-plane/cmd/serviceextensions'
12+
tag: "Source Code"
13+
text: "Envoy integration's source code"
14+
- link: "/security/default_rules/?category=cat-application-security"
15+
tag: "Documentation"
16+
text: "OOTB Application Security Management Rules"
17+
- link: "/security/application_security/troubleshooting"
18+
tag: "Documentation"
19+
text: "Troubleshooting Application Security Management"
20+
---
21+
22+
You can enable application security for the Envoy proxy. The Datadog Envoy integration has support for threat detection and blocking.
23+
24+
## Prerequisites
25+
26+
- The [Datadog Agent][1] is installed and configured for your application's operating system or container, cloud, or virtual environment.
27+
- [Configure the Agent with Remote Configuration][2] to be able to block attackers from the Datadog UI.
28+
29+
## Enabling threat detection
30+
### Get started
31+
32+
The ASM Envoy integration is using the External Processing filter of Envoy.
33+
34+
1. **Configure Envoy** to use the [External Processing filter][3].
35+
For example:
36+
```yaml
37+
http_filters:
38+
# ... other filters
39+
- name: envoy.filters.http.ext_proc
40+
typed_config:
41+
"@type": type.googleapis.com/envoy.extensions.filters.http.ext_proc.v3.ExternalProcessor
42+
config:
43+
grpc_service:
44+
envoy_grpc:
45+
cluster_name: datadog_ext_proc_cluster
46+
timeout: 1s
47+
48+
clusters:
49+
# ... other clusters
50+
- name: datadog_ext_proc_cluster
51+
type: STRICT_DNS
52+
lb_policy: ROUND_ROBIN
53+
http2_protocol_options: {}
54+
transport_socket:
55+
name: envoy.transport_sockets.tls
56+
typed_config:
57+
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
58+
load_assignment:
59+
cluster_name: datadog_ext_proc_cluster
60+
endpoints:
61+
- lb_endpoints:
62+
- endpoint:
63+
address:
64+
socket_address:
65+
address: Your Datadog image host from step 2
66+
port_value: 443
67+
```
68+
69+
**Note**: you need to replace `Your Datadog image host from step 2` with the host where the Datadog Envoy docker image is running.
70+
71+
You can find more configuration options available in the [Envoy External Processor documentation][4].
72+
73+
2. **Spin up a new container with the Datadog Envoy docker image.** The image is available on the [Datadog Go tracer GitHub Registry][5].
74+
75+
**Note**: Envoy integration is done using the [Datadog Go Tracer][6], the image is tagged with the same version as the tracer. The docker image is updated in the same release process as the tracer.
76+
77+
The docker image expose some configuration specifically for the Envoy integration:
78+
| Environment variable | Default value | Description |
79+
|----------------------------------------|-----------------|-------------------------------------------------------------------|
80+
| `DD_SERVICE_EXTENSION_HOST` | `0.0.0.0` | gRPC server listening address. |
81+
| `DD_SERVICE_EXTENSION_PORT` | `443` | gRPC server port. |
82+
| `DD_SERVICE_EXTENSION_HEALTHCHECK_PORT`| `80` | HTTP server port for health checks. |
83+
84+
As the integration is using the Datadog Go Tracer, it inherits all environment variables from the tracer. You can find more information in [Configuring the Go Tracing Library][7] and [ASM Library Configuration][8].
85+
86+
The Datadog Agent needs to be configured to receive traces from the integration:
87+
| Environment variable | Default value | Description |
88+
|----------------------------------------|---------------|-----------------------------------------------------------------------|
89+
| `DD_AGENT_HOST` | `localhost` | Hostname where your Datadog Agent is running. |
90+
| `DD_TRACE_AGENT_PORT` | `8126` | Port of the Datadog Agent for trace collection. |
91+
92+
{{% appsec-getstarted-2-plusrisk %}}
93+
94+
{{< img src="/security/application_security/appsec-getstarted-threat-and-vuln_2.mp4" alt="Video showing Signals explorer and details, and Vulnerabilities explorer and details." video="true" >}}
95+
96+
## Limitations
97+
98+
As of version `1.71.0` the available functionality has the following important limitations:
99+
100+
* The request body is not inspected, regardless of its content type.
101+
102+
## Further Reading
103+
104+
{{< partial name="whats-next/whats-next.html" >}}
105+
106+
[1]: https://app.datadoghq.com/account/settings#agent
107+
[2]: https://docs.datadoghq.com/agent/remote_config/?tab=configurationyamlfile#enabling-remote-configuration
108+
[3]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_proc_filter
109+
[4]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/ext_proc.proto#extensions-filters-http-ext-proc-v3-externalprocessor
110+
[5]: https://github.com/DataDog/dd-trace-go/pkgs/container/dd-trace-go%2Fservice-extensions-callout
111+
[6]: https://github.com/DataDog/dd-trace-go
112+
[7]: https://docs.datadoghq.com/tracing/trace_collection/library_config/go/
113+
[8]: https://docs.datadoghq.com/security/application_security/threats/library_configuration/

‎content/en/security/application_security/threats/setup/threat_detection/gcp-service-extensions.md

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: Enabling ASM for GCP Service Extensions
3+
code_lang: gcp-service-extensions
4+
type: multi-code-lang
5+
code_lang_weight: 50
6+
aliases:
7+
- /security_platform/application_security/getting_started/gcp-service-extensions
8+
- /security/application_security/getting_started/gcp-service-extensions
9+
- /security/application_security/enabling/tracing_libraries/threat_detection/gcp-service-extensions/
10+
further_reading:
11+
- link: 'https://github.com/DataDog/dd-trace-go/tree/main/contrib/envoyproxy/go-control-plane/cmd/serviceextensions'
12+
tag: "Source Code"
13+
text: "ASM Service Extension's source code"
14+
- link: 'https://cloud.google.com/service-extensions/docs/overview'
15+
tag: "Documentation"
16+
text: "Google Cloud Service Extensions overview"
17+
- link: "/security/default_rules/?category=cat-application-security"
18+
tag: "Documentation"
19+
text: "OOTB Application Security Management Rules"
20+
- link: "/security/application_security/troubleshooting"
21+
tag: "Documentation"
22+
text: "Troubleshooting Application Security Management"
23+
---
24+
25+
You can enable application security with GCP Service Extension within GCP Cloud Load Balancing. The Datadog ASM Service Extensions has support for threat detection and blocking.
26+
27+
## Prerequisites
28+
29+
- The [Datadog Agent][1] is installed and configured for your application's operating system or container, cloud, or virtual environment.
30+
- [Configure the Agent with Remote Configuration][2] to be able to block attackers from the Datadog UI.
31+
- In your GCP Project, verify that you have either the project owner or editor role, or else the relevant Compute Engine IAM roles: `compute.instanceAdmin.v1` (to spin up instances) and `compute.networkAdmin` (to set up load balancing).
32+
- A GCP project with a Cloud Load Balancer configured with your services. Your Cloud Load Balancer must be one of the [Application Load Balancer that supports Traffic Callouts][3].
33+
- Ensure that the Compute Engine API and Network Services API are enabled:
34+
```bash
35+
gcloud services enable compute.googleapis.com networkservices.googleapis.com
36+
```
37+
38+
## Enabling threat detection
39+
### Get started
40+
41+
On your GCP project, multiple steps are needed to fully create a Service Extension. Google Cloud provides guides to create [a callout backend service][4] and [create a Service Extension as a traffic extension][5].
42+
43+
You can find a the important steps to create a Service Extension with ASM below:
44+
45+
1. **Create a new VM Compute instance** using the Datadog Service Extension docker image. The image is available on the [Datadog Go tracer GitHub Registry][6].
46+
47+
**Note**: The ASM Service Extension is done using the [Datadog Go Tracer][7], the image is tagged with the same version as the tracer. The docker image is updated in the same release process as the tracer.
48+
49+
The docker image expose some configuration specifically for the ASM Service Extension:
50+
| Environment variable | Default value | Description |
51+
|----------------------------------------|-----------------|-------------------------------------------------------------------|
52+
| `DD_SERVICE_EXTENSION_HOST` | `0.0.0.0` | gRPC server listening address. |
53+
| `DD_SERVICE_EXTENSION_PORT` | `443` | gRPC server port. |
54+
| `DD_SERVICE_EXTENSION_HEALTHCHECK_PORT`| `80` | HTTP server port for health checks. |
55+
56+
57+
As the integration is using the Datadog Go Tracer, it inherits all environment variables from the tracer. You can find more information in [Configuring the Go Tracing Library][8] and [ASM Library Configuration][9].
58+
59+
The Datadog Agent needs to be configured to receive traces from the Service Extension:
60+
| Environment variable | Default value | Description |
61+
|----------------------------------------|---------------|-----------------------------------------------------------------------|
62+
| `DD_AGENT_HOST` | `localhost` | Hostname where your Datadog Agent is running. |
63+
| `DD_TRACE_AGENT_PORT` | `8126` | Port of the Datadog Agent for trace collection. |
64+
65+
2. **Add the VM to an unmanaged instance group.**
66+
67+
Specify `http:80` and `grpc:443` (or any other previously configured values) for the Port mappings of the instance group.
68+
69+
3. **Update the load balancer by creating a backend service and adding a backend.**
70+
71+
Create a callout backend service that uses the HTTP/2 protocol and has an HTTP health check:
72+
- Protocol: HTTP2
73+
- Port name: `grpc`
74+
- Region: us-west1
75+
- Health check port number: `80` (or any other previously configured value)
76+
- Finally add the instance group with the extension server as a backend to the backend service
77+
78+
4. **Create a Traffic Service Extension callout.**
79+
80+
In the Google Cloud console, go to the Service Extensions page and create a new Service Extension.
81+
- Correcly select the type of load balancer you are using
82+
- Select `Traffic extensions` as the type
83+
- Select your forwarding rules
84+
85+
When creating a new Extension Chain:
86+
- Insert `true` in the **Match condition** to send all traffic to the extension
87+
- Select `Callouts` as the **Programability type**
88+
- Select the backend service you created in the previous step
89+
- Select all **Events** from the list where you want ASM to run detection on
90+
91+
{{% appsec-getstarted-2-plusrisk %}}
92+
93+
{{< img src="/security/application_security/appsec-getstarted-threat-and-vuln_2.mp4" alt="Video showing Signals explorer and details, and Vulnerabilities explorer and details." video="true" >}}
94+
95+
## Limitations
96+
97+
As of version `1.71.0` the available functionality has the following important limitations:
98+
99+
* The request body is not inspected, regardless of its content type.
100+
101+
## Further Reading
102+
103+
{{< partial name="whats-next/whats-next.html" >}}
104+
105+
[1]: https://app.datadoghq.com/account/settings#agent
106+
[2]: https://docs.datadoghq.com/agent/remote_config/?tab=configurationyamlfile#enabling-remote-configuration
107+
[3]: https://cloud.google.com/service-extensions/docs/lb-extensions-overview#supported-lbs
108+
[4]: https://cloud.google.com/service-extensions/docs/configure-callout-backend-service
109+
[5]: https://cloud.google.com/service-extensions/docs/configure-traffic-extensions
110+
[6]: https://github.com/DataDog/dd-trace-go/pkgs/container/dd-trace-go%2Fservice-extensions-callout
111+
[7]: https://github.com/DataDog/dd-trace-go
112+
[8]: https://docs.datadoghq.com/tracing/trace_collection/library_config/go/
113+
[9]: https://docs.datadoghq.com/security/application_security/threats/library_configuration/

‎layouts/partials/security-platform/appsec-languages.html

+14
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,20 @@
5858
</div>
5959
</a>
6060
</div>
61+
<div class="col">
62+
<a class="card h-100" href="envoy">
63+
<div class="card-body text-center py-2 px-1">
64+
{{ partial "img.html" (dict "root" . "src" "integrations_logos/envoy.png" "class" "img-fluid" "alt" "envoy" "width" "400") }}
65+
</div>
66+
</a>
67+
</div>
68+
<div class="col">
69+
<a class="card h-100" href="gcp-service-extensions">
70+
<div class="card-body text-center py-2 px-1">
71+
{{ partial "img.html" (dict "root" . "src" "integrations_logos/google_cloud_platform.png" "class" "img-fluid" "alt" "GCP Service Extensions" "width" "400") }}
72+
</div>
73+
</a>
74+
</div>
6175
</div>
6276
</div>
6377
</div>

0 commit comments

Comments
 (0)