Skip to content

Commit b5034b5

Browse files
eliottnesseliottness
committed
setup docs
Signed-off-by: Eliott Bouhana <[email protected]>
1 parent 718d86c commit b5034b5

File tree

3 files changed

+252
-136
lines changed

3 files changed

+252
-136
lines changed

‎content/en/security/application_security/setup/go.md

Lines changed: 0 additions & 136 deletions
This file was deleted.

‎content/en/security/application_security/setup/go/_index.md

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: Enabling App and API Protection for Go
3+
aliases:
4+
- /security_platform/application_security/getting_started/go
5+
- /security/application_security/getting_started/go
6+
- /security/application_security/threats/setup/threat_detection/go
7+
- /security/application_security/threats_detection/go
8+
further_reading:
9+
- link: "/security/application_security/add-user-info/"
10+
tag: "Documentation"
11+
text: "Adding user information to traces"
12+
- link: 'https://github.com/DataDog/dd-trace-go'
13+
tag: "Source Code"
14+
text: 'Go Datadog library source code'
15+
- link: "/security/default_rules/?category=cat-application-security"
16+
tag: "Documentation"
17+
text: "OOTB App and API Protection Rules"
18+
- link: "/security/application_security/troubleshooting"
19+
tag: "Documentation"
20+
text: "Troubleshooting App and API Protection"
21+
---
22+
{{< partial name="app_and_api_protection/callout.html" >}}
23+
24+
## Overview
25+
26+
App and API Protection leverages the [Datadog Go library][5] to monitor and secure your Go service. The library integrate seemlessly into your workflow using [Orchestrion][6] compile-time instrumentation without requiring any code changes.
27+
28+
For detailed compatibility information, including supported Go versions, frameworks, and deployment environments, see [Go Compatibility Requirements][2].
29+
30+
## Environments
31+
32+
### Hosts
33+
{{< appsec-integrations >}}
34+
{{< appsec-integration name="Linux" avatar="linux" link="./setup?tab=environmentvariable" >}}
35+
{{< appsec-integration name="macOS" avatar="apple" link="./setup?tab=environmentvariable" >}}
36+
{{< /appsec-integrations >}}
37+
38+
### Cloud and Container Platforms
39+
{{< appsec-integrations >}}
40+
{{< appsec-integration name="Docker" avatar="docker" link="./setup?tab=dockercli" >}}
41+
{{< appsec-integration name="Kubernetes" avatar="kubernetes" link="./setup?tab=kubernetes" >}}
42+
{{< /appsec-integrations >}}
43+
44+
### AWS
45+
{{< appsec-integrations >}}
46+
{{< appsec-integration name="AWS ECS" avatar="aws-fargate" link="./setup?tab=amazonecs" >}}
47+
{{< /appsec-integrations >}}
48+
49+
## Additional Resources
50+
51+
- [Compatibility Information][2]
52+
53+
[2]: /security/application_security/setup/compatibility/go
54+
[5]: https://github.com/DataDog/dd-trace-go/
55+
[6]: https://datadoghq.dev/orchestrion/
56+

‎content/en/security/application_security/setup/go/setup.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
title: Enabling App and API Protection for Go
3+
aliases:
4+
- /security_platform/application_security/getting_started/go
5+
- /security/application_security/getting_started/go
6+
- /security/application_security/threats/setup/threat_detection/go
7+
- /security/application_security/threats_detection/go
8+
further_reading:
9+
- link: "https://pkg.go.dev/github.com/DataDog/dd-trace-go/v2/appsec"
10+
tag: "Documentation"
11+
text: "Go Security API docs"
12+
- link: "/security/application_security/add-user-info/"
13+
tag: "Documentation"
14+
text: "Adding user information to traces"
15+
- link: 'https://github.com/DataDog/dd-trace-go'
16+
tag: "Source Code"
17+
text: 'Tracer source code'
18+
- link: 'https://github.com/DataDog/orchestrion'
19+
tag: "Source Code"
20+
text: 'Orchestrion source code'
21+
- link: "/security/default_rules/?category=cat-application-security"
22+
tag: "Documentation"
23+
text: "OOTB App and API Protection Rules"
24+
- link: "/security/application_security/troubleshooting"
25+
tag: "Documentation"
26+
text: "Troubleshooting App and API Protection"
27+
---
28+
29+
You can monitor App and API Protection for Go apps running in Docker, Kubernetes, and Amazon ECS.
30+
31+
{{% appsec-getstarted %}}
32+
33+
# Prerequisite
34+
35+
- Your service framework and tools are [compatible][2] with the [Application & API Protection (AAP)][1] product.
36+
- Your deployment environment is [supported][5].
37+
- You have one of the latest two version of [Go][4] installed (following the [Official Release Policy][5]).
38+
39+
## Enabling Application & API Protection (AAP)
40+
41+
### Get started
42+
43+
1. **Install [Orchestrion][10]**:
44+
```console
45+
$ go install github.com/DataDog/orchestrion@latest
46+
```
47+
48+
2. **Register Orchestrion as a Go module** in your project directory:
49+
```console
50+
$ orchestrion pin
51+
```
52+
53+
3. Datadog has a series of pluggable packages which provide out-of-the-box support for instrumenting a series of Go libraries and frameworks.
54+
A list of these packages can be found in the [compatibility requirements][1] page.
55+
Import these packages into your application and follow the configuration instructions listed alongside each integration.
56+
57+
4. **Recompile your program** with Orchestrion with the `appsec` build:
58+
```console
59+
$ orchestrion go build -tags appsec my-program
60+
```
61+
More options on how to use orchestrion can be found in the [Orchestrion usage][7].
62+
63+
Note: If you are building without [CGO][9] on linux. Please read [Building Go applications with CGO disabled][6] for more information.
64+
65+
5. **Redeploy your Go service and enable AAP** by setting the `DD_APPSEC_ENABLED` environment variable to `true`:
66+
67+
{{< tabs >}}
68+
{{% tab "Environment Variable" %}}
69+
70+
```console
71+
$ env DD_APPSEC_ENABLED=true ./my-program
72+
```
73+
74+
{{% /tab %}}
75+
{{% tab "Docker CLI" %}}
76+
77+
Add the following environment variable value to your Docker command line:
78+
79+
```console
80+
$ docker run -e DD_APPSEC_ENABLED=true [...]
81+
```
82+
83+
{{% /tab %}}
84+
{{% tab "Dockerfile" %}}
85+
86+
Add the following environment variable value to your application container's Dockerfile:
87+
88+
```Dockerfile
89+
ENV DD_APPSEC_ENABLED=true
90+
```
91+
92+
{{% /tab %}}
93+
{{% tab "Kubernetes" %}}
94+
95+
Update your application's deployment configuration file for APM and add the AAP environment variable:
96+
97+
```yaml
98+
spec:
99+
template:
100+
spec:
101+
containers:
102+
- name: <CONTAINER_NAME>
103+
image: <CONTAINER_IMAGE>/<TAG>
104+
env:
105+
- name: DD_APPSEC_ENABLED
106+
value: "true"
107+
```
108+
109+
{{% /tab %}}
110+
{{% tab "Amazon ECS" %}}
111+
112+
Update your application's ECS task definition JSON file, by adding this in the environment section:
113+
114+
```json
115+
"environment": [
116+
...,
117+
{
118+
"name": "DD_APPSEC_ENABLED",
119+
"value": "true"
120+
}
121+
]
122+
```
123+
124+
{{% /tab %}}
125+
126+
{{< /tabs >}}
127+
128+
{{% app_and_api_protection_verify_setup %}}
129+
130+
{{% appsec-getstarted-2 %}}
131+
132+
{{< 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" >}}
133+
134+
### Building without CGO
135+
136+
If you are building your Go application without [CGO][9], you can still enable AAP by following these steps:
137+
138+
1. **Add the `appsec` build tag** when compiling your application:
139+
```console
140+
$ CGO_ENABLED=0 orchestrion go build -tags appsec my-program
141+
```
142+
143+
Beware, using `CGO_ENABLED=0` usually guarantees a statically-linked binary. This is NOT be the case in this setup.
144+
145+
2. **Install `libc.so.6` and `libpthread.so.0`** on your system, as these libraries are required by the Datadog WAF:
146+
This can be done by installing the `glibc` package on your system with your package manager. Read more on [Creating a Dockerfile for AAP][3]
147+
148+
3. **Redeploy your Go service** with the `DD_APPSEC_ENABLED=true` environment variable set, as described above.
149+
150+
### Building with Bazel
151+
152+
If you are using Bazel and [rules_go][12] to build your Go application, [orchestrion][7] is not compatible with Bazel.
153+
Instead, you can use the [Datadog Go Tracer library][11] to instrument your application manually.
154+
155+
AAP relies on [purego][13] to support its C++ biddings to DataDog's WAF which requires special attention inside the
156+
`repositories.bzl` generated by Gazelle. Under the `go_repository` rule for `com_github_ebitengine_purego`,
157+
you need to add the `build_directives` attribute with the `gazelle:build_tags cgo` directive. Like seen here:
158+
159+
```starlark
160+
go_repository(
161+
name = "com_github_ebitengine_purego",
162+
build_directives = [
163+
"gazelle:build_tags cgo",
164+
]
165+
build_file_proto_mode = "disable",
166+
importpath = "github.com/ebitengine/purego",
167+
sum = "<your-checksum>",
168+
version = "v0.8.3",
169+
)
170+
```
171+
172+
## Using AAP without APM tracing
173+
174+
If you want to use Application & API Protection without APM tracing functionality, you can deploy with tracing disabled:
175+
176+
1. Configure your tracing library with the `DD_APM_TRACING_ENABLED=false` environment variable in addition to the `DD_APPSEC_ENABLED=true` environment variable.
177+
2. This configuration reduces the amount of APM data sent to Datadog to the minimum required by App and API Protection products.
178+
179+
For more details, see [Standalone App and API Protection][8].
180+
181+
## Further Reading
182+
183+
{{< partial name="whats-next/whats-next.html" >}}
184+
185+
[1]: /security/application_security/setup/compatibility/go/?tab=v2#web-framework-compatibility
186+
[2]: /security/application_security/setup/compatibility/go/
187+
[4]: https://go.dev/
188+
[5]: https://go.dev/doc/devel/release#policy
189+
[6]: /security/application_security/setup/go#building-without-cgo
190+
[7]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/go/?tab=compiletimeinstrumentation#usage
191+
[8]: /security/application_security/guide/standalone_application_security/
192+
[9]: https://go.dev/wiki/cgo
193+
[10]: https://datadoghq.dev/orchestrion
194+
[11]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/go/?tab=manualinstrumentation#add-the-tracer-library-to-your-application
195+
[12]: https://github.com/bazel-contrib/rules_go
196+
[13]: https://github.com/ebitengine/purego

0 commit comments

Comments
 (0)