Account Takeover API

Overview

Account takeover (ATO) is when a fraudster gains control of an account that belongs to a genuine customer. Fraudsters can then make unauthorised transactions, sell the compromised accounts on and/or scrape personal information out of the account which can be sold.

Phishing, spyware and malware can all be used to commit more sophisticated ATO attacks. However, credential stuffing is the most common tactic used to launch ATO attacks.

Credential stuffing uses stolen username and password combinations to automate login requests in order to gain access to user accounts. Estimates on the average success rate of credential stuffing attacks range from 0.1-2% with a peak of 8% quoted by some sources.

Following a breach, stolen credentials are purchased on the darkweb and shared via cracking forums. Data breaches are therefore a major contributing factor to increasing levels of ATO attacks. Combined with high levels of password reuse, this is especially concerning.

Credential stuffing can be scripted by more skilled fraudsters. However, automated tools like Sentry MBA make credential stuffing very easy for anyone to commit. This means there is a range of actors involved in committing ATO; from sophisticated hackers through to teenagers looking to order a ‘free’ pizza.

ATO attacks have significant consequences for merchants. It’s not just the cost of replacing goods or refunding payments - it’s also the time spent by support teams dealing with angry customers and other teams tackling the legal and operational fallout. In addition, there is often significant reputational damage incurred.

How Ravelin Combats Account Takeover

Taking into account the nature of ATO, Ravelin have introduced a number of different ways to combat the issue.

Breached Credentials

Credential stuffing relies on a list of username and password combinations. In order to mitigate against this, we maintain a breached credentials database. Calls can be made to the database either via the v3/login event at login or via /v2/lookup/credentials/check during registration or password change to verify if we’ve seen the credentials in the wild. Though we cannot guarantee that every breached credential will be in our database, this can go a long way to preventing ATO. You can also search for and view users that have logged in with credentials that appear in our database - providing additional context during investigations.

Rate limits

We have added customizable rate limits at login around device, username and IP. Thresholds can be set for this depending on your specific operational requirements. Rate limits are useful for tackling high volume attacks.

In addition, we check for things we know can indicate that a user is a fraudster like proxies and TOR.

Rules

We can set ATO specific rules around device, username, IP and velocity. For example, if the same device tries to access X accounts within a set time frame. Rules are especially useful for tackling ‘low and slow’ volume attacks.

Collecting and surfacing login activity data

By leveraging data collected via v3/login event, we provide oversight of login activity within our dashboard. Login activity reporting is available to explore via our Analytics tool, making it easier to spot anomalies in ‘normal’ login activity across your customer base. In addition, you can interact with login data via a filterable login list and drill down to view login information for a specific customer on their customer profile.

Login Event

The point of login is a critical step in detecting account takeover. We want to prevent the malicious actor from being able to log in just like we want to prevent the fraudster from completing an order.

POST /v3/login?score=true

This is the endpoint used to tell Ravelin about every login attempt, both successful and unsuccessful. Unsuccessful logins can be important signals for an ATO attack. It will provide an ATO recommendation response if asked for via the query parameter score=true. Otherwise it will simply record the data without further processing.

{
    "device": {
      "approxDeviceIdRate": 0,
      "approxDeviceIdRateBlock": true,
      "approxIPAddressRate": 0,
      "approxIPAddressRateBlock": true,
      "browser": "string",
      "cookiesEnabled": true,
      "custom": {
        "additionalProp1": {},
        "additionalProp2": {},
        "additionalProp3": {}
      },
      "deviceId": "string",
      "firstSeen": "string",
      "ipAddress": "string",
      "location": {
        "city": "string",
        "country": "string",
        "custom": {
          "additionalProp1": {},
          "additionalProp2": {},
          "additionalProp3": {}
        },
        "geohash": "string",
        "latitude": 0,
        "longitude": 0,
        "neighbourhood": "string",
        "poBoxNumber": "string",
        "postalCode": "string",
        "region": "string",
        "street1": "string",
        "street2": "string",
        "zone": "string"
      },
      "manufacturer": "string",
      "model": "string",
      "os": "string",
      "screenResolution": "string",
      "type": "string",
      "userAgent": "string"
    },
    "location": {
      "city": "string",
      "country": "string",
      "custom": {
        "additionalProp1": {},
        "additionalProp2": {},
        "additionalProp3": {}
      },
      "geohash": "string",
      "latitude": 0,
      "longitude": 0,
      "neighbourhood": "string",
      "poBoxNumber": "string",
      "postalCode": "string",
      "region": "string",
      "street1": "string",
      "street2": "string",
      "zone": "string"
    },
    "login": {
      "approxUsernameRate": 0,
      "approxUsernameRateBlock": true,
      "authenticationMechanism": {
        "magiclink": {
          "email": "string",
          "failureReason": "string",
          "phoneNumber": "string",
          "success": true,
          "transport": "string"
        },
        "oneTimeCode": {
          "failureReason": "string",
          "success": true
        },
        "password": {
          "failureReason": "string",
          "passwordBcrypted": "string",
          "success": true
        },
        "recaptcha": {
          "failureReason": "string",
          "success": true
        },
        "rsaKey": {
          "failureReason": "string",
          "success": true
        },
        "smsCode": {
          "failureReason": "string",
          "phoneNumber": "string",
          "success": true
        },
        "social": {
          "failureReason": "string",
          "socialProvider": "string",
          "success": true
        },
        "u2f": {
          "failureReason": "string",
          "success": true
        }
      },
      "custom": {
        "additionalProp1": {},
        "additionalProp2": {},
        "additionalProp3": {}
      },
      "customerId": "string",
      "loginId": "string",
      "success": true,
      "username": "string"
    },
    "timestamp": 0
  }

Above is the full login request object. This is similar to our /v2/login endpoint but with additional information regarding the authentication attempt. This request is expected to be sent after all successful and unsuccessful logins from your backend system.

Login

Device

Device is a required field on the login event. Both the deviceId and the IP address must be present in request and are vital to any ATO product. The deviceId can be generated via our javascript library. Details about that can be found in the device fingerprinting section. Any other details can be very useful but are not strictly necessary. For more details about device tracking please see our API and the Guide.

Location

Location is not required as we are aware you will not typically have a location at login time. If you do have location as part of your flow this can be very useful to localise ongoing or repeat attackers. Please see here for details about the location object: Location API

Responses

Success

You can see an example of a successful response from the /v3/login endpoint below. This response is identical to other responses given by the Ravelin platform for payment fraud endpoints. Note that we do provide payment fraud scores at login time as well. The Payment fraud and ATO responses are both included. Ensure you use the correct action when dealing with ATO vs. Payment Fraud.

Example response:

{
    "checks": {
      "additionalProp1": {
        "action": "string"
      },
      "additionalProp2": {
        "action": "string"
      },
      "additionalProp3": {
        "action": "string"
      }
    },
    "credentialStatus": {
      "passwordBreached": true,
      "usernameBreached": true
    },
    "data": {
      "action": "string",
      "ato": {
        "action": "string",
        "rules": {
          "passiveAction": "string",
          "triggered": [
            {
              "action": "string",
              "description": "string",
              "state": "string",
              "triggered": true
            }
          ]
        }
      },
      "cachedScore": true,
      "comment": "string",
      "connect": {
        "fraudulent": true
      },
      "customerId": "string",
      "effectiveTime": "string",
      "lookup": {
        "lookupAction": "string",
        "lookupResult": {
          "email": {
            "address": "string",
            "hasChargebacks": true,
            "reviewedAsFraudster": true
          },
          "hasChargebacks": true,
          "industry": "string",
          "ipAddress": {
            "address": "string",
            "fromTime": 0,
            "hasChargebacks": true,
            "reviewedAsFraudster": true,
            "toTime": 0
          },
          "reviewedAsFraudster": true,
          "telephone": {
            "hasChargebacks": true,
            "number": "string",
            "reviewedAsFraudster": true
          }
        }
      },
      "market": {
        "city": "string",
        "country": "string",
        "region": "string"
      },
      "rules": {
        "passiveAction": "string",
        "triggered": [
          {
            "action": "string",
            "description": "string",
            "state": "string",
            "triggered": true
          }
        ]
      },
      "score": 0,
      "scoreId": "string",
      "source": "string",
      "thresholds": {
        "prevent": 0,
        "review": 0
      },
      "warnings": [
        {
          "class": "string",
          "help": "string",
          "msg": "string",
          "state": "string"
        }
      ]
    },
    "message": "string",
    "status": 0,
    "success": "string",
    "timestamp": "string",
    "traceId": "string",
    "warnings": [
      {
        "docs": "string",
        "id": 0,
        "message": "string"
      }
    ]
  }

Failure

You can see an example of a failed response from the /v3/login endpoint below. A failure response will indicate why the failure happened and will try to direct you to relevant documentation.

{
    "docs": "string",
    "errors": [
      {
        "Docs": "string",
        "Error": "string",
        "Path": "string"
      }
    ],
    "message": "string",
    "retryable": true,
    "status": 0,
    "success": "string",
    "timestamp": "string",
    "traceId": "string"
  }

Action

Using the information supplied to Ravelin, logins and other events are categorized in one of three buckets: PERMIT WARN BLOCK

This information is sent in the response body to scored POST requests (with ?score=true) as defined above.

Requesting an action

Events sent to Ravelin using POST requests get an empty response body by default. The information is stored in our system and no further action is taken during the request. To force an immediate evaluation based on the information received up to and including an event add the ?score=true query parameter.

This will do two things: 1. Process the event payload 2. Force immediate recalculation of the action and return it

The score will be calculated based on the information in this event, and in all events previously received and met with a 200 OK status.

Suggested handling

The ?score=true query parameter is available on every event endpoint. This includes both ATO and Payment Fraud related endpoints. Specify it when you want to make a decision regarding a login attempt.

The most important field in the payload is action under the ATO object:

Other fields are provided for analytic and debugging purposes.

Credentials Check

POST /v2/lookup/credentials/check

Ravelin maintains an up to date list of breached credentials that can be found in the public domain. At login, you can view whether the login attempt was using breached credentials by looking at the credentialStatus object within the /v3/login response.

You can use the database to check if a user is attempting to register a new account, or update an existing one, with credentials that have been seen in the wild via our v2/lookup/credentials/check endpoint. The below request is expected to be sent at password creation or update. The response will tell you if the username and/or password is found in our breached credential database.

Request

{
    "username": "string",   
    "passwordHash": "string"
}

Response

{
    "usernameBreached": true,
    "passwordBreached": true
}

There are three distinct flows where we check if a users credentials have been breached. For each flow, you may want to take a different action. Below we have outlined what we suggest for each flow.

Authentication

While your backend is processing a login request, you can call our v3/login endpoint. Our response will indicate within the credential status object whether or not the username and password appear in Ravelin’s breached credential database.

...
"credentialStatus": {
    "usernameBreached": false,
    "passwordBreached": false
  },
...

...
"credentialStatus": {
    "usernameBreached": true,
    "passwordBreached": false
  },
...

...
"credentialStatus": {
    "usernameBreached": true,
    "passwordBreached": true
  },
...

Registration

At registration, you can call our v2/lookup/credentials/check endpoint. We will return the responses outlined below.

...
"credentialStatus": {
    "usernameBreached": false,
    "passwordBreached": false
  },
...

...
"credentialStatus": {
    "usernameBreached": true,
    "passwordBreached": false
  },
...

...
"credentialStatus": {
    "usernameBreached": true,
    "passwordBreached": true
  },
...

Account update

During an account update (e.g. forgot password, password change), you can call our v2/lookup/credentials/check endpoint. We will return the responses outlined below.

...
"credentialStatus": {
    "usernameBreached": false,
    "passwordBreached": false
  },
...

...
"credentialStatus": {
    "usernameBreached": true,
    "passwordBreached": false
  },
...

...
"credentialStatus": {
    "usernameBreached": true,
    "passwordBreached": true
  },
...