@kirrosh/zond 0.26.1 → 0.27.0

package/src/cli/commands/probe/security.ts

@@ -1,537 +0,0 @@
-import { join } from "path";
-import { mkdir, writeFile } from "fs/promises";
-import { loadEnvironment, loadEnvFile } from "../../../core/parser/variables.ts";
-import {
-  runSecurityProbes,
-  formatSecurityDigest,
-  emitSecurityRegressionSuites,
-  SECURITY_CLASSES,
-  type SecurityClass,
-} from "../../../core/probe/security-probe.ts";
-import { loadSpecForProbe, writeProbeSuites } from "../../../core/probe/runner.ts";
-import { printError, printSuccess, printWarning } from "../../output.ts";
-import { jsonOk, jsonError, printJson } from "../../json-envelope.ts";
-import { getSecretRegistry } from "../../../core/secrets/registry.ts";
-import { applySanitizer } from "../../../core/exporter/exporter.ts";
-import { rotateOutputTarget } from "../../../core/workspace/output-rotation.ts";
-import { tallyBySeverity, formatSummaryLine } from "../../../core/probe/verdict-aggregator.ts";
-import { printMutationBanner, countCleanupFailures } from "../../../core/probe/shared.ts";
-import { persistVerdictsAsOrphans } from "../../../core/probe/orphan-tracker.ts";
-import { SecurityProbe } from "../../../core/probe/security-probe-class.ts";
-import { summarizeDryRun } from "../../../core/probe/dry-run-envelope.ts";
-import { compileOperationFilter } from "../../../core/selectors/operation-filter.ts";
-import { loadSeedBodyOverlays } from "./_seed-bodies.ts";
-
-interface Buckets {
-  high: number;
-  medium: number;
-  low: number;
-  info: number;
-  inconclusive: number;
-  inconclusiveBaseline: number;
-  ok: number;
-  skipped: number;
-}
-
-const SEC_BUCKETS: ReadonlyArray<readonly [string, keyof Buckets & string]> = [
-  ["high", "high"],
-  ["medium", "medium"],
-  ["low", "low"],
-  ["info", "info"],
-  ["inconclusive", "inconclusive"],
-  ["inconclusive-baseline", "inconclusiveBaseline"],
-  ["ok", "ok"],
-  ["skipped", "skipped"],
-];
-
-const SEC_SUMMARY: ReadonlyArray<readonly [string, keyof Buckets & string]> = [
-  ["HIGH", "high"],
-  ["INCONCLUSIVE", "inconclusive"],
-  ["INCONCLUSIVE-BASE", "inconclusiveBaseline"],
-  ["MED", "medium"],
-  ["LOW", "low"],
-  ["INFO", "info"],
-  ["OK", "ok"],
-  ["SKIPPED", "skipped"],
-];
-
-const SEC_ZERO: Buckets = {
-  high: 0, medium: 0, low: 0, info: 0, inconclusive: 0, inconclusiveBaseline: 0, ok: 0, skipped: 0,
-};
-
-export interface ProbeSecurityOptions {
-  specPath: string;
-  classes: string;
-  env?: string;
-  output?: string;
-  emitTests?: string;
-  tag?: string;
-  noCleanup?: boolean;
-  timeoutMs?: number;
-  dryRun?: boolean;
-  json?: boolean;
-  listTags?: boolean;
-  overwrite?: boolean;
-  /** TASK-278: API name for orphan-tracker file path
-   *  (`~/.zond/orphans/<api>/<run-id>.jsonl`). Defaults to "default" when
-   *  the probe is invoked without --api. */
-  apiName?: string;
-  /** TASK-264: refuse to attack PUT/PATCH endpoints whose path-params come
-   *  from `.env.yaml` (seeded fixtures). Trade coverage for guaranteed
-   *  fixture safety. */
-  isolated?: boolean;
-  /** ARV-140: opt-in to POST attacks on endpoints with no DELETE counterpart
-   *  in the spec. Defaults to off so probes can't leak resources the CLI
-   *  has no way to clean up afterwards. */
-  allowLeaks?: boolean;
-  /** m-17 / ARV-51: structured report format for `--output` and the
-   *  non-`--json` stdout path. `--json` envelope is always structured
-   *  (no markdown blob) regardless of this flag. Default: "markdown" so
-   *  human invocations keep the existing behaviour. */
-  report?: "markdown" | "json";
-  /** m-15 ARV-9 / m-17 ARV-J: unified operation selectors. */
-  include?: string[];
-  exclude?: string[];
-  /** ARV-253: surface INFO-severity findings (CRLF accepted, no
-   *  reflection — sanitization signal only). Hidden by default since
-   *  they carry single_signal proof with no exploit pathway. */
-  verbose?: boolean;
-  /** ARV-302: cap the number of endpoints probed in this run (after
-   *  --include / --exclude / --tag filters). Used by `zond audit
-   *  --budget` to keep the security stage inside a wall-clock budget
-   *  on big specs (Stripe: 587 endpoints) instead of unbounded scanning. */
-  maxEndpoints?: number;
-}
-
-function parseClasses(input: string): SecurityClass[] | string {
-  const parts = input.split(",").map(s => s.trim()).filter(Boolean);
-  const out: SecurityClass[] = [];
-  for (const p of parts) {
-    if (!(SECURITY_CLASSES as readonly string[]).includes(p)) {
-      return `Unknown class: ${p}. Available: ${SECURITY_CLASSES.join(", ")}`;
-    }
-    out.push(p as SecurityClass);
-  }
-  if (out.length === 0) return `At least one class required (${SECURITY_CLASSES.join(", ")})`;
-  return out;
-}
-
-export async function probeSecurityCommand(
-  options: ProbeSecurityOptions,
-): Promise<number> {
-  try {
-    const classes = parseClasses(options.classes);
-    if (typeof classes === "string") {
-      if (options.json) printJson(jsonError("probe-security", [classes]));
-      else printError(classes);
-      return 2;
-    }
-
-    const loaded = await loadSpecForProbe({
-      specPath: options.specPath,
-      tag: options.tag,
-      listTags: options.listTags,
-    });
-
-    if (loaded.kind === "tags") {
-      if (options.json) printJson(jsonOk("probe-security", { tags: loaded.tags }));
-      else if (loaded.tags.length === 0) console.log("No tags found in spec.");
-      else {
-        console.log("Available tags:");
-        for (const t of loaded.tags) console.log(`  - ${t}`);
-      }
-      return 0;
-    }
-    if (loaded.kind === "tag-not-found") {
-      const msg = `No endpoints tagged "${loaded.tag}". Available tags: ${loaded.available.length ? loaded.available.join(", ") : "(none)"}`;
-      if (options.json) printJson(jsonError("probe-security", [msg]));
-      else printWarning(msg);
-      return 2;
-    }
-    const { endpoints: rawEndpoints, securitySchemes } = loaded;
-
-    // m-17 / ARV-J: unified --include/--exclude (m-15 ARV-9). Closes
-    // ARV-9 AC#3 for probe-family.
-    let endpoints = rawEndpoints;
-    if (options.include?.length || options.exclude?.length) {
-      const compiled = compileOperationFilter({ includes: options.include, excludes: options.exclude });
-      if (compiled.errors.length > 0) {
-        const message = compiled.errors.join("\n");
-        if (options.json) printJson(jsonError("probe-security", [message]));
-        else printError(message);
-        return 2;
-      }
-      endpoints = endpoints.filter(compiled.filter);
-    }
-    // ARV-302: --max-endpoints cap — see probe/mass-assignment.ts for the
-    // rationale. Applied after user-visible filters; a warning fires so
-    // partial output is obvious.
-    let cappedEndpoints = false;
-    if (typeof options.maxEndpoints === "number" && options.maxEndpoints > 0
-        && endpoints.length > options.maxEndpoints) {
-      const total = endpoints.length;
-      endpoints = endpoints.slice(0, options.maxEndpoints);
-      cappedEndpoints = true;
-      if (!options.json) {
-        process.stderr.write(
-          `zond: probe security capped at ${options.maxEndpoints}/${total} endpoints (--max-endpoints) — pass --max-endpoints <N> or --budget full to widen.\n`,
-        );
-      }
-    }
-
-    let vars: Record<string, string> = {};
-    if (options.env) {
-      const fromFile = await loadEnvFile(options.env);
-      if (!fromFile) {
-        const msg = `Environment file not found: ${options.env}`;
-        if (options.json) printJson(jsonError("probe-security", [msg]));
-        else printError(msg);
-        return 2;
-      }
-      vars = fromFile;
-    } else {
-      vars = await loadEnvironment();
-    }
-
-    if (!options.dryRun && !vars["base_url"]) {
-      const msg = "base_url is required (set in .env.yaml or via --env file). Probing requires a live API.";
-      if (options.json) printJson(jsonError("probe-security", [msg]));
-      else printError(msg);
-      return 2;
-    }
-
-    // m-17 / ARV-50: dry-run answers "what would I attack" — severity is
-    // undefined here, so we use a separate `data.endpoints[]` shape with
-    // explicit `planned: boolean` and `skip_reason` enum. The previous
-    // conflation (severity.skipped == 32, which silently included 14
-    // planned attacks) is what made `severity.skipped == totalEndpoints`
-    // a misleading CI gate (F1-15).
-    if (options.dryRun) {
-      const probe = new SecurityProbe();
-      const plan = await probe.dryRun({
-        specPath: options.specPath,
-        endpoints,
-        securitySchemes,
-        vars,
-        classes,
-        options: { isolated: options.isolated === true },
-      });
-      const data = summarizeDryRun(plan);
-      const { formatDryRunDigest } = await import("../../../core/probe/dry-run-envelope.ts");
-      // ARV-317: persist the planned inventory when --output is given (parity
-      // with probe mass-assignment). --emit-tests is skipped on dry-run —
-      // there are no findings to turn into regression suites.
-      // ARV-321: say so explicitly — see mass-assignment.ts for the friction
-      // that prompted this.
-      if (options.emitTests) {
-        printWarning(`--emit-tests skipped: safe/dry-run mode has no live verdicts to lock in as regression suites. Re-run with --live to emit ${options.emitTests}.`);
-      }
-      if (options.output) {
-        const payload = options.report === "json"
-          ? JSON.stringify(data, null, 2)
-          : formatDryRunDigest(plan);
-        await mkdir(join(options.output, "..").replace(/\/\.$/, ""), { recursive: true }).catch(() => {});
-        rotateOutputTarget(options.output, { overwrite: options.overwrite });
-        await writeFile(options.output, payload + "\n", "utf-8");
-      }
-      if (options.json) {
-        printJson(jsonOk("probe-security", data));
-      } else {
-        console.log(formatDryRunDigest(plan));
-      }
-      return 0;
-    }
-
-    // TASK-259: live security probes mutate via PUT/PATCH/POST + cleanup
-    // DELETE. Skip the banner in --dry-run (no live calls) and --json (warnings
-    // travel in the envelope instead).
-    printMutationBanner("probe-security", vars, { quiet: options.json === true });
-
-    // ARV-265: capture every HTTP request the probe sends so audit-coverage
-    // sees the touches. Dry-run never reaches this branch (early return
-    // above), so AC#5 holds — only live probes pollute the run table.
-    const { withHttpAudit, beginAuditRun, finalizeAuditRun, auditRecordToCase, checksPersistEnabled } =
-      await import("../../../core/audit/persist.ts");
-    const auditEnabled = checksPersistEnabled();
-    // ARV-269: same overlay-lift as probe-mass-assignment.
-    const seedBodies = await loadSeedBodyOverlays(options.apiName);
-    const { value: result, records: auditRecords } = await withHttpAudit(async () =>
-      runSecurityProbes({
-        endpoints,
-        securitySchemes,
-        vars,
-        classes,
-        noCleanup: options.noCleanup,
-        timeoutMs: options.timeoutMs,
-        dryRun: options.dryRun,
-        isolated: options.isolated === true,
-        allowLeaks: options.allowLeaks === true,
-        seedBodies,
-      }),
-    );
-
-    if (auditEnabled && auditRecords.length > 0) {
-      try {
-        const { getDb } = await import("../../../db/schema.ts");
-        const { findCollectionByNameOrId } = await import("../../../db/queries.ts");
-        const { readCurrentSession } = await import("../../../core/context/session.ts");
-        getDb();
-        const collectionId = options.apiName ? findCollectionByNameOrId(options.apiName)?.id : undefined;
-        const session = readCurrentSession();
-        const runId = beginAuditRun({
-          runKind: "probe",
-          ...(collectionId != null ? { collectionId } : {}),
-          ...(session?.id ? { sessionId: session.id } : {}),
-          tags: ["probe", "security", ...classes],
-        });
-        const suiteFile = `apis/${options.apiName ?? "_"}/probes/security.yaml`;
-        finalizeAuditRun(runId, auditRecords.map((rec) =>
-          auditRecordToCase(rec, {
-            suiteName: "probe/security",
-            suiteFile,
-            testName: `security::${rec.request.method.toUpperCase()} ${rec.request.url}`,
-          }),
-        ));
-      } catch (err) {
-        process.stderr.write(`zond: audit persistence failed (${(err as Error).message}).\n`);
-      }
-    }
-
-    // ARV-253: filter verdicts for display under the evidence-chain
-    // principle. INFO-severity findings (CRLF accepted, no reflection
-    // — sanitization signal only) are hidden by default; surfaced under
-    // --verbose for hygiene auditors. JSON envelope keeps the unfiltered
-    // list so agents can opt in explicitly.
-    const displayResult = options.verbose === true
-      ? result
-      : { ...result, verdicts: result.verdicts.map((v) => ({
-          ...v,
-          findings: v.findings.filter((f) => f.severity !== "info"),
-        })) };
-
-    // TASK-168 (m-10): register env vars + redact the digest before
-    // either writing to disk or echoing to stdout.
-    getSecretRegistry().registerAll(vars);
-    const md = applySanitizer(formatSecurityDigest(displayResult, options.specPath));
-
-    // m-17 / ARV-51: --output writes whichever format `--report` selected
-    // (default markdown). `--json` envelope is always structured —
-    // never carries `data.digest.stdout` (F3-15).
-    const reportFmt: "markdown" | "json" = options.report ?? "markdown";
-    const structuredEndpoints = buildStructuredEndpoints(result);
-    if (options.output) {
-      await mkdir(join(options.output, "..").replace(/\/\.$/, ""), { recursive: true }).catch(() => {});
-      rotateOutputTarget(options.output, { overwrite: options.overwrite });
-      const payload = reportFmt === "json"
-        ? JSON.stringify(structuredReport(result, structuredEndpoints), null, 2) + "\n"
-        : md;
-      await writeFile(options.output, payload, "utf-8");
-    }
-
-    let emittedSuites: Array<{ file: string; suite: string; tests: number }> = [];
-    if (options.emitTests && !options.dryRun) {
-      const suites = emitSecurityRegressionSuites(result, endpoints, securitySchemes);
-      const written = await writeProbeSuites({
-        output: options.emitTests,
-        suites,
-        command: "zond probe-security --emit-tests",
-        headerExample: `zond probe-security --api <name> --emit-tests ${options.emitTests}`,
-      });
-      emittedSuites = written.files;
-    }
-
-    const counts = tallyBySeverity(result.verdicts, SEC_BUCKETS, SEC_ZERO);
-    // TASK-259: shared cleanup-failure counter (404 treated as success — the
-    // resource is already gone, which is the cleanup goal). Replaces the
-    // previous local filter that flagged any `cleanup.error` regardless of
-    // the underlying status.
-    const orphans = countCleanupFailures(result.verdicts);
-
-    // TASK-278: persist created-resource records to ~/.zond/orphans/<api>/<run-id>.jsonl
-    // even when cleanup succeeded — successful entries become tombstones that
-    // suppress the leak; failed ones are picked up by `zond cleanup --orphans`.
-    const orphanRunId = `${Date.now()}`;
-    const orphanApi = options.apiName ?? "default";
-    if (!options.dryRun) {
-      try {
-        await persistVerdictsAsOrphans(orphanApi, orphanRunId, result.verdicts);
-      } catch (err) {
-        // Non-fatal — orphan tracking is a hygiene aid, not a probe blocker.
-        if (!options.json) {
-          process.stderr.write(`zond: failed to persist orphan tracker: ${(err as Error).message}\n`);
-        }
-      }
-    }
-    const orphanList = result.verdicts
-      .filter(v => {
-        const c = v.cleanup;
-        if (!c?.attempted || c.id === undefined) return false;
-        if (c.error) return true;
-        return c.status != null && c.status >= 400 && c.status !== 404;
-      })
-      .map(v => ({
-        method: v.method.toUpperCase(),
-        path: v.path,
-        id: String(v.cleanup!.id),
-        deletePath: v.cleanup!.deletePath ?? "",
-        lastStatus: v.cleanup!.status ?? null,
-        error: v.cleanup!.error ?? null,
-      }));
-
-    if (options.json) {
-      // m-17 / ARV-51: structured envelope. `data.digest.stdout` is gone
-      // (F3-15) — markdown lives in `--output <file>` or `--report markdown`
-      // on the non-json path. Severity becomes summary.by_status.
-      printJson(
-        jsonOk("probe-security", {
-          endpoints: structuredEndpoints,
-          summary: {
-            totalEndpoints: result.totalEndpoints,
-            probed: result.specProbed,
-            by_status: byStatus(structuredEndpoints),
-            // ARV-140: pre-flight cleanup-feasibility counts. Lets CI gate on
-            // "no leak-prone POSTs slipped in" independently of HIGH findings.
-            ...(result.cleanupFeasibility ? {
-              cleanup_feasibility: {
-                skipped_no_cleanup: result.cleanupFeasibility.skippedNoCleanup,
-                forced_no_cleanup: result.cleanupFeasibility.forcedNoCleanup,
-                // ARV-153: action POSTs attacked even without a DELETE
-                // counterpart (e.g. /capture, /verify, /cancel).
-                action_no_cleanup_needed: result.cleanupFeasibility.actionNoCleanupNeeded,
-              },
-            } : {}),
-          },
-          orphans,
-          emittedTests: emittedSuites,
-          // ARV-302: surface the partial-run warning so JSON consumers
-          // see that --max-endpoints trimmed the set (otherwise the cap
-          // is invisible in machine-readable output).
-          ...(cappedEndpoints ? {
-            warnings: [
-              `--max-endpoints capped this run at ${options.maxEndpoints}; pass --max-endpoints <N> or --budget full to widen.`,
-            ],
-          } : {}),
-        }),
-      );
-    } else {
-      if (!options.output) {
-        if (reportFmt === "json") {
-          process.stdout.write(JSON.stringify(structuredReport(result, structuredEndpoints), null, 2) + "\n");
-        } else {
-          console.log(md);
-        }
-      } else printSuccess(`${reportFmt === "json" ? "Structured report" : "Digest"} written to ${options.output}`);
-      console.log("");
-      console.log(formatSummaryLine(counts, SEC_SUMMARY));
-      if (emittedSuites.length > 0) {
-        printSuccess(`Emitted ${emittedSuites.length} regression suite(s) in ${options.emitTests}`);
-        // TASK-154 §M: print one ready-to-paste command that re-runs the
-        // emitted suites against the same API. Keeps the CI handoff short
-        // (issue body / runbook entry: copy this line, not three).
-        const envFlag = options.apiName ? ` --env apis/${options.apiName}/.env.yaml` : "";
-        console.log(`Run regression suite on CI: zond run ${options.emitTests}${envFlag}`);
-      } else if (options.emitTests && !options.dryRun) {
-        console.log(`No 2xx findings to emit. Directory ${options.emitTests} not created.`);
-      }
-      if (counts.high > 0) {
-        printWarning(`${counts.high} HIGH-severity finding(s) — review the digest before deploy.`);
-      }
-      if (orphans > 0) {
-        printWarning(
-          `${orphans} orphan resource(s): cleanup DELETE failed (non-404). Manual remediation may be needed.`,
-        );
-        // TASK-278: list each orphan with id + deletePath so the operator can
-        // see what's leaked without grep'ing the digest.
-        if (orphanList.length > 0) {
-          for (const o of orphanList) {
-            const tail = o.lastStatus != null ? `→ ${o.lastStatus}` : (o.error ? `→ err: ${o.error.split(" | ")[0]}` : "");
-            process.stderr.write(`  ${o.method} ${o.path} (id=${o.id}); DELETE ${o.deletePath} ${tail}\n`);
-          }
-          process.stderr.write(`Run \`zond cleanup --orphans --api ${orphanApi}\` to retry.\n`);
-        }
-      }
-      const cleanedCount = result.verdicts.filter(v => v.cleanup?.attempted && v.cleanup.status != null && v.cleanup.status < 400).length;
-      if (cleanedCount > 0) {
-        printWarning(
-          `${cleanedCount} resource(s) created and deleted by probes. FK fixtures in .env.yaml may be stale — re-run \`zond prepare-fixtures --api <name>\` before next CRUD run.`,
-        );
-      }
-    }
-
-    // Exit non-zero on HIGH (CI gate) or cleanup failures (data
-    // integrity). Cleanup failure means probe-security mutated state
-    // it couldn't restore — the operator needs to act.
-    return counts.high > 0 || orphans > 0 ? 1 : 0;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    if (options.json) printJson(jsonError("probe-security", [message]));
-    else printError(message);
-    return 2;
-  }
-}
-
-// m-17 / ARV-51: structured per-endpoint shape used by both the `--json`
-// envelope and the non-json `--report json` path. Mirrors the Probe
-// contract result (src/core/probe/types.ts), but built from the legacy
-// SecurityVerdict[] so the live runner keeps emitting its richer
-// internal structure.
-
-import type { SecurityProbeResult, SecurityVerdict } from "../../../core/probe/security-probe.ts";
-import type { ProbeEndpointResult, ProbeEndpointStatus, ProbeFindingSeverity } from "../../../core/probe/types.ts";
-
-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 findingSeverity(s: string): ProbeFindingSeverity {
-  if (s === "high") return "high";
-  if (s === "low") return "low";
-  if (s === "ok") return "ok";
-  return "inconclusive";
-}
-
-function buildStructuredEndpoints(result: SecurityProbeResult): ProbeEndpointResult[] {
-  return result.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: findingSeverity(f.severity),
-      evidence: {
-        field: f.field,
-        payload: f.payload,
-        status: f.status,
-        echoed: f.echoed,
-        reason: f.reason,
-        ...(f.recommended_action ? { recommended_action: f.recommended_action } : {}),
-      },
-    })),
-    status: statusFromSeverity(v.severity),
-    ...(v.skipReason ? { skip_reason: v.skipReason } : {}),
-  }));
-}
-
-function byStatus(endpoints: ProbeEndpointResult[]): Record<ProbeEndpointStatus, number> {
-  const out: Record<ProbeEndpointStatus, number> = {
-    ok: 0, high: 0, low: 0, inconclusive: 0, skipped: 0,
-  };
-  for (const e of endpoints) out[e.status]++;
-  return out;
-}
-
-function structuredReport(result: SecurityProbeResult, endpoints: ProbeEndpointResult[]): object {
-  return {
-    endpoints,
-    summary: {
-      totalEndpoints: result.totalEndpoints,
-      probed: result.specProbed,
-      by_status: byStatus(endpoints),
-    },
-  };
-}
-