diff --git a/content/en/security/application_security/setup/go.md b/content/en/security/application_security/setup/go.md deleted file mode 100644 index b2bbbb95afe87..0000000000000 --- a/content/en/security/application_security/setup/go.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Enabling AAP for Go -code_lang: go -type: multi-code-lang -code_lang_weight: 20 -aliases: - - /security_platform/application_security/getting_started/go - - /security/application_security/getting_started/go - - /security/application_security/enabling/tracing_libraries/threat_detection/go/ - - /security/application_security/threats/setup/threat_detection/go - - /security/application_security/threats_detection/go - - /security/application_security/setup/aws/fargate/go -further_reading: - - link: "/security/application_security/add-user-info/" - tag: "Documentation" - text: "Adding user information to traces" - - link: 'https://github.com/DataDog/dd-trace-go/tree/v1' - tag: "Source Code" - text: 'Go Datadog library source code' - - link: "/security/default_rules/?category=cat-application-security" - tag: "Documentation" - text: "OOTB App and API Protection Rules" - - link: "/security/application_security/troubleshooting" - tag: "Documentation" - text: "Troubleshooting App and API Protection" ---- - -You can monitor App and API Protection for Go apps running in Docker, Kubernetes, and Amazon ECS. - -{{% appsec-getstarted %}} -- Your service is [supported][2]. - -## Enabling threat detection -### Get started - -1. **Add to your program's go.mod dependencies** the latest version of the Datadog Go library (version 1.53.0 or later). {{% tracing-go-v2 %}} - - ```shell - $ go get -v -u github.com/DataDog/dd-trace-go/v2/ddtrace/tracer - ``` - -2. Datadog has a series of pluggable packages which provide out-of-the-box support for instrumenting a series of Go libraries and frameworks. - A list of these packages can be found in the [compatibility requirements][1] page. Import these packages into your application and follow the configuration instructions listed alongside each integration. - -3. **Recompile your program** with AAP enabled: - ```console - $ go build -v -tags appsec my-program - ``` - - **Notes**: - - The Go build tag `appsec` is not necessary if CGO is enabled with `CGO_ENABLED=1`. - - Datadog WAF needs the following shared libraries on Linux: `libc.so.6` and `libpthread.so.0`. - - When using the build tag `appsec` and CGO is disabled, the produced binary is still linked dynamically to these libraries. - - The Go build tag `datadog.no_waf` can be used to disable AAP at build time in any situation where the requirements above are a hinderance. - -4. **Redeploy your Go service and enable AAP** by setting the `DD_APPSEC_ENABLED` environment variable to `true`: - ```console - $ env DD_APPSEC_ENABLED=true ./my-program - ``` - - Or one of the following methods, depending on where your application runs: - - {{< tabs >}} -{{% tab "Docker CLI" %}} - -Add the following environment variable value to your Docker command line: - -```console -$ docker run -e DD_APPSEC_ENABLED=true [...] -``` - -{{% /tab %}} -{{% tab "Dockerfile" %}} - -Add the following environment variable value to your application container's Dockerfile: - -```Dockerfile -ENV DD_APPSEC_ENABLED=true -``` - -{{% /tab %}} -{{% tab "Kubernetes" %}} - -Update your application's deployment configuration file for APM and add the AAP environment variable: - -```yaml -spec: - template: - spec: - containers: - - name: - image: / - env: - - name: DD_APPSEC_ENABLED - value: "true" -``` - -{{% /tab %}} -{{% tab "Amazon ECS" %}} - -Update your application's ECS task definition JSON file, by adding this in the environment section: - -```json -"environment": [ - ..., - { - "name": "DD_APPSEC_ENABLED", - "value": "true" - } -] -``` - -{{% /tab %}} - -{{< /tabs >}} - -{{% appsec-getstarted-2 %}} - -{{< 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" >}} - -## Using AAP without APM tracing - -If you want to use Application & API Protection without APM tracing functionality, you can deploy with tracing disabled: - -1. Configure your tracing library with the `DD_APM_TRACING_ENABLED=false` environment variable in addition to the `DD_APPSEC_ENABLED=true` environment variable. -2. This configuration will reduce the amount of APM data sent to Datadog to the minimum required by App and API Protection products. - -For more details, see [Standalone App and API Protection][standalone_billing_guide]. -[standalone_billing_guide]: /security/application_security/guide/standalone_application_security/ - -## Further Reading - -{{< partial name="whats-next/whats-next.html" >}} - -[1]: /security/application_security/setup/compatibility/go/#web-framework-compatibility -[2]: /security/application_security/setup/compatibility/go/ diff --git a/content/en/security/application_security/setup/go/_index.md b/content/en/security/application_security/setup/go/_index.md new file mode 100644 index 0000000000000..fc11994193c74 --- /dev/null +++ b/content/en/security/application_security/setup/go/_index.md @@ -0,0 +1,196 @@ +-- +title: Enabling App and API Protection for Go +aliases: + - /security_platform/application_security/getting_started/go + - /security/application_security/getting_started/go + - /security/application_security/threats/setup/threat_detection/go + - /security/application_security/threats_detection/go +further_reading: +- link: "https://pkg.go.dev/github.com/DataDog/dd-trace-go/v2/appsec" + tag: "Documentation" + text: "Go Security API docs" +- link: "/security/application_security/add-user-info/" + tag: "Documentation" + text: "Adding user information to traces" +- link: 'https://github.com/DataDog/dd-trace-go' + tag: "Source Code" + text: 'Tracer source code' +- link: 'https://github.com/DataDog/orchestrion' + tag: "Source Code" + text: 'Orchestrion source code' +- link: "/security/default_rules/?category=cat-application-security" + tag: "Documentation" + text: "OOTB App and API Protection Rules" +- link: "/security/application_security/troubleshooting" + tag: "Documentation" + text: "Troubleshooting App and API Protection" +--- + +You can monitor App and API Protection for Go apps running in Docker, Kubernetes, and Amazon ECS. + +{{% appsec-getstarted %}} + +# Prerequisite + +- Your service framework and tools are [compatible][2] with the [Application & API Protection (AAP)][1] product. +- Your deployment environment is [supported][5]. +- You have one of the latest two version of [Go][4] installed (following the [Official Release Policy][5]). + +## Enabling Application & API Protection (AAP) +### Get started + +1. **Install [Orchestrion][10]**: + ```console + $ go install github.com/DataDog/orchestrion@latest + ``` + +2. **Register Orchestrion as a Go module** in your project directory: + ```console + $ orchestrion pin + ``` + +3. Datadog has a series of pluggable packages which provide out-of-the-box support for instrumenting a series of Go libraries and frameworks. + A list of these packages can be found in the [compatibility requirements][1] page. + Import these packages into your application and follow the configuration instructions listed alongside each integration. + +4. **Recompile your program** with Orchestrion: + ```console + $ orchestrion go build my-program + ``` + More options on how to use orchestrion can be found in the [Orchestrion usage][7]. + + Note: If you are building without [CGO][9] on linux. Please read [Building Go applications with CGO disabled][6] for more information. + +5. **Redeploy your Go service and enable AAP** by setting the `DD_APPSEC_ENABLED` environment variable to `true`: + ```console + $ env DD_APPSEC_ENABLED=true ./my-program + ``` + + Or one of the following methods, depending on where your application runs: + + {{< tabs >}} +{{% tab "Docker CLI" %}} + +Add the following environment variable value to your Docker command line: + +```console +$ docker run -e DD_APPSEC_ENABLED=true [...] +``` + +{{% /tab %}} +{{% tab "Dockerfile" %}} + +Add the following environment variable value to your application container's Dockerfile: + +```Dockerfile +ENV DD_APPSEC_ENABLED=true +``` + +A more detailed guide on how to create a fitting dockerfile is available [here][3]. + +{{% /tab %}} +{{% tab "Kubernetes" %}} + +Update your application's deployment configuration file for APM and add the AAP environment variable: + +```yaml +spec: + template: + spec: + containers: + - name: + image: / + env: + - name: DD_APPSEC_ENABLED + value: "true" +``` + +{{% /tab %}} +{{% tab "Amazon ECS" %}} + +Update your application's ECS task definition JSON file, by adding this in the environment section: + +```json +"environment": [ + ..., + { + "name": "DD_APPSEC_ENABLED", + "value": "true" + } +] +``` + +{{% /tab %}} + +{{< /tabs >}} + +{{% app_and_api_protection_verify_setup %}} + +{{% appsec-getstarted-2 %}} + +{{< 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" >}} + +### Building without CGO + +If you are building your Go application without [CGO][9], you can still enable AAP by following these steps: + +1. **Add the `appsec` build tag** when compiling your application: + ```console + $ CGO_ENABLED=0 orchestrion go build -tags appsec my-program + ``` + + Beware, using `CGO_ENABLED=0` usually guarantees a statically-linked binary. This is NOT be the case in this setup. + +2. **Install `libc.so.6` and `libpthread.so.0`** on your system, as these libraries are required by the Datadog WAF: + 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] + +3. **Redeploy your Go service** with the `DD_APPSEC_ENABLED=true` environment variable set, as described above. + +### Building with Bazel + +If you are using Bazel and [rules_go][12] to build your Go application, [orchestrion][7] is not compatible with Bazel. +Instead, you can use the [Datadog Go Tracer library][11] to instrument your application manually. + +AAP relies on [purego][13] to support its C++ biddings to DataDog's WAF which requires special attention inside the +`repositories.bzl` generated by Gazelle. Under the `go_repository` rule for `com_github_ebitengine_purego`, +you need to add the `build_directives` attribute with the `gazelle:build_tags cgo` directive. Like seen here: + +```starlark + go_repository( + name = "com_github_ebitengine_purego", + build_directives = [ + "gazelle:build_tags cgo", + ] + build_file_proto_mode = "disable", + importpath = "github.com/ebitengine/purego", + sum = "", + version = "v0.8.3", + ) +``` + +## Using AAP without APM tracing + +If you want to use Application & API Protection without APM tracing functionality, you can deploy with tracing disabled: + +1. Configure your tracing library with the `DD_APM_TRACING_ENABLED=false` environment variable in addition to the `DD_APPSEC_ENABLED=true` environment variable. +2. This configuration reduces the amount of APM data sent to Datadog to the minimum required by App and API Protection products. + +For more details, see [Standalone App and API Protection][8]. + +## Further Reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: /security/application_security/setup/compatibility/go/?tab=v2#web-framework-compatibility +[2]: /security/application_security/setup/compatibility/go/ +[3]: /security/application_security/setup/go/dockerfile +[4]: https://go.dev/ +[5]: https://go.dev/doc/devel/release#policy +[6]: /security/application_security/setup/go#building-without-cgo +[7]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/go/?tab=compiletimeinstrumentation#usage +[8]: /security/application_security/guide/standalone_application_security/ +[9]: https://go.dev/wiki/cgo +[10]: https://datadoghq.dev/orchestrion +[11]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/go/?tab=manualinstrumentation#add-the-tracer-library-to-your-application +[12]: https://github.com/bazel-contrib/rules_go +[13]: https://github.com/ebitengine/purego