The AppSec SDK is available as tracer.appsec. It provides methods for user tracking, blocking, and custom security event tracking.
const tracer = require ( 'dd-trace' ). init ({ appsec: { enabled: true }, }) const appsec = tracer . appsec
AppSec must be enabled (DD_APPSEC_ENABLED=true or appsec: { enabled: true } in TracerOptions) for these methods to have effect. All methods are safe to call when AppSec is disabled — they become no-ops.
Methods setUser(user)Links an authenticated user to the current trace.
setUser ( user : User ): void
User properties. The id field is required. Unique identifier of the user.
Role the user is acting under.
Granted authorizations (e.g., OAuth2 scopes).
app . post ( '/login' , ( req , res ) => { const user = authenticate ( req . body ) if ( user ) { tracer . appsec . setUser ({ id: user . id , email: user . email , name: user . displayName , }) } })
isUserBlocked(user)Checks whether the given user should be blocked according to AppSec rules (e.g., a blocklist). If no user is currently linked to the trace, this method also links the given user.
isUserBlocked ( user : User ): boolean
The user to check. The id field is required.
true if the user should be blocked, false otherwise.
app . get ( '/dashboard' , ( req , res ) => { const user = req . session . user if ( tracer . appsec . isUserBlocked ( user )) { tracer . appsec . blockRequest ( req , res ) return // stop processing the request } res . render ( 'dashboard' ) })
blockRequest(req?, res?)Sends a “blocked” response based on the request Accept header and ends the response. After calling this method, you must stop processing the request.
blockRequest ( req ?: IncomingMessage , res ?: OutgoingMessage ): boolean
The request object. If omitted, the current request is used.
The response object. If omitted, the current response is used.
true if the blocking response was sent successfully, false otherwise.
You must stop processing the request after calling blockRequest(). Continued processing after blocking can result in unintended side effects.
if ( tracer . appsec . isUserBlocked ( user )) { tracer . appsec . blockRequest ( req , res ) return // always stop here }
Links a successful login event to the current trace.
trackUserLoginSuccessEvent ( user : User , metadata ?: { [key: string]: string }): void
Deprecated in favor of appsec.eventTrackingV2.trackUserLoginSuccess(). Use that instead for new code.
Properties of the authenticated user.
Custom string key-value pairs to attach to the event.
// Deprecated tracer . appsec . trackUserLoginSuccessEvent ( { id: 'user-123' , email: 'jane@example.com' }, { login_method: 'password' } ) // Use instead: tracer . appsec . eventTrackingV2 . trackUserLoginSuccess ( 'jane@example.com' , { id: 'user-123' , email: 'jane@example.com' }, { login_method: 'password' } )
Links a failed login event to the current trace.
trackUserLoginFailureEvent ( userId : string , exists : boolean , metadata ?: { [key: string]: string }): void
Deprecated in favor of appsec.eventTrackingV2.trackUserLoginFailure().
The user ID of the attempted login.
Whether the user ID exists in the system.
Custom string key-value pairs to attach to the event.
// Deprecated tracer . appsec . trackUserLoginFailureEvent ( 'unknown-user' , false ) // Use instead: tracer . appsec . eventTrackingV2 . trackUserLoginFailure ( 'unknown-user' , false )
Links a custom security event to the current trace.
trackCustomEvent ( eventName : string , metadata ?: { [key: string]: string }): void
The name of the custom event.
Custom string key-value pairs to attach to the event.
tracer . appsec . trackCustomEvent ( 'payment.high_value' , { amount: '9999.00' , currency: 'USD' , user_id: 'user-123' , })
eventTrackingV2The eventTrackingV2 sub-object provides the current generation of user event tracking methods.
Links a successful login event to the current trace. Also calls setUser() internally to link the user.
trackUserLoginSuccess ( login : string , user ?: User | null , metadata ?: any ): void trackUserLoginSuccess ( login : string , userId : string , metadata ?: any ): void
The login key (username, email) used to authenticate.
User properties object, a user ID string, or null.
Custom fields to attach to the event.
app . post ( '/login' , async ( req , res ) => { const user = await authenticate ( req . body . email , req . body . password ) if ( user ) { tracer . appsec . eventTrackingV2 . trackUserLoginSuccess ( req . body . email , { id: user . id , email: user . email }, { login_method: 'password' } ) req . session . userId = user . id res . redirect ( '/dashboard' ) } })
Links a failed login event to the current trace.
trackUserLoginFailure ( login : string , exists : boolean , metadata ?: any ): void trackUserLoginFailure ( login : string , metadata ?: any ): void
The login key used in the failed attempt.
Whether the login exists in the system.
Custom fields to attach to the event.
app . post ( '/login' , async ( req , res ) => { const exists = await userExists ( req . body . email ) tracer . appsec . eventTrackingV2 . trackUserLoginFailure ( req . body . email , exists , { ip: req . ip } ) res . status ( 401 ). json ({ error: 'Invalid credentials' }) })
