@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/probe/mass-assignment/regression.ts

@@ -0,0 +1,141 @@
+import type { EndpointInfo, SecuritySchemeInfo } from "../../generator/types.ts";
+import { flattenToFormFields } from "../../runner/form-encode.ts";
+import type { RawStep, RawSuite } from "../../generator/serializer.ts";
+import {
+  captureFieldFor,
+  convertPath,
+  endpointStem,
+  findDeleteCounterpart,
+  findGetByIdCounterpart,
+  getAuthHeaders,
+} from "../shared.ts";
+import { findIdParam } from "./classify.ts";
+import type {
+  EndpointVerdict,
+  MassAssignmentResult,
+} from "./types.ts";
+
+const ACCEPTABLE_4XX = [400, 401, 403, 409, 415, 422];
+
+/**
+ * Emit YAML suites that lock in the safe behaviour observed during the live
+ * run:
+ *   • rejected (4xx) → assert status ∈ ACCEPTABLE_4XX (no regression to 2xx).
+ *   • accepted-and-ignored → assert 2xx and that injected fields don't echo
+ *     back. Follow-up GET — when available — additionally asserts the field
+ *     is not persisted.
+ *
+ * "applied" / "inconclusive" are deliberately NOT emitted: those are bugs to
+ * fix, not baselines to lock.
+ */
+export function emitRegressionSuites(
+  result: MassAssignmentResult,
+  endpoints: EndpointInfo[],
+  schemes: SecuritySchemeInfo[],
+): RawSuite[] {
+  const suites: RawSuite[] = [];
+  for (const v of result.verdicts) {
+    // ARV-250: "info" carries the post-pivot semantics of the old "low"
+    // (extras silently ignored — useful regression even when severity is
+    // demoted). Both "low" (inconclusive) and "info" (ignored) qualify
+    // for the ignored-baseline suite.
+    const isIgnoredCase = v.severity === "low" || v.severity === "info";
+    if (v.severity !== "ok" && !isIgnoredCase) continue;
+    const ep = endpoints.find(e => e.path === v.path && e.method.toUpperCase() === v.method);
+    if (!ep) continue;
+    const suiteHeaders = getAuthHeaders(ep, schemes);
+    const probeExpectedStatus = v.severity === "ok" ? ACCEPTABLE_4XX : [200, 201, 202, 204];
+    // ARV-150: emit `form:` instead of `json:` when the endpoint uses
+    // form-urlencoded bodies — otherwise the regression suite would send
+    // JSON and re-hit the original "wrong content-type" 400.
+    const bodyField =
+      ep.requestBodyContentType === "application/x-www-form-urlencoded"
+        ? { form: flattenToFormFields(v.request.body) }
+        : { json: v.request.body };
+    const probeStep: RawStep = {
+      name: `mass-assignment: extras must ${v.severity === "ok" ? "be rejected" : "not apply"}`,
+      source: {
+        generator: "mass-assignment-probe",
+        endpoint: `${v.method} ${v.path}`,
+        response_branch: probeExpectedStatus.map(String).join("|"),
+      },
+      [v.method]: convertPath(ep.path),
+      ...bodyField,
+      expect: {
+        status: probeExpectedStatus,
+      },
+    };
+    const tests: RawStep[] = [probeStep];
+    // For ignored case + we have a follow-up GET → emit a verifying GET
+    // that asserts injected fields are absent / overridden.
+    if (isIgnoredCase && v.followUpGet) {
+      const idField = captureFieldFor(ep);
+      probeStep.expect.body = {
+        ...(probeStep.expect.body ?? {}),
+        [idField]: { capture: "created_id" },
+      };
+      const getEp = findGetByIdCounterpart(ep, endpoints);
+      if (getEp) {
+        const idParam = findIdParam(getEp);
+        const getStep: RawStep = {
+          name: `verify extras did not persist`,
+          source: {
+            generator: "mass-assignment-probe",
+            endpoint: `GET ${getEp.path}`,
+            response_branch: "200",
+          },
+          GET: convertPath(getEp.path).replace(`{{${idParam}}}`, "{{created_id}}"),
+          expect: {
+            status: 200,
+            body: extrasNotEqualAssertions(v),
+          },
+        };
+        tests.push(getStep);
+      }
+      // cleanup
+      const delEp = findDeleteCounterpart(ep, endpoints);
+      if (delEp) {
+        const idParam = findIdParam(delEp);
+        const delStep: RawStep = {
+          name: "cleanup",
+          source: {
+            generator: "mass-assignment-probe-cleanup",
+            endpoint: `DELETE ${delEp.path}`,
+          },
+          always: true,
+          DELETE: convertPath(delEp.path).replace(`{{${idParam}}}`, "{{created_id}}"),
+          expect: { status: [200, 202, 204, 404] },
+        } as RawStep & { always: boolean };
+        tests.push(delStep);
+      }
+    }
+    suites.push({
+      name: `mass-assignment ${v.method} ${v.path}`,
+      tags: ["probe-mass-assignment", v.severity === "ok" ? "rejected-baseline" : "ignored-baseline"],
+      source: {
+        type: "probe-suite",
+        generator: "mass-assignment-probe",
+        endpoint: `${v.method} ${v.path}`,
+      },
+      fileStem: `mass-assignment-${endpointStem(ep)}`,
+      base_url: "{{base_url}}",
+      ...(suiteHeaders ? { headers: suiteHeaders } : {}),
+      tests,
+    });
+  }
+  return suites;
+}
+
+function extrasNotEqualAssertions(v: EndpointVerdict): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = {};
+  for (const f of v.fields) {
+    if (f.outcome === "ignored" || f.outcome === "echoed-overwritten" || f.outcome === "absent") {
+      // Assert the suspicious value did NOT take effect. We check that the
+      // observed value (from the live GET) still holds — the API is allowed
+      // to echo a server default; what's forbidden is echoing OUR sentinel.
+      const expectedNotEqual = JSON.stringify(f.injected);
+      out[f.field] = { not_equals: expectedNotEqual };
+    }
+  }
+  return out;
+}

package/src/core/probe/mass-assignment/suspects.ts

@@ -0,0 +1,92 @@
+import type { OpenAPIV3 } from "openapi-types";
+import type { EndpointInfo } from "../../generator/types.ts";
+
+/**
+ * Sentinel values are deliberately distinctive so that — if they appear in a
+ * follow-up GET response — we can be confident the server actually persisted
+ * them rather than coincidentally generating the same value.
+ */
+export const SUSPECTED_FIELDS: Record<string, unknown> = {
+  is_admin: true,
+  is_system: true,
+  verified: true,
+  role: "admin",
+  account_id: "00000000-0000-0000-0000-00000000beef",
+  owner_id: "00000000-0000-0000-0000-00000000beef",
+  user_id: "00000000-0000-0000-0000-00000000beef",
+};
+
+/** Sentinel values for server-assigned fields lifted from response schema. */
+const SERVER_FIELD_SENTINEL = {
+  uuid: "00000000-0000-0000-0000-00000000dead",
+  isoDate: "2000-01-01T00:00:00.000Z",
+  string: "zond-injected",
+  integer: -424242,
+  number: -424242,
+  boolean: false,
+};
+
+function requestPropertyNames(schema?: OpenAPIV3.SchemaObject): Set<string> {
+  const out = new Set<string>();
+  if (!schema) return out;
+  if (schema.properties) {
+    for (const k of Object.keys(schema.properties)) out.add(k);
+  }
+  for (const composite of [schema.allOf, schema.oneOf, schema.anyOf]) {
+    if (Array.isArray(composite)) {
+      for (const sub of composite) {
+        const s = sub as OpenAPIV3.SchemaObject;
+        if (s.properties) for (const k of Object.keys(s.properties)) out.add(k);
+      }
+    }
+  }
+  return out;
+}
+
+export function isStrictContract(schema?: OpenAPIV3.SchemaObject): boolean {
+  if (!schema) return false;
+  return schema.additionalProperties === false;
+}
+
+function pickServerFieldSentinel(s: OpenAPIV3.SchemaObject): unknown {
+  if (s.format === "uuid") return SERVER_FIELD_SENTINEL.uuid;
+  if (s.format === "date-time" || s.format === "date") return SERVER_FIELD_SENTINEL.isoDate;
+  switch (s.type) {
+    case "string": return SERVER_FIELD_SENTINEL.string;
+    case "integer": return SERVER_FIELD_SENTINEL.integer;
+    case "number": return SERVER_FIELD_SENTINEL.number;
+    case "boolean": return SERVER_FIELD_SENTINEL.boolean;
+    default: return SERVER_FIELD_SENTINEL.string;
+  }
+}
+
+/** Server-assigned fields = response 2xx schema props that don't appear in request schema. */
+export function serverAssignedExtras(ep: EndpointInfo): Record<string, unknown> {
+  const reqProps = requestPropertyNames(ep.requestBodySchema);
+  const success = ep.responses.find(r => r.statusCode >= 200 && r.statusCode < 300 && r.schema);
+  const respProps = success?.schema?.properties;
+  const out: Record<string, unknown> = {};
+  if (!respProps) return out;
+  for (const [name, schema] of Object.entries(respProps)) {
+    if (reqProps.has(name)) continue;
+    out[name] = pickServerFieldSentinel(schema as OpenAPIV3.SchemaObject);
+  }
+  return out;
+}
+
+/** Extra fields that aren't legitimate request-body properties. */
+export function suspectedExtras(
+  ep: EndpointInfo,
+  extra: Record<string, unknown> = {},
+): Record<string, unknown> {
+  const reqProps = requestPropertyNames(ep.requestBodySchema);
+  const out: Record<string, unknown> = {};
+  // ARV-252: per-run extras (CLI --suspect-field) compose with the
+  // curated SUSPECTED_FIELDS list. Later additions win on key collision
+  // so a user can override a sentinel value if needed.
+  const merged: Record<string, unknown> = { ...SUSPECTED_FIELDS, ...extra };
+  for (const [name, value] of Object.entries(merged)) {
+    if (!reqProps.has(name)) out[name] = value;
+  }
+  return out;
+}

package/src/core/probe/mass-assignment/types.ts

@@ -0,0 +1,135 @@
+import type { EndpointInfo, SecuritySchemeInfo } from "../../generator/types.ts";
+import type { SeedBodyConfig } from "../../generator/resources-builder.ts";
+import type { RecommendedAction } from "../../diagnostics/failure-hints.ts";
+
+/**
+ * Mass-assignment local severity. Includes the unified severity ladder
+ * (critical/high/medium/low/info — see core/severity) plus two
+ * outcome-style states specific to this probe (inconclusive-baseline,
+ * inconclusive-5xx) and probe-lifecycle markers (ok, skipped).
+ *
+ * 'medium' is retained in the type for backwards compat but ARV-250
+ * stopped emitting it — single-signal proof on absent-fields now caps
+ * to 'low' per the m-21 severity matrix.
+ */
+export type Severity =
+  | "high"
+  | "medium"
+  /** Baseline POST itself failed — we never reached extras-validation, so the
+   *  4xx-with-extras was a false signal. User must fix fixture / FK / scope
+   *  before this endpoint can be probed (TASK-91). */
+  | "inconclusive-baseline"
+  /** Baseline POST returned ≥500 — the endpoint just crashes, mass-assignment
+   *  semantics aren't observable here. Likely a duplicate of validation-probe's
+   *  finding for the same endpoint (TASK-276). */
+  | "inconclusive-5xx"
+  | "low"
+  | "info"
+  | "ok"
+  | "skipped";
+
+export interface FieldVerdict {
+  field: string;
+  injected: unknown;
+  /** "applied" | "ignored" | "echoed-but-overwritten" | "absent" | "unknown" */
+  outcome: "applied" | "ignored" | "echoed-overwritten" | "absent" | "unknown";
+  /** Value as seen in the response body (or follow-up GET if applicable). */
+  observed?: unknown;
+}
+
+export interface EndpointVerdict {
+  method: string;
+  path: string;
+  severity: Severity;
+  /** Canonical short reason (used in markdown header). */
+  summary: string;
+  request: {
+    url: string;
+    body: unknown;
+    injectedFields: string[];
+  };
+  response?: {
+    status: number;
+    body?: unknown;
+  };
+  followUpGet?: {
+    url: string;
+    status: number;
+    body?: unknown;
+  };
+  /** Result of the baseline (no-extras) probe — present whenever we sent it
+   *  (always, except for skipped endpoints). Used to disambiguate
+   *  «extras refused» from «baseline body invalid» (TASK-91). */
+  baseline?: {
+    status: number;
+    body?: unknown;
+  };
+  fields: FieldVerdict[];
+  /** True when request schema has additionalProperties:false (strict). */
+  strictContract: boolean;
+  cleanup?: {
+    attempted: boolean;
+    status?: number;
+    error?: string;
+  };
+  /** Reason this endpoint was skipped (only set when severity === "skipped"). */
+  skipReason?: string;
+  notes?: string[];
+  /** TASK-294: agent-routable action.
+   *  high/medium → `report_backend_bug` (privilege escalation).
+   *  inconclusive-baseline → `fix_fixture` (broken request body, retry).
+   *  inconclusive-5xx → `report_backend_bug` (server crashed).
+   *  low/ok/skipped → undefined. */
+  recommended_action?: RecommendedAction;
+}
+
+export interface MassAssignmentOptions {
+  endpoints: EndpointInfo[];
+  securitySchemes: SecuritySchemeInfo[];
+  /** Substituted variables (base_url, auth_token, api_key, path params). */
+  vars: Record<string, string>;
+  /** When true, do not issue cleanup-DELETE after 2xx responses. */
+  noCleanup?: boolean;
+  /** Per-request fetch timeout (ms). */
+  timeoutMs?: number;
+  /** When false, skip auto-discovery of path-param fixtures via GET-on-list (TASK-92).
+   *  TASK-137: this flag now also controls body-FK discovery (required body
+   *  fields named `*_id` / `*_slug` / `*_uuid` get filled from the matching
+   *  collection list endpoint, eliminating most INCONCLUSIVE-baseline noise). */
+  discover?: boolean;
+  /** ARV-252: per-run extension to SUSPECTED_FIELDS (curated list of
+   *  classic mass-assignment vectors). CLI surfaces this as repeatable
+   *  `--suspect-field name=value`. Full per-api spec-extension support
+   *  (x-zond-suspect-fields) is tracked in ARV-189. */
+  extraSuspectFields?: Record<string, unknown>;
+  /** ARV-269: agent-authored `seed_body` overlays from `.api-resources.local.yaml`,
+   *  keyed by `"METHOD /path"` of the endpoint they apply to (typically the
+   *  resource's create endpoint). When present for a probed endpoint, it
+   *  replaces `generateFromSchema` as the baseline body source — same
+   *  promotion stateful checks took via `resolveCreateBody`. Mass-assignment
+   *  before ARV-269 ignored this overlay; on strict-validating APIs (Stripe)
+   *  every baseline 400'd and the verdict collapsed to INCONCLUSIVE. */
+  seedBodies?: Map<string, SeedBodyConfig>;
+}
+
+export interface MassAssignmentResult {
+  specProbed: number;
+  totalEndpoints: number;
+  verdicts: EndpointVerdict[];
+  warnings: string[];
+}
+
+/** Internal: per-step options for probeEndpoint. */
+export interface ProbeEndpointOpts {
+  noCleanup: boolean;
+  timeoutMs?: number;
+  bodyFkMisses?: Array<{ field: string; reason: string }>;
+  /** TASK-137: field→value pairs from body-FK discovery. Overlaid on baseline
+   *  after generation so a real id/slug replaces the random sentinel. */
+  bodyFkOverlay?: Record<string, string>;
+  /** ARV-252: per-run extras for the suspect-fields list. */
+  extraSuspectFields?: Record<string, unknown>;
+  /** ARV-269: optional agent-authored body overlay for this endpoint
+   *  (usually the resource's create endpoint). Wins over generator. */
+  seedBody?: SeedBodyConfig;
+}

package/src/core/probe/mass-assignment-probe-class.ts

@@ -0,0 +1,198 @@
+/**
+ * `MassAssignmentProbe` — Probe-contract wrapper around the existing
+ * `runMassAssignmentProbes` engine (m-17 / ARV-49).
+ *
+ * dryRun() lists POST/PATCH/PUT endpoints with the suspect fields the
+ * probe would inject (suspectedExtras + serverAssignedExtras). Skip
+ * reasons mirror the live runner (no-body, isolated-protected). This
+ * fills the F2-15 gap (mass-assignment had no --dry-run); ARV-52 wires
+ * the corresponding CLI flag.
+ *
+ * run() delegates to runMassAssignmentProbes; report() converts to
+ * either the legacy markdown digest or the structured per-endpoint
+ * shape (ARV-51).
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { Probe, ProbeContext, ProbeFlags, EndpointPlan, ProbeResult, ProbeReportFormat, ProbeEndpointResult, ProbeEndpointStatus } from "./types.ts";
+import {
+  runMassAssignmentProbes,
+  formatDigestMarkdown,
+  SUSPECTED_FIELDS,
+  type MassAssignmentResult,
+  type EndpointVerdict,
+  type Severity,
+} from "./mass-assignment-probe.ts";
+import { pathTouchesSeededVar } from "./shared.ts";
+import { hasProbeBody } from "./probe-harness.ts";
+
+const FLAGS: ProbeFlags = {
+  api: true,
+  tag: true,
+  include: true,
+  exclude: true,
+  dryRun: true,
+  listTags: true,
+  json: true,
+  output: true,
+  report: true,
+};
+
+function requestPropertyNames(schema?: OpenAPIV3.SchemaObject): Set<string> {
+  const out = new Set<string>();
+  if (!schema) return out;
+  if (schema.properties) for (const k of Object.keys(schema.properties)) out.add(k);
+  for (const composite of [schema.allOf, schema.oneOf, schema.anyOf]) {
+    if (Array.isArray(composite)) {
+      for (const sub of composite) {
+        const s = sub as OpenAPIV3.SchemaObject;
+        if (s.properties) for (const k of Object.keys(s.properties)) out.add(k);
+      }
+    }
+  }
+  return out;
+}
+
+function suspectFieldsFor(ep: { requestBodySchema?: OpenAPIV3.SchemaObject }): string[] {
+  const reqProps = requestPropertyNames(ep.requestBodySchema);
+  const out: string[] = [];
+  for (const name of Object.keys(SUSPECTED_FIELDS)) {
+    if (!reqProps.has(name)) out.push(name);
+  }
+  return out;
+}
+
+function statusFromSeverity(s: Severity): ProbeEndpointStatus {
+  switch (s) {
+    case "high": return "high";
+    case "low": return "low";
+    case "medium": return "low";
+    case "info": return "low";
+    case "ok": return "ok";
+    case "skipped": return "skipped";
+    case "inconclusive-baseline":
+    case "inconclusive-5xx":
+      return "inconclusive";
+  }
+}
+
+function evidenceFromVerdict(v: EndpointVerdict): Record<string, unknown> {
+  return {
+    summary: v.summary,
+    request: { url: v.request.url, injectedFields: v.request.injectedFields },
+    response: v.response ? { status: v.response.status } : undefined,
+    fields: v.fields,
+  };
+}
+
+function toProbeResult(ma: MassAssignmentResult): ProbeResult {
+  const endpoints: ProbeEndpointResult[] = ma.verdicts.map((v) => ({
+    path: v.path,
+    method: v.method,
+    classes_run: ["mass-assignment"],
+    findings:
+      v.severity === "skipped" || v.severity === "ok"
+        ? []
+        : [{
+            class: "mass-assignment",
+            severity:
+              v.severity === "high" ? "high" :
+              v.severity === "low" || v.severity === "medium" ? "low" :
+              "inconclusive",
+            evidence: evidenceFromVerdict(v),
+          }],
+    status: statusFromSeverity(v.severity),
+    ...(v.severity === "skipped" ? { skip_reason: v.skipReason ?? v.summary } : {}),
+  }));
+  const by_status: Record<ProbeEndpointStatus, number> = {
+    ok: 0, high: 0, low: 0, inconclusive: 0, skipped: 0,
+  };
+  for (const ep of endpoints) by_status[ep.status]++;
+  return {
+    endpoints,
+    summary: {
+      totalEndpoints: ma.totalEndpoints,
+      probed: ma.specProbed,
+      by_status,
+    },
+    warnings: ma.warnings,
+  };
+}
+
+export class MassAssignmentProbe implements Probe {
+  readonly name = "mass-assignment";
+  readonly description =
+    "Live probe for mass-assignment / privilege-escalation: classifies POST/PATCH/PUT against suspected extra fields (is_admin, role, account_id, …).";
+  readonly commonFlags = FLAGS;
+
+  async dryRun(ctx: ProbeContext): Promise<EndpointPlan[]> {
+    const isolated = ctx.options["isolated"] === true;
+    const out: EndpointPlan[] = [];
+    for (const ep of ctx.endpoints) {
+      if (ep.deprecated) continue;
+      const m = ep.method.toUpperCase();
+      if (m !== "POST" && m !== "PUT" && m !== "PATCH") continue;
+
+      if (isolated && (m === "PUT" || m === "PATCH") && pathTouchesSeededVar(ep.path, ctx.vars)) {
+        out.push({
+          path: ep.path,
+          method: m,
+          planned: false,
+          classes_planned: [],
+          fields_planned: [],
+          skip_reason: "isolated-protected",
+        });
+        continue;
+      }
+
+      // ARV-150: parity with the live runner — form-urlencoded counts as a body.
+      if (!hasProbeBody(ep)) {
+        out.push({
+          path: ep.path,
+          method: m,
+          planned: false,
+          classes_planned: [],
+          fields_planned: [],
+          skip_reason: "no-body",
+        });
+        continue;
+      }
+
+      const fields = suspectFieldsFor(ep);
+      out.push({
+        path: ep.path,
+        method: m,
+        planned: true,
+        classes_planned: ["mass-assignment"],
+        fields_planned: fields,
+        skip_reason: null,
+      });
+    }
+    return out;
+  }
+
+  async run(ctx: ProbeContext): Promise<ProbeResult> {
+    const ma = await runMassAssignmentProbes({
+      endpoints: ctx.endpoints,
+      securitySchemes: ctx.securitySchemes,
+      vars: ctx.vars,
+      noCleanup: ctx.options["noCleanup"] === true,
+      timeoutMs: typeof ctx.options["timeoutMs"] === "number" ? (ctx.options["timeoutMs"] as number) : undefined,
+      discover: ctx.options["noDiscover"] !== true,
+    });
+    const result = toProbeResult(ma);
+    result.extras = { raw: ma };
+    return result;
+  }
+
+  report(format: ProbeReportFormat, result: ProbeResult): string | object {
+    if (format === "markdown") {
+      const raw = result.extras?.["raw"] as MassAssignmentResult | undefined;
+      if (raw) return formatDigestMarkdown(raw, "");
+      return "(no markdown digest available)";
+    }
+    return {
+      endpoints: result.endpoints,
+      summary: result.summary,
+    };
+  }
+}

package/src/core/probe/mass-assignment-probe.ts

@@ -0,0 +1,27 @@
+/**
+ * Barrel re-export for `zond probe-mass-assignment`.
+ *
+ * The probe pipeline lives in `./mass-assignment/`:
+ *   - types.ts        — public types / interfaces
+ *   - suspects.ts     — suspected-fields table + schema helpers
+ *   - classify.ts     — per-field classification + severity finalisation
+ *   - cleanup.ts      — best-effort DELETE on baseline POSTs
+ *   - digest.ts       — markdown digest formatter
+ *   - regression.ts   — regression-suite YAML emission
+ *   - orchestrator.ts — runMassAssignmentProbes + probeEndpoint loop
+ *
+ * History: split out of a 1135-LOC monolith (ARV-296, 2026-05-18) to keep
+ * each concern in a focused file. The public API surface is unchanged.
+ */
+export type {
+  Severity,
+  FieldVerdict,
+  EndpointVerdict,
+  MassAssignmentOptions,
+  MassAssignmentResult,
+} from "./mass-assignment/types.ts";
+export { SUSPECTED_FIELDS } from "./mass-assignment/suspects.ts";
+export { runMassAssignmentProbes } from "./mass-assignment/orchestrator.ts";
+export { isSubscriptionGated } from "./mass-assignment/classify.ts";
+export { formatDigestMarkdown } from "./mass-assignment/digest.ts";
+export { emitRegressionSuites } from "./mass-assignment/regression.ts";