@kirrosh/zond 0.26.0 → 0.27.0

package/src/core/probe/types.ts

@@ -1,165 +0,0 @@
-/**
- * Probe contract (m-17 / ARV-49).
- *
- * `zond probe <class>` originally grew as three independent commands —
- * static, mass-assignment, security — that ad-hoc-агree on flags and
- * output shape. The agent-readable contract started drifting (security
- * has --dry-run, mass-assignment doesn't; security --json packages
- * markdown into `data.digest.stdout`, run --report json returns
- * structured per-endpoint findings; ARV-9 AC#6 deferred --include/--exclude
- * for the probe family). m-17 raises this from "convention" to
- * "TS-interface validated at boot".
- *
- * `Probe` is the contract every registered probe class MUST satisfy.
- * `commonFlags` is a declarative slot table — the harness uses it both
- * for boot-validation (registry refuses to start if a slot is missing)
- * and for help/feature-detection. dry-run and run return DIFFERENT
- * shapes on purpose (ARV-50): dry-run answers "what would I attack",
- * run answers "what did I find". Severity is undefined in dry-run.
- */
-import type { EndpointInfo, SecuritySchemeInfo } from "../generator/types.ts";
-
-/**
- * Common-flag manifest. Boot-validator checks each registered probe
- * declares every slot — `true` means "this probe's CLI exposes the
- * flag", `false` means "intentionally not supported". We don't allow
- * undefined: forcing a boolean makes "we forgot to wire it" obvious in
- * code review (ARV-9 AC#6, F2-15).
- */
-export interface ProbeFlags {
-  /** `--api <name>` */
-  api: boolean;
-  /** `--tag <tag>` */
-  tag: boolean;
-  /** Repeatable `--include <selector:value>` (m-15 ARV-9 grammar). */
-  include: boolean;
-  /** Repeatable `--exclude <selector:value>`. */
-  exclude: boolean;
-  /** `--dry-run` — list planned attacks without sending requests. */
-  dryRun: boolean;
-  /** `--list-tags` — print spec tags and exit. */
-  listTags: boolean;
-  /** `--json` — emit single JSON envelope on stdout. */
-  json: boolean;
-  /** `--output <file>` — write markdown / SARIF digest to file. */
-  output: boolean;
-  /** `--report <markdown|json|sarif>` — choose the structured report
-   *  format (m-17 ARV-51). */
-  report: boolean;
-}
-
-/**
- * Per-endpoint dry-run record. Returned from `Probe.dryRun()`. Severity
- * is intentionally absent: nothing has been classified yet (ARV-50).
- *
- * `planned: true` means the probe would send live traffic at this
- * endpoint; `planned: false` + `skip_reason` means we identified the
- * endpoint but won't probe it (no body, isolated path-param, …).
- */
-export interface EndpointPlan {
-  path: string;
-  method: string;
-  planned: boolean;
-  /** Probe-class IDs we'd run (e.g. ["ssrf","crlf"] or ["mass-assignment"]). */
-  classes_planned: string[];
-  /** Suspect fields the probe would touch (mass-assignment / security only). */
-  fields_planned: string[];
-  /** Null when planned, populated when planned:false. Closed string set
-   *  per-probe (security: 'no-body'|'no-matched-field'|'isolated-protected'|
-   *  'unresolved-path'; mass-assignment: 'no-body'|'isolated-protected'). */
-  skip_reason: string | null;
-}
-
-/**
- * Severity classifier outcome for a finding. `inconclusive` covers both
- * baseline-failure and 5xx-on-attack — sub-classes carry the detail in
- * `evidence`. Mirrors the existing union in security-probe.ts so we
- * don't double-up on enums.
- */
-export type ProbeFindingSeverity =
-  | "high"
-  | "low"
-  | "inconclusive"
-  | "ok";
-
-export interface ProbeFinding {
-  /** Probe-class id (e.g. "ssrf", "open-redirect", "mass-assignment"). */
-  class: string;
-  severity: ProbeFindingSeverity;
-  /** Free-form evidence: request signature, response signature, baseline
-   *  diff, etc. Schema is per-probe, but stays structured (no markdown). */
-  evidence: Record<string, unknown>;
-}
-
-export type ProbeEndpointStatus = "ok" | "high" | "low" | "inconclusive" | "skipped";
-
-export interface ProbeEndpointResult {
-  path: string;
-  method: string;
-  /** Probe classes that actually ran on this endpoint. */
-  classes_run: string[];
-  findings: ProbeFinding[];
-  status: ProbeEndpointStatus;
-  skip_reason?: string;
-}
-
-export interface ProbeRunSummary {
-  totalEndpoints: number;
-  probed: number;
-  /** Per-status tally; identical to existing severity buckets, but with
-   *  closed shape (ARV-51). */
-  by_status: Record<ProbeEndpointStatus, number>;
-}
-
-/**
- * Result of a live `Probe.run()`. `endpoints[]` is the agent-routable
- * structure; markdown digest is rendered separately by `Probe.report()`.
- */
-export interface ProbeResult {
-  endpoints: ProbeEndpointResult[];
-  summary: ProbeRunSummary;
-  warnings: string[];
-  /** Optional probe-specific extras (e.g. orphans, emittedTests) that
-   *  don't fit the per-endpoint shape but agents still need access to. */
-  extras?: Record<string, unknown>;
-}
-
-export type ProbeReportFormat = "markdown" | "json";
-
-export interface ProbeContext {
-  specPath: string;
-  /** Pre-loaded endpoints (probe harness loads spec once and shares). */
-  endpoints: EndpointInfo[];
-  securitySchemes: SecuritySchemeInfo[];
-  /** Resolved env vars (`base_url`, `auth_token`, fixture vars). Empty
-   *  for dry-run when the env file is absent. */
-  vars: Record<string, string>;
-  /** Selector strings (m-15 ARV-9 grammar: `path:`, `method:`, `tag:`,
-   *  `operation-id:`). Pre-applied to `endpoints` before this context
-   *  reaches the probe. Carried for diagnostics. */
-  filter?: { includes: string[]; excludes: string[] };
-  /** Probe-class subset (e.g. for security: ["ssrf","crlf"]). */
-  classes?: string[];
-  /** Probe-specific options bag — kept opaque so the harness doesn't
-   *  need to know each probe's flag inventory. */
-  options: Record<string, unknown>;
-}
-
-/**
- * The contract. Every registered probe MUST implement all four
- * required methods; missing one trips boot-validation in
- * `registry.ts`. listTags is optional — most probes share the same
- * loadSpecForProbe shortcut via the harness, so we don't force it.
- */
-export interface Probe {
-  readonly name: string;
-  readonly description: string;
-  readonly commonFlags: ProbeFlags;
-  /** List endpoints + classes the probe would attack (no live traffic). */
-  dryRun(ctx: ProbeContext): Promise<EndpointPlan[]>;
-  /** Run the probe live and return structured per-endpoint findings. */
-  run(ctx: ProbeContext): Promise<ProbeResult>;
-  /** Render a structured (json) or human (markdown) digest. */
-  report(format: ProbeReportFormat, result: ProbeResult): string | object;
-}
-

package/src/core/probe/verdict-aggregator.ts

@@ -1,33 +0,0 @@
-/**
- * Tally verdicts by severity into a caller-shaped bucket object and
- * format a one-line summary. Extracted from probe-mass-assignment and
- * probe-security CLI commands which had near-identical countBuckets +
- * Summary printers — they differ only in the severity vocabulary
- * ("medium" vs "inconclusive") and the label/order of the summary line.
- *
- * Generic over the bucket shape so each command keeps its own JSON-
- * envelope keys (camelCase) without rewriting the rest of the pipeline.
- */
-
-export function tallyBySeverity<T extends object>(
-  verdicts: ReadonlyArray<{ severity: string }>,
-  mapping: ReadonlyArray<readonly [severity: string, bucket: keyof T & string]>,
-  zero: T,
-): T {
-  const out: Record<string, number> = { ...(zero as Record<string, number>) };
-  const lookup = new Map<string, string>(mapping);
-  for (const v of verdicts) {
-    const bucket = lookup.get(v.severity);
-    if (bucket !== undefined && bucket in out) out[bucket]! += 1;
-  }
-  return out as T;
-}
-
-export function formatSummaryLine<T extends object>(
-  counts: T,
-  pairs: ReadonlyArray<readonly [label: string, bucket: keyof T & string]>,
-): string {
-  const indexed = counts as Record<string, number>;
-  const parts = pairs.map(([label, key]) => `${label} ${indexed[key] ?? 0}`);
-  return `Summary: ${parts.join(" · ")}`;
-}

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

@@ -1,282 +0,0 @@
-/**
- * `zond probe webhooks` (m-20 ARV-173) — webhook shape-conformance.
- *
- * The probe is **offline**: it reads an ndjson event log captured by
- * the recipe (`docs/recipes/webhook-receiver.md`, e.g. via
- * `stripe listen --print-json`) and validates each event payload
- * against the schema declared in `spec.webhooks.<event>.post.requestBody`.
- *
- * Why offline? m-20 explicitly puts live HTTP infrastructure (tunnels,
- * port binding, receiver servers) in recipes, not core zond:
- *
- *   • A live receiver requires a public URL — that's a recipe concern
- *     (Stripe CLI, ngrok, smee.io are all out-of-band).
- *   • Capture is bursty (events trickle in seconds-to-minutes after a
- *     trigger); the probe can't reliably wait for them inside a CLI
- *     invocation without nasty timeout knobs.
- *   • Decoupling capture from verification lets the same probe run
- *     against logs from prod tap, mitm-proxy dumps, CI artifacts, etc.
- *
- * Recipe captures; probe verifies. Same pattern as quicktype (capture
- * → schema infer) and interactsh (capture → OOB-detect) in m-18.
- *
- * Event log format: ndjson, one event per line. Two recognised shapes:
- *
- *   • Stripe-style — `{type, data: {object: {...}}}` (the payload is
- *     `data.object`; everything else is envelope metadata).
- *   • Generic — `{type|event, body|payload, ...}` (the payload is
- *     whichever of `body`/`payload` is an object; falls back to the
- *     event itself when neither is present).
- *
- * Severity policy: HIGH on shape drift (server announced an event
- * shape via `webhooks:` and is now sending something else). Unknown
- * event types and missing payloads surface at LOW — they're noise
- * categories, not contract bugs the API owner promised against.
- */
-import type { OpenAPIV3, OpenAPIV3_1 } from "openapi-types";
-import type { ValidateFunction, ErrorObject } from "ajv";
-import { makeAjv } from "../util/ajv.ts";
-
-interface SingleSchemaValidator {
-  validate(value: unknown): boolean;
-  errors: ErrorObject[] | null;
-}
-
-/** Compile a single JSON-Schema-shaped object into a callable validator.
- *  3.1-flavour by default (`webhooks:` is OpenAPI 3.1) but tolerates
- *  pre-3.1 specs using `x-webhooks` — they ship Draft-7-ish schemas. */
-function compileSingleSchema(schema: OpenAPIV3.SchemaObject, isV31: boolean): SingleSchemaValidator {
-  const ajv = makeAjv(isV31, { strict: false, allErrors: true });
-  const validate: ValidateFunction = ajv.compile(schema);
-  return {
-    validate(value) { return validate(value) as boolean; },
-    get errors() { return validate.errors ?? null; },
-  };
-}
-
-export type WebhookFindingKind =
-  | "shape_drift"
-  | "unknown_event_type"
-  | "missing_payload"
-  | "malformed_event";
-
-export interface WebhookFinding {
-  /** Line number in the event log (1-indexed) for traceability. */
-  line: number;
-  kind: WebhookFindingKind;
-  severity: "high" | "low";
-  event_type: string | null;
-  message: string;
-  evidence: Record<string, unknown>;
-  /** Reserved suppression trace (audit-trail). Currently unset — the
-   *  agent triages severity from the raw finding. */
-  suppressed_by?: { source: string; rule_index: number; reason: string };
-}
-
-export interface WebhookProbeResult {
-  total_events: number;
-  by_type: Record<string, { ok: number; drift: number; unknown: number }>;
-  declared_events: string[];
-  findings: WebhookFinding[];
-  /** Reason the probe short-circuited without inspecting any event,
-   *  e.g. spec has no webhooks block. Empty string when normal. */
-  skip_reason: string;
-}
-
-/** Extract the webhooks block. Tries OpenAPI 3.1 `webhooks:` first
- *  (the canonical location), falls back to `x-webhooks` for specs
- *  shipped before OpenAPI 3.1 had ratified the field. Returns an
- *  empty object when neither exists. */
-export function readWebhooksMap(spec: unknown): Record<string, OpenAPIV3.PathItemObject> {
-  if (!spec || typeof spec !== "object") return {};
-  const s = spec as Record<string, unknown>;
-  const candidate = (s.webhooks ?? s["x-webhooks"]) as Record<string, OpenAPIV3.PathItemObject> | undefined;
-  if (!candidate || typeof candidate !== "object") return {};
-  return candidate;
-}
-
-/** Pull the request-body schema for the POST operation under a
- *  webhook entry. Returns null when the entry doesn't declare a POST,
- *  or when the POST doesn't carry a JSON requestBody schema. */
-function schemaForEvent(item: OpenAPIV3.PathItemObject | OpenAPIV3_1.PathItemObject): OpenAPIV3.SchemaObject | null {
-  const post = item.post;
-  if (!post) return null;
-  const rb = post.requestBody;
-  if (!rb || (rb as OpenAPIV3.ReferenceObject).$ref) return null;
-  const content = (rb as OpenAPIV3.RequestBodyObject).content ?? {};
-  const json = content["application/json"];
-  if (!json?.schema) return null;
-  return json.schema as OpenAPIV3.SchemaObject;
-}
-
-/** Extract `type` from an event in a tolerant way: try `type` first
- *  (Stripe / GitHub style), then `event` (legacy / SaaS-style), then
- *  give up. Numbers are coerced to strings so an integer-valued
- *  `type` field doesn't masquerade as null. */
-function readEventType(event: Record<string, unknown>): string | null {
-  for (const k of ["type", "event", "event_type"]) {
-    const v = event[k];
-    if (typeof v === "string" && v.length > 0) return v;
-    if (typeof v === "number") return String(v);
-  }
-  return null;
-}
-
-/** Extract the payload from an event. Recognised envelopes (in
- *  priority order): `data.object` (Stripe), `body`, `payload`. Returns
- *  null when none of those carry an object — missing_payload then
- *  surfaces as a LOW finding so the operator can fix the capture
- *  step (and the probe doesn't validate envelope metadata as payload). */
-function readEventPayload(event: Record<string, unknown>): unknown {
-  if (event.data && typeof event.data === "object" && !Array.isArray(event.data)) {
-    const inner = (event.data as Record<string, unknown>).object;
-    if (inner && typeof inner === "object") return inner;
-  }
-  for (const k of ["body", "payload"]) {
-    const v = event[k];
-    if (v && typeof v === "object") return v;
-  }
-  return null;
-}
-
-export interface RunOptions {
-  /** Pre-parsed events. One Record per line; non-object lines should
-   *  surface as malformed_event findings before reaching this layer. */
-  events: Array<{ line: number; event: Record<string, unknown> }>;
-  spec: unknown;
-  /** Optional restriction — only validate events whose `type` is in
-   *  this list. Empty/undefined ⇒ validate everything declared. */
-  onlyTypes?: string[];
-}
-
-export function runWebhooksProbe(opts: RunOptions): WebhookProbeResult {
-  const webhooksMap = readWebhooksMap(opts.spec);
-  const declared = Object.keys(webhooksMap).sort();
-
-  const out: WebhookProbeResult = {
-    total_events: opts.events.length,
-    by_type: {},
-    declared_events: declared,
-    findings: [],
-    skip_reason: "",
-  };
-
-  if (declared.length === 0) {
-    out.skip_reason = "spec declares no `webhooks:` (or `x-webhooks`) entries — nothing to validate against";
-    return out;
-  }
-
-  const isV31 = typeof (opts.spec as { openapi?: string })?.openapi === "string"
-    && (opts.spec as { openapi: string }).openapi.startsWith("3.1");
-  // Compile each schema once; events sharing a type reuse the validator.
-  const validators = new Map<string, SingleSchemaValidator | null>();
-  for (const [name, item] of Object.entries(webhooksMap)) {
-    const schema = schemaForEvent(item);
-    if (!schema) { validators.set(name, null); continue; }
-    try {
-      validators.set(name, compileSingleSchema(schema, isV31));
-    } catch {
-      validators.set(name, null);
-    }
-  }
-
-  const onlyTypes = opts.onlyTypes && opts.onlyTypes.length > 0 ? new Set(opts.onlyTypes) : null;
-
-  for (const { line, event } of opts.events) {
-    const type = readEventType(event);
-    if (!type) {
-      out.findings.push({
-        line, kind: "malformed_event", severity: "low",
-        event_type: null,
-        message: `event has no recognisable type field (tried "type", "event", "event_type")`,
-        evidence: { event_keys: Object.keys(event) },
-      });
-      continue;
-    }
-    if (onlyTypes && !onlyTypes.has(type)) continue;
-    const bucket = out.by_type[type] ?? (out.by_type[type] = { ok: 0, drift: 0, unknown: 0 });
-    const validator = validators.get(type);
-    if (validator === undefined) {
-      bucket.unknown += 1;
-      out.findings.push({
-        line, kind: "unknown_event_type", severity: "low",
-        event_type: type,
-        message: `event type "${type}" is not declared in spec.webhooks (${declared.length} declared)`,
-        evidence: { declared_sample: declared.slice(0, 5) },
-      });
-      continue;
-    }
-    if (validator === null) {
-      // Declared but no schema to validate against → silent pass for
-      // that event type; surfacing every such case would be noise.
-      bucket.ok += 1;
-      continue;
-    }
-    const payload = readEventPayload(event);
-    if (payload == null || typeof payload !== "object" || Array.isArray(payload)) {
-      out.findings.push({
-        line, kind: "missing_payload", severity: "low",
-        event_type: type,
-        message: `event "${type}" carries no object payload (data.object / body / payload)`,
-        evidence: { event_keys: Object.keys(event) },
-      });
-      continue;
-    }
-    const valid = validator.validate(payload);
-    if (valid) { bucket.ok += 1; continue; }
-    bucket.drift += 1;
-    const errs = validator.errors ?? [];
-    out.findings.push({
-      line, kind: "shape_drift", severity: "high",
-      event_type: type,
-      message: `event "${type}" does not conform to declared schema (${errs.length} error(s))`,
-      evidence: {
-        errors: errs.slice(0, 5).map((e) => ({
-          path: e.instancePath ?? "",
-          keyword: e.keyword ?? "",
-          message: e.message ?? "",
-          params: e.params ?? {},
-        })),
-      },
-    });
-  }
-  return out;
-}
-
-/** Parse an ndjson event log. Each line that is non-empty and parses
- *  to an object yields one `{line, event}`. Bad lines surface as
- *  malformed_event findings in the result so the operator gets
- *  pinpointed feedback. */
-export function parseEventLog(text: string): {
-  events: Array<{ line: number; event: Record<string, unknown> }>;
-  malformed: WebhookFinding[];
-} {
-  const events: Array<{ line: number; event: Record<string, unknown> }> = [];
-  const malformed: WebhookFinding[] = [];
-  const lines = text.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const raw = lines[i]!.trim();
-    if (raw.length === 0) continue;
-    try {
-      const parsed = JSON.parse(raw);
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-        events.push({ line: i + 1, event: parsed as Record<string, unknown> });
-      } else {
-        malformed.push({
-          line: i + 1, kind: "malformed_event", severity: "low",
-          event_type: null,
-          message: `event line is not a JSON object`,
-          evidence: { sample: raw.slice(0, 60) },
-        });
-      }
-    } catch (e) {
-      malformed.push({
-        line: i + 1, kind: "malformed_event", severity: "low",
-        event_type: null,
-        message: `ndjson parse failed: ${(e as Error).message}`,
-        evidence: { sample: raw.slice(0, 60) },
-      });
-    }
-  }
-  return { events, malformed };
-}