Credential stuffing: when passwords stolen from another site are tried on your login
Credential stuffing replays username and password pairs leaked from somewhere else against your sign-in page, and any customer who reused a password can lose their account to it.
This guide shows how to tell it apart from password spraying and brute force in your own login logs, which controls slow it without locking real customers out, and what to do after an attack. It comes with a synthetic detection workbook and a local Node.js lab with a regression test.
In this guide
Synthetic login detection workbook and lab
An illustration written for this page, not client code. Part A is the detection workbook: five measures that separate brute force, password spraying and credential stuffing in a login log, each with its basis.
How to use itHide the instructions
Part B gives eight test cases with expected results and the evidence to keep. Parts C to F hold a Node.js lab with nothing to install: a login service on 127.0.0.1, a replay script for three synthetic patterns, a detector, a switchable throttle and a breached-password check against the lab's own invented list, the output recorded on Node.js 26.0.0, and a regression test that fails when the throttle or the check is switched off. Use it to learn, and to test a login you own with test accounts.
credential-stuffing.txt
ILLUSTRATION FOR LEARNING. Everything below was written for this page. The shop, its 60 customer accounts, the "other site", that site's leaked list, every password and every request are invented by the lab itself from fixed word lists. No real credential list is used or needed, and the lab sends nothing anywhere except 127.0.0.1 on your own machine. Use it to learn, and to test a login you own with test accounts. It is not a client's code or a client's result.
==== PART A. DETECTION WORKBOOK ====
Read across one measure to see how it separates the three patterns. Every measure comes from your login log, and none of them needs the password.
The three patterns, as the OWASP Credential Stuffing Prevention Cheat Sheet defines them:
Brute force: testing multiple passwords from dictionary or other source against a single account.
Credential stuffing: testing username/password pairs obtained from the breach of another site.
Password spraying: testing a single weak password against a large number of different accounts.
MEASURE 1. Distinct usernames per source
Brute force: one, or very few.
Password spraying: many.
Credential stuffing: many when the attempts come from one source. Spread over many sources, each source can show only a few, so read this measure login-wide as well.
Basis: the cheat sheet definitions above. MITRE ATT&CK T1110.003 (one password or a small list against many different accounts). T1110.004 detection analytic AN1262 (multiple failed attempts using distinct username/password pairs from a single IP address or session within a short time window, written for common services such as RDP or SMB rather than for web logins). The cheat sheet's warning that spreading requests across many IP addresses may keep the volume from each address low.
Lab rule: a per-source verdict only for a source with 10 or more unsuccessful attempts.
MEASURE 2. Attempts per username
Brute force: many, on the account being guessed.
Password spraying: one per round, because each round tries one password across the list.
Credential stuffing: about one, because each username arrives with its own password from the other site.
Basis: T1110.001 (systematic guessing with a repetitive or iterative mechanism). T1110.003. OWASP OAT-008 (no brute-forcing or guessing of values: credentials used in other applications are tested for validity). OWASP's A07:2025 entry also describes a hybrid form that tries variations of spilled credentials. In a log, that shows as a few attempts per username.
Note: the log never holds a password, so this counts attempts. In a guessing run, each unsuccessful attempt on one username is a different password.
Lab rule: brute force when one username holds 10 or more unsuccessful attempts and at least half of all of them. Spraying or stuffing when 10 or more usernames average 5 or fewer each.
MEASURE 3. Failure share, and the sign-ins inside the pattern
All three: a high failure share, since only a matching guess, a matching common password or a reused pair signs in.
What to act on: each successful sign-in from a source that was failing on other attempts. Brute force succeeds when a guess matches, spraying when an account uses the sprayed password, and stuffing when a customer reused a password from the other site.
Basis: T1110 detection analytic AN1276 (failures for valid or invalid users followed by success from the same IP or user). T1110.004 (the tendency to use the same passwords across accounts). CWE-307 (enough attempts eventually gain access to the targeted account).
Lab rule: a verdict needs 50% or more of the attempts in view to be unsuccessful. Sign-ins to review are successes from a source with 3 or more unsuccessful attempts.
MEASURE 4. Whether the usernames are accounts here
Brute force: the one account being guessed.
Password spraying: your own accounts, apart from any errors in the attacker's list. The cheat sheet notes that a predictable generated username, such as one based on the user's full name or a sequential number, could make enumerating valid usernames for a spraying attack easier.
Credential stuffing: usernames that are not accounts here appear, because the pairs come from another site. The ones that are accounts are the overlap between that site's users and yours.
Basis: the cheat sheet definitions and its section on unpredictable usernames. OAT-008 (lists of credentials stolen from elsewhere).
Lab rule: stuffing when 50% or more of the usernames are not accounts here, spraying when fewer are.
Keep this measure in the log. The reply to the person signing in stays the same either way (WSTG-IDNT-04).
MEASURE 5. Spread over time
None of the definitions sets a speed. The time profiles below are what the lab replays.
Brute force: in the lab, one guess every 10 seconds on the same account: a short repeat gap. T1110.001 describes guessing by a repetitive or iterative mechanism; the pace is the lab's choice.
Password spraying: in the lab, three rounds with half an hour between them: a long repeat gap and a long span. T1110.003 says adversaries may deliberately throttle spraying to avoid triggering alerts.
Credential stuffing: in the lab, a one-minute burst with each username tried once: no repeat gap and a high peak per minute. The cheat sheet warns that stuffing traffic can also come from one address, in concert with many others, at low but consistent volumes, and says to consider both short (burst) and long time periods. A run like that shows no burst at all.
Basis: T1110.001 (a repetitive or iterative mechanism). T1110.003 (many accounts, to avoid account lockouts, and deliberate throttling to avoid triggering alerts). The cheat sheet (short burst and long time periods, and an address sending low but consistent volumes in concert with many others).
Lab measures: peak attempts in any 60 seconds, span, and the median gap between two attempts on one username, each taken over one run. A slow run spread across many addresses needs the same measures over a longer window, such as a day or a week, than the lab uses.
The thresholds in the lab rules are the lab's own. Set yours from your own normal traffic and write them down. ASVS 5.0 requirement 6.1.1 (Level 1) asks that documentation defines how controls such as rate limiting, anti-automation and adaptive response defend against attacks such as credential stuffing and password brute force, how they are configured, and how they prevent malicious account lockout.
==== PART B. TEST CASES FOR A LOGIN YOU OWN ====
Run these on a staging copy where you can, with test accounts made for the purpose. Real customers' accounts stay out of every case. Keep the number of requests small, and lower the limits in staging if you need to reach them. If someone else runs these on production, the rules of engagement name the accounts, the limits and the times.
TC-01 Per-account throttle
Set-up: one test account you can afford to lock (WSTG-ATHN-03 asks for this) and the account limit from your documentation.
Steps: from one source, send wrong passwords up to the documented limit, then one more, then the right password.
Expected: refusals start at the documented limit. The reply does not say whether the account exists. The right password is refused until the window ends, unless your documentation names another route for the owner, such as a reset or a challenge. After the window it signs in.
Evidence to keep: each request's time, status and reply text, any Retry-After value, the matching log lines, and the documented limit.
TC-02 Per-source throttle
Set-up: ten or more test accounts and one source address.
Steps: one wrong password per account, in turn, up to the documented source limit, then one more.
Expected: refusals from that source start at the limit, and a test account signing in correctly from another source is not refused.
Evidence to keep: as TC-01, plus the source address as your log records it.
TC-03 Login-wide throttle
Set-up: staging, with the login-wide trigger lowered so a handful of failures reaches it, several source addresses and several test accounts.
Steps: spread wrong passwords across the sources until the trigger, then sign in correctly with a test account, once straight away and once after a single typo.
Expected: the login-wide response engages, whether that is a tighter allowance per source, a challenge or whatever your documentation names, and both correct sign-ins still work.
Evidence to keep: the trigger value and when it engaged, refusals counted by limit, the test account results, and the alert if one fired.
TC-04 One reply for unknown usernames, with the difference kept in the log
Steps: sign in with a username that is not an account, and with a wrong password for a test account.
Expected: the same status, the same message and no consistent difference in response time. The log records which case each one was.
Evidence to keep: both replies with their timings, and the two log lines.
Basis: WSTG-IDNT-04. ASVS 5.0 requirement 6.3.8 (Level 3).
TC-05 Breached-password check at sign-up
Steps: sign up a test account with a value you know is on the list your check reads, then with a long password that is not on it.
Expected: the first is refused and the reply says why. The second is accepted.
Evidence to keep: both requests and replies, which list or service the check reads, and for a range lookup, a trace showing that only the hash prefix left your server.
Basis: NIST SP 800-63B-4 Sec. 3.1.1.2. ASVS 5.0 requirement 6.2.12 (Level 2).
TC-06 Breached-password check at password change and reset
Steps: as TC-05, through password change for a signed-in test account and through the reset flow.
Expected and evidence: as TC-05, for each route.
TC-07 Alerting
Steps: replay a small synthetic pattern against staging, such as one wrong password for each of twelve test accounts from one source, and note the time.
Expected: an alert reaches a named person. It names the pattern, the measures behind it and any sign-ins to review.
Evidence to keep: the alert text, when it was raised and when it was received, who received it, and the log lines it was built from.
Basis: OWASP A07:2025 (log all failures and alert administrators when credential stuffing, brute force or other attacks are detected or suspected). A09:2025 (alerting thresholds and response escalation not in place is a failure).
TC-08 Every sign-in path
Steps: list every route that checks a password or signs someone in: the web form, any API a mobile app uses, password reset, password change and any older login page. Run TC-01 and TC-05 against each.
Expected: the same limits and the same checks on every path.
Evidence to keep: the route list, and a result for each route.
Basis: API2:2023 (know all the flows that authenticate, and treat credential recovery endpoints as login endpoints for brute force, rate limiting and lockout protections).
==== PART C. THE LAB ====
WHAT IT NEEDS
Node.js, with nothing to install. The files use only built-in modules (node:crypto, node:fs, node:http, node:util, node:path, node:url, node:assert and node:test) and Node.js's built-in fetch. The outputs below were recorded on Node.js 26.0.0 on macOS. The lab was not run on other versions for this page.
WHAT IT DOES AND DOES NOT DO
The login server listens only on 127.0.0.1, on a port the operating system picks, and every request goes to that address. It writes its logs to a logs folder next to the files and closes when each run ends. The breached-password check reads the lab's own invented list in the same process, in the shape of a k-anonymity range lookup, so no password or hash leaves your machine.
Two shortcuts are for the lab only. The x-lab-source header stands in for the client's address, and x-lab-clock for the time in seconds, so two hours of spraying replays in seconds. A real login takes the address from the connection, or from a header its own proxy sets, and the time from its own clock.
The throttle limits (5 failures per account and 10 per source in 15 minutes, and a guarded mode after 20 failures in a minute) are set so the patterns reach them. They are not recommended values.
SET-UP
Create an empty folder, save the six files below into it under the names shown, and run the commands under RUN IT from that folder.
==== File 1 of 6: lab-data.mjs ====
// lab-data.mjs: every account, password, list and request in this lab is
// invented here from fixed word lists, so each run builds the same data.
// No real person, password or leaked list is involved.
import { createHash } from 'node:crypto'
const WORDS = [
'harbour', 'lantern', 'pebble', 'saffron', 'quokka', 'wattle', 'meridian', 'copper',
'tundra', 'violet', 'marble', 'juniper', 'cobalt', 'orchard', 'falcon', 'ember',
]
// A number from 0 to 9999 that depends only on the key, so every run matches.
function numberFor(key) {
const hex = createHash('sha256').update(key).digest('hex')
return parseInt(hex.slice(0, 8), 16) % 10000
}
// An invented password such as pebble-copper-4821.
function inventPassword(key) {
const first = WORDS[numberFor(key + ':first') % WORDS.length]
const second = WORDS[numberFor(key + ':second') % WORDS.length]
const digits = String(numberFor(key + ':digits')).padStart(4, '0')
return first + '-' + second + '-' + digits
}
export function usernameFor(number) {
return 'customer' + String(number).padStart(3, '0') + '@mail.example'
}
// Stand-ins for common passwords, one per spraying round.
export const SPRAY_PASSWORDS = ['Lab-Autumn-2026', 'Lab-Winter-2026', 'Lab-Spring-2026']
// Sixty invented guesses for the brute-force pattern.
export const GUESSES = []
for (let number = 1; number <= 60; number++) GUESSES.push(inventPassword('guess:' + number))
// Customers whose password here is the same as on the other site.
const REUSED = [4, 13, 26, 31, 42, 47]
// The other site's leaked list: 240 invented pairs in a fixed shuffled
// order. Customers 1 to 50 have accounts in the lab shop; 61 to 250 do not.
function buildOtherSiteList() {
const numbers = []
for (let number = 1; number <= 250; number++) {
const hasShopAccount = number <= 50
const isOutsider = number > 60
if (hasShopAccount || isOutsider) numbers.push(number)
}
numbers.sort((first, second) => numberFor('order:' + first) - numberFor('order:' + second))
return numbers.map((number) => ({ number, username: usernameFor(number), password: inventPassword('other-site:' + number) }))
}
export const OTHER_SITE_LIST = buildOtherSiteList()
function otherSitePasswordOf(number) {
return OTHER_SITE_LIST.find((pair) => pair.number === number).password
}
// The lab shop's own 60 customer accounts, with plain passwords that the
// server hashes when it starts.
export function listShopAccounts() {
const accounts = []
for (let number = 1; number <= 60; number++) {
let password = inventPassword('shop:' + number)
if (REUSED.includes(number)) password = otherSitePasswordOf(number)
if (number === 7) password = GUESSES[44] // the 45th guess
if (number === 21 || number === 38) password = SPRAY_PASSWORDS[1]
accounts.push({ username: usernameFor(number), password })
}
return accounts
}
// The breached-password list the sign-up check reads: every password that
// appears in the lab's invented attack material, with how often it appears.
export function listBreachedPasswords() {
const counts = new Map()
const all = OTHER_SITE_LIST.map((pair) => pair.password).concat(SPRAY_PASSWORDS, GUESSES)
for (const password of all) counts.set(password, (counts.get(password) || 0) + 1)
return counts
}
function passwordOf(username) {
return listShopAccounts().find((account) => account.username === username).password
}
// Ten genuine customers spread across the run, two of whom mistype once.
function buildCustomerTraffic(runSeconds) {
const events = []
for (let index = 0; index < 10; index++) {
const username = usernameFor(51 + index)
const source = '192.0.2.' + (10 + index)
const at = Math.round(30 + (index * (runSeconds - 60)) / 9)
if (index === 2 || index === 6) {
events.push({ at, source, username, password: passwordOf(username) + 'x', who: 'customer' })
events.push({ at: at + 8, source, username, password: passwordOf(username), who: 'customer' })
} else {
events.push({ at, source, username, password: passwordOf(username), who: 'customer' })
}
}
return events
}
// One source, one account, many passwords. The attacker stops once one works.
function buildBruteForce() {
const events = []
GUESSES.forEach((password, index) => {
events.push({ at: 60 + index * 10, source: '198.51.100.7', username: usernameFor(7), password, who: 'attacker' })
})
// The real owner of customer007 signs in while the guessing is under way.
events.push({ at: 300, source: '192.0.2.77', username: usernameFor(7), password: passwordOf(usernameFor(7)), who: 'customer' })
return { name: 'brute force', stopOnSuccess: true, events: events.concat(buildCustomerTraffic(660)) }
}
// One source, one password per round across 50 usernames, long pauses between rounds.
function buildSpraying() {
const targets = []
for (let number = 1; number <= 48; number++) targets.push(usernameFor(number))
targets.push(usernameFor(301), usernameFor(302))
const events = []
SPRAY_PASSWORDS.forEach((password, round) => {
targets.forEach((username, index) => {
const at = 60 + round * 2800 + index * 20
events.push({ at, source: '198.51.100.44', username, password, who: 'attacker' })
})
})
return { name: 'password spraying', stopOnSuccess: false, events: events.concat(buildCustomerTraffic(6660)) }
}
// The other site's 240 pairs, each tried once, spread over 30 sources.
function buildStuffing() {
const events = OTHER_SITE_LIST.map((pair, index) => ({
at: 60 + index / 4,
source: '203.0.113.' + ((index % 30) + 1),
username: pair.username,
password: pair.password,
who: 'attacker',
}))
return { name: 'credential stuffing', stopOnSuccess: false, events: events.concat(buildCustomerTraffic(180)) }
}
export function buildPattern(name) {
const builders = { 'brute force': buildBruteForce, 'password spraying': buildSpraying, 'credential stuffing': buildStuffing }
const pattern = builders[name]()
pattern.events.sort((first, second) => first.at - second.at)
return pattern
}
export const PATTERN_NAMES = ['brute force', 'password spraying', 'credential stuffing']
==== File 2 of 6: login-server.mjs ====
// login-server.mjs: a small login service for the lab. It listens only on
// 127.0.0.1, on a port the operating system picks, and writes one JSON line
// per sign-in attempt to a log. The log never holds a password.
//
// Two lab-only shortcuts: the x-lab-source header stands in for the client's
// address, and x-lab-clock for the time in seconds, so hours of traffic replay
// in seconds. A real service takes the address from the connection, or from
// a header its own proxy sets, and the time from its own clock.
import { createHash, randomBytes, scrypt, timingSafeEqual } from 'node:crypto'
import { appendFileSync } from 'node:fs'
import { createServer } from 'node:http'
import { promisify } from 'node:util'
import { listBreachedPasswords, listShopAccounts } from './lab-data.mjs'
const scryptAsync = promisify(scrypt)
// Throttle settings, in failed sign-ins and seconds. One account may fail 5
// times in 900 seconds and one source 10 times. When 20 failures land
// within 60 seconds across the whole login, the login is guarded for 900
// seconds, and each source may then fail only twice in 900 seconds.
const ACCOUNT_LIMIT = 5
const ACCOUNT_WINDOW = 900
const SOURCE_LIMIT = 10
const SOURCE_WINDOW = 900
const GUARD_TRIGGER = 20
const GUARD_TRIGGER_WINDOW = 60
const GUARD_SOURCE_LIMIT = 2
const GUARD_DURATION = 900
async function hashPassword(password, salt) {
return scryptAsync(password, salt, 64)
}
async function buildAccountStore() {
const store = new Map()
for (const account of listShopAccounts()) {
const salt = randomBytes(16)
store.set(account.username, { salt, hash: await hashPassword(account.password, salt) })
}
return store
}
// Hashes the password whether or not the username exists, so an unknown
// username is not answered faster.
async function checkPassword(store, dummy, username, password) {
const record = store.get(username) || dummy
const candidate = await hashPassword(password, record.salt)
const matches = timingSafeEqual(candidate, record.hash)
return matches && store.has(username)
}
// ---- Throttle: per account, per source, and login-wide ----
function countRecent(times, now, window) {
return times.filter((time) => time > now - window).length
}
function createThrottle() {
return { byAccount: new Map(), bySource: new Map(), allFailures: [], guardedUntil: -1 }
}
// Returns the limit that refuses this attempt, or null to let it through.
function findThrottle(throttle, username, source, now) {
const accountFailures = throttle.byAccount.get(username) || []
if (countRecent(accountFailures, now, ACCOUNT_WINDOW) >= ACCOUNT_LIMIT) return 'account'
const sourceFailures = throttle.bySource.get(source) || []
const isGuarded = now < throttle.guardedUntil
if (isGuarded && countRecent(sourceFailures, now, SOURCE_WINDOW) >= GUARD_SOURCE_LIMIT) return 'login-wide'
if (countRecent(sourceFailures, now, SOURCE_WINDOW) >= SOURCE_LIMIT) return 'source'
return null
}
function addTime(map, key, now) {
const times = map.get(key) || []
times.push(now)
map.set(key, times)
}
function recordFailure(throttle, username, source, now) {
addTime(throttle.byAccount, username, now)
addTime(throttle.bySource, source, now)
throttle.allFailures.push(now)
if (countRecent(throttle.allFailures, now, GUARD_TRIGGER_WINDOW) >= GUARD_TRIGGER) {
throttle.guardedUntil = now + GUARD_DURATION
}
}
// A correct password clears that account's failures.
function recordSuccess(throttle, username) {
throttle.byAccount.delete(username)
}
// ---- Breached-password check, in the shape of a k-anonymity range lookup ----
function sha1Hex(text) {
return createHash('sha1').update(text, 'utf8').digest('hex').toUpperCase()
}
// The lab's own range service: hash suffixes and counts for one 5-character prefix.
export function buildRangeLookup() {
const lines = new Map()
for (const [password, count] of listBreachedPasswords()) {
const hash = sha1Hex(password)
const prefix = hash.slice(0, 5)
const found = lines.get(prefix) || []
found.push(hash.slice(5) + ':' + count)
lines.set(prefix, found)
}
return (prefix) => (lines.get(prefix.toUpperCase()) || []).join('\r\n')
}
// Only the first five characters of the hash leave this function.
export function isBreachedPassword(password, lookupRange) {
const hash = sha1Hex(password)
const body = lookupRange(hash.slice(0, 5))
const suffixes = body.split('\r\n').map((line) => line.split(':')[0])
return suffixes.includes(hash.slice(5))
}
// ---- HTTP handling ----
function readJson(request) {
return new Promise((resolve) => {
let text = ''
request.on('data', (chunk) => { text = text + chunk })
request.on('end', () => {
try { resolve(JSON.parse(text)) } catch { resolve({}) }
})
})
}
function reply(response, status, body, headers) {
response.writeHead(status, Object.assign({ 'content-type': 'application/json' }, headers || {}))
response.end(JSON.stringify(body))
}
async function handleLogin(state, request, response) {
const body = await readJson(request)
const username = String(body.username || '')
const source = String(request.headers['x-lab-source'] || 'unknown')
const now = Number(request.headers['x-lab-clock'] || 0)
const entry = { at: now, source, username, knownUser: state.store.has(username), outcome: '', throttle: null }
const limit = state.throttleOn ? findThrottle(state.throttle, username, source, now) : null
if (limit) {
entry.outcome = 'throttled'
entry.throttle = limit
appendFileSync(state.logPath, JSON.stringify(entry) + '\n')
return reply(response, 429, { error: 'Too many attempts. Try again later.' }, { 'retry-after': String(SOURCE_WINDOW) })
}
const isValid = await checkPassword(state.store, state.dummy, username, String(body.password || ''))
entry.outcome = isValid ? 'success' : 'failure'
appendFileSync(state.logPath, JSON.stringify(entry) + '\n')
if (isValid) {
recordSuccess(state.throttle, username)
return reply(response, 200, { signedIn: true })
}
recordFailure(state.throttle, username, source, now)
return reply(response, 401, { error: 'Invalid username or password.' })
}
// Sign-up and password change share one rule: a breached password is
// refused, and the reply says why. In a real service, password change also
// needs a signed-in session and the same throttle as /login.
async function handleNewPassword(state, request, response, isChange) {
const body = await readJson(request)
const username = String(body.username || '')
const password = String((isChange ? body.newPassword : body.password) || '')
if (isChange) {
const isCurrent = await checkPassword(state.store, state.dummy, username, String(body.currentPassword || ''))
if (!isCurrent) return reply(response, 401, { error: 'Current password is incorrect.' })
}
if (state.breachCheckOn && isBreachedPassword(password, state.lookupRange)) {
return reply(response, 400, { error: 'This password has appeared in a data breach. Choose a different one.' })
}
if (isChange) {
await savePassword(state.store, username, password)
return reply(response, 200, { saved: true })
}
// An existing username gets the same reply and is left unchanged, so
// sign-up does not reveal which accounts exist. A real service would
// email the address either way.
if (!state.store.has(username)) await savePassword(state.store, username, password)
return reply(response, 201, { received: true })
}
async function savePassword(store, username, password) {
const salt = randomBytes(16)
store.set(username, { salt, hash: await hashPassword(password, salt) })
}
async function route(state, request, response) {
if (request.method !== 'POST') return reply(response, 404, { error: 'Not found.' })
if (request.url === '/login') return handleLogin(state, request, response)
if (request.url === '/signup') return handleNewPassword(state, request, response, false)
if (request.url === '/change-password') return handleNewPassword(state, request, response, true)
return reply(response, 404, { error: 'Not found.' })
}
export async function startLoginServer(options) {
const dummySalt = randomBytes(16)
const state = {
store: await buildAccountStore(),
dummy: { salt: dummySalt, hash: await hashPassword(randomBytes(16).toString('hex'), dummySalt) },
throttle: createThrottle(),
throttleOn: options.throttleOn,
breachCheckOn: options.breachCheckOn,
lookupRange: buildRangeLookup(),
logPath: options.logPath,
}
const server = createServer((request, response) => { route(state, request, response) })
await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
const url = 'http://127.0.0.1:' + server.address().port
const close = () => new Promise((resolve) => server.close(resolve))
return { url, close }
}
==== File 3 of 6: replay.mjs ====
// replay.mjs: sends one pattern's sign-in attempts to the lab server, in
// order, and counts what came back. It knows which attempts are the
// attacker's and which are genuine customers'; the detector does not.
async function sendAttempt(url, event) {
const response = await fetch(url + '/login', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-lab-source': event.source,
'x-lab-clock': String(event.at),
},
body: JSON.stringify({ username: event.username, password: event.password }),
})
await response.text()
return response.status
}
function emptySummary() {
return {
sent: 0,
attacker: { signedIn: 0, refused: 0, throttled: 0 },
customers: { names: new Set(), signedIn: new Set(), throttled: new Set() },
}
}
function countReply(summary, event, status) {
if (event.who === 'attacker') {
if (status === 200) summary.attacker.signedIn += 1
if (status === 401) summary.attacker.refused += 1
if (status === 429) summary.attacker.throttled += 1
return
}
summary.customers.names.add(event.username)
if (status === 200) summary.customers.signedIn.add(event.username)
if (status === 429) summary.customers.throttled.add(event.username)
}
export async function replayPattern(url, pattern) {
const summary = emptySummary()
let attackerDone = false
for (const event of pattern.events) {
if (event.who === 'attacker' && attackerDone) continue
const status = await sendAttempt(url, event)
summary.sent += 1
countReply(summary, event, status)
if (event.who === 'attacker' && status === 200 && pattern.stopOnSuccess) attackerDone = true
}
return summary
}
export function describeReplay(summary) {
const attacker = summary.attacker
const customers = summary.customers
const lines = []
lines.push('Replay: ' + summary.sent + ' attempts sent. Attacker: ' + attacker.signedIn + ' signed in, '
+ attacker.refused + ' wrong password, ' + attacker.throttled + ' throttled.')
let line = 'Customers: ' + customers.signedIn.size + ' of ' + customers.names.size + ' signed in.'
const blocked = Array.from(customers.throttled).filter((name) => !customers.signedIn.has(name))
if (blocked.length > 0) line = line + ' Throttled and not signed in: ' + blocked.join(', ') + '.'
lines.push(line)
return lines
}
==== File 4 of 6: detector.mjs ====
// detector.mjs: reads the lab's login log and classifies what it sees, using
// only what a defender can measure: usernames per source, attempts per
// username, the failure share, whether the usernames are accounts here, and
// how the attempts spread over time. It never sees a password.
import { readFileSync } from 'node:fs'
export function readLog(logPath) {
const lines = readFileSync(logPath, 'utf8').split('\n').filter((line) => line.trim() !== '')
return lines.map((line) => JSON.parse(line))
}
function countBy(entries, key) {
const counts = new Map()
for (const entry of entries) counts.set(entry[key], (counts.get(entry[key]) || 0) + 1)
return counts
}
function median(values) {
const sorted = values.slice().sort((first, second) => first - second)
return sorted[Math.floor(sorted.length / 2)]
}
// The most attempts inside any 60-second stretch.
function findPeakPerMinute(times) {
const sorted = times.slice().sort((first, second) => first - second)
let peak = 0
let start = 0
for (let end = 0; end < sorted.length; end++) {
while (sorted[end] - sorted[start] >= 60) start += 1
peak = Math.max(peak, end - start + 1)
}
return peak
}
// The typical gap between two attempts on the same username, in minutes.
function findRepeatGap(entries) {
const lastSeen = new Map()
const gaps = []
for (const entry of entries) {
if (lastSeen.has(entry.username)) gaps.push(entry.at - lastSeen.get(entry.username))
lastSeen.set(entry.username, entry.at)
}
return gaps.length === 0 ? null : median(gaps) / 60
}
// Every measure but the failure share is taken over unsuccessful attempts:
// wrong passwords and throttled attempts.
export function measure(entries) {
const unsuccessful = entries.filter((entry) => entry.outcome !== 'success')
const byUsername = countBy(unsuccessful, 'username')
const isKnown = new Map()
for (const entry of unsuccessful) isKnown.set(entry.username, entry.knownUser)
const unknownCount = Array.from(isKnown.values()).filter((known) => !known).length
const times = unsuccessful.map((entry) => entry.at)
return {
unsuccessful: unsuccessful.length,
failureShare: Math.round((100 * unsuccessful.length) / Math.max(entries.length, 1)),
usernames: byUsername.size,
perUsername: unsuccessful.length / Math.max(byUsername.size, 1),
maxOnOne: Math.max(0, ...byUsername.values()),
notAccountsHere: Math.round((100 * unknownCount) / Math.max(byUsername.size, 1)),
sources: countBy(unsuccessful, 'source').size,
peakPerMinute: findPeakPerMinute(times),
spanMinutes: times.length === 0 ? 0 : (Math.max(...times) - Math.min(...times)) / 60,
repeatGapMinutes: findRepeatGap(unsuccessful),
}
}
export function classify(measures) {
if (measures.unsuccessful < 10 || measures.failureShare < 50) return 'normal'
if (measures.maxOnOne >= 10 && measures.maxOnOne >= measures.unsuccessful / 2) return 'brute force'
if (measures.usernames >= 10 && measures.perUsername <= 5) {
return measures.notAccountsHere >= 50 ? 'credential stuffing' : 'password spraying'
}
return 'unusual, review'
}
// Successful sign-ins from a source with at least three unsuccessful attempts.
function findSignInsToReview(entries) {
const unsuccessful = entries.filter((entry) => entry.outcome !== 'success')
const failuresBySource = countBy(unsuccessful, 'source')
return entries.filter((entry) => entry.outcome === 'success' && (failuresBySource.get(entry.source) || 0) >= 3)
}
export function analyse(entries) {
const loginWide = measure(entries)
const failuresBySource = countBy(entries.filter((entry) => entry.outcome !== 'success'), 'source')
const bySource = []
for (const [source, count] of failuresBySource) {
if (count < 10) continue
const sourceMeasures = measure(entries.filter((entry) => entry.source === source))
bySource.push({ source, measures: sourceMeasures, verdict: classify(sourceMeasures) })
}
return {
loginWide: { measures: loginWide, verdict: classify(loginWide) },
bySource,
throttled: countBy(entries.filter((entry) => entry.outcome === 'throttled'), 'throttle'),
review: findSignInsToReview(entries),
}
}
function round(value) {
return Math.round(value * 10) / 10
}
function plural(count, word) {
return count + ' ' + word + (count === 1 ? '' : 's')
}
function describeMeasures(measures) {
const gap = measures.repeatGapMinutes === null ? 'none' : round(measures.repeatGapMinutes) + ' min'
return [
' volume: ' + plural(measures.unsuccessful, 'unsuccessful attempt') + ' (' + measures.failureShare + '% of all attempts), '
+ plural(measures.sources, 'source') + ', peak ' + measures.peakPerMinute + ' a minute, span ' + round(measures.spanMinutes) + ' min',
' shape: ' + plural(measures.usernames, 'username') + ', ' + round(measures.perUsername) + ' per username, max '
+ measures.maxOnOne + ' on one, ' + measures.notAccountsHere + '% not accounts here, repeat gap ' + gap,
]
}
function describeAlert(scope, verdict, review) {
const names = review.map((entry) => entry.username + ' from ' + entry.source)
const toReview = names.length === 0 ? 'no successful sign-ins to review.' : 'review sign-ins: ' + names.join('; ') + '.'
return 'ALERT ' + scope + ': ' + verdict + ' suspected; ' + toReview
}
export function describeAnalysis(result) {
const lines = ['Detector, login-wide:'].concat(describeMeasures(result.loginWide.measures))
lines.push(' verdict: ' + result.loginWide.verdict.toUpperCase())
if (result.bySource.length === 0) lines.push('Detector, by source: no source reached 10 unsuccessful attempts')
for (const item of result.bySource) {
lines.push('Detector, source ' + item.source + ':')
for (const line of describeMeasures(item.measures)) lines.push(line)
lines.push(' verdict: ' + item.verdict.toUpperCase())
}
const throttled = Array.from(result.throttled).map(([limit, count]) => limit + ' ' + count)
lines.push('Throttled, by limit: ' + (throttled.length === 0 ? 'none' : throttled.join(', ')))
if (result.loginWide.verdict !== 'normal') lines.push(describeAlert('login-wide', result.loginWide.verdict, result.review))
for (const item of result.bySource) {
if (item.verdict === 'normal') continue
const fromSource = result.review.filter((entry) => entry.source === item.source)
lines.push(describeAlert('source ' + item.source, item.verdict, fromSource))
}
return lines
}
==== File 5 of 6: run-lab.mjs ====
// run-lab.mjs: replays each pattern with the throttle off and then on,
// runs the detector on each log, then tries the breached-password check.
import { mkdirSync, rmSync } from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { analyse, describeAnalysis, readLog } from './detector.mjs'
import { buildPattern, listShopAccounts, OTHER_SITE_LIST, PATTERN_NAMES } from './lab-data.mjs'
import { buildRangeLookup, isBreachedPassword, startLoginServer } from './login-server.mjs'
import { describeReplay, replayPattern } from './replay.mjs'
const LOG_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'logs')
async function runOnce(patternName, throttleOn, runNumber) {
const logPath = path.join(LOG_DIR, 'run-' + runNumber + '.jsonl')
const server = await startLoginServer({ throttleOn, breachCheckOn: true, logPath })
const summary = await replayPattern(server.url, buildPattern(patternName))
await server.close()
console.log('==== ' + patternName + ', throttle ' + (throttleOn ? 'on' : 'off') + ' ====')
for (const line of describeReplay(summary)) console.log(line)
for (const line of describeAnalysis(analyse(readLog(logPath)))) console.log(line)
console.log('')
}
async function post(url, route, body) {
const response = await fetch(url + route, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(body),
})
return response.status + ' ' + (await response.text())
}
async function tryPasswordChecks(breachCheckOn) {
const logPath = path.join(LOG_DIR, 'password-checks.jsonl')
const server = await startLoginServer({ throttleOn: true, breachCheckOn, logPath })
const breached = OTHER_SITE_LIST[99].password
const fresh = 'violet-saffron-quokka-lantern-2207'
const current = listShopAccounts()[50]
console.log('==== breached-password check ' + (breachCheckOn ? 'on' : 'off') + ' ====')
console.log('Sign-up, password from the lab list: ' + await post(server.url, '/signup', { username: 'new-a@mail.example', password: breached }))
console.log('Sign-up, password not on the list: ' + await post(server.url, '/signup', { username: 'new-b@mail.example', password: fresh }))
const change = { username: current.username, currentPassword: current.password, newPassword: breached }
console.log('Change to a password from the list: ' + await post(server.url, '/change-password', change))
await server.close()
console.log('')
}
function showRangeLookup() {
const lookup = buildRangeLookup()
const asked = []
const recordingLookup = (prefix) => {
asked.push(prefix)
return lookup(prefix)
}
const isBreached = isBreachedPassword(OTHER_SITE_LIST[99].password, recordingLookup)
const returned = lookup(asked[0]).split('\r\n').length
console.log('==== range lookup ====')
console.log('Sent to the range service: ' + asked[0] + ' (' + asked[0].length + ' characters of the SHA-1 hash)')
console.log('Suffixes returned for that prefix: ' + returned + '. Match found locally: ' + (isBreached ? 'yes' : 'no'))
}
rmSync(LOG_DIR, { recursive: true, force: true })
mkdirSync(LOG_DIR)
let runNumber = 1
for (const patternName of PATTERN_NAMES) {
for (const throttleOn of [false, true]) {
await runOnce(patternName, throttleOn, runNumber)
runNumber += 1
}
}
await tryPasswordChecks(false)
await tryPasswordChecks(true)
showRangeLookup()
==== File 6 of 6: lab.test.mjs ====
// lab.test.mjs: a regression test for the throttle and the breached-password
// check. It passes with both switched on, the default, and fails when
// LAB_THROTTLE=off or LAB_BREACH_CHECK=off.
import assert from 'node:assert/strict'
import { mkdirSync } from 'node:fs'
import path from 'node:path'
import { before, test } from 'node:test'
import { fileURLToPath } from 'node:url'
import { analyse, readLog } from './detector.mjs'
import { buildPattern, listShopAccounts, OTHER_SITE_LIST, PATTERN_NAMES } from './lab-data.mjs'
import { startLoginServer } from './login-server.mjs'
import { replayPattern } from './replay.mjs'
const throttleOn = process.env.LAB_THROTTLE !== 'off'
const breachCheckOn = process.env.LAB_BREACH_CHECK !== 'off'
const LOG_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'logs')
const runs = new Map()
async function runPattern(name, index) {
const logPath = path.join(LOG_DIR, 'test-' + index + '-' + Date.now() + '.jsonl')
const server = await startLoginServer({ throttleOn, breachCheckOn, logPath })
try {
const summary = await replayPattern(server.url, buildPattern(name))
return { summary, entries: readLog(logPath) }
} finally {
await server.close()
}
}
// Attacker attempts that reached the password check.
function countChecked(run, source) {
return run.entries.filter((entry) => entry.source.startsWith(source) && entry.outcome !== 'throttled').length
}
async function post(route, body) {
const server = await startLoginServer({ throttleOn, breachCheckOn, logPath: path.join(LOG_DIR, 'test-post.jsonl') })
try {
const response = await fetch(server.url + route, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(body),
})
return response.status
} finally {
await server.close()
}
}
before(async () => {
mkdirSync(LOG_DIR, { recursive: true })
for (let index = 0; index < PATTERN_NAMES.length; index++) {
runs.set(PATTERN_NAMES[index], await runPattern(PATTERN_NAMES[index], index))
}
})
test('TC-01 per account: guessing on one account stops at the account limit', () => {
const run = runs.get('brute force')
assert.ok(countChecked(run, '198.51.100.7') <= 5, 'password checks: ' + countChecked(run, '198.51.100.7'))
assert.equal(run.summary.attacker.signedIn, 0)
})
test('TC-02 per source: one source trying many accounts is slowed', () => {
const run = runs.get('password spraying')
assert.ok(countChecked(run, '198.51.100.44') <= 50, 'password checks: ' + countChecked(run, '198.51.100.44'))
})
test('TC-03 login-wide: a surge of failures across many sources is slowed', () => {
const run = runs.get('credential stuffing')
assert.ok(countChecked(run, '203.0.113.') <= 120, 'password checks: ' + countChecked(run, '203.0.113.'))
})
test('TC-04 customers who type the right password still sign in during stuffing', () => {
const customers = runs.get('credential stuffing').summary.customers
assert.equal(customers.signedIn.size, customers.names.size)
})
test('TC-05 the detector names each pattern, which raises its alert', () => {
for (const name of PATTERN_NAMES) {
assert.equal(analyse(runs.get(name).entries).loginWide.verdict, name)
}
})
test('TC-06 sign-up refuses a password on the breached list', async () => {
assert.equal(await post('/signup', { username: 'new-a@mail.example', password: OTHER_SITE_LIST[99].password }), 400)
})
test('TC-07 password change refuses a password on the breached list', async () => {
const customer = listShopAccounts()[50]
const change = { username: customer.username, currentPassword: customer.password, newPassword: OTHER_SITE_LIST[99].password }
assert.equal(await post('/change-password', change), 400)
})
test('TC-08 sign-up accepts a password that is not on the list', async () => {
assert.equal(await post('/signup', { username: 'new-b@mail.example', password: 'violet-saffron-quokka-lantern-2207' }), 201)
})
==== RUN IT ====
node run-lab.mjs
node --test lab.test.mjs
LAB_THROTTLE=off node --test lab.test.mjs
LAB_BREACH_CHECK=off node --test lab.test.mjs
LAB_THROTTLE=off LAB_BREACH_CHECK=off node --test lab.test.mjs
==== PART D. OUTPUT OF node run-lab.mjs (Node.js 26.0.0, macOS) ====
==== brute force, throttle off ====
Replay: 58 attempts sent. Attacker: 1 signed in, 44 wrong password, 0 throttled.
Customers: 11 of 11 signed in.
Detector, login-wide:
volume: 46 unsuccessful attempts (79% of all attempts), 3 sources, peak 7 a minute, span 7.2 min
shape: 3 usernames, 15.3 per username, max 44 on one, 0% not accounts here, repeat gap 0.2 min
verdict: BRUTE FORCE
Detector, source 198.51.100.7:
volume: 44 unsuccessful attempts (98% of all attempts), 1 source, peak 6 a minute, span 7.2 min
shape: 1 username, 44 per username, max 44 on one, 0% not accounts here, repeat gap 0.2 min
verdict: BRUTE FORCE
Throttled, by limit: none
ALERT login-wide: brute force suspected; review sign-ins: customer007@mail.example from 198.51.100.7.
ALERT source 198.51.100.7: brute force suspected; review sign-ins: customer007@mail.example from 198.51.100.7.
==== brute force, throttle on ====
Replay: 73 attempts sent. Attacker: 0 signed in, 5 wrong password, 55 throttled.
Customers: 10 of 11 signed in. Throttled and not signed in: customer007@mail.example.
Detector, login-wide:
volume: 63 unsuccessful attempts (86% of all attempts), 4 sources, peak 7 a minute, span 9.8 min
shape: 3 usernames, 21 per username, max 61 on one, 0% not accounts here, repeat gap 0.2 min
verdict: BRUTE FORCE
Detector, source 198.51.100.7:
volume: 60 unsuccessful attempts (100% of all attempts), 1 source, peak 6 a minute, span 9.8 min
shape: 1 username, 60 per username, max 60 on one, 0% not accounts here, repeat gap 0.2 min
verdict: BRUTE FORCE
Throttled, by limit: account 56
ALERT login-wide: brute force suspected; no successful sign-ins to review.
ALERT source 198.51.100.7: brute force suspected; no successful sign-ins to review.
==== password spraying, throttle off ====
Replay: 162 attempts sent. Attacker: 2 signed in, 148 wrong password, 0 throttled.
Customers: 10 of 10 signed in.
Detector, login-wide:
volume: 150 unsuccessful attempts (93% of all attempts), 3 sources, peak 3 a minute, span 109.7 min
shape: 52 usernames, 2.9 per username, max 3 on one, 4% not accounts here, repeat gap 46.7 min
verdict: PASSWORD SPRAYING
Detector, source 198.51.100.44:
volume: 148 unsuccessful attempts (99% of all attempts), 1 source, peak 3 a minute, span 109.7 min
shape: 50 usernames, 3 per username, max 3 on one, 4% not accounts here, repeat gap 46.7 min
verdict: PASSWORD SPRAYING
Throttled, by limit: none
ALERT login-wide: password spraying suspected; review sign-ins: customer021@mail.example from 198.51.100.44; customer038@mail.example from 198.51.100.44.
ALERT source 198.51.100.44: password spraying suspected; review sign-ins: customer021@mail.example from 198.51.100.44; customer038@mail.example from 198.51.100.44.
==== password spraying, throttle on ====
Replay: 162 attempts sent. Attacker: 0 signed in, 45 wrong password, 105 throttled.
Customers: 10 of 10 signed in.
Detector, login-wide:
volume: 152 unsuccessful attempts (94% of all attempts), 3 sources, peak 3 a minute, span 109.7 min
shape: 52 usernames, 2.9 per username, max 3 on one, 4% not accounts here, repeat gap 46.7 min
verdict: PASSWORD SPRAYING
Detector, source 198.51.100.44:
volume: 150 unsuccessful attempts (100% of all attempts), 1 source, peak 3 a minute, span 109.7 min
shape: 50 usernames, 3 per username, max 3 on one, 4% not accounts here, repeat gap 46.7 min
verdict: PASSWORD SPRAYING
Throttled, by limit: source 105
ALERT login-wide: password spraying suspected; no successful sign-ins to review.
ALERT source 198.51.100.44: password spraying suspected; no successful sign-ins to review.
==== credential stuffing, throttle off ====
Replay: 252 attempts sent. Attacker: 6 signed in, 234 wrong password, 0 throttled.
Customers: 10 of 10 signed in.
Detector, login-wide:
volume: 236 unsuccessful attempts (94% of all attempts), 32 sources, peak 235 a minute, span 1 min
shape: 236 usernames, 1 per username, max 1 on one, 81% not accounts here, repeat gap none
verdict: CREDENTIAL STUFFING
Detector, by source: no source reached 10 unsuccessful attempts
Throttled, by limit: none
ALERT login-wide: credential stuffing suspected; review sign-ins: customer026@mail.example from 203.0.113.7; customer047@mail.example from 203.0.113.26; customer042@mail.example from 203.0.113.16; customer004@mail.example from 203.0.113.19; customer013@mail.example from 203.0.113.11; customer031@mail.example from 203.0.113.16.
==== credential stuffing, throttle on ====
Replay: 252 attempts sent. Attacker: 2 signed in, 60 wrong password, 178 throttled.
Customers: 10 of 10 signed in.
Detector, login-wide:
volume: 240 unsuccessful attempts (95% of all attempts), 32 sources, peak 239 a minute, span 1 min
shape: 240 usernames, 1 per username, max 1 on one, 79% not accounts here, repeat gap none
verdict: CREDENTIAL STUFFING
Detector, by source: no source reached 10 unsuccessful attempts
Throttled, by limit: login-wide 178
ALERT login-wide: credential stuffing suspected; review sign-ins: customer026@mail.example from 203.0.113.7; customer047@mail.example from 203.0.113.26.
==== breached-password check off ====
Sign-up, password from the lab list: 201 {"received":true}
Sign-up, password not on the list: 201 {"received":true}
Change to a password from the list: 200 {"saved":true}
==== breached-password check on ====
Sign-up, password from the lab list: 400 {"error":"This password has appeared in a data breach. Choose a different one."}
Sign-up, password not on the list: 201 {"received":true}
Change to a password from the list: 400 {"error":"This password has appeared in a data breach. Choose a different one."}
==== range lookup ====
Sent to the range service: E2EBF (5 characters of the SHA-1 hash)
Suffixes returned for that prefix: 1. Match found locally: yes
==== PART E. REGRESSION TEST RESULTS (Node.js 26.0.0, macOS) ====
Each run reported 8 tests. The counts are copied from the test runner's summary lines.
Switches pass fail exit code
both on (default) 8 0 0
LAB_THROTTLE=off 5 3 1
LAB_BREACH_CHECK=off 6 2 1
LAB_THROTTLE=off LAB_BREACH_CHECK=off 3 5 1
With LAB_THROTTLE=off, these failed: TC-01, TC-02, TC-03. Their messages:
AssertionError [ERR_ASSERTION]: password checks: 45
AssertionError [ERR_ASSERTION]: password checks: 150
AssertionError [ERR_ASSERTION]: password checks: 240
With LAB_BREACH_CHECK=off, these failed: TC-06, TC-07. Their messages:
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
201 !== 400
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
200 !== 400
==== PART F. READING THE OUTPUT ====
Replay lines come from replay.mjs, which knows which attempts are the attacker's. Detector lines come from the log alone.
volume: unsuccessful attempts (wrong password or throttled), their share of all attempts in view, how many sources sent them, the most in any 60 seconds, and the time from first to last.
shape: how many usernames, unsuccessful attempts per username, the most on one username, the share of usernames that are not accounts here, and the median gap between two attempts on one username.
verdict: the lab rule from Part A that matched. NORMAL means none did.
Throttled, by limit: which limit refused how many attempts. login-wide is the guarded mode's tighter allowance per source.
ALERT: one line for each verdict that is not normal, with the successful sign-ins to review.
What the six runs show
Brute force. With the throttle off, the 45th guess signed in to customer007. With it on, five guesses reached the password check and 55 were refused, and the account's real owner was refused too while the limit held. That refusal is the cost of a limit counted per account.
Password spraying. With the throttle off, the two accounts that used the sprayed password signed in. With it on, the source limit refused 105 of the 150 attempts and none signed in. No account saw more than three attempts, so the per-account limit never applied.
Credential stuffing. No source reached 10 unsuccessful attempts, so only the login-wide view named the pattern. With the throttle off, all six customers who reused a password signed in. With it on, 62 of the 240 attempts reached the password check and two reused passwords still worked: one before the guard engaged, and one from a source still inside its guarded allowance. The throttle slowed the run. It did not decide whether a correct password belonged to its owner.
Breached-password check. With it on, the password from the lab's list was refused at sign-up and at password change, with the reason, and a password that is not on the list was accepted.
==== USING IT ON YOUR OWN LOGIN ====
1. Make your login log carry what the detector reads: the time, the source address, the username, whether it is an account, the outcome, and which limit refused the attempt. Leave the password out.
2. Export a period of normal traffic in the same one-JSON-object-per-line shape and run analyse() from detector.mjs on it. Usernames are personal information, so keep the export wherever your logs are kept. Set your thresholds above what normal traffic shows, and run the detector over a long window as well as a short one, since a slow run spread across many addresses can stay under any one-minute peak.
3. To replay patterns against a staging copy, change buildPattern() to use your test accounts and invented usernames, keep the counts small, and lower the staging limits so a few attempts reach them. Drop the two lab headers: your login takes the address and the time from the request itself.
4. Keep a test shaped like lab.test.mjs in your suite, so a change that switches off a limit or the breached-password check fails a build instead of reaching production.What credential stuffing is, and why reused passwords make it work
Credential stuffing is the replay of username and password pairs taken from one site against the login of another.
OWASP's Credential Stuffing Prevention Cheat Sheet defines it as testing username/password pairs obtained from the breach of another site. OWASP's catalogue of automated threats lists it as OAT-008, defined by mass log in attempts used to verify the validity of stolen username/password pairs, and gives account takeover, credential replay and password re-use among its other names. MITRE ATT&CK tracks it as T1110.004, a sub-technique of T1110 Brute Force.
It works because people reuse passwords. MITRE's entry says breach dumps may be useful to an adversary taking advantage of the tendency for users to use the same passwords across personal and business accounts. NIST makes the same point in SP 800-63B-4, the current revision of its authentication guideline, published in July 2025: the use of distinct passwords is important to avoid "password stuffing" attacks, in which an attacker uses a compromised password from one site to access the user's account on other sites.
The cheat sheet adds that stuffing relies on reused usernames as well, and that a significant number of websites use the email address as the username.
Nothing on your own site has to be broken for this to happen. The list comes from someone else's breach, and your login does the rest by answering each attempt with a yes or a no. OWASP's A07:2025 entry describes an application without defences against automated threats being used as a password oracle to determine whether credentials are valid.
Each yes is a customer account in someone else's hands. OWASP's API2:2023 entry describes the impact as complete control of other users' accounts, reading their personal data and performing sensitive actions on their behalf, and says systems are unlikely to be able to distinguish attackers' actions from legitimate user ones.
The standards treat a login that lets this run as a weakness in its own right. A07:2025 Authentication Failures lists permitting credential stuffing and brute force among its weaknesses. MITRE catalogues the missing control as CWE-307, Improper Restriction of Excessive Authentication Attempts: a product that does not implement sufficient measures to prevent multiple failed authentication attempts within a short time frame.
ASVS 5.0 requirement 6.3.1, a Level 1 requirement, asks that controls to prevent attacks such as credential stuffing and password brute force are implemented according to the application's security documentation.
This guide covers the replay itself: telling it apart from similar attacks in your logs, the controls that slow it, and testing that they notice. Authentication failures as a whole, request limits across an application, the choice of multi-factor methods, how sessions start and end, and where security logs go and who they alert each have their own guide in this library, and this page leaves the detail to them.
Password spraying vs credential stuffing vs brute force
Three attacks reach the same login form and differ in where the passwords come from.
The cheat sheet's definitions are the clearest place to start. Brute force is testing multiple passwords from dictionary or other source against a single account. Credential stuffing is testing username/password pairs obtained from the breach of another site. Password spraying is testing a single weak password against a large number of different accounts.
The cheat sheet calls stuffing and spraying separate, distinct attacks, and says the defences against them are in many cases the same and would also be effective against brute force.
MITRE draws the same lines under T1110. T1110.001 Password Guessing describes an adversary with no prior knowledge of legitimate credentials who may systematically guess a password using a repetitive or iterative mechanism. T1110.003 Password Spraying describes a single or small list of commonly used passwords tried against many different accounts, and says this is done to avoid the account lockouts that brute forcing a single account with many passwords would normally cause.
T1110.004 Credential Stuffing describes credentials from breach dumps of unrelated accounts, used to gain access through credential overlap.
Labels are not used consistently, so read the definition behind one. OWASP's OAT-007 Credential Cracking covers brute force, dictionary and guessing attacks and lists password spraying among its other names, while OAT-008 says credential stuffing does not involve any brute-forcing or guessing of values. OWASP's A07:2025 entry describes a hybrid form of credential stuffing, also known as password spray attacks, in which the attacker uses variations or increments of spilled credentials, such as a leaked password with its number raised by one. This guide uses the cheat sheet's three definitions throughout.
The difference decides which control catches which attack. A limit on failures for one account stops brute force. Spraying is shaped to stay under that limit, by MITRE's description, and stuffing tries each username about once, so neither gives a per-account limit much to count.
A limit per source address catches spraying or stuffing sent from one place, and the cheat sheet warns that spreading requests across a large number of IP addresses may defeat both block-lists and rate limiting, because each address sends little.
The workbook on this page turns these differences into five measures you can take from a login log.
Login anomaly detection: what to measure in your logs
You can only tell these patterns apart if the login log records enough about each attempt.
The workbook's measures need six fields per attempt: the time, the source address, the username as typed, whether that username is an account, the outcome, and which limit refused the attempt, if one did. ASVS 5.0 requirement 16.3.1, at Level 2, asks that all authentication operations are logged, including successful and unsuccessful attempts, and requirement 16.2.1 asks that each entry includes the necessary metadata, such as when, where, who and what, to allow a detailed investigation of the timeline.
Requirement 16.2.5 says some data, such as credentials, may not be allowed to be logged at all.
The lab's log never holds a password, which is why it counts attempts per username rather than passwords tried.
Read one measure across the three patterns and they separate. Brute force puts many attempts on one username. Spraying puts one attempt per round on each of many usernames that are real accounts, and MITRE says adversaries may deliberately throttle it to avoid triggering alerts.
Stuffing puts about one attempt on each of many usernames, some of which are not accounts at all because the pairs came from another site. Speed is not part of any of these definitions. The lab replays brute force as quick repeats and stuffing as a one-minute burst, and the cheat sheet warns that stuffing traffic can also come from many addresses at low but consistent volumes.
Each pattern has a far higher failure share than ordinary sign-ins, since only a matching guess, a matching common password or a reused pair gets through, so the event to act on is the success inside the pattern.
MITRE's detection guidance for T1110 describes multiple authentication failures for valid or invalid users followed by success from the same IP or user.
Watch two views at once: each source, and the whole login. In the lab, the per-source view named the brute-force and spraying runs, each sent from one address. The stuffing run was spread across 30 addresses, none of which reached the ten unsuccessful attempts the per-source rule needs, and only the login-wide view named it: 236 usernames, one attempt each, 81% of them not accounts in the shop, at a peak of 235 a minute.
The cheat sheet asks for the same breadth.
Mitigation decisions should not rely on a single predictable volume limit, and should consider short bursts and long periods, and an address that sends low but consistent traffic in concert with many others. The lab's detector reads one run at a time, and its peak measure uses a 60-second window.
A slow run spread across many addresses over days needs the same measures taken over a longer window than the lab uses.
Whether a username exists belongs in the log, not in the reply. WSTG-IDNT-04 describes enumerating users through login error messages, error codes and response times, and ASVS 5.0 requirement 6.3.8, at Level 3, asks that valid users cannot be deduced from failed authentication challenges, such as through error messages, HTTP response codes or different response times.
The lab's login gives the same reply either way and hashes the submitted password even for an unknown username, while its log records which case it was.
Every control should also report what it did. The cheat sheet says each defence should generate volume metrics, ideally including both detected and mitigated attack volume and allowing filtering on fields such as IP address, and that monitoring them may reveal defences that have failed or attacks nobody had identified.
Where those numbers are stored, how long they are kept and who is paged belong to the security logging and monitoring guide.
Why a lockout policy alone can hurt real customers
Locking an account after a few failures is the obvious answer to guessing, and it has a cost the attacker can choose to impose.
MITRE's mitigation for T1110 says to set account lockout policies after a certain number of failed login attempts, and warns that too strict a policy may create a denial of service condition, with all accounts used in the brute force being locked out.
Its entries for password guessing and credential stuffing both call the attack a risky option for the adversary because it could cause numerous authentication failures and account lockouts. Each of those lockouts lands on a real customer.
The lab shows the trade in one run. With the throttle on, its per-account limit stopped the brute-force run after five wrong guesses, well before the 45th guess that worked with the throttle off. The account's real owner signed in partway through and was refused as well, because a limit counted per account cannot tell the owner from the attacker.
Against a run that touches many accounts, a strict enough per-account lockout does the same to every customer on the attacker's list, which is MITRE's warning in miniature.
The standards cap failures and describe ways to keep an attacker from locking the owner out. NIST SP 800-63B-4, written for government information systems, says in section 3.2.2 that, unless an authenticator type says otherwise, the verifier SHALL limit consecutive failed attempts using a specific authenticator on a single account to no more than 100 by disabling that authenticator, which then has to be rebound before it can be used again.
The limit of 100 is an upper bound that agencies MAY lower. It says additional techniques MAY be used to reduce the chance that an attacker locks the legitimate claimant out: a bot detection and mitigation challenge before authentication, a wait after each failure that grows as the account approaches its allowance (its example runs from 30 seconds up to an hour), and risk-based or adaptive techniques that weigh signals such as the claimant's IP address, geolocation, the timing of request patterns and browser metadata. It also says a successful sign-in SHOULD clear the earlier failed attempts for the authenticators used.
OWASP's Authentication Cheat Sheet says the failure counter should be tied to the account rather than the source address, so spreading attempts across addresses does not escape it, and describes exponential lockout, which starts very short and doubles after each failure.
It says a lockout system must not become a way to lock other users out, and that one way is to let the forgotten-password flow sign the owner in even while the account is locked. The Credential Stuffing Prevention Cheat Sheet adds that mitigations, especially blocking an address, should be temporary.
It says CAPTCHAs are not perfect, that in many cases tools or services exist that can break them, and that to improve usability it may be desirable to ask for a CAPTCHA only when a sign-in looks suspicious or high risk.
OWASP's A07:2025 entry puts it in one line: limit or increasingly delay failed login attempts, but be careful not to create a denial of service scenario.
A delay on its own is not a limit. CWE-307's third example makes the login sleep before checking the password, and notes that because there is no limit on parallel connections, this does not increase the amount of time an attacker needs.
Whatever you choose, ASVS 5.0 requirement 6.1.1, at Level 1, asks for it in writing: documentation that defines how controls such as rate limiting, anti-automation and adaptive response defend against attacks such as credential stuffing and password brute force, how they are configured, and how they prevent malicious account lockout. Request limits across the rest of an application are the subject of the rate limiting guide.
Credential stuffing prevention: the controls that change the outcome
Throttling and detection slow an attack and tell you it is happening.
The controls below change what a correct password is worth, or how many of your customers have one an attacker already holds.
- Multi-factor authentication, wherever you can require it. The cheat sheet calls MFA by far the best defence against the majority of password-related attacks, including credential stuffing and password spraying, and A07:2025 says to implement and enforce it where possible to prevent automated credential stuffing, brute force and stolen credential reuse attacks. Where requiring it of every customer is not feasible, the cheat sheet says it should still be possible to require it of all administrators, and to ask for a second factor when a sign-in looks suspicious, such as one from a new device or from an address that has tried several accounts.
- Check new passwords against breached ones. NIST SP 800-63B-4 section 3.1.1.2 says that when a password is established or changed, verifiers SHALL compare it against a blocklist of commonly used, expected or compromised passwords, which may include passwords from previous breach corpuses. If the password is on the list, the subscriber SHALL be required to choose another and SHALL be told why. ASVS 5.0 requirement 6.2.12, at Level 2, asks for passwords submitted at registration or password change to be checked against a set of breached passwords, and 6.2.4, at Level 1, against at least the top 3000 passwords that match the password policy.
- Use a range lookup, so the password stays on your server. Have I Been Pwned's API documentation describes its Pwned Passwords service as hundreds of millions of passwords previously exposed in data breaches, searchable by k-anonymity: your server sends only the first 5 characters of the password's SHA-1 hash, receives the suffix of every hash with that prefix with a count for each, and looks for a match itself. It offers an Add-Padding header so the response size does not reveal the prefix, and warns against checking as each character is typed. The lab's check works the same way against its own invented list.
- Act on what you learn about breached accounts. NIST says verifiers SHALL force a password change when there is evidence a password has been compromised, and SHALL NOT require periodic changes otherwise. MITRE's mitigation for T1110 says to proactively reset accounts known to be part of breached credentials, either immediately or after detecting brute force attempts.
- Make room for password managers. NIST says verifiers SHALL allow password managers and autofill, and A07:2025 says to encourage and enable their use where possible. A customer with a different password for every site has nothing on a stuffing list that works on yours.
- Consider usernames that are not email addresses. The cheat sheet says requiring users to create their own username makes valid pairs harder to obtain, since many of the available credential lists only include email addresses, and that generated usernames protect more but are user-unfriendly.
- Put the same controls on every way in. API2:2023 says to know all the possible flows that authenticate to an API, such as mobile, web and deep links, to treat credential recovery and forgot-password endpoints as login endpoints for brute force, rate limiting and lockout protections, and to make anti-brute force mechanisms stricter than the API's regular rate limits. A limit on the web form does nothing for a mobile login API that skips it.
What multi-factor authentication changes, and what it does not
Multi-factor authentication changes what a stuffing run wins.
A pair from another site's breach can still be the right password, but on an account where a second factor is enforced, the password alone no longer signs anyone in. OWASP's Multifactor Authentication Cheat Sheet notes that a correct password followed by a failed second factor could mean one of two things: the user has lost their second factor or does not have it available, or the password has been compromised.
It says to notify the user of the failed attempt and encourage them to change their password if they do not recognise it.
The Credential Stuffing Prevention Cheat Sheet draws the same line: a wrong password is generally not worth a notification, but a correct password that then failed the MFA check is.
It changes nothing on a path where the second factor is not asked for. The MFA cheat sheet says that where an application offers several ways to authenticate, all of them should require MFA or have other protections, and names a separate login API and an associated mobile app as an area that is missed.
Among MFA's disadvantages it lists that users may be locked out if they lose or cannot use a factor, and that processes letting users bypass or reset MFA may be exploitable by attackers. ASVS 5.0 requirement 6.4.3 asks that a forgotten-password reset does not bypass any enabled multi-factor mechanism.
It also leaves the password check in place: if the reply to a correct password looks different from the reply to a wrong one, a stuffing run still learns which pairs are right, so the second step's reply is worth a test of its own.
One-time codes do not stop phishing either. NIST SP 800-63B-4 says passwords are not phishing-resistant, and that authenticators which rely on typing in an output, such as out-of-band and one-time password authenticators, SHALL NOT be considered phishing-resistant, because typing the code does not bind it to the session, so an impostor site could relay it.
That is a different attack from stuffing. The choice of factor, push prompts and recovery belong to the MFA security guide.
Credential stuffing test: checking that your controls notice and slow it
A credential stuffing test does not need a real credential list, and should not use one.
The question is whether your login notices each pattern and slows it, and synthetic traffic against test accounts answers that. Part B of the workbook gives eight test cases, each with an expected result and the evidence to keep: the per-account, per-source and login-wide limits, one reply for unknown usernames, the breached-password check at sign-up, change and reset, alerting, and every sign-in path.
Run them on a staging copy with test accounts made for the purpose. WSTG-ATHN-03, the test for weak lockout mechanisms, says testing a lockout needs access to an account you are willing or can afford to lock. Keep the volume small and lower the limits in staging so a handful of attempts reaches them.
If the test runs against production, its rules of engagement name the accounts, the limits and the times, and real customers' accounts stay out of it.
What the lab replays
The lab is an illustration written for this page, and it runs on your own machine. A small login service for an invented shop holds 60 customer accounts and logs every attempt without the password. It listens only on 127.0.0.1, on a port the operating system assigns because the lab asks Node.js to listen on port 0, and nothing in the lab contacts any other address.
A replay script sends three labelled patterns: 60 guesses at one account from one address; three rounds of one password across 50 usernames from one address, with half an hour between rounds; and 240 pairs from an invented other site's leaked list, spread across 30 addresses.
Ten genuine customers sign in during each run, two of them after a typo. A detector reads only the log and names each pattern by the workbook's measures.
What the six runs showed
The detector named all three patterns in all six runs, with the throttle off and on. With the throttle off, the brute-force run signed in on its 45th guess, spraying signed in to the two accounts that used the sprayed password, and stuffing signed in to all six customers who reused a password from the other site.
With the throttle on, no guess reached the right password, spraying signed in to none, and stuffing still signed in to two of the six: 62 of its 240 attempts reached the password check.
The throttle slowed every pattern. It cannot tell whether a correct password belongs to its owner, which is why the detector lists each successful sign-in inside a pattern for review, and why the cheat sheet says that no alternative defence, in isolation, is as effective as multi-factor authentication.
The regression test
lab.test.mjs runs eight checks on Node.js's built-in test runner, which its documentation marks stable from version 20.0.0. On Node.js 26.0.0 all eight passed with both controls on. With the throttle switched off, the three throttle checks failed. With the breached-password check off, the sign-up and password-change checks failed, and with both off, five failed.
The test runner sets the exit code to 1 when any test fails, so the same file in a build pipeline fails the build for a change that removes either control.
After an attack: the accounts, your customers and notification
Treat every successful sign-in inside the pattern as an account that may have been taken over, since MITRE's detection guidance points at exactly that sequence: failures, then success from the same source.
For each one, end its active sessions, require a new password and look at what was done in the account. NIST SP 800-63B-4 says verifiers SHALL force a password change when there is evidence the authenticator has been compromised, and A07:2025 says that if you suspect a breach, force password resets immediately.
ASVS 5.0 requirement 7.4.5 asks that administrators can terminate active sessions for an individual user or for all users, and 7.4.3 that users are offered the option to end all other sessions after a password change. How sessions end is the subject of the session management guide.
Tell the affected customers what happened, plainly. The cheat sheet's guidance on notifying users shapes the message: someone signed in with their correct password, so the password is known outside your site, and because passwords get reused across sites, the email account behind the login may be compromised as well.
Ask them to choose a new password used nowhere else, to change it on any other site where they used the same one, and to turn on multi-factor authentication if you offer it. Say what you have already done, such as ending their sessions, and how to reach you.
The cheat sheet also warns against overwhelming users with notifications that do not matter to them, so keep this message for accounts where a sign-in succeeded.
An account takeover can also be a privacy question. If the accounts held personal information, such as names, addresses, orders or messages, whoever signed in could see it. The OAIC explains how the Notifiable Data Breaches scheme applies to entities covered by the Privacy Act 1988.
Under the scheme, an organisation or agency covered by the Privacy Act 1988 must notify affected individuals and the OAIC when a data breach is likely to result in serious harm to a person whose personal information is involved.
Whether your business is covered, and whether a particular takeover meets that test, are questions for a privacy adviser, and worth asking early, while the facts are still being gathered.
Where an outside review fits
The workbook and lab test what you already know about your login.
A test from outside looks for the paths and gaps you have not listed. A Clever Ops web application and API penetration test covers authentication and sessions, and a WordPress security audit checks the login and password-reset flows. Lockout and rate-limit checks use a small, agreed number of requests, and Clever Ops does not run load or denial-of-service testing.
Destructive actions are off by default for real people's accounts and records that existed before the test, and reset, lockout and deletion checks run only on test accounts and test records where the rules of engagement allow them.
Where read-only code access is in scope, the brute-force and credential-stuffing controls are read in code and compared with the application's own security documentation, which is what ASVS 5.0 requirement 6.3.1 asks for. If Clever Ops built or hosts your application, the work is a security review rather than an independent test, and the report says who built it and who hosts it.
If accounts are being taken over right now, call an incident response specialist first: Clever Ops does not provide incident response.
Frequently asked questions
Where the passwords come from. Credential stuffing replays username and password pairs leaked from another site, so each username arrives with its own password and some of the usernames may not be accounts on your site at all. Password spraying tries one weak password, or a small list, against many different accounts, and MITRE says it is done that way to avoid the lockouts that guessing one account would cause. In a log, stuffing shows as about one attempt per username, whether it arrives as a burst or spread thinly across many addresses over a longer period, and spraying shows as the same accounts revisited round after round.
MITRE files it under T1110 Brute Force, as sub-technique T1110.004, beside password guessing and password spraying. OWASP separates them: its OAT-008 entry says credential stuffing does not involve any brute-forcing or guessing of values, because the credentials were used elsewhere and are only being tested here. The defences overlap either way: OWASP's cheat sheet says that in many cases the defences against stuffing and spraying are the same, and that they would also be effective against brute force.
It stops a correct password from being enough on its own, on every path where the second factor is required. OWASP calls it by far the best defence against the majority of password-related attacks, including credential stuffing. It leaves gaps where a login path skips it, such as a separate API or a mobile app, and where a recovery process lets someone bypass or reset it. A correct password followed by a failed second factor could mean the user has lost or cannot use their second factor, or that the password has been compromised, and OWASP says to notify the user and encourage them to change the password if they do not recognise the attempt.
Not by itself. Stuffing tries each username about once: in the lab's stuffing run, no username had more than one unsuccessful attempt, so a limit counted per account had nothing to count. A strict lockout also hands the attacker a way to lock real customers out, and MITRE warns that too strict a policy may create a denial of service condition. Pair a per-account limit with limits per source and across the whole login, make refusals temporary, keep a route back in for the real owner, and check new passwords against breached ones.
Look for many different usernames failing with about one attempt each, some of them not accounts on your site, followed by successful sign-ins from the same sources. The attempts can arrive as a burst or as low, steady traffic over a longer period, so check both short and long windows. Look across the whole login as well as per address, because an attack spread across many addresses can keep each one below a per-source threshold, as the lab's 30-address run did. The workbook on this page lists the five measures and what each pattern looks like in them.
Yes, and that is the safer way to do it. The test asks whether your controls notice and slow each pattern, not whether a real customer reused a password. Invent the usernames and passwords, as the lab on this page does, use test accounts on a staging copy, keep the number of requests small, and lower the limits so a few attempts reach them. Real customers' accounts stay out of it.
Tell the customers whose accounts were signed into, so they can change their password and check other sites where they used the same one. Notification beyond that is a legal question. The OAIC explains that under the Notifiable Data Breaches scheme, an organisation or agency covered by the Privacy Act 1988 must notify affected individuals and the OAIC when a data breach is likely to result in serious harm to a person whose personal information is involved. Whether that applies to your business and to this takeover is a question for a privacy adviser.
Scope the right test for your application
Tell us what you have built, who uses it and when it needs to launch. You will get a plain-English recommendation: a website audit, a web application test or a referral to a specialist.