fraud-sim 0.2.0 → 0.5.1

package/src/scenarios/adaptive-attacker.js

@@ -22,6 +22,7 @@
 import { sleep } from '../utils/sleep.js';
 import { buildLoginPayload } from '../utils/faker-helpers.js';
 import { deterministic } from '../llm/deterministic.js';
+import { randomInt } from '../utils/random.js';
 
 export default {
   id: 'adaptive-attacker',
@@ -45,8 +46,13 @@ export default {
       throw new Error('adaptive-attacker requires options.targetUserId');
     }
 
-    // Fall back to a seeded deterministic provider when no LLM is supplied.
-    const llm = ctx.llm ?? deterministic({ seed: 42 });
+    // Fall back to the deterministic provider when no LLM is supplied. Its seed
+    // is drawn from the run's own random source rather than being hardcoded:
+    // under a seeded run that makes the strategy sequence reproducible, and it
+    // makes two different run seeds actually produce different attacks. A fixed
+    // provider seed would have made every seeded run of this scenario identical
+    // no matter what seed the caller passed.
+    const llm = ctx.llm ?? deterministic({ seed: randomInt(1, 2 ** 31 - 1) });
 
     const results = {
       attempts: 0,
@@ -68,10 +74,13 @@ export default {
       timestamp: Date.now(),
     });
 
+    // Declared outside the loop: each round's strategy is merged over the
+    // parameters actually sent the round before.
+    let parameters;
+
     for (let round = 1; round <= options.maxRounds; round++) {
       if (signal.aborted) break;
 
-      let parameters;
       let reasoning;
 
       if (round === 1) {
@@ -109,6 +118,27 @@ export default {
         reasoning = strategy?.reasoning ?? '';
       }
 
+      const payload = buildLoginPayload(options.targetUserId, {
+        ip_address: parameters.ip,
+        user_agent: parameters.userAgent,
+        ...(parameters.deviceFingerprint
+          ? { device_fingerprint: parameters.deviceFingerprint }
+          : {}),
+      });
+
+      // Record what was actually sent, not what was asked for. A parameter the
+      // strategy left unset is filled in by the payload builder, and the
+      // attacker has to see that value: round 1 never names a fingerprint, so
+      // without this the history said `null` and the device the defender
+      // challenged could never be replayed. It also makes an omitted key mean
+      // "keep it" rather than silently rotating it every round.
+      parameters = {
+        ...parameters,
+        ip: payload.ip_address,
+        userAgent: payload.user_agent,
+        deviceFingerprint: payload.device_fingerprint,
+      };
+
       // Emit the adaptation BEFORE sending — this is the demo moment.
       emit({
         type: 'attacker_adapts',
@@ -119,14 +149,6 @@ export default {
       });
       results.strategyHistory.push({ round, reasoning, parameters });
 
-      const payload = buildLoginPayload(options.targetUserId, {
-        ip_address: parameters.ip,
-        user_agent: parameters.userAgent,
-        ...(parameters.deviceFingerprint
-          ? { device_fingerprint: parameters.deviceFingerprint }
-          : {}),
-      });
-
       const t0 = Date.now();
       emit({ type: 'attempt', round, payload, timestamp: t0 });
 

package/src/scenarios/card-testing.js

@@ -0,0 +1,174 @@
+/**
+ * Scenario: card-testing
+ *
+ * An attacker holding a list of stolen card numbers needs to know which ones
+ * are still live. They probe each card with a tiny authorisation — small enough
+ * that a cardholder may not notice and a fraud system may not care — and then
+ * escalate to a real charge on whichever cards come back approved.
+ *
+ * The tell is not any single transaction. It is the shape of the traffic: many
+ * distinct cards, drawn from a handful of BIN ranges, all card-not-present, all
+ * for near-identical trivial amounts, in a short window.
+ *
+ * Defensive systems should catch this via:
+ *   - Micro-authorisation velocity  (many tiny auths in a short window)
+ *   - BIN range velocity            (many cards sharing few BIN prefixes)
+ *   - CNP transaction patterns      (no cardholder present, no address match)
+ *   - Decline-rate monitoring       (a high decline ratio is itself the signal)
+ *
+ * Note on card data: `fraud-sim` never generates Luhn-valid numbers and never
+ * emits a full PAN. Payloads carry an opaque token, a published test BIN, and
+ * four synthetic digits — which is what a risk API receives in practice.
+ *
+ * Realistic block rates against a well-tuned system: 80-95%, and most of the
+ * value is in *how early* the block comes.
+ */
+
+import { sleep } from '../utils/sleep.js';
+import { buildCardAuthPayload } from '../utils/faker-helpers.js';
+import { newResults, scoreAndCount } from '../utils/results.js';
+import { cardBins, randomLast4, newCardToken, randomIp, pickDemoIp } from '../utils/random.js';
+
+export default {
+  id: 'card-testing',
+  name: 'Card testing / BIN attack',
+  description:
+    'An attacker validates a list of stolen cards with micro-authorisations, then escalates to real charges on the cards that come back approved.',
+
+  defaultOptions: {
+    attackerUserId: 'card_tester_001', // the merchant-side account doing the probing
+    cardCount: 60, // distinct cards in the stolen list
+    binCount: 3, // how many BIN ranges the list is drawn from — few is the tell
+    microAmountMinor: 5000, // NGN 50 probe
+    largeAmountMinor: 15000000, // NGN 150,000 once a card is known good
+    escalateAfter: 1, // approvals on a card before attempting the real charge
+    delayMs: 80,
+    maxTotalAttempts: 300,
+    ipPersona: 'random',
+    reuseIp: true, // card testers usually run from one host until it stops working
+  },
+
+  async run(ctx) {
+    const { options, emit, signal } = ctx;
+
+    if (options.cardCount < 1) {
+      throw new Error('card-testing requires options.cardCount >= 1');
+    }
+    if (options.binCount < 1) {
+      throw new Error('card-testing requires options.binCount >= 1');
+    }
+
+    const results = newResults({
+      cardsTested: 0,
+      cardsValidated: 0, // probes that came back ALLOW
+      escalations: 0, // large charges attempted
+      escalationsAllowed: 0, // large charges that got through — actual loss
+    });
+
+    const bins = cardBins().slice(0, options.binCount);
+    const attacker = resolveIp(options);
+
+    emit({
+      type: 'milestone',
+      message:
+        `Probing ${options.cardCount} cards across ${bins.length} BIN range(s) ` +
+        `with NGN ${(options.microAmountMinor / 100).toLocaleString()} authorisations`,
+      timestamp: Date.now(),
+    });
+
+    for (let i = 0; i < options.cardCount; i++) {
+      if (signal.aborted) break;
+      if (results.attempts >= options.maxTotalAttempts) break;
+
+      const card = {
+        token: newCardToken(),
+        bin: bins[i % bins.length],
+        last4: randomLast4(),
+      };
+
+      // A fresh host per card would defeat the point — the attacker is trying
+      // to stay cheap, and reusing infrastructure is what makes them catchable.
+      const ip = options.reuseIp ? attacker : resolveIp(options);
+
+      const probe = await scoreAndCount({
+        ctx,
+        method: 'scoreAction',
+        payload: buildCardAuthPayload(options.attackerUserId, card, options.microAmountMinor, {
+          ip_address: ip.ip,
+          details: { probe: true },
+        }),
+        results,
+        stage: 'probe',
+        ipIntel: ip.intel,
+      });
+
+      results.cardsTested++;
+
+      if (probe?.decision === 'ALLOW') {
+        results.cardsValidated++;
+
+        if (results.cardsValidated % options.escalateAfter === 0) {
+          if (results.attempts >= options.maxTotalAttempts) break;
+
+          emit({
+            type: 'milestone',
+            message: `Card ${card.bin}••${card.last4} approved — escalating to a real charge`,
+            timestamp: Date.now(),
+          });
+
+          const charge = await scoreAndCount({
+            ctx,
+            method: 'scoreAction',
+            payload: buildCardAuthPayload(
+              options.attackerUserId,
+              card,
+              options.largeAmountMinor,
+              { ip_address: ip.ip, details: { probe: false } }
+            ),
+            results,
+            stage: 'escalation',
+            ipIntel: ip.intel,
+          });
+
+          results.escalations++;
+          if (charge?.decision === 'ALLOW') results.escalationsAllowed++;
+        }
+      }
+
+      try {
+        await sleep(options.delayMs, signal);
+      } catch {
+        break; // aborted
+      }
+    }
+
+    const lossMinor = results.escalationsAllowed * options.largeAmountMinor;
+
+    emit({
+      type: 'milestone',
+      message:
+        `${results.cardsValidated} of ${results.cardsTested} cards validated; ` +
+        `${results.escalationsAllowed} of ${results.escalations} charges succeeded ` +
+        `(NGN ${(lossMinor / 100).toLocaleString()} at risk)`,
+      timestamp: Date.now(),
+    });
+
+    return {
+      ...results,
+      // The headline number for this scenario is not the block rate — it is
+      // whether any escalated charge got through at all.
+      estimatedLossKobo: lossMinor,
+      attackerSucceeded: results.escalationsAllowed > 0,
+      binsUsed: bins,
+    };
+  },
+};
+
+function resolveIp(options) {
+  if (!options.ipPersona || options.ipPersona === 'random') {
+    return { ip: randomIp(), intel: undefined };
+  }
+  const persona = options.ipPersona === 'mixed' ? 'hosting' : options.ipPersona;
+  const { ip, ...intel } = pickDemoIp(persona);
+  return { ip, intel };
+}

package/src/scenarios/credential-stuffing.js

@@ -1,45 +1,78 @@
 /**
  * Scenario: credential-stuffing
  *
- * A botnet attempts to authenticate using stolen credentials. Each attempt
- * comes from a different IP, rotates user agents, and paces attempts to
- * evade naive rate limits. This is the most common automated attack against
- * fintech login endpoints.
+ * A botnet replays a stolen credential dump against a login endpoint. Attempts
+ * come from many IPs, rotate user agents, and — crucially — spray across many
+ * *different* user accounts, because a credential dump is a list of victims,
+ * not one victim tried repeatedly. This is the most common automated attack
+ * against fintech login endpoints.
  *
  * Defensive systems should catch this via:
  *   - LOGIN_VELOCITY_USER (many attempts on one user)
  *   - LOGIN_VELOCITY_IP   (many attempts from one IP)
- *   - IP_PROXY_VPN        (datacenter / VPN IPs)
  *   - IP_MANY_USERS       (one IP trying many user accounts)
+ *   - IP_PROXY_VPN        (datacenter / VPN IPs)
  *   - NEW_DEVICE          (every attempt is a new device fingerprint)
  *
  * Realistic block rates against a well-tuned system: 85-95%.
+ *
+ * ── Calibration note ──────────────────────────────────────────────────
+ * The defaults below are deliberately tuned to *cross* the thresholds that
+ * typical rule engines ship with, rather than to look gentle. Two settings
+ * matter most:
+ *
+ *   - `attemptsPerIp` must exceed the target's per-IP velocity limit within
+ *     its window, or that rule never fires. Common defaults sit near 20 per
+ *     5 minutes; the default here is 25.
+ *   - `targetUserIds` must contain more accounts than the target's
+ *     "one IP, many users" limit (commonly 10), or that rule never fires.
+ *
+ * A run that stays under both limits will report a low block rate that says
+ * nothing about the defence — it only means the attack was too quiet to be
+ * worth catching. Turn these *down* to probe where a system's floor is; leave
+ * them at the defaults to measure whether it catches an ordinary attack.
  */
 
 import { sleep } from '../utils/sleep.js';
 import { buildLoginPayload } from '../utils/faker-helpers.js';
-import { randomIp, randomUserAgent } from '../utils/random.js';
+import {
+  randomIp,
+  randomUserAgent,
+  randomFloat,
+  pickDemoIp,
+  DEMO_IP_POOL,
+} from '../utils/random.js';
+
+/**
+ * Personas drawn from DEMO_IP_POOL when `ipPersona: 'mixed'`.
+ *
+ * Includes `domestic` on purpose: a real botnet rents residential proxies in
+ * the victim's own country precisely to avoid the geo signals that the other
+ * personas trip. An all-foreign mix makes every attempt look identical to the
+ * defence, which flatters the block rate and produces a monotonous event feed.
+ */
+const MIXED_PERSONAS = ['hosting', 'proxy', 'foreign', 'domestic'];
 
 export default {
   id: 'credential-stuffing',
   name: 'Credential stuffing attack',
   description:
-    'A botnet attempts to authenticate using stolen credentials. Distinct IPs, rotating user agents, paced to evade simple rate limits.',
+    'A botnet replays a stolen credential dump. Distinct IPs, rotating user agents, sprayed across many accounts to evade per-user rate limits.',
 
   defaultOptions: {
-    targetUserId: null, // required
-    attackerCount: 50, // distinct IPs
-    attemptsPerIp: 3, // attempts before rotating IP
-    delayMs: 200, // ms between attempts
-    maxTotalAttempts: 200, // safety ceiling — prevents runaway sims
+    targetUserIds: null, // required — array of accounts from the "dump"
+    targetUserId: null, // back-compat: single account, equivalent to [targetUserId]
+    attackerCount: 20, // distinct IPs
+    attemptsPerIp: 25, // attempts before rotating IP — must beat per-IP velocity limits
+    delayMs: 100, // ms between attempts
+    maxTotalAttempts: 500, // safety ceiling — prevents runaway sims
+    ipPersona: 'random', // 'random' | 'mixed' | 'domestic' | 'hosting' | 'proxy' | 'foreign'
   },
 
   async run(ctx) {
     const { options, target, emit, signal } = ctx;
 
-    if (!options.targetUserId) {
-      throw new Error('credential-stuffing requires options.targetUserId');
-    }
+    const userIds = resolveUserIds(options);
 
     const results = {
       attempts: 0,
@@ -49,31 +82,64 @@ export default {
       errors: 0,
     };
 
+    const usersSeen = new Set();
+
     emit({
       type: 'milestone',
-      message: `Starting credential stuffing: ${options.attackerCount} IPs × ${options.attemptsPerIp} attempts (max ${options.maxTotalAttempts} total)`,
+      message:
+        `Starting credential stuffing: ${options.attackerCount} IPs × ${options.attemptsPerIp} attempts ` +
+        `across ${userIds.length} account${userIds.length === 1 ? '' : 's'} ` +
+        `(max ${options.maxTotalAttempts} total)`,
       timestamp: Date.now(),
     });
 
+    if (userIds.length === 1) {
+      emit({
+        type: 'milestone',
+        message:
+          'Only one target account supplied — "one IP, many users" detection cannot fire. ' +
+          'Pass options.targetUserIds with several accounts to exercise it.',
+        timestamp: Date.now(),
+      });
+    }
+
+    // Draw pool IPs without replacement so each attacker is distinct until the
+    // pool is exhausted, then cycle — a real botnet reuses its exits too.
+    const ipSource = makeIpSource(options.ipPersona);
+
     outer: for (let i = 0; i < options.attackerCount; i++) {
       if (signal.aborted) break;
 
-      // Each "attacker IP" is a different IP + user agent combination
-      const attackerIp = randomIp();
+      // Each "attacker" is a different IP + user agent combination
+      const attacker = ipSource(i);
+      const attackerIp = attacker.ip;
       const userAgent = randomUserAgent();
 
       for (let j = 0; j < options.attemptsPerIp; j++) {
         if (signal.aborted) break outer;
         if (results.attempts >= options.maxTotalAttempts) break outer;
 
-        const payload = buildLoginPayload(options.targetUserId, {
+        // Spray across the dump: this IP walks the account list rather than
+        // hammering one user, which is what makes it credential stuffing.
+        const userId = userIds[results.attempts % userIds.length];
+        usersSeen.add(userId);
+
+        const payload = buildLoginPayload(userId, {
           ip_address: attackerIp,
           user_agent: userAgent,
           // Crucially: new device fingerprint per attempt (botnet behaviour)
         });
 
         const t0 = Date.now();
-        emit({ type: 'attempt', round: results.attempts, payload, timestamp: t0 });
+        emit({
+          type: 'attempt',
+          round: results.attempts,
+          payload,
+          // Present only for pool-backed IPs — lets a target pre-warm its
+          // IP-intel cache instead of doing live lookups mid-run.
+          ipIntel: attacker.intel,
+          timestamp: t0,
+        });
 
         let response;
         try {
@@ -119,6 +185,66 @@ export default {
       stepUp: results.stepUp,
       allowed: results.allowed,
       errors: results.errors,
+      accountsTargeted: usersSeen.size,
     };
   },
 };
+
+// ── internals ───────────────────────────────────────────────────────────
+
+/**
+ * Accept either `targetUserIds` (preferred) or the legacy single
+ * `targetUserId`, and validate.
+ */
+function resolveUserIds(options) {
+  const { targetUserIds, targetUserId } = options;
+
+  if (targetUserIds != null) {
+    if (!Array.isArray(targetUserIds) || targetUserIds.length === 0) {
+      throw new Error('credential-stuffing: options.targetUserIds must be a non-empty array');
+    }
+    return targetUserIds;
+  }
+
+  if (targetUserId) return [targetUserId];
+
+  throw new Error(
+    'credential-stuffing requires options.targetUserIds (an array of accounts), ' +
+      'or options.targetUserId for a single account'
+  );
+}
+
+/**
+ * Build a function that returns the i-th attacker's IP and, where known, its
+ * declared intel. Pool draws are without replacement until exhausted.
+ */
+function makeIpSource(persona) {
+  if (persona === 'random' || persona == null) {
+    return () => ({ ip: randomIp(), intel: undefined });
+  }
+
+  if (persona === 'mixed') {
+    const shuffled = shuffle(DEMO_IP_POOL.filter((e) => MIXED_PERSONAS.includes(e.persona)));
+    return (i) => toAttacker(shuffled[i % shuffled.length]);
+  }
+
+  // A single named persona — validate eagerly so a typo fails on the first
+  // attacker rather than silently behaving like 'random'.
+  pickDemoIp(persona);
+  const shuffled = shuffle(DEMO_IP_POOL.filter((e) => e.persona === persona));
+  return (i) => toAttacker(shuffled[i % shuffled.length]);
+}
+
+function toAttacker(entry) {
+  const { ip, ...intel } = entry;
+  return { ip, intel };
+}
+
+function shuffle(arr) {
+  const out = [...arr];
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = Math.floor(randomFloat() * (i + 1));
+    [out[i], out[j]] = [out[j], out[i]];
+  }
+  return out;
+}

package/src/scenarios/index.js

@@ -1,25 +1,56 @@
 /**
  * Scenario registry — all built-in scenarios.
  *
- * v0.1 shipped with two scenarios:
+ * v0.1 shipped:
  *   - credential-stuffing
  *   - account-drain
  *
- * v0.2 adds:
+ * v0.2 added:
  *   - adaptive-attacker (LLM-driven)
  *
- * v0.3 will add:
- *   - promo-abuse
+ * v0.3 adds seven, completing the planned library:
  *   - card-testing
- *   - sim-swap-takeover
+ *   - promo-abuse
  *   - mule-network
  *   - slow-drain
  *   - session-hijack
+ *   - sim-swap-takeover
  *   - velocity-evasion
+ *
+ * v0.5 adds the other half of the measurement:
+ *   - legitimate-users — ordinary customers, not an attack. Every block it
+ *     receives is a false positive. Listed first so a suite measures customers
+ *     before its own attacks have burned any shared state on the target.
+ *
+ * Endpoint requirements differ by scenario. `credential-stuffing`,
+ * `account-drain`, `adaptive-attacker`, `slow-drain` and `velocity-evasion`
+ * need only `scoreLogin` / `scoreWithdrawal`. `card-testing`, `promo-abuse` and
+ * `session-hijack` also need `scoreAction`; a scenario throws with a clear
+ * message if the adapter does not implement what it needs.
  */
 
+import legitimateUsers from './legitimate-users.js';
 import credentialStuffing from './credential-stuffing.js';
 import accountDrain from './account-drain.js';
 import adaptiveAttacker from './adaptive-attacker.js';
+import cardTesting from './card-testing.js';
+import promoAbuse from './promo-abuse.js';
+import muleNetwork from './mule-network.js';
+import slowDrain from './slow-drain.js';
+import sessionHijack from './session-hijack.js';
+import simSwapTakeover from './sim-swap-takeover.js';
+import velocityEvasion from './velocity-evasion.js';
 
-export const scenarios = [credentialStuffing, accountDrain, adaptiveAttacker];
+export const scenarios = [
+  legitimateUsers,
+  credentialStuffing,
+  accountDrain,
+  adaptiveAttacker,
+  cardTesting,
+  promoAbuse,
+  muleNetwork,
+  slowDrain,
+  sessionHijack,
+  simSwapTakeover,
+  velocityEvasion,
+];