New

If you signed up before June 3, 2021, see the migration guide to learn about the recent API changes.

Signals

Castle's exposed signals for authenticated, risk-scored events

Note: this feature is enabled for environments created after April 19, 2021. Please contact Castle support if you would like to enable this feature for environments created before this date.

Summary

Castle exposes a variety of signals in the API response body.

Most signals appear only on the event from which they triggered. The exception to this is the “unapproved” signals (such as unapproved_country). These “unapproved” signals will continue to appear until the triggering device and/or context is approved. Approval occurs either via explicit feedback or automatically after several weeks of regular usage patterns by that end-user. Practically, this means that “new” signals (such as new_device or new_language) will only appear once.

Example

{
  "action": "challenge",
  "user_id": "d84bac6e-3ba8-490a-90ae-a4782b4f9f5a",
  "device_token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6InJtUllyb0haZFZuZFcyR1p6VzdPLWdSSkt1STciLCJxdWFsaWZpZXIiOiJBUUlDQ2pFeU1qYzFORE0wTkRVIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ._hCtxD77NRQhmPtmB5CP2EE1vb8KZa9j6hY1ee-SXMw",
  "risk": 0.93,
  "signals": {
    "bot_behavior": {},
    "proxy_ip": {},
    "disposable_email": {},
    "spoofed_device": {},
    "multiple_accounts_per_device": {}
  }
}

List of signals

Automated activity

NameDescription
bot_behaviorBot behavior can be detected even if the activity is originating from a legitimate device and/or IP address. By evaluating the way the device is held and how its user interacts with the application, non-human behavior can be detected based on data points triggered in a repetitive or unnatural manner.
credential_stuffingCredential stuffing is a automated type of attack in which stolen account credentials, in particular e-mail addresses, are used to gain unauthorized access to user accounts. Credential stuffing attacks, unlike credential cracking, do not attempt to guess any passwords with brute force, but rather leverage a list of leaked credentials.
generated_emailThis signal will enable you to catch automated attempts in which the attacker is either repeating the same email pattern or submitting completely random emails. The email provider may still be legitimate and non-disposable.
high_activity_accountExecuting a large volume of closely-spaced requests from the same user account is indicative of an automated attack or abuse. In contrast to traditional rate limiting, “High activity account” will look at a baseline of normal behavior for the user account to determine when to trigger.
high_activity_deviceExecuting a large volume of closely-spaced requests from the same device is indicative of an automated attack or abuse. In contrast to traditional rate limiting, “High activity device” will look at a baseline of normal behavior for the device to determine when to trigger.
high_activity_ipExecuting a large volume of closely-spaced requests from the same IP is indicative of an automated attack or abuse. In contrast to traditional rate limiting, “High activity IP” will look at a baseline of normal behavior for the IP to determine when to trigger.

Anomalous behavior

NameDescription
impossible_travelImpossible Travel is a calculation derived by comparing the user’s current location with their last known location, and assessing whether or not the trip is likely or even possible in the lapse of time between these two measurements. This can help prevent man-in-the-middle attacks, certain account takeovers, and many offshore attacks.
multiple_accounts_per_deviceThe device was used to log into multiple user accounts, which could be indicative of account abuse or promotion abuse.

Device data error

NameDescription
missing_device_dataThe data forwarded from the device to the server is empty. Possibly due to an attacker attempting to bypass the client-side analysis, however, it could also be due to a misconfigured integration.
invalid_device_dataThe data forwarded from the device to the server could not be interpreted, most likely due to a replay attack or tampering.

Device intelligence

NameDescription
spoofed_deviceDevice spoofing can be carried out in numerous ways, including using a generator designed to mimic the entire client context of the device, or by simply replacing the user agent string in the browser.
headless_browserA headless browser is a browser that can be used without a graphical interface. It can be controlled programmatically to automate attacks like web scraping, fake account registrations, and credit card testing.
http_client_libraryHTTP client libraries are used to send requests to an application with relatively little effort using a command line or a script. They are frequently used in less sophisticated but high-volume automated attacks and abuse.
web_crawlerA web crawler is an application that automatically searches and indexes documents on the Internet. It should be considered abnormal if an authenticated client is claiming to be a web crawler.

Email intelligence

NameDescription
disposable_email_domainA disposable email domain indicates that the email address was issued by a service that issues temporary inboxes that expire after a short period of time. Examples of these providers are Mailinator, TempMail, and Guerrilla Mail.
invalid_emailAn invalid email is an address that does not conform to internet email standards, or the email does not exist on the recipient’s server. Examples include addresses without the @ sign, addresses that include certain special characters and/or spaces, or failed SMTP authentication attempts.

IP intelligence

NameDescription
abuse_ipAn IP address that was recently found in one of the many publicly accessible abuse and spam databases.
datacenter_ipAn IP address belonging to a hosting provider, data center, or content delivery network can serve to provide anonymity, as well as be used to launch large-scale automated fraud campaigns.
proxy_ipProxy servers are used to mask the actual location of a user by routing their connection through another server, often at a remote location. This signal involves both identifying whether the IP address is included in known proxy lists, and running tests in the client to determine timezone and timing anomalies or the presence of a proxy server.
tor_ipTor anonymizes internet traffic and is frequently used by fraudsters to conceal their true identities. A Tor IP is an IP address that matches an entry in Tor’s official list of exit nodes, which is updated on a regular basis.

Unobserved characteristics

NameDescription
new_countryThis signal triggers when a user account was accessed from a new country. It only triggers once per user and country combination.
new_deviceThis signal triggers when a user account was accessed from a new device, but not for the first one. It only triggers once per device.
new_device_typeThis signal triggers when a user account was accessed from a new device type. It only triggers once per user and device type combination.
new_ispThis signal triggers when a user account was accessed from a new Internet Service Provider, ISP. It only triggers once per user and ISP combination.
new_languageThis signal triggers when a user account was accessed from a device using a new language setting. It only triggers once per user and language combination.
new_osThis signal triggers when a user account was accessed from a new operating system, OS. It only triggers once per user and OS combination.

Unapproved characteristics

NameDescription
unapproved_countryThis signal triggers when a user account was accessed from a new country. It’s different from “New country” in that it will keep triggering until the user completes a challenge or the country, becomes part of the user’s normal behavior.
unapproved_deviceThis signal triggers when a user account was accessed from a new device, but not for the first one. It’s different from “New device” in that it will keep triggering until the user completes a challenge, or the device becomes part of the user’s normal behavior.
unapproved_device_typeThis signal triggers when a user account was accessed from a new device type. It’s different from “New device type” in that it will keep triggering until the user completes a challenge, or the device type becomes part of the user’s normal behavior.
unapproved_ispThis signal triggers when a user account was accessed from a new Internet Service Provider, ISP. It’s different from “New ISP” in that it will keep triggering until the user completes a challenge, or the ISP becomes part of the user’s normal behavior.
unapproved_languageThis signal triggers when a user account was accessed from a device using a new language setting. It’s different from “New language” in that it will keep triggering until the user completes a challenge, or the language becomes part of the user’s normal behavior.
unapproved_osThis signal triggers when a user account was accessed from a new operating system, OS. It’s different from “New OS” in that it will keep triggering until the user completes a challenge, or the OS becomes part of the user’s normal behavior.