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.
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) |
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.
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.