fraud-sim 0.2.0 → 0.5.1

package/src/scenarios/legitimate-users.js

@@ -0,0 +1,290 @@
+/**
+ * Scenario: legitimate-users
+ *
+ * Not an attack. Ordinary customers doing ordinary things — logging in from
+ * their own phone, paying people they have paid before, occasionally buying a
+ * new phone or travelling — which is the traffic a defence must let through.
+ *
+ * Every other scenario measures how much attack traffic gets stopped. On its
+ * own that number is easy to game: a defence that blocks everything has a 100%
+ * block rate. This scenario is the other half of the measurement. A block here
+ * is a false positive — a real customer refused — and a step-up is friction.
+ *
+ * Each customer has a stable identity: one device, one browser, one home
+ * address in a domestic city, and a couple of payees they already know. A short
+ * warm-up gives the target some history before anything is measured, because a
+ * real customer is not a stranger to the system the way a simulated one is.
+ * Warm-up decisions are reported separately and excluded from the rates.
+ *
+ * Sessions are spread across days on a simulated clock, not sent as a burst,
+ * so a velocity rule only fires on this traffic if it would fire on a real
+ * customer's week. That holds only if the target reads the event timestamp —
+ * see `simulatedTime` in the report.
+ *
+ * Behaviour, per measured session:
+ *   - routine       own device, home network                 → should ALLOW
+ *   - new device    a new phone, home network                → STEP_UP is fair
+ *   - travel        own device, a foreign residential network → STEP_UP is fair
+ *   - withdrawal    to a known payee, a normal amount        → should ALLOW
+ *   - new payee     a small first payment to someone new     → STEP_UP is fair
+ *
+ * A customer whose login is blocked gives up for that session; one who is
+ * challenged is assumed to pass the challenge and carry on, as most do.
+ */
+
+import { sleep } from '../utils/sleep.js';
+import { simulatedClock, humaniseMs } from '../utils/clock.js';
+import {
+  buildLoginPayload,
+  buildWithdrawalPayload,
+  newDeviceFingerprint,
+  newPayee,
+  newSessionId,
+} from '../utils/faker-helpers.js';
+import { newResults, scoreAndCount } from '../utils/results.js';
+import { randomFloat } from '../utils/random-source.js';
+import { demoIpPool, pickDemoIp, pickOne, randomBrowserUserAgent, randomInt } from '../utils/random.js';
+
+/** Stages, in the order the report lists them. */
+const STAGES = [
+  'routine-login',
+  'new-device-login',
+  'travel-login',
+  'known-payee-withdrawal',
+  'new-payee-withdrawal',
+];
+
+export default {
+  id: 'legitimate-users',
+  name: 'Legitimate customers',
+  traffic: 'legitimate',
+  description:
+    'Ordinary customers logging in and paying people they know. Not an attack: measures false positives and friction.',
+
+  defaultOptions: {
+    targetUserIds: null, // required — one customer per id
+    warmupLogins: 2, // history per customer before anything is measured
+    sessionsPerUser: 4, // measured sessions per customer
+    sessionGapHours: 8, // simulated time between a customer's sessions
+    withdrawalRate: 0.5, // share of sessions that include a payment
+    newDeviceRate: 0.1, // share of sessions on a new phone
+    travelRate: 0.05, // share of sessions from abroad
+    newPayeeRate: 0.1, // share of payments to someone new
+    amountMinor: 2500000, // typical payment (25,000 major units)
+    delayMs: 20,
+  },
+
+  async run(ctx) {
+    const { options, emit, signal } = ctx;
+
+    const userIds = options.targetUserIds;
+    if (!Array.isArray(userIds) || userIds.length === 0) {
+      throw new Error('legitimate-users requires options.targetUserIds (one id per customer)');
+    }
+    for (const key of ['withdrawalRate', 'newDeviceRate', 'travelRate', 'newPayeeRate']) {
+      if (!(options[key] >= 0 && options[key] <= 1)) {
+        throw new Error(`legitimate-users requires options.${key} between 0 and 1`);
+      }
+    }
+    if (options.newDeviceRate + options.travelRate > 1) {
+      throw new Error('legitimate-users requires newDeviceRate + travelRate <= 1');
+    }
+
+    const results = newResults();
+    const warmup = newResults();
+    const byStage = Object.fromEntries(
+      STAGES.map((s) => [s, { events: 0, allowed: 0, stepUp: 0, blocked: 0 }])
+    );
+    const blockedCustomers = new Set();
+    const falsePositiveReasons = new Map();
+    let valueBlockedMinor = 0;
+
+    const clock = simulatedClock({ start: Date.now(), stepMs: options.sessionGapHours * 3_600_000 });
+    const customers = userIds.map((id, i) => newCustomer(id, i));
+
+    emit({
+      type: 'milestone',
+      message:
+        `${customers.length} ordinary customers, ${options.sessionsPerUser} sessions each — ` +
+        'every block from here on is a false positive',
+      timestamp: Date.now(),
+    });
+
+    const send = async (customer, method, payload, stage, ipIntel, tally) => {
+      const response = await scoreAndCount({ ctx, method, payload, results: tally, stage, ipIntel });
+      if (tally === results && response) {
+        const decision = response.decision;
+        const row = byStage[stage];
+        row.events++;
+        if (decision === 'ALLOW') row.allowed++;
+        else if (decision === 'STEP_UP') row.stepUp++;
+        else if (decision === 'BLOCK') {
+          row.blocked++;
+          blockedCustomers.add(customer.id);
+          for (const reason of response.reasons ?? []) {
+            const code = typeof reason === 'string' ? reason : reason?.code;
+            if (code) falsePositiveReasons.set(code, (falsePositiveReasons.get(code) ?? 0) + 1);
+          }
+        }
+      }
+      try {
+        await sleep(options.delayMs, signal);
+      } catch {
+        // aborted — the loops check `signal` before the next send
+      }
+      return response;
+    };
+
+    // ── Warm-up: the history a real customer would already have ─────────
+    for (let i = 0; i < options.warmupLogins && !signal.aborted; i++) {
+      for (const customer of customers) {
+        if (signal.aborted) break;
+        await send(
+          customer,
+          'scoreLogin',
+          loginPayload(customer, customer.home.ip, clock),
+          'warmup-login',
+          customer.home.intel,
+          warmup
+        );
+      }
+      clock.advance();
+    }
+
+    // ── Measured sessions ───────────────────────────────────────────────
+    for (let s = 0; s < options.sessionsPerUser && !signal.aborted; s++) {
+      for (const customer of customers) {
+        if (signal.aborted) break;
+
+        const roll = randomFloat();
+        let stage = 'routine-login';
+        let network = customer.home;
+
+        if (roll < options.travelRate) {
+          stage = 'travel-login';
+          network = foreignNetwork();
+        } else if (roll < options.travelRate + options.newDeviceRate) {
+          stage = 'new-device-login';
+          // A new phone, so a new fingerprint — and from now on it is theirs.
+          customer.device = newDeviceFingerprint();
+        }
+
+        const loginSent = loginPayload(customer, network.ip, clock);
+        const login = await send(
+          customer,
+          'scoreLogin',
+          loginSent,
+          stage,
+          network.intel,
+          results
+        );
+
+        if (!login || login.decision === 'BLOCK') continue;
+        if (randomFloat() >= options.withdrawalRate) continue;
+
+        const toNewPayee = randomFloat() < options.newPayeeRate;
+        // A first payment to someone new is usually small; a payment to a
+        // known payee varies around the customer's usual amount.
+        const amount = toNewPayee
+          ? Math.round(options.amountMinor * (0.1 + randomFloat() * 0.2))
+          : Math.round(options.amountMinor * (0.5 + randomFloat()));
+        const payee = toNewPayee ? newPayee() : pickOne(customer.payees);
+
+        const withdrawal = await send(
+          customer,
+          'scoreWithdrawal',
+          buildWithdrawalPayload(
+            customer.id,
+            { amount, ...payee, is_new_payee: toNewPayee },
+            {
+              // Same session, device and network as the login, a few minutes on.
+              session_id: loginSent.session_id,
+              ip_address: network.ip,
+              device_fingerprint: customer.device,
+              timestamp: new Date(Date.parse(loginSent.timestamp) + randomInt(1, 10) * 60_000).toISOString(),
+            }
+          ),
+          toNewPayee ? 'new-payee-withdrawal' : 'known-payee-withdrawal',
+          network.intel,
+          results
+        );
+
+        if (withdrawal?.decision === 'BLOCK') valueBlockedMinor += amount;
+        // Once paid, a new payee is a known one next time.
+        if (toNewPayee) customer.payees.push(payee);
+      }
+      clock.advance();
+    }
+
+    const scored = Math.max(0, results.attempts - results.errors);
+
+    if (results.blocked > 0) {
+      emit({
+        type: 'milestone',
+        message:
+          `${results.blocked} ordinary customer event${results.blocked === 1 ? ' was' : 's were'} ` +
+          `blocked — ${blockedCustomers.size} of ${customers.length} customers refused at least once`,
+        timestamp: Date.now(),
+      });
+    }
+
+    return {
+      ...results,
+      customers: customers.length,
+      customersBlocked: blockedCustomers.size,
+      falsePositiveRate: scored > 0 ? results.blocked / scored : 0,
+      frictionRate: scored > 0 ? (results.blocked + results.stepUp) / scored : 0,
+      valueBlockedMinor,
+      byStage,
+      falsePositiveReasons: Object.fromEntries(
+        [...falsePositiveReasons].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      ),
+      warmup: {
+        attempts: warmup.attempts,
+        blocked: warmup.blocked,
+        stepUp: warmup.stepUp,
+        allowed: warmup.allowed,
+        errors: warmup.errors,
+      },
+      simulatedTime: true,
+      simulatedSpan: humaniseMs(clock.elapsedMs()),
+    };
+  },
+};
+
+/**
+ * One customer's stable identity.
+ *
+ * Each gets their own home address in the documentation range, carrying the
+ * geolocation of a domestic city. Sharing the market's few domestic pool
+ * addresses would put a dozen customers on one IP and trip any users-per-IP
+ * rule — a false positive manufactured by the simulator, not found by it.
+ */
+function newCustomer(id, index) {
+  const domestic = demoIpPool().filter((e) => e.persona === 'domestic');
+  const { ip: _poolIp, ...intel } = domestic[index % domestic.length];
+  return {
+    id,
+    device: newDeviceFingerprint(),
+    userAgent: randomBrowserUserAgent(),
+    // 192.0.2.100–254: RFC 5737, clear of the shared pool's .10–.12.
+    home: { ip: `192.0.2.${100 + (index % 155)}`, intel },
+    payees: [newPayee(), newPayee()],
+  };
+}
+
+function foreignNetwork() {
+  const { ip, ...intel } = pickDemoIp('foreign');
+  return { ip, intel };
+}
+
+function loginPayload(customer, ip, clock) {
+  // Sessions minutes apart within a round, not all on the same millisecond.
+  return buildLoginPayload(customer.id, {
+    session_id: newSessionId('sess'),
+    ip_address: ip,
+    user_agent: customer.userAgent,
+    device_fingerprint: customer.device,
+    timestamp: new Date(clock.epoch() + randomInt(0, 90) * 60_000).toISOString(),
+  });
+}

package/src/scenarios/mule-network.js

@@ -0,0 +1,201 @@
+/**
+ * Scenario: mule-network
+ *
+ * Stolen funds are rarely withdrawn in one move. They are layered: a source
+ * account pushes money to a set of intermediary "mule" accounts, each of which
+ * forwards nearly all of it onward to a common destination, keeping a small cut
+ * as payment. The mules are often real people with real, previously clean
+ * accounts — which is exactly why per-account rules struggle here.
+ *
+ * No individual transfer in this scenario need look unusual. What gives it away
+ * is the graph: a fan-out followed by a fan-in, with high pass-through and low
+ * retention at every intermediate hop.
+ *
+ * Defensive systems should catch this via:
+ *   - Graph clustering        (accounts linked by transaction flow)
+ *   - Pass-through ratio      (money in ≈ money out, within hours)
+ *   - Fan-in concentration    (many unrelated accounts, one destination)
+ *   - Dormancy-then-activity  (a quiet account suddenly moving funds)
+ *
+ * A system scoring transactions one at a time, with no memory of the graph,
+ * will pass this scenario cleanly — which is the point of running it.
+ */
+
+import { sleep } from '../utils/sleep.js';
+import {
+  buildTransferPayload,
+  newDeviceFingerprint,
+} from '../utils/faker-helpers.js';
+import { newResults, scoreAndCount } from '../utils/results.js';
+import { simulatedClock, humaniseMs } from '../utils/clock.js';
+import { randomAccountNumber, randomIp } from '../utils/random.js';
+
+export default {
+  id: 'mule-network',
+  name: 'Mule network layering',
+  description:
+    'A source account fans funds out to intermediary mules, each of which forwards nearly all of it to one final destination.',
+
+  defaultOptions: {
+    sourceUserId: null, // required — the compromised or complicit origin
+    muleCount: 8,
+    amountPerMuleMinor: 30000000, // NGN 300,000 to each mule
+    retentionRatio: 0.05, // the cut each mule keeps; the rest is forwarded
+    finalDestinationAccount: null, // null → generated
+    forwardDelayMinutes: 45, // simulated gap between receiving and forwarding
+    delayMs: 100, // wall-clock pacing, unrelated to the simulated gap
+    maxTotalAttempts: 100,
+  },
+
+  async run(ctx) {
+    const { options, emit, signal } = ctx;
+
+    if (!options.sourceUserId) {
+      throw new Error('mule-network requires options.sourceUserId');
+    }
+    if (options.muleCount < 1) {
+      throw new Error('mule-network requires options.muleCount >= 1');
+    }
+    if (options.retentionRatio < 0 || options.retentionRatio >= 1) {
+      throw new Error('mule-network requires 0 <= options.retentionRatio < 1');
+    }
+
+    const results = newResults({
+      fanOutTransfers: 0,
+      forwardTransfers: 0,
+      fanOutAllowed: 0,
+      forwardAllowed: 0,
+      totalMovedMinor: 0,
+      reachedDestinationMinor: 0,
+    });
+
+    const destination = options.finalDestinationAccount ?? randomAccountNumber();
+    const clock = simulatedClock({ start: Date.now() });
+
+    // Each mule is a distinct account, device and network — they are separate
+    // people. That is what makes the graph, not the endpoints, the signal.
+    const mules = Array.from({ length: options.muleCount }, (_, i) => ({
+      userId: `mule_${String(i + 1).padStart(2, '0')}`,
+      account: randomAccountNumber(),
+      device: newDeviceFingerprint(),
+      ip: randomIp(),
+    }));
+
+    emit({
+      type: 'milestone',
+      message:
+        `Layering NGN ${((options.amountPerMuleMinor * mules.length) / 100).toLocaleString()} ` +
+        `through ${mules.length} mules to ${destination}, ` +
+        `each keeping ${(options.retentionRatio * 100).toFixed(0)}%`,
+      timestamp: Date.now(),
+    });
+
+    // ── Stage 1: fan out from the source to every mule ──────────────────
+    for (const mule of mules) {
+      if (signal.aborted) break;
+      if (results.attempts >= options.maxTotalAttempts) break;
+
+      const response = await scoreAndCount({
+        ctx,
+        method: 'scoreWithdrawal',
+        payload: buildTransferPayload(
+          options.sourceUserId,
+          mule.account,
+          options.amountPerMuleMinor,
+          { timestamp: clock.iso() }
+        ),
+        results,
+        stage: 'fan-out',
+      });
+
+      results.fanOutTransfers++;
+      if (response?.decision === 'ALLOW') {
+        results.fanOutAllowed++;
+        results.totalMovedMinor += options.amountPerMuleMinor;
+        mule.funded = true;
+      }
+
+      clock.advance(60_000); // a minute between outbound transfers
+
+      try {
+        await sleep(options.delayMs, signal);
+      } catch {
+        break;
+      }
+    }
+
+    if (results.fanOutAllowed === 0) {
+      emit({
+        type: 'milestone',
+        message: 'Every outbound transfer was stopped — the network never funded',
+        timestamp: Date.now(),
+      });
+      return finalise(results, destination, mules, clock);
+    }
+
+    // ── Stage 2: each funded mule forwards its cut onward ───────────────
+    clock.advance(options.forwardDelayMinutes * 60_000);
+
+    emit({
+      type: 'milestone',
+      message:
+        `${results.fanOutAllowed} mules funded — forwarding onward after ` +
+        `${humaniseMs(options.forwardDelayMinutes * 60_000)}`,
+      timestamp: Date.now(),
+    });
+
+    const forwardMinor = Math.round(options.amountPerMuleMinor * (1 - options.retentionRatio));
+
+    for (const mule of mules) {
+      if (signal.aborted) break;
+      if (!mule.funded) continue;
+      if (results.attempts >= options.maxTotalAttempts) break;
+
+      const response = await scoreAndCount({
+        ctx,
+        method: 'scoreWithdrawal',
+        payload: buildTransferPayload(mule.userId, destination, forwardMinor, {
+          ip_address: mule.ip,
+          device_fingerprint: mule.device,
+          timestamp: clock.iso(),
+        }),
+        results,
+        stage: 'forward',
+      });
+
+      results.forwardTransfers++;
+      if (response?.decision === 'ALLOW') {
+        results.forwardAllowed++;
+        results.reachedDestinationMinor += forwardMinor;
+      }
+
+      clock.advance(5 * 60_000);
+
+      try {
+        await sleep(options.delayMs, signal);
+      } catch {
+        break;
+      }
+    }
+
+    return finalise(results, destination, mules, clock);
+  },
+};
+
+function finalise(results, destination, mules, clock) {
+  const passThroughRatio =
+    results.totalMovedMinor > 0 ? results.reachedDestinationMinor / results.totalMovedMinor : 0;
+
+  return {
+    ...results,
+    finalDestinationAccount: destination,
+    muleAccounts: mules.map((m) => m.account),
+    // The ratio a graph-aware system should find alarming: money arriving and
+    // leaving an intermediary almost untouched.
+    passThroughRatio: Math.round(passThroughRatio * 1000) / 1000,
+    estimatedLossKobo: results.reachedDestinationMinor,
+    attackerSucceeded: results.reachedDestinationMinor > 0,
+    simulatedTime: true,
+    simulatedSpan: humaniseMs(clock.elapsedMs()),
+  };
+}

package/src/scenarios/promo-abuse.js

@@ -0,0 +1,168 @@
+/**
+ * Scenario: promo-abuse
+ *
+ * One person creating many accounts to farm a signup bonus or referral reward.
+ * Each account is individually unremarkable — a plausible name, a plausible
+ * phone number, a real signup flow. The fraud is only visible in aggregate.
+ *
+ * The attacker's constraint is effort: creating a genuinely independent
+ * identity per account (new device, new network, new payout destination) costs
+ * more than the bonus is worth. So they reuse something. This scenario models
+ * that reuse explicitly and lets you dial it up or down.
+ *
+ * Defensive systems should catch this via:
+ *   - Device clustering        (one fingerprint behind many accounts)
+ *   - IP /24 clustering        (accounts from one subnet)
+ *   - Referral graph anomalies (one referrer, many referees, no onward activity)
+ *   - Payout concentration     (many accounts cashing out to one destination)
+ *
+ * The interesting question this scenario answers is not "is it blocked" but
+ * "how many accounts got through before it was". A system that catches account
+ * 40 has already paid 39 bonuses.
+ */
+
+import { sleep } from '../utils/sleep.js';
+import {
+  buildSignupPayload,
+  buildActionPayload,
+  newDeviceFingerprint,
+} from '../utils/faker-helpers.js';
+import { newResults, scoreAndCount } from '../utils/results.js';
+import { randomIp, ipInSameSubnet, randomAccountNumber, alphanumeric } from '../utils/random.js';
+
+export default {
+  id: 'promo-abuse',
+  name: 'Promo and referral abuse',
+  description:
+    'One actor creates many accounts to farm signup bonuses, reusing devices, subnets, and a shared payout destination.',
+
+  defaultOptions: {
+    accountCount: 40,
+    bonusMinor: 200000, // NGN 2,000 per signup
+    deviceCount: 3, // distinct fingerprints spread across all accounts
+    subnetCount: 2, // distinct /24s the signups come from
+    sharedPayoutAccount: null, // null → generated; all cash-outs land here
+    claimBonus: true, // also attempt the bonus claim after signup
+    delayMs: 120,
+    maxTotalAttempts: 200,
+  },
+
+  async run(ctx) {
+    const { options, emit, signal } = ctx;
+
+    if (options.accountCount < 1) {
+      throw new Error('promo-abuse requires options.accountCount >= 1');
+    }
+    if (options.deviceCount < 1 || options.subnetCount < 1) {
+      throw new Error('promo-abuse requires deviceCount and subnetCount >= 1');
+    }
+
+    const results = newResults({
+      accountsAttempted: 0,
+      accountsCreated: 0, // signups that were not blocked
+      bonusesClaimed: 0, // claims that came back ALLOW — actual payout
+      firstBlockedAtAccount: null,
+    });
+
+    // The reused resources. Fewer of these = a lazier, more catchable attacker.
+    const devices = Array.from({ length: options.deviceCount }, () => newDeviceFingerprint());
+    const subnetSeeds = Array.from({ length: options.subnetCount }, () => randomIp());
+    const payoutAccount = options.sharedPayoutAccount ?? randomAccountNumber();
+    const referrer = `promo_farmer_${alphanumeric(6)}`;
+
+    emit({
+      type: 'milestone',
+      message:
+        `Farming ${options.accountCount} accounts for NGN ` +
+        `${(options.bonusMinor / 100).toLocaleString()} each across ${devices.length} device(s) ` +
+        `and ${subnetSeeds.length} subnet(s), all paying out to ${payoutAccount}`,
+      timestamp: Date.now(),
+    });
+
+    for (let i = 0; i < options.accountCount; i++) {
+      if (signal.aborted) break;
+      if (results.attempts >= options.maxTotalAttempts) break;
+
+      const userId = `promo_acct_${String(i + 1).padStart(3, '0')}`;
+      const device = devices[i % devices.length];
+      const ip = ipInSameSubnet(subnetSeeds[i % subnetSeeds.length]);
+
+      results.accountsAttempted++;
+
+      const signup = await scoreAndCount({
+        ctx,
+        method: 'scoreAction',
+        payload: buildSignupPayload(userId, {
+          ip_address: ip,
+          device_fingerprint: device,
+          details: {
+            referred_by: referrer,
+            signup_bonus_kobo: options.bonusMinor,
+            payout_account: payoutAccount,
+          },
+        }),
+        results,
+        stage: 'signup',
+      });
+
+      if (signup?.decision === 'BLOCK') {
+        if (results.firstBlockedAtAccount == null) {
+          results.firstBlockedAtAccount = i + 1;
+          emit({
+            type: 'milestone',
+            message: `First signup blocked at account ${i + 1} — ${results.bonusesClaimed} bonuses already paid`,
+            timestamp: Date.now(),
+          });
+        }
+      } else {
+        results.accountsCreated++;
+
+        if (options.claimBonus && results.attempts < options.maxTotalAttempts) {
+          const claim = await scoreAndCount({
+            ctx,
+            method: 'scoreAction',
+            payload: buildActionPayload(
+              userId,
+              'promo_claim',
+              {
+                bonus_kobo: options.bonusMinor,
+                payout_account: payoutAccount,
+                referred_by: referrer,
+              },
+              { ip_address: ip, device_fingerprint: device }
+            ),
+            results,
+            stage: 'claim',
+          });
+
+          if (claim?.decision === 'ALLOW') results.bonusesClaimed++;
+        }
+      }
+
+      try {
+        await sleep(options.delayMs, signal);
+      } catch {
+        break;
+      }
+    }
+
+    const paidMinor = results.bonusesClaimed * options.bonusMinor;
+
+    emit({
+      type: 'milestone',
+      message:
+        `${results.accountsCreated} of ${results.accountsAttempted} accounts created, ` +
+        `${results.bonusesClaimed} bonuses paid (NGN ${(paidMinor / 100).toLocaleString()})`,
+      timestamp: Date.now(),
+    });
+
+    return {
+      ...results,
+      estimatedLossKobo: paidMinor,
+      attackerSucceeded: results.bonusesClaimed > 0,
+      sharedPayoutAccount: payoutAccount,
+      devicesUsed: devices.length,
+      subnetsUsed: subnetSeeds.length,
+    };
+  },
+};