@kirrosh/zond 0.26.0 → 0.27.0

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

@@ -1,135 +0,0 @@
-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

@@ -1,198 +0,0 @@
-/**
- * `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

@@ -1,27 +0,0 @@
-/**
- * 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";

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

@@ -1,240 +0,0 @@
-/**
- * TASK-146: emit-template generator.
- *
- * Builds a ready-to-edit YAML probe template for a single endpoint, so the
- * user doesn't have to copy-paste the boilerplate from the skill (Phase 5.1).
- * Used when the auto-prober marked an endpoint INCONCLUSIVE / INCONCLUSIVE-5XX
- * and the user wants to drop down to manual catch-up.
- *
- * Heuristics:
- *  - Suspected fields: classic mass-assignment vectors (is_admin, role,
- *    owner_id, account_id, ...).
- *  - readOnly: true / x-zond-protected fields lifted from the request body
- *    schema — these MUST NOT round-trip back from the server.
- *  - For POST endpoints with discoverable item path (GET-by-id / DELETE
- *    counterpart) we emit a full create → verify → cleanup chain.
- */
-import type { OpenAPIV3 } from "openapi-types";
-import type { EndpointInfo } from "../generator/types.ts";
-import type { RawSuite, RawStep } from "../generator/serializer.ts";
-import { serializeSuite } from "../generator/serializer.ts";
-import { readOpenApiSpec, extractEndpoints } from "../generator/openapi-reader.ts";
-import { findDeleteCounterpart, findGetByIdCounterpart, captureFieldFor } from "./shared.ts";
-import { SUSPECTED_FIELDS } from "./mass-assignment-probe.ts";
-
-export interface EmitTemplateOptions {
-  specPath: string;
-  method: string;
-  path: string;
-}
-
-export type EmitTemplateResult =
-  | { kind: "ok"; yaml: string; chain: "full" | "single"; protectedFields: string[] }
-  | { kind: "endpoint-not-found"; method: string; path: string; nearest: string[] };
-
-export async function buildMassAssignmentTemplate(
-  opts: EmitTemplateOptions,
-): Promise<EmitTemplateResult> {
-  const doc = await readOpenApiSpec(opts.specPath);
-  const all = extractEndpoints(doc);
-
-  const wantMethod = opts.method.toUpperCase();
-  const target = all.find(
-    e => e.method.toUpperCase() === wantMethod && pathsEqual(e.path, opts.path),
-  );
-
-  if (!target) {
-    const nearest = all
-      .filter(e => e.method.toUpperCase() === wantMethod)
-      .map(e => e.path)
-      .filter(p => similar(p, opts.path))
-      .slice(0, 5);
-    return { kind: "endpoint-not-found", method: wantMethod, path: opts.path, nearest };
-  }
-
-  const protectedFields = collectProtectedFields(target.requestBodySchema);
-  const baselineBody = buildBaselineSkeleton(target.requestBodySchema);
-  const privilegedBody = mergePrivileged(baselineBody, protectedFields);
-
-  const isMutatingCreateLike = wantMethod === "POST";
-  const readSibling = isMutatingCreateLike ? findGetByIdCounterpart(target, all) : undefined;
-  const deleteSibling = findDeleteCounterpart(target, all);
-
-  const suite = isMutatingCreateLike && readSibling
-    ? buildFullChain(target, readSibling, deleteSibling, privilegedBody, protectedFields)
-    : buildSingleStep(target, privilegedBody, protectedFields);
-
-  return {
-    kind: "ok",
-    yaml: serializeSuite(suite),
-    chain: isMutatingCreateLike && readSibling ? "full" : "single",
-    protectedFields,
-  };
-}
-
-function collectProtectedFields(schema?: OpenAPIV3.SchemaObject): string[] {
-  if (!schema || !schema.properties) return [];
-  const out: string[] = [];
-  for (const [name, raw] of Object.entries(schema.properties)) {
-    const prop = raw as OpenAPIV3.SchemaObject & { "x-zond-protected"?: boolean };
-    if (prop.readOnly === true || prop["x-zond-protected"] === true) out.push(name);
-  }
-  return out;
-}
-
-function buildBaselineSkeleton(schema?: OpenAPIV3.SchemaObject): Record<string, unknown> {
-  // Skeleton is intentionally minimal — `# …real create body sourced from
-  // fixtures…` placeholder shows up in the YAML so the user fills it in.
-  if (!schema || !schema.properties) return {};
-  const out: Record<string, unknown> = {};
-  for (const [name, raw] of Object.entries(schema.properties)) {
-    const prop = raw as OpenAPIV3.SchemaObject;
-    if (prop.readOnly === true) continue;
-    if (schema.required?.includes(name)) {
-      out[name] = placeholderForType(prop);
-    }
-  }
-  return out;
-}
-
-function placeholderForType(prop: OpenAPIV3.SchemaObject): unknown {
-  if (prop.example !== undefined) return prop.example;
-  switch (prop.type) {
-    case "integer":
-    case "number": return 1;
-    case "boolean": return false;
-    case "array": return [];
-    case "object": return {};
-    default: return `ma-test-{{$randomString}}`;
-  }
-}
-
-function mergePrivileged(
-  baseline: Record<string, unknown>,
-  protectedFields: string[],
-): Record<string, unknown> {
-  const merged: Record<string, unknown> = { ...baseline };
-  // Suspected fields always added.
-  for (const [k, v] of Object.entries(SUSPECTED_FIELDS)) merged[k] = v;
-  // readOnly / x-zond-protected fields: inject distinctive sentinel values
-  // so we can detect server-side echo vs server-side regeneration.
-  for (const f of protectedFields) {
-    if (!(f in merged)) merged[f] = `attacker-${f}-{{$uuid}}`;
-  }
-  return merged;
-}
-
-/** ARV-198: declared content type signals whether the create step needs
- *  `form:` (Stripe v1, Rails/PHP-style APIs) or the default `json:` body. */
-function isFormEndpoint(ep: EndpointInfo): boolean {
-  return ep.requestBodyContentType === "application/x-www-form-urlencoded";
-}
-
-function buildFullChain(
-  create: EndpointInfo,
-  read: EndpointInfo,
-  del: EndpointInfo | undefined,
-  privilegedBody: Record<string, unknown>,
-  protectedFields: string[],
-): RawSuite {
-  const idVar = captureFieldFor(create) || "created_id";
-  const tests: RawStep[] = [];
-
-  // ARV-198: when the spec declares only application/x-www-form-urlencoded
-  // for this mutating endpoint, emit a `form:` block + Content-Type header.
-  // The serializer force-quotes form values (ARV-162) so booleans/numbers
-  // round-trip as strings on the wire; the template is paste-ready against
-  // Stripe-style APIs without any post-processing.
-  const createIsForm = isFormEndpoint(create);
-  const createStep: Record<string, unknown> = {
-    name: "create with privileged fields",
-    [create.method.toUpperCase()]: create.path,
-    expect: { status: [200, 201], body: { id: { capture: idVar } } },
-  };
-  if (createIsForm) {
-    createStep.headers = { "Content-Type": "application/x-www-form-urlencoded" };
-    createStep.form = privilegedBody;
-  } else {
-    createStep.json = privilegedBody;
-  }
-  tests.push(createStep as unknown as RawStep);
-
-  // Canonical assertion vocabulary: only `not_equals` is supported (no `not`,
-  // no `not_starts_with`). For protected fields we assert the exact attacker
-  // sentinel value did NOT round-trip back from the server.
-  const verifyBody: Record<string, Record<string, unknown>> = {};
-  for (const k of Object.keys(SUSPECTED_FIELDS)) {
-    verifyBody[k] = { not_equals: SUSPECTED_FIELDS[k] };
-  }
-  for (const f of protectedFields) {
-    if (!(f in verifyBody)) verifyBody[f] = { not_contains: "attacker-" };
-  }
-
-  tests.push({
-    name: "verify privileged fields not echoed",
-    [read.method.toUpperCase()]: read.path.replace(/\{[^}]+\}/, `{{${idVar}}}`),
-    expect: { status: 200, body: verifyBody as unknown as Record<string, Record<string, string>> },
-  } as unknown as RawStep);
-
-  if (del) {
-    tests.push({
-      name: "cleanup",
-      [del.method.toUpperCase()]: del.path.replace(/\{[^}]+\}/, `{{${idVar}}}`),
-      always: true,
-      expect: { status: [200, 202, 204] },
-    } as unknown as RawStep);
-  }
-
-  return {
-    name: `ma ${slugFromPath(create.path)}`,
-    base_url: "{{base_url}}",
-    headers: { Authorization: "Bearer {{auth_token}}" },
-    tests,
-  };
-}
-
-function buildSingleStep(
-  ep: EndpointInfo,
-  privilegedBody: Record<string, unknown>,
-  _protectedFields: string[],
-): RawSuite {
-  const method = ep.method.toUpperCase();
-  const tests: RawStep[] = [];
-  const step: Record<string, unknown> = {
-    name: `mass-assignment ${method} ${ep.path}`,
-    [method]: ep.path,
-    expect: { status: [400, 422] },
-  };
-  if (method !== "GET" && method !== "DELETE") {
-    // ARV-198: same form/json branching as the full-chain create — see
-    // buildFullChain for rationale (Stripe-style mutators declare only
-    // application/x-www-form-urlencoded).
-    if (isFormEndpoint(ep)) {
-      step.headers = { "Content-Type": "application/x-www-form-urlencoded" };
-      step.form = privilegedBody;
-    } else {
-      step.json = privilegedBody;
-    }
-  }
-  tests.push(step as unknown as RawStep);
-  return {
-    name: `ma ${slugFromPath(ep.path)}`,
-    base_url: "{{base_url}}",
-    headers: { Authorization: "Bearer {{auth_token}}" },
-    tests,
-  };
-}
-
-function pathsEqual(a: string, b: string): boolean {
-  return a.replace(/\/$/, "") === b.replace(/\/$/, "");
-}
-
-function similar(a: string, b: string): boolean {
-  const aSeg = a.split("/").filter(Boolean);
-  const bSeg = b.split("/").filter(Boolean);
-  return aSeg.some(s => bSeg.includes(s));
-}
-
-function slugFromPath(p: string): string {
-  return p.replace(/^\//, "").replace(/\/?\{[^}]+\}/g, "").replace(/\//g, "-") || "endpoint";
-}