fraud-sim 0.2.0 → 0.5.0

package/src/scenarios/session-hijack.js

@@ -0,0 +1,234 @@
+/**
+ * Scenario: session-hijack
+ *
+ * The victim logs in legitimately. Everything about that login is clean — their
+ * usual device, their usual network, their usual hour. Then the session token
+ * is stolen (malware, an XSS payload, a shoulder-surfed cookie, a proxy on a
+ * hostile network) and replayed from somewhere else.
+ *
+ * The attacker never authenticates. There is no failed login, no new-device
+ * login event, no password reset — none of the signals an account-takeover rule
+ * watches for. From the login endpoint's perspective, nothing happened.
+ *
+ * Defensive systems should catch this via:
+ *   - Session continuity checks   (device at action vs device at login)
+ *   - IP continuity within session
+ *   - Impossible travel within a single session
+ *   - Re-authentication on sensitive actions regardless of session age
+ *
+ * This scenario exists to test one specific claim: that the system scores the
+ * *session*, not just the login. A system that only scores logins will let the
+ * withdrawal through and report a perfect block rate on the login endpoint.
+ */
+
+import { sleep } from '../utils/sleep.js';
+import {
+  buildLoginPayload,
+  buildWithdrawalPayload,
+  buildActionPayload,
+  newSessionId,
+  newDeviceFingerprint,
+} from '../utils/faker-helpers.js';
+import { newResults, scoreAndCount } from '../utils/results.js';
+import { randomIp, pickDemoIp, randomUserAgent } from '../utils/random.js';
+
+export default {
+  id: 'session-hijack',
+  name: 'Session hijack',
+  description:
+    "The victim logs in normally; the session token is then replayed from a different device and network to move funds.",
+
+  defaultOptions: {
+    targetUserId: null, // required
+    benignActionsBeforeHijack: 2, // the victim's own activity first
+    amountMinor: 20000000, // NGN 200,000 once the session is stolen
+    withdrawAfterHijack: true,
+    hijackFromPersona: 'foreign', // where the stolen session is replayed from
+    delayMs: 150,
+  },
+
+  async run(ctx) {
+    const { options, emit, signal } = ctx;
+
+    if (!options.targetUserId) {
+      throw new Error('session-hijack requires options.targetUserId');
+    }
+
+    const results = newResults({
+      loginDecision: null,
+      hijackedActionDecision: null,
+      withdrawalDecision: null,
+      hijackDetected: false,
+    });
+
+    // The victim's genuine context, stable across the legitimate part.
+    const sessionId = newSessionId('sess');
+    const victim = {
+      device: newDeviceFingerprint(),
+      ip: pickIp('domestic'),
+      userAgent: randomUserAgent(),
+    };
+
+    // ── Stage 1: the victim's own, entirely legitimate login ────────────
+    emit({
+      type: 'milestone',
+      message: 'Victim logs in normally — usual device, usual network',
+      timestamp: Date.now(),
+    });
+
+    const login = await scoreAndCount({
+      ctx,
+      method: 'scoreLogin',
+      payload: buildLoginPayload(options.targetUserId, {
+        session_id: sessionId,
+        device_fingerprint: victim.device,
+        ip_address: victim.ip.ip,
+        user_agent: victim.userAgent,
+      }),
+      results,
+      stage: 'victim-login',
+      ipIntel: victim.ip.intel,
+    });
+
+    results.loginDecision = login?.decision ?? null;
+
+    if (login?.decision === 'BLOCK') {
+      emit({
+        type: 'milestone',
+        message:
+          'The victim\'s own login was blocked. That is a false positive, not a defence — ' +
+          'the hijack has not happened yet.',
+        timestamp: Date.now(),
+      });
+      return finalise(results, false);
+    }
+
+    // ── Stage 2: ordinary in-session activity by the real user ──────────
+    for (let i = 0; i < options.benignActionsBeforeHijack; i++) {
+      if (signal.aborted) break;
+
+      await scoreAndCount({
+        ctx,
+        method: 'scoreAction',
+        payload: buildActionPayload(
+          options.targetUserId,
+          'view_balance',
+          {},
+          {
+            session_id: sessionId,
+            device_fingerprint: victim.device,
+            ip_address: victim.ip.ip,
+            user_agent: victim.userAgent,
+          }
+        ),
+        results,
+        stage: 'victim-activity',
+      });
+
+      try {
+        await sleep(options.delayMs, signal);
+      } catch {
+        break;
+      }
+    }
+
+    // ── Stage 3: the session is stolen and replayed elsewhere ───────────
+    const attacker = {
+      device: newDeviceFingerprint(),
+      ip: pickIp(options.hijackFromPersona),
+      userAgent: randomUserAgent(),
+    };
+
+    emit({
+      type: 'milestone',
+      message:
+        `Session ${sessionId} replayed from a different device and network ` +
+        `(${attacker.ip.intel?.country ?? attacker.ip.ip}) — no new login, no password change`,
+      timestamp: Date.now(),
+    });
+
+    const hijackedAction = await scoreAndCount({
+      ctx,
+      method: 'scoreAction',
+      payload: buildActionPayload(
+        options.targetUserId,
+        'view_balance',
+        {},
+        {
+          session_id: sessionId, // the one thing that did not change
+          device_fingerprint: attacker.device,
+          ip_address: attacker.ip.ip,
+          user_agent: attacker.userAgent,
+        }
+      ),
+      results,
+      stage: 'hijacked-action',
+      ipIntel: attacker.ip.intel,
+    });
+
+    results.hijackedActionDecision = hijackedAction?.decision ?? null;
+    if (hijackedAction?.decision === 'BLOCK' || hijackedAction?.decision === 'STEP_UP') {
+      results.hijackDetected = true;
+      emit({
+        type: 'milestone',
+        message: `Session continuity break detected at the first hijacked action (${hijackedAction.decision})`,
+        timestamp: Date.now(),
+      });
+    }
+
+    // ── Stage 4: cash out on the stolen session ─────────────────────────
+    if (!options.withdrawAfterHijack || signal.aborted) {
+      return finalise(results, results.hijackDetected);
+    }
+
+    const withdrawal = await scoreAndCount({
+      ctx,
+      method: 'scoreWithdrawal',
+      payload: buildWithdrawalPayload(
+        options.targetUserId,
+        { amount: options.amountMinor },
+        {
+          session_id: sessionId,
+          device_fingerprint: attacker.device,
+          ip_address: attacker.ip.ip,
+        }
+      ),
+      results,
+      stage: 'hijacked-withdrawal',
+      ipIntel: attacker.ip.intel,
+    });
+
+    results.withdrawalDecision = withdrawal?.decision ?? null;
+    if (withdrawal?.decision === 'BLOCK' || withdrawal?.decision === 'STEP_UP') {
+      results.hijackDetected = true;
+    }
+
+    if (withdrawal?.decision === 'ALLOW') {
+      emit({
+        type: 'milestone',
+        message:
+          `Withdrawal of NGN ${(options.amountMinor / 100).toLocaleString()} allowed on a session ` +
+          'whose device and network both changed mid-flight — session continuity is not being scored',
+        timestamp: Date.now(),
+      });
+    }
+
+    return finalise(results, results.hijackDetected, options.amountMinor);
+  },
+};
+
+function pickIp(persona) {
+  if (!persona || persona === 'random') return { ip: randomIp(), intel: undefined };
+  const { ip, ...intel } = pickDemoIp(persona);
+  return { ip, intel };
+}
+
+function finalise(results, detected, amountMinor = 0) {
+  const succeeded = results.withdrawalDecision === 'ALLOW';
+  return {
+    ...results,
+    hijackDetected: detected,
+    attackerSucceeded: succeeded,
+    estimatedLossKobo: succeeded ? amountMinor : 0,
+  };
+}

package/src/scenarios/sim-swap-takeover.js

@@ -0,0 +1,253 @@
+/**
+ * Scenario: sim-swap-takeover
+ *
+ * The attacker does not break the authentication — they redirect it. By
+ * socially engineering or bribing a telco into porting the victim's number to a
+ * SIM they control, every SMS OTP now arrives on the attacker's handset. Then
+ * they walk through the front door: password reset, OTP confirmed, login,
+ * withdrawal.
+ *
+ * Every individual step passes. The password reset is confirmed by a real OTP.
+ * The login satisfies two factors. The withdrawal comes from an authenticated,
+ * verified session. The only thing wrong is that the second factor stopped
+ * belonging to the customer a few minutes ago.
+ *
+ * Defensive systems should catch this via:
+ *   - Telco porting check      (number ported within N days → distrust SMS OTP)
+ *   - OTP-to-new-device        (second factor confirmed on an unseen handset)
+ *   - Login-immediately-after-port heuristic
+ *   - Step-up escalation       (fall back to a factor the attacker cannot port)
+ *
+ * This scenario is the strongest argument for treating SMS OTP as a signal
+ * rather than proof. A system relying on OTP alone will pass every stage.
+ */
+
+import { sleep } from '../utils/sleep.js';
+import {
+  buildLoginPayload,
+  buildWithdrawalPayload,
+  buildActionPayload,
+  newDeviceFingerprint,
+  newSessionId,
+} from '../utils/faker-helpers.js';
+import { newResults, scoreAndCount } from '../utils/results.js';
+import { simulatedClock, humaniseMs } from '../utils/clock.js';
+import { randomPhoneNumber, randomIp, pickDemoIp } from '../utils/random.js';
+
+export default {
+  id: 'sim-swap-takeover',
+  name: 'SIM swap takeover',
+  description:
+    "The victim's number is ported to the attacker's SIM, redirecting OTPs; the attacker then resets the password, logs in, and withdraws.",
+
+  defaultOptions: {
+    targetUserId: null, // required
+    minutesSincePort: 20, // how recently the number was ported
+    amountMinor: 40000000, // NGN 400,000 — SIM swaps target high-value accounts
+    reportPortEvent: true, // tell the target about the port, if it accepts one
+    attemptPasswordReset: true,
+    ipPersona: 'domestic', // SIM swappers are usually in-country
+    delayMs: 200,
+  },
+
+  async run(ctx) {
+    const { options, emit, signal } = ctx;
+
+    if (!options.targetUserId) {
+      throw new Error('sim-swap-takeover requires options.targetUserId');
+    }
+
+    const results = newResults({
+      stages: [], // ordered record of what happened at each step
+      blockedAtStage: null,
+      resetDecision: null,
+      loginDecision: null,
+      withdrawalDecision: null,
+    });
+
+    const clock = simulatedClock({ start: Date.now() });
+    const portedAt = new Date(clock.epoch() - options.minutesSincePort * 60_000).toISOString();
+
+    const attacker = {
+      device: newDeviceFingerprint(), // a handset the account has never seen
+      ip: pickIp(options.ipPersona),
+      session: newSessionId('swap'),
+      phone: randomPhoneNumber(),
+    };
+
+    const record = (stage, decision) => {
+      results.stages.push({ stage, decision: decision ?? 'ERROR' });
+      if ((decision === 'BLOCK' || decision === 'STEP_UP') && results.blockedAtStage == null) {
+        results.blockedAtStage = stage;
+      }
+    };
+
+    emit({
+      type: 'milestone',
+      message:
+        `Number ported to the attacker's SIM ${humaniseMs(options.minutesSincePort * 60_000)} ago — ` +
+        'all SMS OTPs now arrive on their handset',
+      timestamp: Date.now(),
+    });
+
+    // ── Stage 0: tell the target the number was ported ──────────────────
+    // A system integrated with a telco porting feed would already know. Systems
+    // that accept the signal from the fintech need to be told.
+    if (options.reportPortEvent && typeof ctx.target.reportEvent === 'function') {
+      try {
+        await ctx.target.reportEvent('sim-swap', {
+          user_id: options.targetUserId,
+          ported_at: portedAt,
+          new_msisdn: attacker.phone,
+          metadata: { _simulated: true },
+        });
+      } catch {
+        // Not every target models this. The attack proceeds either way.
+      }
+    }
+
+    // ── Stage 1: password reset, confirmed by the redirected OTP ────────
+    if (options.attemptPasswordReset) {
+      const reset = await scoreAndCount({
+        ctx,
+        method: 'scoreAction',
+        payload: buildActionPayload(
+          options.targetUserId,
+          'password_reset',
+          {
+            confirmed_by: 'sms_otp',
+            otp_delivered_to: attacker.phone,
+            msisdn_ported_at: portedAt,
+          },
+          {
+            session_id: attacker.session,
+            device_fingerprint: attacker.device,
+            ip_address: attacker.ip.ip,
+            timestamp: clock.iso(),
+          }
+        ),
+        results,
+        stage: 'password-reset',
+        ipIntel: attacker.ip.intel,
+      });
+
+      results.resetDecision = reset?.decision ?? null;
+      record('password-reset', reset?.decision);
+
+      if (reset?.decision === 'BLOCK') {
+        emit({
+          type: 'milestone',
+          message: 'Password reset blocked — the port was treated as disqualifying the OTP',
+          timestamp: Date.now(),
+        });
+        return finalise(results, options, clock);
+      }
+
+      clock.advance(3 * 60_000);
+      try {
+        await sleep(options.delayMs, signal);
+      } catch {
+        return finalise(results, options, clock);
+      }
+    }
+
+    // ── Stage 2: login from the attacker's handset ──────────────────────
+    const login = await scoreAndCount({
+      ctx,
+      method: 'scoreLogin',
+      payload: buildLoginPayload(options.targetUserId, {
+        session_id: attacker.session,
+        device_fingerprint: attacker.device,
+        ip_address: attacker.ip.ip,
+        timestamp: clock.iso(),
+        metadata: {
+          login_method: 'sms_otp',
+          platform: 'android',
+          msisdn_ported_at: portedAt,
+          _simulated: true,
+        },
+      }),
+      results,
+      stage: 'login',
+      ipIntel: attacker.ip.intel,
+    });
+
+    results.loginDecision = login?.decision ?? null;
+    record('login', login?.decision);
+
+    if (login?.decision === 'BLOCK') {
+      emit({
+        type: 'milestone',
+        message: 'Login blocked — new device plus a recent port was enough',
+        timestamp: Date.now(),
+      });
+      return finalise(results, options, clock);
+    }
+
+    clock.advance(2 * 60_000);
+    try {
+      await sleep(options.delayMs, signal);
+    } catch {
+      return finalise(results, options, clock);
+    }
+
+    // ── Stage 3: immediate high-value withdrawal ────────────────────────
+    emit({
+      type: 'milestone',
+      message: `Withdrawing NGN ${(options.amountMinor / 100).toLocaleString()} minutes after the port`,
+      timestamp: Date.now(),
+    });
+
+    const withdrawal = await scoreAndCount({
+      ctx,
+      method: 'scoreWithdrawal',
+      payload: buildWithdrawalPayload(
+        options.targetUserId,
+        { amount: options.amountMinor },
+        {
+          session_id: attacker.session,
+          device_fingerprint: attacker.device,
+          ip_address: attacker.ip.ip,
+          timestamp: clock.iso(),
+        }
+      ),
+      results,
+      stage: 'withdrawal',
+      ipIntel: attacker.ip.intel,
+    });
+
+    results.withdrawalDecision = withdrawal?.decision ?? null;
+    record('withdrawal', withdrawal?.decision);
+
+    if (withdrawal?.decision === 'ALLOW') {
+      emit({
+        type: 'milestone',
+        message:
+          'Withdrawal allowed. Every stage was confirmed by an OTP the attacker received — ' +
+          'SMS as proof of identity is the whole vulnerability here.',
+        timestamp: Date.now(),
+      });
+    }
+
+    return finalise(results, options, clock);
+  },
+};
+
+function pickIp(persona) {
+  if (!persona || persona === 'random') return { ip: randomIp(), intel: undefined };
+  const { ip, ...intel } = pickDemoIp(persona);
+  return { ip, intel };
+}
+
+function finalise(results, options, clock) {
+  const succeeded = results.withdrawalDecision === 'ALLOW';
+  return {
+    ...results,
+    attackerSucceeded: succeeded,
+    estimatedLossKobo: succeeded ? options.amountMinor : 0,
+    // Which stage first pushed back. `null` means the whole chain succeeded.
+    blockedAtStage: results.blockedAtStage,
+    simulatedTime: true,
+    simulatedSpan: humaniseMs(clock.elapsedMs()),
+  };
+}

package/src/scenarios/slow-drain.js

@@ -0,0 +1,171 @@
+/**
+ * Scenario: slow-drain
+ *
+ * The patient version of an account takeover. Instead of emptying an account in
+ * minutes, the attacker withdraws small amounts spaced far enough apart that no
+ * short-window velocity rule ever trips. Over days the account is emptied
+ * anyway.
+ *
+ * This is the scenario that separates systems with a real baseline from systems
+ * with a counter. Any engine can catch five withdrawals in a minute. Catching
+ * twenty withdrawals over four days — each individually ordinary, but ten times
+ * the account's normal weekly outflow — requires knowing what normal is.
+ *
+ * Defensive systems should catch this via:
+ *   - Multi-window velocity     (hourly AND daily AND weekly counters)
+ *   - Baseline deviation        (this user does not usually behave like this)
+ *   - Cumulative amount rules   (total moved since a trust event)
+ *   - Payee-diversity anomalies (many new destinations over a long window)
+ *
+ * ── On simulated time ─────────────────────────────────────────────────
+ * A real slow drain takes days, so this scenario advances the `timestamp` field
+ * rather than sleeping. That is faithful only if the target derives its windows
+ * from the event timestamp. A system that stamps arrival time server-side will
+ * see one compressed burst and block it for the wrong reason — a pass here
+ * would be meaningless. The report sets `simulatedTime: true` so this is never
+ * silently assumed.
+ */
+
+import { sleep } from '../utils/sleep.js';
+import {
+  buildWithdrawalPayload,
+  newDeviceFingerprint,
+  newSessionId,
+} from '../utils/faker-helpers.js';
+import { newResults, scoreAndCount } from '../utils/results.js';
+import { simulatedClock, humaniseMs } from '../utils/clock.js';
+import { randomIp, randomInt } from '../utils/random.js';
+
+export default {
+  id: 'slow-drain',
+  name: 'Slow drain below velocity thresholds',
+  description:
+    'Withdrawals individually below every short-window threshold, spaced over days, that collectively empty the account.',
+
+  defaultOptions: {
+    targetUserId: null, // required
+    withdrawalCount: 20,
+    amountMinor: 2500000, // NGN 25,000 — deliberately modest
+    amountJitterMinor: 500000, // vary amounts so they don't look scripted
+    intervalMinutes: 300, // 5 simulated hours between withdrawals
+    sameDevice: true, // a patient attacker keeps one stable device
+    delayMs: 60, // wall-clock pacing only
+    maxTotalAttempts: 100,
+  },
+
+  async run(ctx) {
+    const { options, emit, signal } = ctx;
+
+    if (!options.targetUserId) {
+      throw new Error('slow-drain requires options.targetUserId');
+    }
+    if (options.intervalMinutes <= 0) {
+      throw new Error('slow-drain requires options.intervalMinutes > 0');
+    }
+
+    const results = newResults({
+      withdrawalsAttempted: 0,
+      drainedMinor: 0,
+      firstBlockedAtWithdrawal: null,
+      firstStepUpAtWithdrawal: null,
+    });
+
+    const clock = simulatedClock({
+      start: Date.now(),
+      stepMs: options.intervalMinutes * 60_000,
+    });
+
+    // A patient attacker is not rotating infrastructure — that would create the
+    // very novelty signals they are trying to avoid.
+    const device = options.sameDevice ? newDeviceFingerprint() : null;
+    const ip = options.sameDevice ? randomIp() : null;
+    const sessionId = newSessionId('drain');
+
+    const totalSpanMs = options.withdrawalCount * options.intervalMinutes * 60_000;
+
+    emit({
+      type: 'milestone',
+      message:
+        `Draining NGN ${(options.amountMinor / 100).toLocaleString()} at a time, ` +
+        `every ${humaniseMs(options.intervalMinutes * 60_000)}, ` +
+        `over a simulated ${humaniseMs(totalSpanMs)}`,
+      timestamp: Date.now(),
+    });
+
+    emit({
+      type: 'milestone',
+      message:
+        'Timestamps are simulated. If the target derives its velocity windows from ' +
+        'server arrival time rather than the event timestamp, this run measures a burst, not a slow drain.',
+      timestamp: Date.now(),
+    });
+
+    for (let i = 0; i < options.withdrawalCount; i++) {
+      if (signal.aborted) break;
+      if (results.attempts >= options.maxTotalAttempts) break;
+
+      const jitter = options.amountJitterMinor
+        ? randomInt(-options.amountJitterMinor, options.amountJitterMinor)
+        : 0;
+      const amount = Math.max(1, options.amountMinor + jitter);
+
+      const overrides = { timestamp: clock.iso(), session_id: sessionId };
+      if (device) overrides.device_fingerprint = device;
+      if (ip) overrides.ip_address = ip;
+
+      const response = await scoreAndCount({
+        ctx,
+        method: 'scoreWithdrawal',
+        payload: buildWithdrawalPayload(options.targetUserId, { amount }, overrides),
+        results,
+        stage: 'withdrawal',
+      });
+
+      results.withdrawalsAttempted++;
+
+      if (response?.decision === 'ALLOW') {
+        results.drainedMinor += amount;
+      } else if (response?.decision === 'BLOCK' && results.firstBlockedAtWithdrawal == null) {
+        results.firstBlockedAtWithdrawal = i + 1;
+        emit({
+          type: 'milestone',
+          message:
+            `Blocked at withdrawal ${i + 1} of ${options.withdrawalCount} — ` +
+            `NGN ${(results.drainedMinor / 100).toLocaleString()} already gone ` +
+            `over ${humaniseMs(clock.elapsedMs())}`,
+          timestamp: Date.now(),
+        });
+      } else if (response?.decision === 'STEP_UP' && results.firstStepUpAtWithdrawal == null) {
+        results.firstStepUpAtWithdrawal = i + 1;
+      }
+
+      clock.advance();
+
+      try {
+        await sleep(options.delayMs, signal);
+      } catch {
+        break;
+      }
+    }
+
+    if (results.firstBlockedAtWithdrawal == null) {
+      emit({
+        type: 'milestone',
+        message:
+          `Never blocked. NGN ${(results.drainedMinor / 100).toLocaleString()} drained across ` +
+          `${results.withdrawalsAttempted} withdrawals — short-window velocity alone does not catch this.`,
+        timestamp: Date.now(),
+      });
+    }
+
+    return {
+      ...results,
+      estimatedLossKobo: results.drainedMinor,
+      attackerSucceeded: results.firstBlockedAtWithdrawal == null && results.drainedMinor > 0,
+      simulatedTime: true,
+      simulatedSpan: humaniseMs(clock.elapsedMs()),
+      // How much got out before anything fired — the number that matters here.
+      drainedBeforeFirstBlockMinor: results.drainedMinor,
+    };
+  },
+};