@kirrosh/zond 0.22.0 → 0.23.0

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

@@ -0,0 +1,120 @@
+/**
+ * Live probe-runtime primitives shared by mass-assignment and security
+ * probes. TASK-185 (m-11) extracted the static spec/scaffold half into
+ * `runner.ts`; this module covers the per-endpoint primitives that
+ * were still duplicated between the two probe entry points.
+ *
+ * Scope: small, pure helpers — URL building, baseline body generation,
+ * JSON+auth header construction. Cleanup logic is intentionally NOT
+ * unified: mass-assignment uses fire-and-forget DELETE before attacks,
+ * security-probe uses snapshot/restore + retry-aware DELETE after
+ * attacks. Different invariants, different shapes — see TASK-189 notes.
+ */
+
+import type { EndpointInfo, SecuritySchemeInfo } from "../generator/types.ts";
+import { generateFromSchema } from "../generator/data-factory.ts";
+import { substituteDeep, substituteString } from "../parser/variables.ts";
+import { convertPath, liveAuthHeaders } from "./shared.ts";
+import { encodeFormBody } from "../runner/form-encode.ts";
+
+/** ARV-150: form-encoded mutating endpoint (Stripe v1 pattern).
+ *  Stripe and other Rails/PHP APIs declare requestBody.content with ONLY
+ *  application/x-www-form-urlencoded — the probes previously skipped
+ *  every such endpoint, masking real mass-assignment vectors. */
+export function isFormBody(ep: EndpointInfo): boolean {
+  return (
+    ep.requestBodyContentType === "application/x-www-form-urlencoded"
+    && ep.requestBodySchema !== undefined
+  );
+}
+
+/** Probes can drive either application/json or application/x-www-form-urlencoded
+ *  endpoints. Anything else (multipart, octet-stream, …) still gets skipped —
+ *  no general way to construct attack payloads without a body schema. */
+export function hasProbeBody(ep: EndpointInfo): boolean {
+  if (ep.method === "GET" || ep.method === "DELETE") return false;
+  if (!ep.requestBodySchema) return false;
+  return (
+    ep.requestBodyContentType === "application/json"
+    || ep.requestBodyContentType === "application/x-www-form-urlencoded"
+  );
+}
+
+/** Serialise an attack body using whichever content type the endpoint
+ *  declares. Returns the wire-format string + the Content-Type to set. */
+export function serializeProbeBody(
+  ep: EndpointInfo,
+  body: Record<string, unknown>,
+): { content: string; contentType: string } {
+  if (isFormBody(ep)) {
+    return { content: encodeFormBody(body), contentType: "application/x-www-form-urlencoded" };
+  }
+  return { content: JSON.stringify(body), contentType: "application/json" };
+}
+
+/**
+ * Resolve an endpoint's URL against the live `base_url` + path-param
+ * substitutions. Returns the resolved URL and any leftover `{{var}}`
+ * markers the caller couldn't fill — use those to skip the endpoint
+ * with a meaningful reason.
+ */
+export function buildProbeUrl(
+  ep: EndpointInfo,
+  vars: Record<string, string>,
+): { url: string; unresolved: string[] } {
+  const baseUrl = (vars["base_url"] ?? "").replace(/\/+$/, "");
+  const templated = `${baseUrl}${convertPath(ep.path)}`;
+  const url = String(substituteString(templated, vars));
+  const unresolved = Array.from(url.matchAll(/\{\{([^}]+)\}\}/g)).map(m => m[1]!);
+  return { url, unresolved };
+}
+
+/**
+ * Standard probe headers: JSON content-type/accept plus the resolved
+ * auth header for the endpoint. Empty `liveAuthHeaders` is fine — the
+ * spread is a no-op for unauthenticated endpoints.
+ */
+export function buildJsonAuthHeaders(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  vars: Record<string, string>,
+): Record<string, string> {
+  return {
+    "content-type": "application/json",
+    accept: "application/json",
+    ...liveAuthHeaders(ep, schemes, vars),
+  };
+}
+
+/** ARV-150: like buildJsonAuthHeaders but picks the Content-Type from the
+ *  endpoint's spec (form-urlencoded for Stripe v1, JSON otherwise). Accept
+ *  stays JSON — the server still answers in JSON even when the body is
+ *  form-encoded. */
+export function buildBodyAuthHeaders(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  vars: Record<string, string>,
+): Record<string, string> {
+  const ct = isFormBody(ep) ? "application/x-www-form-urlencoded" : "application/json";
+  return {
+    "content-type": ct,
+    accept: "application/json",
+    ...liveAuthHeaders(ep, schemes, vars),
+  };
+}
+
+/**
+ * Synthesize a baseline body from the endpoint's request schema and
+ * substitute live vars. Returns null when the result isn't a JSON
+ * object (array / scalar / null) — both probes treat that as a skip
+ * reason ("request body not a JSON object").
+ */
+export function buildBaselineFromSpec(
+  ep: EndpointInfo,
+  vars: Record<string, string>,
+): Record<string, unknown> | null {
+  const raw = ep.requestBodySchema ? generateFromSchema(ep.requestBodySchema) : {};
+  const sub = substituteDeep(raw, vars);
+  if (typeof sub !== "object" || sub === null || Array.isArray(sub)) return null;
+  return sub as Record<string, unknown>;
+}

package/src/core/probe/registry.ts

@@ -0,0 +1,89 @@
+/**
+ * Probe registry + boot-time validator (m-17 / ARV-49).
+ *
+ * The CLI bootstrap calls `bootstrapProbes()` exactly once — that
+ * function imports each registered probe class and pushes it through
+ * `registerProbe`, which throws if the contract from `types.ts` is
+ * not fully implemented. Boot fails loud with a list of missing slots,
+ * so adding a new probe class without --dry-run / --report support is
+ * impossible (replaces the conventions-then-drift status quo that
+ * produced F1-15 / F2-15 / F3-15 in feedback round 15).
+ */
+import type { Probe, ProbeFlags } from "./types.ts";
+
+const REQUIRED_METHODS: Array<keyof Probe> = ["dryRun", "run", "report"];
+const REQUIRED_FLAGS: Array<keyof ProbeFlags> = [
+  "api",
+  "tag",
+  "include",
+  "exclude",
+  "dryRun",
+  "listTags",
+  "json",
+  "output",
+  "report",
+];
+
+export interface ValidationResult {
+  ok: boolean;
+  errors: string[];
+}
+
+/** Pure validator — used by both `registerProbe` and the contract test
+ *  in `tests/contracts/probe-interface.test.ts`. */
+export function validateProbe(p: unknown): ValidationResult {
+  const errors: string[] = [];
+  if (p === null || typeof p !== "object") {
+    return { ok: false, errors: ["Probe is not an object"] };
+  }
+  const probe = p as Partial<Probe>;
+  const label = probe.name ?? "<anonymous>";
+  if (typeof probe.name !== "string" || probe.name.length === 0) {
+    errors.push("Probe is missing required field name");
+  }
+  if (typeof probe.description !== "string" || probe.description.length === 0) {
+    errors.push(`Probe "${label}" is missing required field description`);
+  }
+  for (const m of REQUIRED_METHODS) {
+    if (typeof (probe as Record<string, unknown>)[m] !== "function") {
+      errors.push(`Probe "${label}" is missing required method ${m}`);
+    }
+  }
+  if (probe.commonFlags === undefined || probe.commonFlags === null || typeof probe.commonFlags !== "object") {
+    errors.push(`Probe "${label}" is missing required field commonFlags`);
+  } else {
+    const flags = probe.commonFlags as unknown as Record<string, unknown>;
+    for (const f of REQUIRED_FLAGS) {
+      const v = flags[f as string];
+      if (typeof v !== "boolean") {
+        errors.push(`Probe "${label}" commonFlags is missing slot ${f} (must be boolean)`);
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+const PROBES = new Map<string, Probe>();
+
+export function registerProbe(probe: Probe): void {
+  const r = validateProbe(probe);
+  if (!r.ok) {
+    throw new Error(
+      `Invalid probe registration:\n  - ${r.errors.join("\n  - ")}`,
+    );
+  }
+  if (PROBES.has(probe.name)) {
+    throw new Error(`Probe "${probe.name}" is already registered`);
+  }
+  PROBES.set(probe.name, probe);
+}
+
+export function listProbes(): readonly Probe[] {
+  return Array.from(PROBES.values());
+}
+
+/** Test helper — wipes the registry between unit tests. NOT exported
+ *  through `index.ts`; tests import this module directly. */
+export function clearProbes(): void {
+  PROBES.clear();
+}

package/src/core/probe/runner.ts

@@ -0,0 +1,136 @@
+/**
+ * Shared scaffolding for the four probe commands (`probe validation`,
+ * `probe methods`, `probe mass-assignment`, `probe security`).
+ *
+ * Each command historically duplicated the same boilerplate: read the
+ * spec, optionally filter by tag, mkdir the output dir, write the
+ * generated suites with an autogen header, and record them in the
+ * workspace manifest. This module collapses that scaffolding into two
+ * helpers (`loadSpecForProbe` / `writeProbeSuites`) so the cli layer
+ * stays thin.
+ *
+ * Live-runner commands (`mass-assignment`, `security`) reuse the
+ * write-suites half for their `--emit-tests` flag; the actual HTTP
+ * orchestration lives in `mass-assignment-probe.ts` /
+ * `security-probe.ts`.
+ *
+ * Goals are documented in TASK-185 (m-11).
+ */
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  serializeSuite,
+} from "../generator/index.ts";
+import type { EndpointInfo, SecuritySchemeInfo, RawSuite } from "../generator/index.ts";
+import { collectTags, filterByTag } from "../generator/chunker.ts";
+import {
+  recordGeneratedFiles,
+  inferApiName,
+  autoGenHeader,
+  type RecordInput,
+} from "../workspace/manifest.ts";
+import { findWorkspaceRoot } from "../workspace/root.ts";
+
+export interface LoadSpecForProbeOptions {
+  specPath: string;
+  tag?: string;
+  /** When true, the caller wants the available-tags list, not endpoints. */
+  listTags?: boolean;
+}
+
+export type LoadSpecResult =
+  | { kind: "endpoints"; endpoints: EndpointInfo[]; securitySchemes: SecuritySchemeInfo[] }
+  | { kind: "tags"; tags: string[] }
+  | { kind: "tag-not-found"; tag: string; available: string[] };
+
+/**
+ * Read the spec, optionally filter by tag, and surface either the
+ * filtered endpoints or the list of available tags. Centralises the
+ * tag-not-found error path so probe commands all produce identical
+ * messaging.
+ */
+export async function loadSpecForProbe(opts: LoadSpecForProbeOptions): Promise<LoadSpecResult> {
+  const doc = await readOpenApiSpec(opts.specPath);
+  const allEndpoints = extractEndpoints(doc);
+  const securitySchemes = extractSecuritySchemes(doc);
+
+  if (opts.listTags) {
+    return { kind: "tags", tags: collectTags(allEndpoints) };
+  }
+
+  if (opts.tag) {
+    const filtered = filterByTag(allEndpoints, opts.tag);
+    if (filtered.length === 0) {
+      return { kind: "tag-not-found", tag: opts.tag, available: collectTags(allEndpoints) };
+    }
+    return { kind: "endpoints", endpoints: filtered, securitySchemes };
+  }
+
+  return { kind: "endpoints", endpoints: allEndpoints, securitySchemes };
+}
+
+export interface WriteProbeSuitesOptions {
+  /** Directory to write suites into. Created recursively if missing. */
+  output: string;
+  /** Suites produced by the underlying probe generator. */
+  suites: RawSuite[];
+  /** Manifest `by` field — e.g. `"zond probe-methods --emit"`. */
+  command: string;
+  /** First arg of `autoGenHeader` (label). Defaults to `command`. */
+  headerLabel?: string;
+  /** Concrete repro command shown in the autogen header. */
+  headerExample?: string;
+  /** Manifest category (defaults to `"probes"`). */
+  category?: RecordInput["category"];
+}
+
+export interface WroteProbeSuites {
+  files: Array<{ file: string; suite: string; tests: number }>;
+}
+
+/**
+ * Materialise generator output to disk and register the files in the
+ * workspace manifest. Safe on empty input — returns an empty result and
+ * avoids creating an empty directory (m-9 P5).
+ */
+export async function writeProbeSuites(
+  opts: WriteProbeSuitesOptions,
+): Promise<WroteProbeSuites> {
+  if (opts.suites.length === 0) return { files: [] };
+
+  await mkdir(opts.output, { recursive: true });
+
+  const files: WroteProbeSuites["files"] = [];
+  const manifestEntries: RecordInput[] = [];
+  const inferredApi = inferApiName(opts.output);
+  const headerLabel = opts.headerLabel ?? opts.command;
+  const headerExample = opts.headerExample ?? opts.command;
+
+  for (const suite of opts.suites) {
+    const fileName = `${suite.fileStem ?? suite.name}.yaml`;
+    const filePath = join(opts.output, fileName);
+    await Bun.write(filePath, autoGenHeader(headerLabel, headerExample) + serializeSuite(suite));
+    files.push({ file: filePath, suite: suite.name, tests: suite.tests.length });
+    manifestEntries.push({
+      path: filePath,
+      by: opts.command,
+      api: inferredApi,
+      category: opts.category ?? "probes",
+    });
+  }
+
+  try {
+    const ws = findWorkspaceRoot();
+    if (!ws.fromFallback && manifestEntries.length > 0) {
+      recordGeneratedFiles(ws.root, manifestEntries);
+    }
+  } catch {
+    /* best-effort: manifest is observability, never fail probe emit on it */
+  }
+
+  return { files };
+}

package/src/core/probe/security-probe-class.ts

@@ -0,0 +1,201 @@
+/**
+ * `SecurityProbe` — Probe-contract wrapper around the existing
+ * `runSecurityProbes` engine in `security-probe.ts` (m-17 / ARV-49).
+ *
+ * Behavior is unchanged on this step. dryRun() returns the structured
+ * EndpointPlan[] shape (used by the new dry-run envelope in ARV-50);
+ * run() delegates to runSecurityProbes(); report() is a thin renderer
+ * that converts the SecurityProbeResult to either a markdown digest
+ * (existing formatter) or the structured per-endpoint shape (ARV-51).
+ */
+import type { Probe, ProbeContext, ProbeFlags, EndpointPlan, ProbeResult, ProbeReportFormat, ProbeEndpointResult, ProbeEndpointStatus } from "./types.ts";
+import {
+  runSecurityProbes,
+  formatSecurityDigest,
+  detectFields,
+  SECURITY_CLASSES,
+  type SecurityClass,
+  type SecurityProbeResult,
+  type SecurityVerdict,
+} from "./security-probe.ts";
+import { hasJsonBody, pathTouchesSeededVar } from "./shared.ts";
+
+const FLAGS: ProbeFlags = {
+  api: true,
+  tag: true,
+  include: true,
+  exclude: true,
+  dryRun: true,
+  listTags: true,
+  json: true,
+  output: true,
+  report: true,
+};
+
+function planForSecurity(
+  ctx: ProbeContext,
+  classes: SecurityClass[],
+  isolated: boolean,
+): EndpointPlan[] {
+  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;
+    }
+
+    if (!hasJsonBody(ep)) {
+      out.push({
+        path: ep.path,
+        method: m,
+        planned: false,
+        classes_planned: [],
+        fields_planned: [],
+        skip_reason: "no-body",
+      });
+      continue;
+    }
+
+    const detected = detectFields(ep, classes);
+    if (detected.length === 0) {
+      out.push({
+        path: ep.path,
+        method: m,
+        planned: false,
+        classes_planned: [],
+        fields_planned: [],
+        skip_reason: "no-matched-field",
+      });
+      continue;
+    }
+
+    const classesPlanned = Array.from(new Set(detected.map((d) => d.class)));
+    const fieldsPlanned = Array.from(new Set(detected.map((d) => d.field)));
+    out.push({
+      path: ep.path,
+      method: m,
+      planned: true,
+      classes_planned: classesPlanned,
+      fields_planned: fieldsPlanned,
+      skip_reason: null,
+    });
+  }
+  return out;
+}
+
+function statusFromSeverity(s: SecurityVerdict["severity"]): ProbeEndpointStatus {
+  if (s === "high") return "high";
+  if (s === "low") return "low";
+  if (s === "ok") return "ok";
+  if (s === "skipped") return "skipped";
+  return "inconclusive";
+}
+
+function evidenceFromFinding(f: SecurityVerdict["findings"][number]): Record<string, unknown> {
+  return {
+    field: f.field,
+    payload: f.payload,
+    status: f.status,
+    echoed: f.echoed,
+    reason: f.reason,
+    ...(f.recommended_action ? { recommended_action: f.recommended_action } : {}),
+  };
+}
+
+function toProbeResult(sec: SecurityProbeResult): ProbeResult {
+  const endpoints: ProbeEndpointResult[] = sec.verdicts.map((v) => ({
+    path: v.path,
+    method: v.method,
+    classes_run: Array.from(new Set(v.detectedFields.map((d) => d.class))),
+    findings: v.findings.map((f) => ({
+      class: f.class,
+      severity:
+        f.severity === "inconclusive" || f.severity === "inconclusive-baseline"
+          ? "inconclusive"
+          : f.severity === "skipped"
+          ? "ok"
+          : f.severity === "info"
+          // ARV-253: ProbeFindingSeverity has no "info" tier. Collapse
+          // info → low for the public probe-result envelope; the digest
+          // / structured per-endpoint shape preserves the distinction.
+          ? "low"
+          : f.severity === "medium"
+          // ARV-254: ProbeFindingSeverity has no "medium" tier — collapse
+          // to "low" for the wire shape. MEDIUM is a digest-only severity
+          // marker (SSRF accept on endpoint declaring delivery, no OOB);
+          // by design it must NOT gate CI as a HIGH would.
+          ? "low"
+          : f.severity,
+      evidence: evidenceFromFinding(f),
+    })),
+    status: statusFromSeverity(v.severity),
+    ...(v.skipReason ? { skip_reason: v.skipReason } : {}),
+  }));
+  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: sec.totalEndpoints,
+      probed: sec.specProbed,
+      by_status,
+    },
+    warnings: sec.warnings,
+  };
+}
+
+export class SecurityProbe implements Probe {
+  readonly name = "security";
+  readonly description =
+    "Live security probes: SSRF / CRLF / open-redirect. Spec-driven field detection + baseline-OK gate.";
+  readonly commonFlags = FLAGS;
+
+  async dryRun(ctx: ProbeContext): Promise<EndpointPlan[]> {
+    const classes = (ctx.classes ?? SECURITY_CLASSES) as SecurityClass[];
+    const isolated = ctx.options["isolated"] === true;
+    return planForSecurity(ctx, classes, isolated);
+  }
+
+  async run(ctx: ProbeContext): Promise<ProbeResult> {
+    const classes = (ctx.classes ?? SECURITY_CLASSES) as SecurityClass[];
+    const sec = await runSecurityProbes({
+      endpoints: ctx.endpoints,
+      securitySchemes: ctx.securitySchemes,
+      vars: ctx.vars,
+      classes,
+      noCleanup: ctx.options["noCleanup"] === true,
+      timeoutMs: typeof ctx.options["timeoutMs"] === "number" ? (ctx.options["timeoutMs"] as number) : undefined,
+      isolated: ctx.options["isolated"] === true,
+    });
+    const result = toProbeResult(sec);
+    // Pass through the raw sec result for legacy markdown rendering and
+    // for orphan-tracker consumers that need the full SecurityVerdict[].
+    result.extras = { raw: sec };
+    return result;
+  }
+
+  report(format: ProbeReportFormat, result: ProbeResult): string | object {
+    if (format === "markdown") {
+      const raw = (result.extras?.["raw"] as SecurityProbeResult | undefined);
+      if (raw) return formatSecurityDigest(raw, "");
+      return "(no markdown digest available)";
+    }
+    return {
+      endpoints: result.endpoints,
+      summary: result.summary,
+    };
+  }
+}