appsec

func MonitorHTTPResponseBody ¶ added in v2.1.0

func MonitorHTTPResponseBody(ctx context.Context, body any) error

MonitorHTTPResponseBody runs the security monitoring rules on the given response body (in object form, not encoded as the literal HTTP response body payload bytes), and returns an error if the HTTP response is configured to be blocked. The given context must be the HTTP request context as returned by the net/http.Request.Context method, or equivalent. Calls to this function are ignored if AppSec is disabled or the provided context is incorrect.

func MonitorParsedHTTPBody ¶

func MonitorParsedHTTPBody(ctx context.Context, body any) error

MonitorParsedHTTPBody runs the security monitoring rules on the given *parsed* HTTP request body and returns if the HTTP request is suspicious and configured to be blocked. 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. This function always returns nil when appsec is disabled.

func SetUser ¶

func SetUser(ctx context.Context, id string, opts ...tracer.UserMonitoringOption) error

SetUser wraps tracer.SetUser and extends it with user blocking. On top of associating the authenticated user information to the service entry span, it checks whether the given user ID is blocked or not by returning an error when it is. A user ID is blocked when it is present in your denylist of users to block at https://app.datadoghq.com/security/appsec/denylist When an error is returned, the caller must immediately abort its execution and the request handler's. The blocking response will be automatically sent by the APM tracer middleware on use according to your blocking configuration. This function always returns nil when appsec is disabled and doesn't block users.

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.

package main

import (
	"context"

	"github.com/DataDog/dd-trace-go/v2/appsec"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

func main() {
	// Create an example span and set a custom appsec event example to it.
	span, ctx := tracer.StartSpanFromContext(context.TODO(), "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 TrackUserLoginFailure ¶

func TrackUserLoginFailure(ctx context.Context, login string, exists bool, md map[string]string)

TrackUserLoginFailure denotes a failed user login event, which is used by back-end side event monitoring, such as Account Take-Over (ATO) monitoring, ultimately allowing IP address and/or user ID deny-lists to be configured in order to block associated malicious activity.

The login is the username that was provided by the user as part of the authentication attempt, and a single user may have multiple different logins (i.e; user name, email address, etc...).

The exists argument allows to distinguish whether the user for which a login attempt failed exists in the system or not, which is usedul when sifting through login activity in search for malicious behavior & compromise.

The provided metata is attached to the failed user login event.

package main

import (
	"context"

	"github.com/DataDog/dd-trace-go/v2/appsec"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

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

func TrackUserLoginSuccess ¶

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

TrackUserLoginSuccess denotes a successful user login event, which is used by back-end side event monitoring, such as Account Take-Over (ATO) monitoring, ultimately allowing IP address and/or user ID deny-lists to be configured in order to block associated malicious activity.

The login is the username that was provided by the user as part of the authentication attempt, and a single user may have multiple different logins (i.e; user name, email address, etc...). The user however has exactly one user ID which canonically identifies them.

The provided metadata is attached to the successful user login event.

This function calso calls SetUser with the provided user ID and login, as well as any provided [tracer.UserMonitoringOption]s, and returns an error if the provided user ID is found to be on a configured deny list. See the documentation for SetUser for more information.

package main

import (
	"context"

	"github.com/DataDog/dd-trace-go/v2/appsec"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

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