User Monitoring and Protection

Docs > Datadog Security > Application Security Management > Application Threat Management > User Monitoring and Protection

Overview

Instrument your services and track user activity to detect and block bad actors.

Add authenticated user information on traces to identify and block bad actors targeting your authenticated attack surface. To do this, set the user ID tag on the running APM trace, providing the necessary instrumentation for ASM to block authenticated attackers. This allows ASM to associate attacks and business logic events to users.

Track user logins and activity to detect account takeovers and business logic abuse with out-of-the-box detection rules, and to ultimately block attackers.

The custom user activity for which out-of-the-box detection rules are available are as follow:

Built-in event names	Required metadata	Related rules
`activity.sensitive`	`{ "name": "coupon_use", "required_role": "user" }`	Rate limited activity from IP Unauthorized activity detected
`users.login.success`	User ID is mandatory, optional metadata can be added	Credential Stuffing attack Bruteforce attack Distributed Credential Stuffing
`users.login.failure`	User ID and `usr.exists` are mandatory, optional metadata can be added	Credential Stuffing attack Bruteforce attack Distributed Credential Stuffing
`users.signup`	`{ "usr.id": "12345" }`	Excessive account creations from an IP
`users.delete`	`{ "usr.id": "12345" }`	Excessive account deletion from an IP
`users.password_reset`	`{ "usr.id": "12345", "usr.login": "user@email.com", "exists": true }`	Password reset brute force attempts
`payment.failure`	None	Excessive payment failures from IP

Adding authenticated user information to traces and enabling user blocking capability

Automated Detection of User Activity: Datadog Tracing Libraries attempt to detect and report user activity events automatically. For more information, see Disabling automatic user activity event tracking.

You can add custom tags to your root span, or use the instrumentation functions described below.

Use the Java tracer’s API for adding custom tags to a root span and add user information so that you can monitor authenticated requests in the application.

User monitoring tags are applied on the root span and start with the prefix usr followed by the name of the field. For example, usr.name is a user monitoring tag that tracks the user’s name.

Note: Check that you have added necessary dependencies to your application.

The example below shows how to obtain the root span, add the relevant user monitoring tags, and enable user blocking capability:

import io.opentracing.Span;
import io.opentracing.util.GlobalTracer;
import datadog.appsec.api.blocking.Blocking;
import datadog.trace.api.interceptor.MutableSpan;

// Get the active span
final Span span = GlobalTracer.get().activeSpan();
if ((span instanceof MutableSpan)) {
   MutableSpan localRootSpan = ((MutableSpan) span).getLocalRootSpan();
   // Setting the mandatory user id tag
   localRootSpan.setTag("usr.id", "d131dd02c56eec4");
   // Setting optional user monitoring tags
   localRootSpan.setTag("usr.name", "Jean Example");
   localRootSpan.setTag("usr.email", "jean.example@example.com");
   localRootSpan.setTag("usr.session_id", "987654321");
   localRootSpan.setTag("usr.role", "admin");
   localRootSpan.setTag("usr.scope", "read:message, write:files");
}

Blocking
    .forUser("d131dd02c56eec4")
    .blockIfMatch();

The .NET tracer package provides the SetUser() function, which allows you to monitor authenticated requests by adding user information to the trace.

The example below shows how to add the relevant user monitoring tags and enable user blocking capability:


using Datadog.Trace;

// ...

    var userDetails = new UserDetails()
    {
        // the systems internal identifier for the users
        Id = "d41452f2-483d-4082-8728-171a3570e930",
        // the email address of the user
        Email = "test@adventure-works.com",
        // the user's name, as displayed by the system
        Name = "Jane Doh",
        // the user's session id
        SessionId = "d0632156-132b-4baa-95b2-a492c5f9cb16",
        // the role the user is making the request under
        Role = "standard",
    };
    Tracer.Instance.ActiveScope?.Span.SetUser(userDetails);

For information and options, read the .NET tracer documentation.

The Go tracer package provides the SetUser() function, which allows you to monitor authenticated requests by adding user information to the trace. For more options, see the Go tracer documentation.

This example shows how to retrieve the current tracer span, use it to set user monitoring tags, and enable user blocking capability:

import "gopkg.in/DataDog/dd-trace-go.v1/appsec"
func handler(w http.ResponseWriter, r *http.Request) {
  if appsec.SetUser(r.Context(), "my-uid") != nil {
    // The user must be blocked by aborting the request handler asap.
    // The blocking response is automatically handled and sent by the appsec middleware.
    return 
  }
}

Use one of the following APIs to add user information to a trace so that you can monitor authenticated requests in the application:

Starting with ddtrace 1.1.0, the Datadog::Kit::Identity.set_user method is available. This is the recommended API for adding user information to traces:

# Get the active trace
trace = Datadog::Tracing.active_trace

# Set mandatory user id tag
Datadog::Kit::Identity.set_user(trace, id: 'd131dd02c56eeec4')

# Or set any of these optional user monitoring tags
Datadog::Kit::Identity.set_user(
  trace,

  # mandatory id
  id: 'd131dd02c56eeec4',

  # optional tags with known semantics
  name: 'Jean Example',
  email:, 'jean.example@example.com',
  session_id:, '987654321',
  role: 'admin',
  scope: 'read:message, write:files',

  # optional free-form tags
  another_tag: 'another_value',
)

If Datadog::Kit::Identity.set_user does not meet your needs, you can use set_tag instead.

User monitoring tags are applied on the trace and start with the prefix usr. followed by the name of the field. For example, usr.name is a user monitoring tag that tracks the user’s name.

The example below shows how to obtain the active trace and add relevant user monitoring tags:

Notes:

Tag values must be strings.
The usr.id tag is mandatory.

# Get the active trace
trace = Datadog::Tracing.active_trace

# Set mandatory user id tag
trace.set_tag('usr.id', 'd131dd02c56eeec4')

# Set optional user monitoring tags with known sematics
trace.set_tag('usr.name', 'Jean Example')
trace.set_tag('usr.email', 'jean.example@example.com')
trace.set_tag('usr.session_id', '987654321')
trace.set_tag('usr.role', 'admin')
trace.set_tag('usr.scope', 'read:message, write:files')

# Set free-form tags:
trace.set_tag('usr.another_tag', 'another_value')

The PHP tracer provides the \DDTrace\set_user() function, which allows you to monitor and block authenticated requests.

\DDTrace\set_user() adds the relevant user tags and metadata to the trace and automatically performs user blocking.

The following example shows how to set user monitoring tags and enable user blocking:

<?php
// Blocking is performed internally through the set_user call.
\DDTrace\set_user(
    // A unique identifier of the user is required.
    '123456789',

    // All other fields are optional.
    [
        'name' =>  'Jean Example',
        'email' => 'jean.example@example.com',
        'session_id' => '987654321',
        'role' => 'admin',
        'scope' => 'read:message, write:files',
    ]
);
?>

The Node tracer package provides the tracer.setUser(user) function, which allows you to monitor authenticated requests by adding user information to the trace.

The example below shows how to add relevant user monitoring tags and enable user blocking capability:

const tracer = require('dd-trace').init()

function handle () {
  tracer.setUser({
    id: '123456789', // *REQUIRED* Unique identifier of the user.

    // All other fields are optional.
    email: 'jane.doe@example.com', // Email of the user.
    name: 'Jane Doe', // User-friendly name of the user.
    session_id: '987654321', // Session ID of the user.
    role: 'admin', // Role the user is making the request under.
    scope: 'read:message, write:files', // Scopes or granted authorizations the user currently possesses.

    // Arbitrary fields are also accepted to attach custom data to the user (RBAC, Oauth, etc…)
    custom_tag: 'custom data'
  })

// Set the currently authenticated user and check whether they are blocked
if (tracer.appsec.isUserBlocked(user)) {  // also set the currently authenticated user
  return tracer.appsec.blockRequest(req, res) // blocking response is sent
  }

}

For information and options, read the Node.js tracer documentation.

Monitor authenticated requests by adding user information to the trace with the set_user function provided by the Python tracer package.

This example shows how to set user monitoring tags and enable user blocking capability:

from ddtrace.contrib.trace_utils import set_user
from ddtrace import tracer
# Call set_user() to trace the currently authenticated user id
user_id = "some_user_id"
set_user(tracer, user_id, name="John", email="test@test.com", scope="some_scope",
         role="manager", session_id="session_id", propagate=True)

A note on usr.id and usr.login: Investigation login abuse rely on two similar, but different concepts. usr.id contains the unique identifier of the user account in database. It's unique and immutable. It's unavailable when someone tries to log into a non-existant account. User blocking targets usr.id.
The user generally isn't aware of their user ID. Instead, they rely on mutable identifiers (phone number, username, email address...). The string used by the user to log into an account should be reported as usr.login in login events.
If no usr.login is provided, usr.id will be used instead.

Starting in dd-trace-java v1.8.0, you can use the Java tracer’s API to track user events.