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 namesRequired metadataRelated rules
activity.sensitive{ "name": "coupon_use", "required_role": "user" }Rate limited activity from IP
Unauthorized activity detected
users.login.successUser ID is mandatory, optional metadata can be addedCredential Stuffing attack
Bruteforce attack
Distributed Credential Stuffing
users.login.failureUser ID and usr.exists are mandatory, optional metadata can be addedCredential 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.failureNoneExcessive 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.

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)

Adding business logic information (login success, login failure, any business logic) to traces

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-py v1.9.0, you can use the Python tracer’s API to track user events.

The following examples show how to track login events or custom events (using signup as an example).

from ddtrace.appsec.trace_utils import track_user_login_success_event
from ddtrace import tracer
metadata = {"usr.login": "user@email.com"}
# name, email, scope, role, session_id and propagate are optional arguments which 
# default to None except propagate that defaults to True. They'll be 
# passed to the set_user() function
track_user_login_success_event(tracer, "userid", metadata)
from ddtrace.appsec.trace_utils import track_user_login_failure_event
from ddtrace import tracer
metadata = {"usr.login": "user@email.com"}
# exists indicates if the failed login user exists in the system
exists = False
# if no numeric userId is available, any unique identifier will do (username, email...)
track_user_login_failure_event(tracer, "userid", exists, metadata)
from ddtrace.appsec.trace_utils import track_custom_event
from ddtrace import tracer
metadata = {"usr.id": "userid"}
event_name = "users.signup"
track_custom_event(tracer, event_name, metadata)

Tracking business logic information without modifying the code

If your service has ASM enabled and Remote Configuration enabled, you can create a custom WAF rule to flag any request it matches with a custom business logic tag. This doesn’t require any modification to your application, and can be done entirely from Datadog.

To get started, navigate to the Custom WAF Rule page and click on “Create New Rule”.

Access the Custom WAF Rule Menu from the ASM homepage by clicking on Protection, then In-App WAF and Custom Rules

This will open a menu in which you may define your custom WAF rule. By selecting the “Business Logic” category, you will be able to configure an event type (for instance, users.password_reset). You can then select the service you want to track, and a specific endpoint. You may also use the rule condition to target a specific parameter to identify the codeflow you want to instrument. When the condition matches, the library tags the trace and flags it to be forwarded to ASM. If you don’t need the condition, you may set a broad condition to match everything.

Screenshot of the form that appear when you click on the Create New Rule button

Once saved, the rule is deployed to instances of the service that have Remote Configuration enabled.

Automatic user activity event tracking

When ASM is enabled, Datadog Tracing Libraries attempt to detect user activity events automatically.

The events that can be automatically detected are:

  • users.login.success
  • users.login.failure
  • users.signup

Automatic user activity event tracking modes

Automatic user activity tracking offers the following modes:

  • identification mode (short name: ident):
    • This mode is the default and always collects the user ID or best effort.
    • The user ID is collected on login success and login failure. With failure, the user ID is collected regardless of whether the user exists or not.
    • When the instrumented framework doesn’t clearly provide a user ID, but rather a structured user object, the user ID is determined on a best effort basis based on the object field names. This list of field names are considered, ordered by priority:
      • id
      • email
      • username
      • login
      • user
    • If no user ID is available or found, the user event is not emitted.
  • anonymization mode (short name: anon):
    • This mode is the same as identification, but anonymizes the user ID by hashing (SHA256) it and cropping the resulting hash.
  • disabled mode:
    • ASM libraries do not collect any user ID from their automated instrumentations.
    • User login events are not emitted.
All modes only affect automated instrumentation. The modes don't apply to manual collection. Manual collection is configured using an SDK, and those settings are not overridden by automated instrumentation.

Manual configuration

Datadog libraries allow you to configure auto-instrumentation by using the DD_APPSEC_AUTO_USER_INSTRUMENTATION_MODE environment variable with the short name for the mode: ident|anon|disabled.

The default mode is identification mode (short name: ident).

For example, DD_APPSEC_AUTO_USER_INSTRUMENTATION_MODE=anon.

Deprecated modes

Previous modes are deprecated, but compatibility will be maintained until the next major release.

The following modes are deprecated:

  • safe mode: The trace library does not include any PII information on the events metadata. The tracer library tries to collect the user ID, and only if the user ID is a valid GUID
  • extended mode: The trace library tries to collect the user ID, and the user email. In this mode, Datadog does not check the type for the user ID to be a GUID. The trace library reports whatever value can be extracted from the event.

Note: There could be cases in which the trace library won’t be able to extract any information from the user event. The event would be reported with empty metadata. In those cases, use the SDK to manually instrument the user events.

Disabling user activity event tracking

To disable automated user activity detection through your ASM Software Catalog, change the automatic tracking mode environment variable DD_APPSEC_AUTO_USER_INSTRUMENTATION_MODE to disabled on the service you want to deactivate. All modes only affect automated instrumentation and require Remote Configuration to be enabled.

For manual configuration, you can set the environment variable DD_APPSEC_AUTOMATED_USER_EVENTS_TRACKING_ENABLED to false on your service and restart it. This must be set on the application hosting the Datadog Tracing Library, and not on the Datadog Agent.

Further Reading

PREVIEWING: hannahkm/clarify-v2-docs