@keelpin/fuzz-runtime

The mock toolkit is open-source so you can audit how Argent manufactures the violation signal. The rest of Argent is commercial. Closed product, open trust anchor.

@keelpin/fuzz-runtime is the MIT-licensed runtime that backs every business-logic fuzzer the closed Argent AppSec product generates. When Argent reports a CONFIRMED_VIOLATION — say, a cross-tenant document read — that signal is manufactured by running a generated fuzzer against the four mocks in this package: MockDb, MockHttp, MockClock, MockRng, plus the harness glue.

If the mocks are wrong, the violation could be artifactual. So we open-sourced them.

Why this is open-source

Argent makes a strong claim:

"We found a real authorization bug in your code."

A reasonable customer asks:

"How do I know your fuzzer didn't fake the violation?"

Reading this repo answers that question. You can:

• Read the mock code and verify it behaves like a real DB / HTTP / clock.
• Pin Argent to a specific runtime version and audit that exact build.
• Run your own fuzzers locally against the same toolkit.
• File a PR if a mock diverges from real-world behavior in a way that matters.

The argument: a CONFIRMED_VIOLATION from Argent should be mechanically equivalent to a real-world exploit. The mock toolkit is the layer where that equivalence is defined. So that layer is public.

What's in the box

| Module | Purpose | |-------------|-----------------------------------------------------------------------------| | MockDb | Schema-driven in-memory store with a Prisma-shape proxy and snapshot/restore. | | MockHttp | Outgoing-fetch interceptor. Un-intercepted egress THROWS — no pass-through. | | MockClock | Controllable Date.now, setTimeout, and performance.now. | | MockRng | Deterministic xoroshiro128++ PRNG patching Math.random and crypto.getRandomValues. | | harness | Test-runner glue: build an Express-shape req / res, capture the result. |

Install

pnpm add -D @keelpin/fuzz-runtime
# or
npm i -D @keelpin/fuzz-runtime

Requires Node.js 20 or newer.

The 30-second example

The canonical case: a handler that fetches a document by ID without scoping to the requesting session's organization. A user in org-B should not be able to read a document owned by org-A. If they can, that's a CWE-639 cross-tenant IDOR.

import { describe, expect, test, beforeEach } from 'vitest';
import { MockDb, harness } from '@keelpin/fuzz-runtime';

const schema = {
  models: {
    Document: {
      fields: {
        id:      { type: 'String', isId: true },
        orgId:   { type: 'String' },
        title:   { type: 'String' },
        ownerId: { type: 'String' },
      },
    },
  },
} as const;

// The handler under test — a typical Express handler.
async function getDocument(req: any, res: any) {
  const { id } = req.params;
  const doc = await req.db.Document.findUnique({ where: { id } });
  if (doc === null) return res.status(404).end();
  return res.status(200).json(doc);
}

describe('cross-tenant document read', () => {
  let db: MockDb;

  beforeEach(() => {
    db = new MockDb({ schema });
    db.seed('Document', { id: 'doc-1', orgId: 'org-A', title: 'A-internal', ownerId: 'alice' });
  });

  test('positive control — same-tenant read works', async () => {
    const res = await harness.invoke(getDocument, {
      principal: { id: 'alice', orgId: 'org-A' },
      params: { id: 'doc-1' },
    }, { db });
    expect(res.status).toBe(200);
  });

  test('attack — cross-tenant read should be denied', async () => {
    const res = await harness.invoke(getDocument, {
      principal: { id: 'bob', orgId: 'org-B' },
      params: { id: 'doc-1' },
    }, { db });
    expect([403, 404]).toContain(res.status); // FAILS: handler returns 200.
  });
});

The attack test fails because the handler queries by id only and never checks document.orgId === session.orgId. That failure is the mechanical definition of "violation" — and the mocks make it reproducible, deterministic, and auditable.

Trust-anchor invariants

These are the contract behaviors the package's CI verifies on every PR:

1. No real network. MockHttp.install() patches globalThis.fetch and any un-intercepted egress THROWS. There is no pass-through to the real network in any mode. (node:http/node:https are best-effort blocked too.)
2. No real time drift. MockClock.install() replaces Date.now, setTimeout, setInterval, and performance.now. setTimeout callbacks only fire when MockClock.tick(ms) advances past their target.
3. No non-determinism. MockRng is xoroshiro128++ with an explicit seed. Math.random() and crypto.getRandomValues() are patched to draw from the same stream.
4. No raw SQL. MockDb.$queryRaw and MockDb.$executeRaw always reject. A fuzzer cannot escape the typed model surface to construct a fake violation through SQL injection of the mock itself.
5. Snapshot isolation. Every scenario in a fuzzer brackets state with snapshot() / restore() so cross-scenario contamination is impossible.

Compatibility with the closed Argent generator

The closed Argent generator emits fuzzer source that imports from this package under a strict semver range (^1.0.0 for v1). Breaking changes to the public surface require a major bump and a 1-week public-comment window — the public comment requirement is itself part of the trust-anchor posture.

The full compatibility contract lives in docs/compatibility.md (planned).

Versioning

Strict semver. Public surface = src/index.ts. Internals (PRNG state layout, MockDb storage layout) can change in patch releases.

License

MIT — © 2026 Titanium Computing, Inc.

Argent AppSec itself is not MIT-licensed. Only this runtime is.

Contributing

See CONTRIBUTING.md. MIT-only contributions; SPDX scan runs in CI.