Module: Datadog::Kit::AppSec::Events::V2

Defined in:
lib/datadog/kit/appsec/events/v2.rb

Overview

The second version of Business Logic Events SDK

Constant Summary collapse

LOGIN_SUCCESS_EVENT = 
'users.login.success'
LOGIN_FAILURE_EVENT = 
'users.login.failure'
TELEMETRY_METRICS_NAMESPACE = 
'appsec'
TELEMETRY_METRICS_SDK_EVENT = 
'sdk.event'
TELEMETRY_METRICS_SDK_VERSION = 
'v2'
TELEMETRY_METRICS_EVENTS_INTO_TYPES = 
{
  LOGIN_SUCCESS_EVENT => 'login_success',
  LOGIN_FAILURE_EVENT => 'login_failure'
}.freeze

Class Method Summary collapse

Class Method Details

.track_user_login_failure(login, user_exists = false, metadata = {}) ⇒ void

This method returns an undefined value.

Attach user login failure information to the service entry span and trigger AppSec event processing.

Examples:

Login only

Datadog::Kit::AppSec::Events::V2.('[email protected]')

With user existence and metadata

Datadog::Kit::AppSec::Events::V2.(
  '[email protected]',
  true,
  ip: '192.168.1.1', device: 'mobile', 'usr.country': 'US'
)

Parameters:

  • login (String) —

    The user login (e.g., username or email).

  • user_exists (Boolean) (defaults to: false) —

    Whether the user exists in the system.

  • metadata (Hash<Symbol, String>) (defaults to: {}) —

    Additional flat free-form metadata to attach to the event.

Raises:

  • (TypeError) 


97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/datadog/kit/appsec/events/v2.rb', line 97

def (, user_exists = false, metadata = {})
  trace = service_entry_trace
  span = service_entry_span

  if trace.nil? || span.nil?
    return Datadog.logger.warn(
      'Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events'
    )
  end

  raise TypeError, '`login` argument must be a String' unless .is_a?(String)
  raise TypeError, '`metadata` argument must be a Hash' unless metadata.is_a?(Hash)

  unless user_exists.is_a?(TrueClass) || user_exists.is_a?(FalseClass)
    raise TypeError, '`user_exists` argument must be a boolean'
  end

  set_span_tags(span, metadata, namespace: LOGIN_FAILURE_EVENT)
  span.set_tag('appsec.events.users.login.failure.track', 'true')
  span.set_tag('_dd.appsec.events.users.login.failure.sdk', 'true')
  span.set_tag('appsec.events.users.login.failure.usr.login', )
  span.set_tag('appsec.events.users.login.failure.usr.exists', user_exists.to_s)

  ::Datadog::AppSec::TraceKeeper.keep!(trace)

  record_event_telemetry_metric(LOGIN_FAILURE_EVENT)
  ::Datadog::AppSec::Instrumentation.gateway.push('appsec.events.user_lifecycle', LOGIN_FAILURE_EVENT)

  user = ::Datadog::AppSec::Instrumentation::Gateway::User.new(nil, )
  ::Datadog::AppSec::Instrumentation.gateway.push('identity.set_user', user)
end

.track_user_login_success(login, user_or_id = nil, metadata = {}) ⇒ void

This method returns an undefined value.

Attach user login success information to the service entry span and trigger AppSec event processing.

Examples:

Login only

Datadog::Kit::AppSec::Events::V2.('[email protected]')

Login and user attributes

Datadog::Kit::AppSec::Events::V2.(
  '[email protected]',
  { id: 'user-123', email: '[email protected]', name: 'Alice' },
  ip: '192.168.1.1', device: 'mobile', 'usr.country': 'US'
)

Parameters:

  • login (String) —

    The user login (e.g., username or email).

  • user_or_id (String, Hash<Symbol, String>) (defaults to: nil) —

    (optional) If a String, considered as a user ID, if a Hash, considered as a user attributes. The Hash must include ‘:id` as a key.

  • metadata (Hash<Symbol, String>) (defaults to: {}) —

    Additional flat free-form metadata to attach to the event.

Raises:

  • (TypeError) 


44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/datadog/kit/appsec/events/v2.rb', line 44

def (, user_or_id = nil, metadata = {})
  trace = service_entry_trace
  span = service_entry_span

  if trace.nil? || span.nil?
    return Datadog.logger.warn(
      'Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events'
    )
  end

  raise TypeError, '`login` argument must be a String' unless .is_a?(String)
  raise TypeError, '`metadata` argument must be a Hash' unless metadata.is_a?(Hash)

  user_attributes = build_user_attributes(user_or_id, )

  set_span_tags(span, metadata, namespace: LOGIN_SUCCESS_EVENT)
  set_span_tags(span, user_attributes, namespace: "#{LOGIN_SUCCESS_EVENT}.usr")
  span.set_tag('appsec.events.users.login.success.track', 'true')
  span.set_tag('_dd.appsec.events.users.login.success.sdk', 'true')

  ::Datadog::AppSec::TraceKeeper.keep!(trace)

  record_event_telemetry_metric(LOGIN_SUCCESS_EVENT)
  ::Datadog::AppSec::Instrumentation.gateway.push('appsec.events.user_lifecycle', LOGIN_SUCCESS_EVENT)

  # NOTE: Guard-clause will not work with Steep typechecking
  return Kit::Identity.set_user(trace, span, **user_attributes) if user_attributes.key?(:id) # steep:ignore

  # NOTE: This is a fallback for the case when we don't have an ID,
  #       but need to trigger WAF.
  user = ::Datadog::AppSec::Instrumentation::Gateway::User.new(nil, )
  ::Datadog::AppSec::Instrumentation.gateway.push('identity.set_user', user)
end