fraud-sim 0.2.0

package/src/runner.js

@@ -0,0 +1,87 @@
+/**
+ * Runner — orchestrates the lifecycle of a single scenario execution.
+ *
+ * Responsibilities:
+ *   - Merge user options with scenario defaults
+ *   - Provide the ScenarioContext (target, emit, signal)
+ *   - Forward events to the user's onEvent callback
+ *   - Wrap scenario errors with useful context
+ *   - Emit a final 'summary' event when the scenario completes
+ *
+ * Non-responsibilities:
+ *   - The runner does NOT know about HTTP, LLMs, faker, or specific scenarios.
+ *     Every concrete behaviour lives in a scenario or an adapter.
+ */
+
+export class Runner {
+  async run(scenario, config) {
+    const startedAt = Date.now();
+
+    const options = {
+      ...(scenario.defaultOptions ?? {}),
+      ...(config.options ?? {}),
+    };
+
+    const onEvent = config.onEvent ?? (() => {});
+    const signal = config.signal ?? new AbortController().signal;
+
+    // Wrap onEvent so we never let a buggy subscriber crash the runner.
+    const emit = (event) => {
+      try {
+        onEvent(event);
+      } catch (err) {
+        // Subscribers should not break simulations.
+        // We log to stderr but continue.
+        console.error('[fraud-sim] subscriber threw:', err);
+      }
+    };
+
+    const context = {
+      options,
+      target: config.target,
+      llm: config.llm, // optional, used only by adaptive scenarios (v0.2+)
+      emit,
+      signal,
+    };
+
+    let report;
+    try {
+      report = await scenario.run(context);
+    } catch (err) {
+      emit({
+        type: 'error',
+        message: `Scenario "${scenario.id}" failed: ${err.message}`,
+        details: { stack: err.stack },
+        timestamp: Date.now(),
+      });
+      throw err;
+    }
+
+    // Normalise the report. Scenarios may return loose shapes; the runner
+    // ensures the canonical fields exist so downstream tooling is reliable.
+    const normalised = {
+      scenarioId: scenario.id,
+      scenarioName: scenario.name,
+      startedAt,
+      completedAt: Date.now(),
+      durationMs: Date.now() - startedAt,
+      attempts: report.attempts ?? 0,
+      blocked: report.blocked ?? 0,
+      stepUp: report.stepUp ?? 0,
+      allowed: report.allowed ?? 0,
+      blockRate:
+        (report.attempts ?? 0) > 0 ? (report.blocked ?? 0) / report.attempts : 0,
+      stepUpRate:
+        (report.attempts ?? 0) > 0 ? (report.stepUp ?? 0) / report.attempts : 0,
+      ...report, // scenarios can add custom fields
+    };
+
+    emit({
+      type: 'summary',
+      report: normalised,
+      timestamp: Date.now(),
+    });
+
+    return normalised;
+  }
+}

package/src/scenarios/account-drain.js

@@ -0,0 +1,255 @@
+/**
+ * Scenario: account-drain
+ *
+ * An attacker who has obtained valid credentials logs in from a new device,
+ * changes the password to lock out the legitimate user, and rapidly drains
+ * the account through withdrawals to new payees.
+ *
+ * Defensive systems should catch this via:
+ *   - NEW_DEVICE                      (login from unknown device)
+ *   - WITHDRAWAL_AFTER_PWD_CHANGE     (withdrawal soon after password reset)
+ *   - DEVICE_SESSION_MISMATCH         (device changed mid-session)
+ *   - NEW_PAYEE_HIGH_AMOUNT           (first transaction to new payee, high amount)
+ *   - DRAIN_PATTERN                   (multiple new payees in short window)
+ *
+ * Realistic outcomes:
+ *   - Login itself may STEP_UP (NEW_DEVICE)
+ *   - First withdrawal: STEP_UP or BLOCK depending on amount
+ *   - Drain pattern detection should BLOCK by the 3rd withdrawal
+ */
+
+import { sleep } from '../utils/sleep.js';
+import {
+  buildLoginPayload,
+  buildWithdrawalPayload,
+  newSessionId,
+  newDeviceFingerprint,
+} from '../utils/faker-helpers.js';
+import { randomIp } from '../utils/random.js';
+
+export default {
+  id: 'account-drain',
+  name: 'Account takeover and drain',
+  description:
+    'Attacker logs in from a new device, changes the password, and rapidly drains funds to new payees.',
+
+  defaultOptions: {
+    targetUserId: null, // required
+    attackerIp: null, // optional — random if not provided
+    withdrawalCount: 5,
+    amountKobo: 4500000, // NGN 45,000 per withdrawal
+    delayBetweenWithdrawalsMs: 15000, // 15 seconds
+    postLoginPauseMs: 30000, // 30 seconds — attackers move fast after password change
+    skipPasswordChange: false,
+  },
+
+  async run(ctx) {
+    const { options, target, emit, signal } = ctx;
+
+    if (!options.targetUserId) {
+      throw new Error('account-drain requires options.targetUserId');
+    }
+
+    const results = {
+      attempts: 0,
+      blocked: 0,
+      stepUp: 0,
+      allowed: 0,
+      errors: 0,
+      loginDecision: null,
+      withdrawalDecisions: [],
+      attackerSucceeded: false,
+    };
+
+    const attackerIp = options.attackerIp ?? randomIp();
+    const attackerDevice = newDeviceFingerprint();
+    const sessionId = newSessionId('drain');
+
+    // ── Step 1: login from new device ─────────────────────────────────
+    emit({
+      type: 'milestone',
+      message: `Attacker attempts login from new device (IP: ${attackerIp})`,
+      timestamp: Date.now(),
+    });
+
+    const loginPayload = buildLoginPayload(options.targetUserId, {
+      session_id: sessionId,
+      ip_address: attackerIp,
+      device_fingerprint: attackerDevice,
+      user_agent: 'Mozilla/5.0 (Linux; Android 13; SM-A546B)',
+    });
+
+    const t0 = Date.now();
+    emit({ type: 'attempt', round: 0, payload: loginPayload, timestamp: t0 });
+
+    let loginResponse;
+    try {
+      loginResponse = await target.scoreLogin(loginPayload);
+    } catch (err) {
+      results.errors++;
+      emit({
+        type: 'error',
+        message: `Login attempt failed: ${err.message}`,
+        timestamp: Date.now(),
+      });
+      return finalise(results);
+    }
+
+    emit({
+      type: 'response',
+      round: 0,
+      response: loginResponse,
+      latencyMs: Date.now() - t0,
+      timestamp: Date.now(),
+    });
+
+    results.attempts++;
+    results.loginDecision = loginResponse.decision;
+    incrementCount(results, loginResponse.decision);
+
+    if (loginResponse.decision === 'BLOCK') {
+      emit({
+        type: 'milestone',
+        message: 'Login blocked — attacker cannot proceed',
+        timestamp: Date.now(),
+      });
+      return finalise(results);
+    }
+
+    // ── Step 2: change password (simulated — reported to target) ──────
+    if (!options.skipPasswordChange) {
+      emit({
+        type: 'milestone',
+        message: 'Attacker changes password to lock out the legitimate user',
+        timestamp: Date.now(),
+      });
+
+      try {
+        await target.reportEvent('password-changed', {
+          user_id: options.targetUserId,
+          changed_at: new Date().toISOString(),
+          metadata: { _simulated: true },
+        });
+      } catch {
+        // Non-critical — some targets won't support this endpoint
+      }
+    }
+
+    // Realistic attackers move fast after a password change
+    try {
+      await sleep(options.postLoginPauseMs, signal);
+    } catch {
+      return finalise(results);
+    }
+
+    // ── Step 3: rapid withdrawals to new payees ───────────────────────
+    emit({
+      type: 'milestone',
+      message: `Attacker attempts ${options.withdrawalCount} rapid withdrawals to new payees`,
+      timestamp: Date.now(),
+    });
+
+    for (let i = 0; i < options.withdrawalCount; i++) {
+      if (signal.aborted) break;
+
+      const wdPayload = buildWithdrawalPayload(
+        options.targetUserId,
+        {
+          amount: options.amountKobo,
+          is_new_payee: true,
+        },
+        {
+          session_id: sessionId,
+          ip_address: attackerIp,
+          device_fingerprint: attackerDevice,
+        }
+      );
+
+      const wt0 = Date.now();
+      emit({
+        type: 'attempt',
+        round: results.attempts,
+        payload: wdPayload,
+        timestamp: wt0,
+      });
+
+      let wdResponse;
+      try {
+        wdResponse = await target.scoreWithdrawal(wdPayload);
+      } catch (err) {
+        results.errors++;
+        emit({
+          type: 'error',
+          message: `Withdrawal ${i + 1} failed: ${err.message}`,
+          timestamp: Date.now(),
+        });
+        continue;
+      }
+
+      emit({
+        type: 'response',
+        round: results.attempts,
+        response: wdResponse,
+        latencyMs: Date.now() - wt0,
+        timestamp: Date.now(),
+      });
+
+      results.attempts++;
+      results.withdrawalDecisions.push({
+        index: i + 1,
+        decision: wdResponse.decision,
+        reasons: wdResponse.reasons,
+      });
+      incrementCount(results, wdResponse.decision);
+
+      // Stop draining once any withdrawal is blocked — a real attacker would
+      // realise the system has noticed and pivot or abandon
+      if (wdResponse.decision === 'BLOCK') {
+        emit({
+          type: 'milestone',
+          message: `Withdrawal ${i + 1} blocked — attacker gives up`,
+          timestamp: Date.now(),
+        });
+        break;
+      }
+
+      // If all withdrawals succeed, the attacker has fully drained the account
+      if (i === options.withdrawalCount - 1 && wdResponse.decision === 'ALLOW') {
+        results.attackerSucceeded = true;
+        emit({
+          type: 'milestone',
+          message: 'All withdrawals succeeded — account fully drained',
+          timestamp: Date.now(),
+        });
+      }
+
+      try {
+        await sleep(options.delayBetweenWithdrawalsMs, signal);
+      } catch {
+        break;
+      }
+    }
+
+    return finalise(results);
+  },
+};
+
+function incrementCount(results, decision) {
+  if (decision === 'BLOCK') results.blocked++;
+  else if (decision === 'STEP_UP') results.stepUp++;
+  else if (decision === 'ALLOW') results.allowed++;
+  else results.errors++;
+}
+
+function finalise(results) {
+  return {
+    attempts: results.attempts,
+    blocked: results.blocked,
+    stepUp: results.stepUp,
+    allowed: results.allowed,
+    errors: results.errors,
+    loginDecision: results.loginDecision,
+    withdrawalDecisions: results.withdrawalDecisions,
+    attackerSucceeded: results.attackerSucceeded,
+  };
+}

package/src/scenarios/adaptive-attacker.js

@@ -0,0 +1,206 @@
+/**
+ * Scenario: adaptive-attacker
+ *
+ * The headline scenario. An attacker probes a login endpoint and, after each
+ * block, asks an LLM (via ctx.llm) what to change for the next attempt. Round
+ * by round it rotates IPs, device fingerprints, user agents, and timing based
+ * on the reasons the defender returned — the same loop a real adaptive actor
+ * runs, made visible.
+ *
+ * The demo moment is the `attacker_adapts` event: it carries the LLM's
+ * reasoning and is emitted BEFORE each adapted attempt is sent, so a dashboard
+ * can show *why* the attacker is about to do what it does.
+ *
+ * Defensive systems should catch this via the same signals as credential
+ * stuffing (IP reputation, device mismatch, velocity), but the point of the
+ * scenario is to see whether a defender holds up as the attacker learns.
+ *
+ * Works with no LLM: if `ctx.llm` is undefined it falls back to the seeded
+ * deterministic provider, so the scenario is fully reproducible in CI.
+ */
+
+import { sleep } from '../utils/sleep.js';
+import { buildLoginPayload } from '../utils/faker-helpers.js';
+import { deterministic } from '../llm/deterministic.js';
+
+export default {
+  id: 'adaptive-attacker',
+  name: 'LLM adaptive attacker',
+  description:
+    'An attacker that uses an LLM to adapt its login strategy based on which attempts get blocked.',
+
+  defaultOptions: {
+    targetUserId: null, // required
+    maxRounds: 10,
+    baselineIp: '197.211.62.14', // realistic residential starting point
+    delayMs: 1000, // wall-clock pacing between rounds (the attacker's own
+    //                chosen delay is recorded, not enacted — see run())
+    // The LLM is passed via ctx.llm, not options.
+  },
+
+  async run(ctx) {
+    const { options, target, emit, signal } = ctx;
+
+    if (!options.targetUserId) {
+      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 });
+
+    const results = {
+      attempts: 0,
+      blocked: 0,
+      stepUp: 0,
+      allowed: 0,
+      errors: 0,
+      rounds: 0,
+      outcome: 'attacker_defeated',
+      strategyHistory: [],
+    };
+
+    // The history the LLM reasons over. One entry per completed round.
+    const history = [];
+
+    emit({
+      type: 'milestone',
+      message: `Adaptive attacker engaging user ${options.targetUserId} (up to ${options.maxRounds} rounds, provider: ${llm.name ?? 'unknown'})`,
+      timestamp: Date.now(),
+    });
+
+    for (let round = 1; round <= options.maxRounds; round++) {
+      if (signal.aborted) break;
+
+      let parameters;
+      let reasoning;
+
+      if (round === 1) {
+        // Hardcoded baseline: residential-looking IP, common browser UA.
+        parameters = {
+          ip: options.baselineIp,
+          deviceFingerprint: null, // let the payload builder generate one
+          userAgent:
+            'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+          delayMs: options.delayMs,
+        };
+        reasoning = 'Baseline attempt: residential-looking IP with a common browser user agent.';
+      } else {
+        // Ask the LLM what to change based on everything so far.
+        let strategy;
+        try {
+          strategy = await llm.generateStrategy({
+            scenarioId: 'adaptive-attacker',
+            history,
+            round,
+            maxRound: options.maxRounds,
+          });
+        } catch (err) {
+          // Providers shouldn't throw, but guard anyway — never crash the run.
+          results.errors++;
+          emit({
+            type: 'error',
+            message: `LLM provider threw on round ${round}: ${err.message}`,
+            timestamp: Date.now(),
+          });
+          strategy = { reasoning: 'Provider error — reusing previous parameters.', parameters };
+        }
+
+        parameters = { ...parameters, ...(strategy?.parameters ?? {}) };
+        reasoning = strategy?.reasoning ?? '';
+      }
+
+      // Emit the adaptation BEFORE sending — this is the demo moment.
+      emit({
+        type: 'attacker_adapts',
+        round,
+        reasoning,
+        parameters,
+        timestamp: Date.now(),
+      });
+      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 });
+
+      let response;
+      try {
+        response = await target.scoreLogin(payload);
+      } catch (err) {
+        results.errors++;
+        emit({
+          type: 'error',
+          message: `Round ${round} attempt failed: ${err.message}`,
+          timestamp: Date.now(),
+        });
+        results.rounds = round;
+        // Record the failure in history so the LLM can react to it.
+        history.push({ round, parameters, decision: 'ERROR', reasons: [] });
+        continue;
+      }
+
+      const latencyMs = Date.now() - t0;
+      emit({ type: 'response', round, response, latencyMs, timestamp: Date.now() });
+
+      results.attempts++;
+      results.rounds = round;
+      const decision = response?.decision ?? 'ERROR';
+      const reasons = Array.isArray(response?.reasons) ? response.reasons : [];
+
+      if (decision === 'BLOCK') results.blocked++;
+      else if (decision === 'STEP_UP') results.stepUp++;
+      else if (decision === 'ALLOW') results.allowed++;
+      else results.errors++;
+
+      history.push({ round, parameters, decision, reasons });
+
+      if (decision === 'ALLOW') {
+        results.outcome = 'attacker_succeeded';
+        emit({
+          type: 'milestone',
+          message: `Round ${round}: ALLOW — attacker found a gap and succeeded`,
+          timestamp: Date.now(),
+        });
+        break;
+      }
+
+      // Pace the next round by the sim's own knob (options.delayMs), not the
+      // strategy's delayMs. The attacker's chosen delay is a real adaptation —
+      // it's recorded in the attacker_adapts event and strategyHistory — but
+      // enacting a 5–15s velocity-evasion wait per round would make a run take
+      // minutes for no benefit. This is a simulator; the decision is what's
+      // interesting, not the wall-clock wait.
+      try {
+        await sleep(options.delayMs, signal);
+      } catch {
+        break; // aborted
+      }
+    }
+
+    if (results.outcome !== 'attacker_succeeded') {
+      emit({
+        type: 'milestone',
+        message: `Attacker defeated after ${results.rounds} round(s) — no ALLOW reached`,
+        timestamp: Date.now(),
+      });
+    }
+
+    return {
+      attempts: results.attempts,
+      blocked: results.blocked,
+      stepUp: results.stepUp,
+      allowed: results.allowed,
+      errors: results.errors,
+      rounds: results.rounds,
+      outcome: results.outcome,
+      strategyHistory: results.strategyHistory,
+    };
+  },
+};

package/src/scenarios/credential-stuffing.js

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ *
+ * 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)
+ *   - NEW_DEVICE          (every attempt is a new device fingerprint)
+ *
+ * Realistic block rates against a well-tuned system: 85-95%.
+ */
+
+import { sleep } from '../utils/sleep.js';
+import { buildLoginPayload } from '../utils/faker-helpers.js';
+import { randomIp, randomUserAgent } from '../utils/random.js';
+
+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.',
+
+  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
+  },
+
+  async run(ctx) {
+    const { options, target, emit, signal } = ctx;
+
+    if (!options.targetUserId) {
+      throw new Error('credential-stuffing requires options.targetUserId');
+    }
+
+    const results = {
+      attempts: 0,
+      blocked: 0,
+      stepUp: 0,
+      allowed: 0,
+      errors: 0,
+    };
+
+    emit({
+      type: 'milestone',
+      message: `Starting credential stuffing: ${options.attackerCount} IPs × ${options.attemptsPerIp} attempts (max ${options.maxTotalAttempts} total)`,
+      timestamp: Date.now(),
+    });
+
+    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();
+      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, {
+          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 });
+
+        let response;
+        try {
+          response = await target.scoreLogin(payload);
+        } catch (err) {
+          results.errors++;
+          emit({
+            type: 'error',
+            message: `Attempt ${results.attempts} failed: ${err.message}`,
+            timestamp: Date.now(),
+          });
+          continue;
+        }
+
+        const latencyMs = Date.now() - t0;
+
+        emit({
+          type: 'response',
+          round: results.attempts,
+          response,
+          latencyMs,
+          timestamp: Date.now(),
+        });
+
+        results.attempts++;
+        const decision = response?.decision ?? 'ERROR';
+        if (decision === 'BLOCK') results.blocked++;
+        else if (decision === 'STEP_UP') results.stepUp++;
+        else if (decision === 'ALLOW') results.allowed++;
+        else results.errors++;
+
+        try {
+          await sleep(options.delayMs, signal);
+        } catch {
+          break outer; // aborted
+        }
+      }
+    }
+
+    return {
+      attempts: results.attempts,
+      blocked: results.blocked,
+      stepUp: results.stepUp,
+      allowed: results.allowed,
+      errors: results.errors,
+    };
+  },
+};

package/src/scenarios/index.js

@@ -0,0 +1,25 @@
+/**
+ * Scenario registry — all built-in scenarios.
+ *
+ * v0.1 shipped with two scenarios:
+ *   - credential-stuffing
+ *   - account-drain
+ *
+ * v0.2 adds:
+ *   - adaptive-attacker (LLM-driven)
+ *
+ * v0.3 will add:
+ *   - promo-abuse
+ *   - card-testing
+ *   - sim-swap-takeover
+ *   - mule-network
+ *   - slow-drain
+ *   - session-hijack
+ *   - velocity-evasion
+ */
+
+import credentialStuffing from './credential-stuffing.js';
+import accountDrain from './account-drain.js';
+import adaptiveAttacker from './adaptive-attacker.js';
+
+export const scenarios = [credentialStuffing, accountDrain, adaptiveAttacker];

package/src/streaming/index.js

@@ -0,0 +1,6 @@
+/**
+ * Streaming helpers — push simulation events to a live consumer (a browser
+ * dashboard, a log tail, etc.) as they happen rather than only at the end.
+ */
+
+export { sseStream } from './sse.js';