appsec

Documentation

Overview

Package appsec provides application security features in the form of SDK functions that can be manually called to monitor specific code paths and data. Application Security is currently transparently integrated into the APM tracer and cannot be used nor started alone at the moment. You can read more on how to enable and start Application Security for Go at https://docs.datadoghq.com/security_platform/application_security/getting_started/go

Index

• func MonitorParsedHTTPBody(ctx context.Context, body interface{})
• func TrackCustomEvent(ctx context.Context, name string, md map[string]string)
• func TrackUserLoginFailureEvent(ctx context.Context, uid string, exists bool, md map[string]string)
• func TrackUserLoginSuccessEvent(ctx context.Context, uid string, md map[string]string, ...)

Examples

• MonitorParsedHTTPBody
• MonitorParsedHTTPBody (CustomContext)
• TrackCustomEvent
• TrackUserLoginFailureEvent
• TrackUserLoginSuccessEvent

Functions

func MonitorParsedHTTPBody

func MonitorParsedHTTPBody(ctx context.Context, body interface{})

MonitorParsedHTTPBody runs the security monitoring rules on the given *parsed* HTTP request body. The given context must be the HTTP request context as returned by the Context() method of an HTTP request. Calls to this function are ignored if AppSec is disabled or the given context is incorrect. Note that passing the raw bytes of the HTTP request body is not expected and would result in inaccurate attack detection.

Example

Monitor HTTP request parsed body

package main

import (
	"encoding/json"
	"io"
	"net/http"

	"gopkg.in/DataDog/dd-trace-go.v1/appsec"

	httptrace "gopkg.in/DataDog/dd-trace-go.v1/contrib/net/http"
)

type parsedBodyType struct {
	Value string `json:"value"`
}

func customBodyParser(body io.ReadCloser) (*parsedBodyType, error) {
	var parsedBody parsedBodyType
	err := json.NewDecoder(body).Decode(&parsedBody)
	return &parsedBody, err
}

func main() {
	mux := httptrace.NewServeMux()
	mux.HandleFunc("/body", func(w http.ResponseWriter, r *http.Request) {
		// Use the SDK to monitor the request's parsed body
		body, err := customBodyParser(r.Body)
		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
		appsec.MonitorParsedHTTPBody(r.Context(), body)
		w.Write([]byte("Body monitored using AppSec SDK\n"))
	})
	http.ListenAndServe(":8080", mux)
}

Example (CustomContext)

Monitor HTTP request parsed body with a framework customized context type

r := echo.New()
r.Use(echotrace.Middleware())
r.POST("/body", func(c echo.Context) (e error) {
	req := c.Request()
	body, err := customBodyParser(req.Body)
	if err != nil {
		return c.String(http.StatusInternalServerError, err.Error())
	}
	// Use the SDK to monitor the request's parsed body
	appsec.MonitorParsedHTTPBody(c.Request().Context(), body)
	return c.String(http.StatusOK, "Body monitored using AppSec SDK")
})

r.Start(":8080")

func TrackCustomEvent

func TrackCustomEvent(ctx context.Context, name string, md map[string]string)

TrackCustomEvent sets a custom event as service entry span tags. This span is obtained through the given Go context which should contain the currently running span. This function does nothing when no span is found in the given Go context, along with an error message. Such events trigger the backend-side events monitoring ultimately blocking the IP address and/or user id associated to them.

Example

package main

import (
	"context"

	"gopkg.in/DataDog/dd-trace-go.v1/appsec"
	"gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
)

func main() {
	// Create an example span and set a custom appsec event example to it.
	span, ctx := tracer.StartSpanFromContext(context.Background(), "example")
	defer span.Finish()
	appsec.TrackCustomEvent(ctx, "my-custom-event", map[string]string{"region": "us-east-1"})

	// To go further in this example, you can add extra security-related context with the authenticated user id when the
	// request is being served for an authenticated user.
	tracer.SetUser(span, "user id")
}

func TrackUserLoginFailureEvent

func TrackUserLoginFailureEvent(ctx context.Context, uid string, exists bool, md map[string]string)

TrackUserLoginFailureEvent sets a failed user login event, with the given user id and the optional metadata, as service entry span tags. The exists argument allows to distinguish whether the given user id actually exists or not. The service entry span is obtained through the given Go context which should contain the currently running span. This function does nothing when no span is found in the given Go context and logs an error message instead. Such events trigger the backend-side events monitoring, such as the Account Take-Over (ATO) monitoring, ultimately blocking the IP address and/or user id associated to them.

Example

package main

import (
	"context"

	"gopkg.in/DataDog/dd-trace-go.v1/appsec"
	"gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
)

func main() {
	// Create an example span and set a user login failure appsec event example to it.
	span, ctx := tracer.StartSpanFromContext(context.Background(), "example")
	defer span.Finish()
	appsec.TrackUserLoginFailureEvent(ctx, "user id", false, nil)
}

func TrackUserLoginSuccessEvent

func TrackUserLoginSuccessEvent(ctx context.Context, uid string, md map[string]string, opts ...tracer.UserMonitoringOption)

TrackUserLoginSuccessEvent sets a successful user login event, with the given user id and optional metadata, as service entry span tags. It also calls tracer.SetUser() to set the currently identified user, along with the given tracer.UserMonitoringOption options. The service entry span is obtained through the given Go context which should contain the currently running span. This function does nothing when no span is found in the given Go context and logs an error message instead. Such events trigger the backend-side events monitoring, such as the Account Take-Over (ATO) monitoring, ultimately blocking the IP address and/or user id associated to them.

Example

package main

import (
	"context"

	"gopkg.in/DataDog/dd-trace-go.v1/appsec"
	"gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
)

func main() {
	// Create an example span and set a user login success appsec event example to it.
	span, ctx := tracer.StartSpanFromContext(context.Background(), "example")
	defer span.Finish()
	appsec.TrackUserLoginSuccessEvent(ctx, "user id", map[string]string{"region": "us-east-1"}, tracer.WithUserName("username"))
}