How To Protect Login

Sending login events for risk scoring

How to instrument the login flow so that BotBye risk scoring can detect account takeover, credential stuffing and brute-force attacks.

Send an event for every attempt

Risk scoring works by spotting patterns, and the strongest signals for account takeover, credential stuffing and brute-force come from the failed attempts, not the successful ones. Several detections are driven entirely by failed logins:

  • repeated failures against a single account (password guessing)
  • many failures from one IP (brute force)
  • one IP trying many different logins, whether or not the accounts exist (credential stuffing, account enumeration)

If only successful logins are reported, these counters stay at zero and the engine has nothing to score against. Successful events alone can't tell a legitimate user from an attacker who finally guessed right.

Send the event on every login attempt, whatever the result. Don't make the call conditional on a successful login (a common mistake is if (loginSucceeded) evaluate(...)) — that hides exactly the failed attempts the engine needs.

Set the status to the real outcome

  • "SUCCESSFUL" — credentials were correct, login granted
  • "FAILED" — login was rejected. This covers both a wrong password on an existing account and an attempt against an account that doesn't exist
  • "ATTEMPTED" — optional, for an intermediate step (e.g. password ok, waiting on 2FA)

Map the user fields

Set status, accountId and username per outcome:

Case status accountId username
Existing account, correct password SUCCESSFUL real account id submitted login
Existing account, wrong password FAILED real account id submitted login
Login attempt to a non-existent account FAILED empty string "" submitted login (as typed)

Don't put a placeholder in accountId. For an attempt against an account that doesn't exist, leave accountId empty rather than sending something like "unknown". A constant value would collapse every non-existent-account attempt into one synthetic account: it inflates the per-account counters and makes account enumeration look like a single account. An empty accountId is automatically excluded from per-account metrics, while the attempt is still captured by the IP-level signals — which is exactly what detects this kind of probing.

Put the login the user submitted in username, exactly as typed: it doesn't have to match a real account, and it is what counts the different logins tried from one IP. Send it on every attempt.

Prefer not to send the raw login? Send a stable pseudonym in username instead, for example sha256(lowercase(trim(login)) + secret_salt). Only equality between values matters, so a consistent hash works as well as the plain login; keep the salt and normalisation fixed. Don't use such a hash as accountId: every typed login would become a separate user.

Example (Node SDK)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
async function handleLogin({ ip, headers, method, url, token, login, password }) {
  const user = await findUserByLogin(login);
  const loginSucceeded = !!user && (await checkPassword(user, password));

  const result = await evaluate({
    type: "full",
    request: { ip, headers, requestMethod: method, requestUri: url, token },
    event: {
      type: "login",
      // send this for EVERY attempt, not only the happy path:
      status: loginSucceeded ? "SUCCESSFUL" : "FAILED",
    },
    user: {
      // stable account id when the account exists (success OR wrong password);
      // empty string when the account doesn't exist —
      // do NOT use a placeholder like "unknown"
      accountId: user?.id ?? "",
      // the login the user *submitted*, exactly as typed — not a looked-up value.
      // it doesn't need to match a real account. this is the key field for spotting
      // someone probing many different logins.
      username: login,
      email: user?.email, // optional, when the account exists
    },
    // your separate profile username, if you have one (only when the account exists)
    customFields: user ? { profileName: user.username } : undefined,
  });

  if (result.decision === "BLOCK") return { status: 403 };
  // CHALLENGE -> step up (CAPTCHA / MFA); ALLOW -> proceed
}

What you'll see

Once failed attempts start flowing in, risk_score and the signals array become meaningful, and decision starts returning CHALLENGE / BLOCK on the attack patterns above.

On the Free plan the decision works the same, but risk_score is returned as 0.0, scores as {}, and signals keeps only the reasons that name something on your side. The full values come from the Starter plan up.