@kirrosh/zond 0.21.0 → 0.23.0

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

@@ -0,0 +1,212 @@
+/**
+ * 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;
+}
+
+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[] = [];
+
+  tests.push({
+    name: "create with privileged fields",
+    [create.method.toUpperCase()]: create.path,
+    json: privilegedBody,
+    expect: { status: [200, 201], body: { id: { capture: idVar } } },
+  } 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") 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";
+}

package/src/core/probe/method-probe.ts

@@ -0,0 +1,164 @@
+/**
+ * HTTP method completeness probe (T48).
+ *
+ * Goal: catch the class of bugs where an API responds to *unsupported* HTTP
+ * methods with anything other than 405 / 404. A 500 here means an unhandled
+ * exception in the routing layer; a 200/201 means a forgotten or shadowed
+ * route; both are bug candidates.
+ *
+ * For every path declared in the spec, we look at which of {GET, POST, PUT,
+ * PATCH, DELETE} are *not* declared and emit one probe step per missing
+ * method. Each probe expects status in [404, 405, 401, 403] — anything else
+ * (notably 5xx, 200, 201) is a regular test failure surfaced via the
+ * existing runner / reporter / `zond db diagnose` flow.
+ *
+ * The probes are deterministic — same spec → same suites — so the generated
+ * YAML can be committed as a regression test.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { EndpointInfo, SecuritySchemeInfo } from "../generator/types.ts";
+import type { RawSuite, RawStep } from "../generator/serializer.ts";
+import { pathWithByAliases, getAuthHeaders } from "./shared.ts";
+import {
+  ALL_METHODS,
+  ACCEPTABLE_UNSUPPORTED_STATUSES,
+  bucketEndpointsByPath,
+  pathWithMethodPlaceholders,
+  type Method,
+} from "./method-shared.ts";
+
+// 405-or-equivalent statuses for an *undeclared* method probe. ARV-2
+// (m-15) extracted this list to method-shared.ts so the live
+// `unsupported_method` check stays in lock-step with the offline probe.
+const ACCEPTABLE_STATUSES = [...ACCEPTABLE_UNSUPPORTED_STATUSES];
+
+// ──────────────────────────────────────────────
+// Types
+// ──────────────────────────────────────────────
+
+export interface MethodProbeOptions {
+  endpoints: EndpointInfo[];
+  securitySchemes: SecuritySchemeInfo[];
+}
+
+export interface MethodProbeResult {
+  suites: RawSuite[];
+  /** Number of distinct paths probed. */
+  probedPaths: number;
+  /** Paths skipped because every method in {GET,POST,PUT,PATCH,DELETE} is declared. */
+  skippedPaths: number;
+  /** Total generated probe steps. */
+  totalProbes: number;
+}
+
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+
+function convertPath(path: string): string {
+  return path.replace(/\{([^}]+)\}/g, "{{$1}}");
+}
+
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function pathStem(path: string): string {
+  // TASK-159 (m-9 P3): preserve placeholder name (`by-org`, `by-proj`)
+  // instead of collapsing every `{x}` to a generic `by-id`.
+  const cleaned = pathWithByAliases(path)
+    .replace(/^\//, "")
+    .replace(/\//g, "-");
+  return slugify(cleaned) || "root";
+}
+
+// pathWithPlaceholders + bucketByPath moved to ./method-shared.ts for
+// reuse by the live `unsupported_method` check (m-15 ARV-2).
+const pathWithPlaceholders = pathWithMethodPlaceholders;
+const bucketByPath = (endpoints: EndpointInfo[]): Array<{
+  path: string;
+  declared: Set<string>;
+  sample: EndpointInfo;
+}> => Array.from(bucketEndpointsByPath(endpoints).values());
+
+// ──────────────────────────────────────────────
+// Public API
+// ──────────────────────────────────────────────
+
+export function generateMethodProbes(opts: MethodProbeOptions): MethodProbeResult {
+  const { endpoints, securitySchemes } = opts;
+  const methodSet: readonly Method[] = ALL_METHODS;
+
+  const buckets = bucketByPath(endpoints);
+  const suites: RawSuite[] = [];
+  let probedPaths = 0;
+  let skippedPaths = 0;
+  let totalProbes = 0;
+
+  for (const bucket of buckets) {
+    const missing = methodSet.filter((m) => !bucket.declared.has(m));
+    if (missing.length === 0) {
+      skippedPaths++;
+      continue;
+    }
+
+    const concretePath = pathWithPlaceholders(
+      bucket.path,
+      bucket.sample.parameters,
+    );
+    const headers = getAuthHeaders(bucket.sample, securitySchemes);
+
+    const steps: RawStep[] = missing.map((method) => {
+      // ARV-179: OPTIONS on an undeclared path is legitimately handled
+      // by most stacks (CORS preflight, 200/204 with Allow header). Let
+      // the probe accept 2xx for OPTIONS only; everything else keeps
+      // the strict "no 2xx, no 5xx" expectation.
+      const acceptable = method === "OPTIONS"
+        ? [200, 204, ...ACCEPTABLE_STATUSES]
+        : ACCEPTABLE_STATUSES;
+      const expectLabel = method === "OPTIONS"
+        ? `${method} ${bucket.path} — undeclared method must not 5xx (OPTIONS may legitimately succeed)`
+        : `${method} ${bucket.path} — undeclared method must reject (no 5xx, no 2xx)`;
+      const step: RawStep = {
+        name: expectLabel,
+        source: {
+          generator: "method-probe",
+          endpoint: `${method} ${bucket.path}`,
+          response_branch: acceptable.map(String).join("|"),
+        },
+        [method]: convertPath(concretePath),
+        expect: { status: acceptable },
+      };
+      // Body-bearing methods on an undeclared route — send a minimal valid
+      // JSON object to provoke any body-parsing path while the router is
+      // still expected to reject the method first.
+      if (method === "POST" || method === "PUT" || method === "PATCH") {
+        (step as any).json = {};
+      }
+      return step;
+    });
+
+    probedPaths++;
+    totalProbes += steps.length;
+
+    const stem = pathStem(bucket.path);
+    suites.push({
+      name: `probe methods ${bucket.path}`,
+      tags: ["probe-methods", "negative-method", "no-5xx", "smoke"],
+      source: {
+        type: "probe-suite",
+        generator: "method-probe",
+        endpoint: bucket.path,
+      },
+      fileStem: `probe-methods-${stem}`,
+      base_url: "{{base_url}}",
+      ...(headers ? { headers } : {}),
+      tests: steps,
+    });
+  }
+
+  return { suites, probedPaths, skippedPaths, totalProbes };
+}

package/src/core/probe/method-shared.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared bits between the offline `method-probe` (which emits YAML
+ * suites) and the live `unsupported_method` check from `core/checks`
+ * (m-15 ARV-2). Both ask the same question — "which HTTP methods aren't
+ * declared on this path?" — so the constants and helpers live here so
+ * the two stay in lock-step (ARV-2 AC #4).
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { EndpointInfo } from "../generator/types.ts";
+
+/** ARV-179: full HTTP method complement used for `unsupported_method`
+ *  enumeration. Matches schemathesis V4 `DEFAULT_UNEXPECTED_METHODS`
+ *  minus the WebDAV-style `query` (not a REST norm) and `CONNECT`
+ *  (irrelevant to API routing). `HEAD` is intentionally excluded
+ *  because most stacks auto-derive it from `GET`, so a 2xx response is
+ *  expected behaviour rather than a leak. */
+export const ALL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "TRACE"] as const;
+export type Method = (typeof ALL_METHODS)[number];
+
+/** Statuses we accept for an *undeclared* method on a path. 405 is
+ *  canonical, 404 is a common fallback (path not registered for that
+ *  method), 401/403 are acceptable when auth is checked before routing. */
+export const ACCEPTABLE_UNSUPPORTED_STATUSES = [401, 403, 404, 405] as const;
+
+/** ARV-179: OPTIONS is special — it's legitimately implemented by most
+ *  stacks for CORS preflight and may legitimately return 2xx with
+ *  `Allow`/`Access-Control-*` headers. A 2xx OPTIONS on an undeclared
+ *  path is the spec-compliant outcome, not a finding. Use this helper
+ *  in both the offline probe and the live check to keep the policy in
+ *  one place. */
+export function isPermissibleOptionsResponse(method: string, status: number): boolean {
+  return method.toUpperCase() === "OPTIONS" && status >= 200 && status < 300;
+}
+
+/**
+ * Replace `{name}` segments with valid-shape placeholders so the
+ * request can reach the routing layer without being rejected purely on
+ * path syntax. Used by both the offline probe and the live check.
+ */
+export function pathWithMethodPlaceholders(
+  path: string,
+  parameters: OpenAPIV3.ParameterObject[],
+): string {
+  return path.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    const param = parameters.find((p) => p.name === name && p.in === "path");
+    const schema = param?.schema as OpenAPIV3.SchemaObject | undefined;
+    if (schema?.format === "uuid") return "00000000-0000-0000-0000-000000000000";
+    if (schema?.type === "integer" || schema?.type === "number") return "999999999";
+    return "nonexistent-zzzzz";
+  });
+}
+
+export function bucketEndpointsByPath(endpoints: EndpointInfo[]): Map<string, {
+  path: string;
+  declared: Set<string>;
+  sample: EndpointInfo;
+}> {
+  const map = new Map<string, { path: string; declared: Set<string>; sample: EndpointInfo }>();
+  for (const ep of endpoints) {
+    if (ep.deprecated) continue;
+    let bucket = map.get(ep.path);
+    if (!bucket) {
+      bucket = { path: ep.path, declared: new Set(), sample: ep };
+      map.set(ep.path, bucket);
+    }
+    bucket.declared.add(ep.method.toUpperCase());
+  }
+  return map;
+}