@kirrosh/zond 0.23.0 → 0.26.0

package/src/core/probe/security/cleanup.ts

@@ -0,0 +1,125 @@
+import type { EndpointInfo, SecuritySchemeInfo } from "../../generator/types.ts";
+import { executeRequest } from "../../runner/http-client.ts";
+import {
+  captureFieldFor,
+  findDeleteCounterpart,
+  liveAuthHeaders,
+} from "../shared.ts";
+import type { ProbeStepOpts, SecurityVerdict } from "./types.ts";
+import { joinBaseAndPath } from "../../util/url.ts";
+
+/**
+ * Best-effort DELETE on stateful endpoints after a successful baseline /
+ * attack. Handles eventual-consistency retries (round-5) and persists
+ * id/deletePath on the verdict so `zond cleanup --orphans` can replay
+ * the DELETE without re-running the probe.
+ */
+export async function tryCleanup(
+  ep: EndpointInfo,
+  allEndpoints: EndpointInfo[],
+  schemes: SecuritySchemeInfo[],
+  vars: Record<string, string>,
+  responseBody: unknown,
+  verdict: SecurityVerdict,
+  opts: ProbeStepOpts,
+): Promise<void> {
+  const delEp = findDeleteCounterpart(ep, allEndpoints);
+  if (!delEp) {
+    // Surface the gap. Round-4 dogfooding: 3 DSN keys leaked from
+    // POST /keys/ silently because the spec didn't expose a DELETE
+    // counterpart — flagging it in the digest gives the operator a
+    // chance to clean up by hand instead of finding out later.
+    accumulateCleanupError(verdict, `no DELETE counterpart for ${ep.method.toUpperCase()} ${ep.path}; possible leaked resource`);
+    return;
+  }
+  const idField = captureFieldFor(ep);
+  const id = pickId(responseBody, idField);
+  if (!id) {
+    accumulateCleanupError(verdict, `cleanup skipped: response had no usable id for ${ep.method.toUpperCase()} ${ep.path}`);
+    return;
+  }
+  // DELETE path has one path-param at the end; replace it with the captured id.
+  const concretePath = delEp.path.replace(/\{[^}]+\}/, encodeURIComponent(String(id)));
+  const url = joinBaseAndPath(vars["base_url"], concretePath);
+  const headers = liveAuthHeaders(delEp, schemes, vars);
+
+  // TASK-278: stash id + deletePath on the verdict so the orphan tracker
+  // (and `zond cleanup --orphans`) can replay this DELETE without re-running
+  // the probe. Done before retries so even an aborted run leaves a trace.
+  {
+    const prior = verdict.cleanup ?? { attempted: false };
+    verdict.cleanup = {
+      ...prior,
+      attempted: prior.attempted || true,
+      id,
+      deletePath: concretePath,
+    };
+  }
+
+  // Eventual-consistency retry (round-5 follow-up): POST creates on the
+  // write replica, immediate DELETE hits a read replica that hasn't seen
+  // the new id yet → 404. Two short backoffs swallow that transient
+  // 404; a 404 that survives the backoff is a real leak and lands in
+  // verdict.cleanup.error. Only 404 is retried — 5xx, network errors,
+  // 401/403 fail fast (the situation isn't going to improve).
+  const RETRY_DELAYS_MS = opts.cleanupRetryDelaysMs ?? [200, 1000];
+  let lastResp: { status: number } | null = null;
+  let lastNetErr: string | null = null;
+  for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
+    if (attempt > 0) await new Promise(r => setTimeout(r, RETRY_DELAYS_MS[attempt - 1]!));
+    try {
+      const resp = await executeRequest(
+        { method: "DELETE", url, headers },
+        { timeout: opts.timeoutMs ?? 30000, retries: 0 },
+      );
+      lastResp = { status: resp.status };
+      if (resp.status >= 200 && resp.status < 300) {
+        const prior = verdict.cleanup ?? { attempted: false };
+        verdict.cleanup = {
+          attempted: true,
+          status: resp.status,
+          ...(prior.error ? { error: prior.error } : {}),
+          ...(prior.id !== undefined ? { id: prior.id } : {}),
+          ...(prior.deletePath ? { deletePath: prior.deletePath } : {}),
+        };
+        return;
+      }
+      // Only retry transient 404 (eventual-consistency window).
+      if (resp.status !== 404) break;
+    } catch (err) {
+      lastNetErr = err instanceof Error ? err.message : String(err);
+      // Network errors are not retried — they're not transient in the
+      // eventual-consistency sense (they're config/connectivity issues).
+      break;
+    }
+  }
+
+  if (lastNetErr) {
+    accumulateCleanupError(verdict, `DELETE ${delEp.path} network error: ${lastNetErr}`);
+  } else if (lastResp) {
+    const tail = lastResp.status === 404 ? " (persisted across retries — likely real leak)" : "";
+    accumulateCleanupError(verdict, `DELETE ${delEp.path} → ${lastResp.status} (id=${id})${tail}`);
+  }
+}
+
+function accumulateCleanupError(verdict: SecurityVerdict, msg: string): void {
+  const prior = verdict.cleanup ?? { attempted: false };
+  const errors = prior.error ? `${prior.error} | ${msg}` : msg;
+  verdict.cleanup = {
+    attempted: true,
+    ...(prior.status ? { status: prior.status } : {}),
+    ...(prior.id !== undefined ? { id: prior.id } : {}),
+    ...(prior.deletePath ? { deletePath: prior.deletePath } : {}),
+    error: errors,
+  };
+}
+
+function pickId(body: unknown, field: string): string | number | undefined {
+  if (!body || typeof body !== "object") return undefined;
+  const obj = body as Record<string, unknown>;
+  for (const key of [field, "id", "slug", "uuid", "key"]) {
+    const v = obj[key];
+    if (typeof v === "string" || typeof v === "number") return v;
+  }
+  return undefined;
+}

package/src/core/probe/security/detectors.ts

@@ -0,0 +1,71 @@
+import type { OpenAPIV3 } from "openapi-types";
+import type { EndpointInfo } from "../../generator/types.ts";
+import type { SecurityClass, SecurityFieldHit } from "./types.ts";
+
+// ARV-310: SSRF only targets URL-shaped field names — url / *_url / *_uri /
+// href / endpoint. Dropped the unanchored `webhook` / `callback` substrings
+// that matched free-text fields (e.g. `callback_message`, and grouped
+// `description` hits) which are not request-forgeable sinks. Schema
+// format=uri|url still qualifies a field regardless of name.
+const SSRF_NAME_RE =
+  /(url$|uri$|^href$|^endpoint$)/i;
+// ARV-310: CRLF targets header-reflected / redirect-shaped fields (email
+// Subject, log prefix, redirect targets), NOT free-text body fields. Dropped
+// `^name$` / `^title$` / `^description$` / `^tag$` — those are not header
+// sinks and produced the bulk of the GitHub-scan false positives
+// (name ×37, name,description ×22, title ×9).
+const CRLF_NAME_RE =
+  /(^subject$|^message_subject$|prefix$|^location$|^redirect$)/i;
+const OPEN_REDIRECT_NAME_RE =
+  /(^redirect$|^next$|^return_to$|^redirect_url$|^redirect_to$|^redirectTo$)/i;
+
+function matchesClass(
+  cls: SecurityClass,
+  name: string,
+  schema: OpenAPIV3.SchemaObject,
+): boolean {
+  // Skip enum-bounded fields — payload would obviously fail validation
+  // and we'd just waste requests on guaranteed-4xx attempts.
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) return false;
+  if (schema.type !== "string" && schema.type !== undefined) return false;
+  switch (cls) {
+    case "ssrf":
+      return SSRF_NAME_RE.test(name) || schema.format === "uri" || schema.format === "url";
+    case "crlf":
+      return CRLF_NAME_RE.test(name);
+    case "open-redirect":
+      return OPEN_REDIRECT_NAME_RE.test(name);
+  }
+}
+
+export function detectFields(
+  ep: EndpointInfo,
+  classes: SecurityClass[],
+): SecurityFieldHit[] {
+  const out: SecurityFieldHit[] = [];
+  const schema = ep.requestBodySchema;
+  if (!schema || !schema.properties) return out;
+  for (const [name, propSchema] of Object.entries(schema.properties)) {
+    const s = propSchema as OpenAPIV3.SchemaObject;
+    for (const cls of classes) {
+      if (matchesClass(cls, name, s)) out.push({ field: name, class: cls });
+    }
+  }
+  return out;
+}
+
+export const PAYLOADS: Record<SecurityClass, string[]> = {
+  ssrf: [
+    "http://127.0.0.1:80/",
+    "http://169.254.169.254/latest/meta-data/",
+    "file:///etc/passwd",
+  ],
+  crlf: [
+    "zond-safe\r\nX-Zond-Injected: yes",
+    "zond-safe%0d%0aX-Zond-Injected: yes",
+  ],
+  "open-redirect": [
+    "https://zond-attacker.example.tld",
+    "//zond-attacker.example.tld",
+  ],
+};

package/src/core/probe/security/digest.ts

@@ -0,0 +1,104 @@
+import type {
+  SecurityProbeResult,
+  SecuritySeverity,
+  SecurityVerdict,
+} from "./types.ts";
+import { encodePathForRepro } from "../shared.ts";
+
+/** TASK-154 §N: clip noisy payloads (some SSRF/CRLF/redirect strings are URL-
+ *  encoded blobs > 60 chars). Keep the leading prefix users recognise plus an
+ *  ellipsis, so the digest line stays readable. */
+function truncatePayload(payload: string, max: number): string {
+  if (payload.length <= max) return payload;
+  return payload.slice(0, max - 1) + "…";
+}
+
+export function formatSecurityDigest(
+  result: SecurityProbeResult,
+  specPath: string,
+): string {
+  const lines: string[] = [];
+  lines.push(`# zond probe-security digest`);
+  lines.push("");
+  lines.push(`Spec: \`${specPath}\``);
+  lines.push(`Classes: ${result.classes.join(", ")}`);
+  lines.push(`Endpoints scanned: ${result.totalEndpoints} · probed: ${result.specProbed}`);
+  // ARV-140 AC#4: surface the cleanup-feasibility outcome up front so a
+  // green run doesn't hide "we attacked 14 leak-prone POSTs anyway".
+  if (result.cleanupFeasibility) {
+    const f = result.cleanupFeasibility;
+    if (f.skippedNoCleanup > 0) {
+      lines.push(`Cleanup pre-flight: ${f.skippedNoCleanup} endpoint(s) skipped (no DELETE counterpart). Pass \`--allow-leaks\` to attack anyway.`);
+    } else if (f.forcedNoCleanup > 0) {
+      lines.push(`Cleanup pre-flight: ${f.forcedNoCleanup} endpoint(s) attacked despite no DELETE counterpart (--allow-leaks).`);
+    }
+    // ARV-153: surface action-verb POSTs we now attack without a DELETE
+    // counterpart so green runs make the recall win visible.
+    if (f.actionNoCleanupNeeded > 0) {
+      lines.push(`Cleanup pre-flight: ${f.actionNoCleanupNeeded} action POST(s) attacked (no resource created — DELETE counterpart not needed).`);
+    }
+  }
+  lines.push("");
+
+  // Cleanup failures section is mandatory and goes FIRST when present —
+  // round-4 dogfooding: a "green" run (HIGH=0) silently leaked DSN keys
+  // and left renamed projects, because cleanup failures were buried in
+  // per-verdict objects. Surface them prominently so a green probe is a
+  // signal the org is clean, not just that nothing crashed.
+  const cleanupFailures = result.verdicts.filter(v => v.cleanup?.error);
+  if (cleanupFailures.length > 0) {
+    lines.push(`## ⚠️ Cleanup failures (${cleanupFailures.length}) — manual remediation may be required`);
+    lines.push("");
+    for (const v of cleanupFailures) {
+      lines.push(`- **${v.method} ${v.path}** — ${v.cleanup!.error}`);
+      // ARV-245 (R-04/F16): paste-ready manual repro when we have a
+      // deletePath. Auto-encode the path so operators dealing with
+      // CRLF-poisoned ids (round-4 GitHub labels) don't have to remember
+      // to percent-encode `\r`/`\n`/spaces themselves.
+      const dp = v.cleanup?.deletePath;
+      if (dp) {
+        const encoded = encodePathForRepro(dp);
+        const note = /[\r\n\t ]/.test(dp) ? " (note: id contains whitespace/CRLF — percent-encoded)" : "";
+        lines.push(`  - Manual repro: \`zond request DELETE ${encoded} --api <name>\`${note}`);
+      }
+    }
+    lines.push("");
+  }
+
+  const buckets: Record<SecuritySeverity, SecurityVerdict[]> = {
+    high: [], medium: [], low: [], info: [], inconclusive: [], "inconclusive-baseline": [], ok: [], skipped: [],
+  };
+  for (const v of result.verdicts) buckets[v.severity].push(v);
+
+  const ordered: SecuritySeverity[] = ["high", "inconclusive", "inconclusive-baseline", "medium", "low", "info", "ok", "skipped"];
+  const titles: Record<SecuritySeverity, string> = {
+    high: "🚨 HIGH — header-reflection / HTML reflection / 5xx",
+    medium: "⚠️ MEDIUM — SSRF accept on endpoint declaring delivery (no OOB confirmation)",
+    low: "🟡 LOW — storage observed, no dangerous-context reflection (verify manually)",
+    info: "·  INFO — accepted, no reflection observed (sanitization signal only)",
+    inconclusive: "❓ INCONCLUSIVE — could not classify",
+    "inconclusive-baseline": "⚠️ INCONCLUSIVE-BASELINE — baseline 4xx, attacks not run",
+    ok: "✅ OK — payloads rejected with 4xx",
+    skipped: "⏭️ SKIPPED — no detected fields / no body",
+  };
+  for (const sev of ordered) {
+    const list = buckets[sev];
+    if (list.length === 0) continue;
+    lines.push(`## ${titles[sev]} (${list.length})`);
+    lines.push("");
+    for (const v of list) {
+      const cleanupTag = v.cleanup?.error ? " 🧹 cleanup-failure" : "";
+      lines.push(`- **${v.method} ${v.path}**${cleanupTag} — ${v.summary}`);
+      for (const f of v.findings) {
+        // TASK-154 §N: surface the actual payload that triggered the finding
+        // — without it the digest is useless for case-study writing (which
+        // SSRF target? which CRLF shape?). Truncate long payloads so the
+        // line stays readable.
+        const payload = truncatePayload(f.payload, 60);
+        lines.push(`  - \`${f.field}\` / ${f.class} [\`${payload}\`] → ${f.status} (${f.severity}) — ${f.reason}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}