@kirrosh/zond 0.23.0 → 0.26.0

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

@@ -0,0 +1,175 @@
+import { classify as classifyRecommendedAction } from "../../classifier/recommended-action.ts";
+import type { EndpointInfo } from "../../generator/types.ts";
+import type { EndpointVerdict } from "./types.ts";
+
+/** Lower-cased anchored fragments for the SaaS-flavoured 403 wordings we
+ *  encounter in the wild (paid plan / role-scope / feature-flag gates).
+ *  Each entry is one independent signal — a body matching any one of them
+ *  is treated as subscription-gated. Formerly the anti-FP registry rule
+ *  `subscription-gated/paid-plan-403` (ARV-125); now inlined as a plain
+ *  evidence signal on the baseline summary — NOT a suppressor. */
+const SUBSCRIPTION_GATED_PATTERNS: RegExp[] = [
+  /\bpaid plan\b/i,
+  /\bsubscription (?:required|needed)\b/i,
+  /\bnot (?:available|enabled) (?:on|for) your\b/i,
+  /\bplan (?:does not include|doesn['']?t include)\b/i,
+  /\brequires? (?:the )?[\w:-]+ scope\b/i,
+  /\bmissing (?:the )?[\w:-]+ scope\b/i,
+  /\bfeature (?:is )?(?:not enabled|disabled|not available)\b/i,
+  /\binsufficient (?:permissions?|scope)\b/i,
+];
+
+/** Reason text surfaced on the baseline summary when a 403 body names a
+ *  subscription/scope gate — signals to the triage agent that fixture
+ *  edits won't help. */
+const SUBSCRIPTION_GATED_REASON =
+  "endpoint is env/subscription-gated (paid plan, role/scope, feature flag); " +
+  "not a fixture issue — wontfix unless scope changes";
+
+function matchesSubscriptionGated(message: string): boolean {
+  for (const re of SUBSCRIPTION_GATED_PATTERNS) {
+    if (re.test(message)) return true;
+  }
+  return false;
+}
+
+/** ARV-56: route through the single classifier instead of carrying the
+ *  severity→action switch inline. */
+export function stampRecommendedAction(verdict: EndpointVerdict): void {
+  const action = classifyRecommendedAction({
+    finding_class: "probe:mass_assignment",
+    severity: verdict.severity as Parameters<typeof classifyRecommendedAction>[0]["severity"],
+  });
+  if (action) verdict.recommended_action = action;
+}
+
+/**
+ * Build a one-line summary for INCONCLUSIVE-baseline verdicts. We surface
+ * the server's error code/name when present so the user can immediately
+ * see *which* FK / scope / fixture failed and fix it before re-probing.
+ */
+export function inconclusiveBaselineSummary(
+  status: number,
+  body: unknown,
+  bodyFkMisses?: Array<{ field: string; reason: string }>,
+): string {
+  const hint = extractBaselineHint(body);
+  const base = `baseline body invalid — server returned ${status}`;
+  // ARV-104 (F9): when status is 403 and the response body names a
+  // subscription/scope gate (paid plan, feature flag, role/scope
+  // insufficient), the right answer isn't "fix fixture" — there's
+  // nothing to fix. Surface a wontfix reason on the summary as raw
+  // evidence for the triage agent (this is a hint, NOT a suppressor).
+  const gated = status === 403 && hint !== undefined && matchesSubscriptionGated(hint);
+  const tail = gated
+    ? ` — ${SUBSCRIPTION_GATED_REASON}`
+    : " — fix fixture / FK value / path-params and re-probe";
+  // TASK-137: if body-FK auto-discovery couldn't fill required FK fields, name
+  // them in the summary so the user knows exactly what to add to env (or
+  // why discover-fk missed — e.g. nested list endpoint, 403 from scope).
+  let fkClause = "";
+  if (bodyFkMisses && bodyFkMisses.length > 0) {
+    const names = bodyFkMisses.map(m => m.field).join(", ");
+    fkClause = ` — unresolved body FKs: ${names}`;
+  }
+  return hint
+    ? `${base} (${hint})${fkClause}${tail}`
+    : `${base}${fkClause}${tail}`;
+}
+
+/** ARV-104 (F9): quick yes/no on whether a 403 body names a
+ *  subscription/scope gate. Public predicate for callers (and tests)
+ *  that want the signal without composing a summary string. */
+export const isSubscriptionGated = matchesSubscriptionGated;
+
+function extractBaselineHint(body: unknown): string | undefined {
+  if (typeof body === "string") {
+    const trimmed = body.trim();
+    if (trimmed.length === 0) return undefined;
+    return trimmed.length > 120 ? `${trimmed.slice(0, 120)}…` : trimmed;
+  }
+  if (typeof body !== "object" || body === null) return undefined;
+  const obj = body as Record<string, unknown>;
+  // Common error-envelope fields across SaaS APIs.
+  const candidates = [
+    obj.message,
+    obj.error,
+    (obj.error as Record<string, unknown> | undefined)?.message,
+    obj.detail,
+    obj.title,
+    obj.name,
+    obj.code,
+  ];
+  for (const c of candidates) {
+    if (typeof c === "string" && c.length > 0) {
+      return c.length > 120 ? `${c.slice(0, 120)}…` : c;
+    }
+  }
+  return undefined;
+}
+
+export function needsFollowUp(verdict: EndpointVerdict): boolean {
+  return verdict.fields.some(f => f.outcome === "absent" || f.outcome === "unknown");
+}
+
+export function classifyFromBody(
+  verdict: EndpointVerdict,
+  body: Record<string, unknown> | undefined,
+  fromGet = false,
+): void {
+  if (!body) return;
+  for (const field of verdict.fields) {
+    // Once a field is decisively classified (applied/echoed-overwritten),
+    // don't downgrade. But "absent" on POST may still flip to applied/ignored
+    // after GET — so only re-check those.
+    if (field.outcome === "applied" || field.outcome === "echoed-overwritten") continue;
+    if (!(field.field in body)) {
+      // GET also missing → ignored. POST missing → keep "absent" so we GET later.
+      field.outcome = fromGet ? "ignored" : "absent";
+      continue;
+    }
+    const observed = body[field.field];
+    field.observed = observed;
+    if (Bun.deepEquals(observed, field.injected)) {
+      field.outcome = "applied";
+    } else if (fromGet) {
+      field.outcome = "ignored";
+    } else {
+      field.outcome = "echoed-overwritten";
+    }
+  }
+}
+
+export function findIdParam(ep: EndpointInfo): string {
+  const m = ep.path.match(/\{([^}]+)\}/);
+  return m ? m[1]! : "id";
+}
+
+export function finaliseSeverity(v: EndpointVerdict, strict: boolean): void {
+  const applied = v.fields.filter(f => f.outcome === "applied");
+  const absent = v.fields.filter(f => f.outcome === "absent");
+
+  if (applied.length > 0) {
+    v.severity = "high";
+    v.summary = `accepted-and-applied: ${applied.map(f => f.field).join(", ")}`;
+    return;
+  }
+  if (absent.length > 0) {
+    // ARV-252: absent-but-unverifiable carries single_signal proof.
+    // Surfaced as INFO and only shown under --verbose so the report
+    // stays clean; the verdict still travels through the JSON envelope
+    // for agents that want to triage it explicitly.
+    v.severity = "info";
+    v.summary = `inconclusive — could not verify via follow-up GET (${absent.map(f => f.field).join(", ")})`;
+    return;
+  }
+  // ARV-252: silently-ignored = correct framework behaviour (Rails
+  // strong params / FastAPI extra=ignore). Severity stays INFO so it
+  // never gates CI, AND the CLI display layer suppresses it entirely
+  // (even under --verbose). Reports must not be noise-floored by
+  // correct behaviour. Verdicts still travel through the JSON envelope
+  // for agents that explicitly want to inspect them.
+  v.severity = "info";
+  const status = v.response?.status ?? 0;
+  v.summary = `accepted ${status} but extras silently ignored${strict ? " (despite additionalProperties:false — server should reject)" : ""}`;
+}

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

@@ -0,0 +1,52 @@
+import type { EndpointInfo, SecuritySchemeInfo } from "../../generator/types.ts";
+import { executeRequest } from "../../runner/http-client.ts";
+import {
+  captureFieldFor,
+  findDeleteCounterpart,
+  liveAuthHeaders,
+} from "../shared.ts";
+import { buildProbeUrl } from "../probe-harness.ts";
+import { findIdParam } from "./classify.ts";
+
+/**
+ * Best-effort DELETE on the baseline (no-extras) probe so the injected
+ * POST doesn't trip a unique-constraint and we don't leak resources.
+ */
+export async function tryCleanupBaseline(
+  ep: EndpointInfo,
+  allEndpoints: EndpointInfo[],
+  schemes: SecuritySchemeInfo[],
+  vars: Record<string, string>,
+  baselineBody: unknown,
+  opts: { timeoutMs?: number },
+): Promise<void> {
+  const body =
+    typeof baselineBody === "object" && baselineBody !== null
+      ? (baselineBody as Record<string, unknown>)
+      : undefined;
+  if (!body) return;
+  const idField = captureFieldFor(ep);
+  const id = body[idField];
+  if (id === undefined) return;
+  const delEp = findDeleteCounterpart(ep, allEndpoints);
+  if (!delEp) return;
+  const delVars = { ...vars, [findIdParam(delEp)]: String(id), id: String(id) };
+  const delUrl = buildProbeUrl(delEp, delVars);
+  if (delUrl.unresolved.length > 0) return;
+  try {
+    await executeRequest(
+      {
+        method: "DELETE",
+        url: delUrl.url,
+        headers: {
+          accept: "application/json",
+          ...liveAuthHeaders(delEp, schemes, vars),
+        },
+      },
+      { timeout: opts.timeoutMs ?? 30000, retries: 0 },
+    );
+  } catch {
+    // best-effort — if cleanup fails we'll leak a baseline resource, but
+    // that's a deployment problem, not a probe bug.
+  }
+}

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

@@ -0,0 +1,114 @@
+import { SUSPECTED_FIELDS } from "./suspects.ts";
+import type {
+  EndpointVerdict,
+  MassAssignmentResult,
+  Severity,
+} from "./types.ts";
+
+const SEVERITY_ORDER: Severity[] = [
+  "high",
+  "inconclusive-baseline",
+  "inconclusive-5xx",
+  "medium",
+  "low",
+  "info",
+  "ok",
+  "skipped",
+];
+
+const SEVERITY_HEADER: Record<Severity, string> = {
+  high: "🚨 HIGH — privilege escalation candidates",
+  "inconclusive-baseline": "⚠️  INCONCLUSIVE — baseline body invalid (fix fixture / FK / scope and re-probe)",
+  "inconclusive-5xx": "⚠️  INCONCLUSIVE — baseline 5xx (endpoint crashes — likely duplicate of validation-probe)",
+  medium: "⚠️  MEDIUM — inconclusive (no follow-up GET available)",
+  low: "ℹ️  LOW — inconclusive (single-signal, follow-up GET unavailable)",
+  info: "·  INFO — accepted-and-ignored (correct framework behaviour, often ineligible to report)",
+  ok: "✅ OK — rejected 4xx (best behaviour)",
+  skipped: "⏭️  SKIPPED",
+};
+
+export function formatDigestMarkdown(
+  result: MassAssignmentResult,
+  specPath: string,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Mass-assignment probe digest`);
+  lines.push("");
+  lines.push(`**Spec:** \`${specPath}\``);
+  lines.push(`**Endpoints probed:** ${result.specProbed} of ${result.totalEndpoints} mutating endpoints`);
+  lines.push("");
+  lines.push(`**Suspected fields tested:** ${Object.keys(SUSPECTED_FIELDS).join(", ")}`);
+  lines.push("");
+
+  const buckets = groupBySeverity(result.verdicts);
+  for (const sev of SEVERITY_ORDER) {
+    const items = buckets[sev];
+    if (!items || items.length === 0) continue;
+    lines.push(`## ${SEVERITY_HEADER[sev]} (${items.length})`);
+    lines.push("");
+    for (const v of items) {
+      lines.push(`### ${v.method} ${v.path}`);
+      lines.push("");
+      if (v.severity === "skipped") {
+        lines.push(`- Skipped: ${v.skipReason ?? v.summary}`);
+        lines.push("");
+        continue;
+      }
+      lines.push(`- ${v.summary}`);
+      lines.push(`- Injected: ${v.request.injectedFields.map(n => `\`${n}\``).join(", ")}`);
+      if (v.baseline) {
+        lines.push(`- Baseline (no extras): ${v.baseline.status}`);
+      }
+      if (v.response) {
+        lines.push(`- With extras: ${v.response.status}`);
+      }
+      if (v.followUpGet) {
+        lines.push(`- Follow-up GET → ${v.followUpGet.status}`);
+      }
+      const interesting = v.fields.filter(f => f.outcome !== "ignored" && f.outcome !== "absent");
+      if (interesting.length > 0) {
+        lines.push(`- Per-field outcomes:`);
+        for (const f of interesting) {
+          const obs = f.observed === undefined ? "n/a" : JSON.stringify(f.observed);
+          lines.push(`  - \`${f.field}\` → **${f.outcome}** (injected ${JSON.stringify(f.injected)}, observed ${obs})`);
+        }
+      }
+      if (v.cleanup) {
+        if (v.cleanup.attempted) {
+          lines.push(`- Cleanup DELETE: ${v.cleanup.status ?? "errored"}${v.cleanup.error ? ` — ${v.cleanup.error}` : ""}`);
+        } else {
+          lines.push(`- Cleanup skipped: ${v.cleanup.error ?? "unknown"}`);
+        }
+      }
+      if (v.notes && v.notes.length > 0) {
+        for (const n of v.notes) lines.push(`- Note: ${n}`);
+      }
+      if (v.severity === "high") {
+        lines.push(`- **Action:** treat as P0 — server should reject or strip these fields.`);
+      }
+      if (v.severity === "inconclusive-baseline") {
+        lines.push(
+          `- **Action:** the baseline POST itself failed — set the right fixture / FK / path-params in your env (e.g. \`domain_id\`, \`account_id\`) and re-run.`,
+        );
+      }
+      if (v.severity === "inconclusive-5xx") {
+        lines.push(
+          `- **Action:** baseline crashed with 5xx — fix the underlying server bug (validation-probe likely reported it for the same endpoint) before mass-assignment can be observed here.`,
+        );
+      }
+      lines.push("");
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push(`## Warnings`);
+    lines.push("");
+    for (const w of result.warnings) lines.push(`- ${w}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function groupBySeverity(verdicts: EndpointVerdict[]): Partial<Record<Severity, EndpointVerdict[]>> {
+  return Object.groupBy(verdicts, (v) => v.severity);
+}