@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/src/dast/zap.ts

@@ -0,0 +1,246 @@
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { buildTargets, type Target, type UrlConfig } from './targets.js';
+import type { Finding } from '../core/finding.js';
+
+/**
+ * STEP TWO OF THE DAST ADD-ON: hand the targets to ZAP, put each verdict next to
+ * the finding it came from.
+ *
+ * targets.ts turned Defuse's proven (flow-verified) findings into a list of
+ * addresses to probe. This file drives OWASP ZAP's active scanner against each
+ * one, restricted to the single ZAP rule that matches the finding's category,
+ * and reports ONE verdict per target:
+ *
+ *   confirmed       ZAP reproduced the bug at that URL with its own payloads.
+ *   not-confirmed   ZAP ran the rule and raised nothing. THE FINDING STANDS.
+ *   could-not-test  ZAP never got to render a verdict (input isn't a request
+ *                   parameter, the scan errored, or it timed out).
+ *
+ * The honesty rule from finding.ts carries over: not-confirmed is NOT cleared.
+ * A dynamic scanner that can't reach a code path proves nothing about it, so a
+ * finding Defuse traced by data flow keeps its status unless ZAP positively
+ * reproduces it. ZAP only ever ADDS confidence; it never subtracts a finding.
+ *
+ * Every target appears in the output exactly once. The run asserts
+ * results.length === targets.length so nothing is dropped silently.
+ */
+
+type Verdict = 'confirmed' | 'not-confirmed' | 'could-not-test';
+
+interface Result {
+    id: string;
+    rule: string;
+    zapRule: string;
+    url: string;
+    from: string;
+    param: string;
+    zap: Verdict;
+    detail: string;
+}
+
+interface Outcome {
+    zap: Verdict;
+    detail: string;
+}
+
+// ZAP's one-call active scan needs the whole request, not just the param, because
+// the scanner replays it and only mutates the one field. DVWA hides each bug behind
+// its submit button (Submit=Submit), so without that in the seed the vulnerable
+// branch never runs. `trigger` carries those extra seed fields; it is calibration
+// the generic model can't see, so it lives in the config, not here.
+interface Config extends UrlConfig {
+    trigger?: string;
+}
+
+// Which HTTP methods carry the tainted input. $_REQUEST is GET or POST, and a page
+// often guards one while reading the other ($_REQUEST['ip'] behind an isset($_POST['Submit'])),
+// so a REQUEST source has to be tried both ways. A COOKIE source is not a request
+// parameter this harness can mutate (the Cookie header is pinned for auth), so it is
+// reported could-not-test, never not-confirmed.
+function methods(from: string): ('GET' | 'POST')[] {
+    if (from === 'POST') return ['POST'];
+    if (from === 'GET') return ['GET'];
+    if (from === 'REQUEST') return ['GET', 'POST'];
+    return [];
+}
+
+// One scan covers every target that attacks the same spot the same way.
+export function groupKey(t: Target): string {
+    return [t.zapRule, t.from, t.url, t.param, t.cookie, t.trigger ?? '', t.untestable ?? ''].join('|');
+}
+
+// confirmed iff ZAP raised at least one alert of the finding's own rule.
+export function classify(zapRule: string, alertPluginIds: string[]): Verdict {
+    return alertPluginIds.includes(zapRule) ? 'confirmed' : 'not-confirmed';
+}
+
+// Put each ZAP outcome next to its target by id. A target with no outcome (a
+// group that never ran) becomes could-not-test, never a dropped row.
+export function joinResults(targets: Target[], byKey: Map<string, Outcome>): Result[] {
+    return targets.map((t) => {
+        const outcome = byKey.get(groupKey(t)) ?? { zap: 'could-not-test' as const, detail: 'no scan ran for this target' };
+        return { id: t.id, rule: t.rule, zapRule: t.zapRule, url: t.url, from: t.from, param: t.param, ...outcome };
+    });
+}
+
+const ZAP = process.env.ZAP ?? 'http://localhost:8080';
+const AUTH = process.env.DAST_COOKIE ?? ''; // e.g. "PHPSESSID=abc"; combined with each target's security cookie
+const POLL_MS = 3000;
+const SCAN_TIMEOUT_MS = Number(process.env.DAST_SCAN_TIMEOUT_MS ?? 300_000);
+const RULE_DESC = 'defuse-dast-cookie';
+
+async function zap(apiPath: string, params: Record<string, string> = {}): Promise<Record<string, unknown>> {
+    const url = new URL(`/JSON/${apiPath}/`, ZAP);
+    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    const res = await fetch(url);
+    const body = (await res.json()) as Record<string, unknown>;
+    if (typeof body.code === 'string' && typeof body.message === 'string') {
+        throw new Error(`ZAP ${apiPath}: ${body.message} (${body.code})`);
+    }
+    return body;
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+async function setCookie(cookie: string): Promise<void> {
+    await zap('replacer/action/removeRule', { description: RULE_DESC }).catch(() => undefined);
+    if (cookie === '') return;
+    await zap('replacer/action/addRule', {
+        description: RULE_DESC,
+        enabled: 'true',
+        matchType: 'REQ_HEADER',
+        matchString: 'Cookie',
+        matchRegex: 'false',
+        replacement: cookie,
+    });
+}
+
+// One method against one target. confirmed / not-confirmed come from ZAP; a thrown
+// ZAP error becomes could-not-test.
+async function scanOnce(t: Target, verb: 'GET' | 'POST', trigger: string): Promise<Outcome> {
+    try {
+        const cookie = [AUTH, t.cookie].filter(Boolean).join('; ');
+        await setCookie(cookie);
+        const seedParams = [`${t.param}=test`, trigger].filter(Boolean).join('&');
+
+        // Seed the request so the URL is in ZAP's tree (the scan errors otherwise) and so
+        // the vulnerable branch actually runs before the scanner starts mutating the param.
+        let scanUrl = t.url;
+        let postData = '';
+        if (verb === 'GET') {
+            scanUrl = `${t.url}?${seedParams}`;
+            await zap('core/action/accessUrl', { url: scanUrl, followRedirects: 'false' });
+        } else {
+            postData = seedParams;
+            const { pathname, host } = new URL(t.url);
+            const req =
+                `POST ${pathname} HTTP/1.1\r\n` +
+                `Host: ${host}\r\n` +
+                (cookie ? `Cookie: ${cookie}\r\n` : '') +
+                `Content-Type: application/x-www-form-urlencoded\r\n` +
+                `Content-Length: ${Buffer.byteLength(postData)}\r\n\r\n${postData}`;
+            await zap('core/action/sendRequest', { request: req, followRedirects: 'false' });
+        }
+
+        // Only the finding's own rule runs. The policy is global state, so groups go
+        // one at a time. ponytail: sequential scans, parallelise per-rule policies if it's ever too slow.
+        await zap('ascan/action/disableAllScanners', { scanPolicyName: '' });
+        await zap('ascan/action/enableScanners', { ids: t.zapRule, scanPolicyName: '' });
+
+        const started = await zap('ascan/action/scan', {
+            url: scanUrl,
+            method: verb,
+            postData,
+            recurse: 'false',
+            inScopeOnly: 'false',
+        });
+        const scanId = String(started.scan);
+
+        const deadline = Date.now() + SCAN_TIMEOUT_MS;
+        for (;;) {
+            const status = String((await zap('ascan/view/status', { scanId })).status);
+            if (status === '100') break;
+            if (Date.now() > deadline) {
+                await zap('ascan/action/stop', { scanId }).catch(() => undefined);
+                return { zap: 'could-not-test', detail: `scan timed out after ${SCAN_TIMEOUT_MS / 1000}s` };
+            }
+            await sleep(POLL_MS);
+        }
+
+        const alertIds = (await zap('ascan/view/alertsIds', { scanId })).alertsIds as string[];
+        const pluginIds: string[] = [];
+        for (const id of alertIds) {
+            const alert = (await zap('core/view/alert', { id })).alert as { pluginId?: string | number } | undefined;
+            if (alert?.pluginId !== undefined) pluginIds.push(String(alert.pluginId));
+        }
+        const verdict = classify(t.zapRule, pluginIds);
+        const hits = pluginIds.filter((p) => p === t.zapRule).length;
+        return {
+            zap: verdict,
+            detail: verdict === 'confirmed' ? `ZAP rule ${t.zapRule} raised ${hits} alert(s) via ${verb}` : `ZAP rule ${t.zapRule} ran via ${verb} and raised none`,
+        };
+    } catch (e) {
+        return { zap: 'could-not-test', detail: `${verb}: ${(e as Error).message}` };
+    }
+}
+
+// A target may need more than one method (REQUEST). confirmed wins; otherwise
+// not-confirmed if any method actually ran; could-not-test only if none could.
+async function scanGroup(t: Target, trigger: string): Promise<Outcome> {
+    // Not "not-confirmed": that would say ZAP tried and failed, when it never got in.
+    if (t.untestable !== undefined) return { zap: 'could-not-test', detail: t.untestable };
+    const verbs = methods(t.from);
+    if (verbs.length === 0) {
+        return { zap: 'could-not-test', detail: `input comes from a ${t.from.toLowerCase()}, not a request parameter this scan can mutate` };
+    }
+    const outcomes: Outcome[] = [];
+    for (const verb of verbs) {
+        const outcome = await scanOnce(t, verb, trigger);
+        if (outcome.zap === 'confirmed') return outcome;
+        outcomes.push(outcome);
+    }
+    return outcomes.find((o) => o.zap === 'not-confirmed') ?? outcomes[0]!;
+}
+
+async function main(): Promise<void> {
+    const [reportPath, configPath] = process.argv.slice(2);
+    if (reportPath === undefined || configPath === undefined) {
+        console.error('usage: DAST_COOKIE=PHPSESSID=... node dist/src/dast/zap.js report.json urls.json');
+        process.exit(1);
+    }
+    const report = JSON.parse(readFileSync(reportPath, 'utf8')) as { findings: Finding[] };
+    const config = JSON.parse(readFileSync(configPath, 'utf8')) as Config;
+    const { targets, skipped, noUrl } = buildTargets(report, config);
+    const trigger = config.trigger ?? '';
+
+    // One scan per group; its outcome fills every target in the group.
+    const byKey = new Map<string, Outcome>();
+    let done = 0;
+    for (const t of targets) {
+        const key = groupKey(t);
+        if (byKey.has(key)) continue;
+        process.stderr.write(`[${++done}] ${t.rule} ${t.from} ${t.url} (${t.param}) ... `);
+        const outcome = await scanGroup(t, t.trigger ?? trigger);
+        byKey.set(key, outcome);
+        process.stderr.write(`${outcome.zap}\n`);
+    }
+
+    const results = joinResults(targets, byKey);
+    if (results.length !== targets.length) {
+        throw new Error(`dropped targets: ${targets.length} in, ${results.length} out`);
+    }
+
+    console.log(JSON.stringify(results, null, 2));
+
+    const n = (v: Verdict): number => results.filter((r) => r.zap === v).length;
+    console.error(
+        `\n${results.length} findings tested: ${n('confirmed')} confirmed, ${n('not-confirmed')} not confirmed, ${n('could-not-test')} could not test.` +
+            `\nBefore ZAP: ${skipped} proven findings had no ZAP rule or named input, ${noUrl} had no URL.` +
+            `\nA not-confirmed finding stays a finding: ZAP reproducing nothing does not clear what Defuse traced.`,
+    );
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    void main();
+}

package/src/engine/scan.ts

@@ -0,0 +1,200 @@
+/**
+ * THE NODE SHELL
+ * ==============
+ *
+ * Everything that only makes sense on a machine with a filesystem: walking a
+ * directory, honouring --exclude, reading bytes, and shortening paths against
+ * the working directory so terminal output stays readable.
+ *
+ * The analysis itself is NOT here. It moved to src/core/analyze.ts when the
+ * browser UI arrived, so the web version could run the same code rather than a
+ * lookalike. What is left is the pipeline seam:
+ *
+ *   collectFiles  ->  read text  ->  analyze()  ->  a ScanResult
+ *
+ * If you find yourself wanting to change how a FINDING is produced, this is the
+ * wrong file - that belongs in core/analyze.ts, where the browser sees it too.
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { analyze, type AnalysisResult, type SourceFile } from '../core/analyze.js';
+import { buildCoverageReport, type CoverageReport } from '../core/coverage.js';
+import type { Finding } from '../core/finding.js';
+import { SCANNABLE_EXTENSIONS } from '../parse/languages.js';
+import { useNodeGrammars } from '../parse/node-grammars.js';
+import { checkRuntimeVersions, RUNTIME_VERSION_RULE, type RuntimeCheckResult } from '../platform/runtime-version.js';
+import type { DependencyReport } from '../platform/dependency-rule.js';
+import { collectFiles } from './walk.js';
+
+export type { FileParseProblem, Suppression } from '../core/analyze.js';
+
+export interface ScanOptions {
+  /** Only run these rule ids. Empty = all. */
+  readonly only?: readonly string[];
+  /** Glob-ish paths to skip entirely. Reported, never silently applied. */
+  readonly exclude?: readonly string[];
+  /** Turn off cross-file resolution (faster, less memory, fewer findings). */
+  readonly noCrossFile?: boolean;
+  /** Print progress to stderr. */
+  readonly onProgress?: (done: number, total: number, file: string) => void;
+}
+
+export interface ScanResult {
+  readonly target: string;
+  readonly findings: readonly Finding[];
+  /** Lines the tracer proved safe. Reported so "clean" can mean "checked". */
+  readonly verifiedClean: AnalysisResult['verifiedClean'];
+  /** Branches and cases not followed because they cannot run, with the reason. */
+  readonly unreachableCode: AnalysisResult['unreachableCode'];
+  /** Map and list reads answered by key or position, with the write that answers each. */
+  readonly collectionReadsResolved: AnalysisResult['collectionReadsResolved'];
+  /** Calls where a trace ended because the result is new data, not the argument. */
+  readonly tracesStoppedAtNewData: AnalysisResult['tracesStoppedAtNewData'];
+  /**
+   * Which PHP the project declares, and what php.net's facts say about it -
+   * platform/runtime-version.ts. Null when --only left the check out.
+   */
+  readonly runtimeVersions: RuntimeCheckResult | null;
+  /**
+   * What `scan --deps` read and asked osv.dev. Absent when the check did not run -
+   * scan() never sets it; the CLI adds it, because it is the one network call.
+   */
+  readonly dependencies?: DependencyReport;
+  /** Per-file participation, so a file a flow passes through is never "clean". */
+  readonly fileRoles: AnalysisResult['fileRoles'];
+  /** Where the tracer ran out, counted for this scan. */
+  readonly traceLimits: AnalysisResult['traceLimits'];
+  readonly stats: AnalysisResult['stats'] & {
+    readonly filesFound: number;
+    readonly filesWithParseErrors: number;
+  };
+  readonly byLanguage: AnalysisResult['byLanguage'];
+  readonly parseProblems: AnalysisResult['parseProblems'];
+  readonly oversizedFiles: readonly string[];
+  /** What --exclude removed. A gap the user chose is still a gap worth printing. */
+  readonly excluded: {
+    readonly patterns: readonly string[];
+    readonly fileCount: number;
+    readonly directories: readonly string[];
+  };
+  /** Findings the code explicitly asked us to ignore. Reported, never hidden. */
+  readonly suppressions: AnalysisResult['suppressions'];
+  readonly coverage: CoverageReport;
+  /** How cross-file resolution went. */
+  readonly crossFile: AnalysisResult['crossFile'];
+  /** What the scan spent on syntax trees, and whether it had to spill. */
+  readonly treeMemory: AnalysisResult['treeMemory'];
+}
+
+export async function scan(target: string, options: ScanOptions = {}): Promise<ScanResult> {
+  // Tell the parser it is running on Node before anything loads a grammar.
+  // The browser worker makes the equivalent call with its own loader.
+  useNodeGrammars();
+
+  const walk = await collectFiles(target, {
+    scannable: SCANNABLE_EXTENSIONS,
+    exclude: options.exclude ?? [],
+  });
+
+  // Read the text. A file we cannot read simply never reaches the analyzer;
+  // it shows up as the gap between filesFound and filesParsed.
+  const inputs: SourceFile[] = [];
+  for (const filePath of walk.files) {
+    try {
+      inputs.push({ path: filePath, source: await readFile(filePath, 'utf8') });
+    } catch {
+      // permissions, a broken symlink, a race with a build tool
+    }
+  }
+
+  /**
+   * DEFUSE_TREE_BUDGET_MB - how much WebAssembly heap the scan may hold in syntax
+   * trees before it starts freeing the least recently used one.
+   *
+   * An environment variable rather than a flag, deliberately. It exists to be
+   * turned down hard in testing: the interesting question about the tree store
+   * is not "does it work when nothing is ever evicted" but "are the findings
+   * still identical when almost everything is". A budget of 1 MB forces a
+   * re-parse for nearly every cross-file hop, which is exactly the condition
+   * the identity check should be run under.
+   *
+   * Anyone who genuinely needs it in production can set it, and the value used
+   * is printed in the report either way.
+   */
+  const budgetMb = Number(process.env['DEFUSE_TREE_BUDGET_MB']);
+  const treeBudget =
+    Number.isFinite(budgetMb) && budgetMb > 0 ? Math.round(budgetMb * 1024 * 1024) : undefined;
+
+  const result = await analyze(inputs, {
+    ...(options.only ? { only: options.only } : {}),
+    ...(options.noCrossFile !== undefined ? { noCrossFile: options.noCrossFile } : {}),
+    ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+    ...(treeBudget !== undefined ? { treeBudgetBytes: treeBudget } : {}),
+    toDisplay: (absolutePath) => path.relative(process.cwd(), absolutePath) || absolutePath,
+  });
+
+  /*
+   * THE RUNTIME VERSION CHECK reads declarations, not code, so it runs beside
+   * the analysis rather than inside it. Its findings join the same list - a
+   * PHP release with a known critical flaw belongs next to the code problems,
+   * not in a footnote - and they are all signature-based by construction.
+   */
+  const runtimeVersions =
+    !options.only || options.only.length === 0 || options.only.includes(RUNTIME_VERSION_RULE.id)
+      ? await (async () => {
+          const files = [];
+          for (const filePath of walk.runtimeFiles) {
+            try {
+              files.push({
+                path: path.relative(process.cwd(), filePath) || filePath,
+                text: await readFile(filePath, 'utf8'),
+              });
+            } catch {
+              // unreadable - same treatment as a source file
+            }
+          }
+          return checkRuntimeVersions(files, {
+            today: new Date().toISOString().slice(0, 10),
+            phpFilesScanned: result.byLanguage['php'] ?? 0,
+          });
+        })()
+      : null;
+
+  return {
+    target,
+    findings: [...result.findings, ...(runtimeVersions?.findings ?? [])],
+    verifiedClean: result.verifiedClean,
+    unreachableCode: result.unreachableCode,
+    collectionReadsResolved: result.collectionReadsResolved,
+    tracesStoppedAtNewData: result.tracesStoppedAtNewData,
+    runtimeVersions,
+    fileRoles: result.fileRoles,
+    traceLimits: result.traceLimits,
+    stats: {
+      ...result.stats,
+      filesFound: walk.files.length,
+      filesSkipped: walk.files.length - result.stats.filesParsed,
+      filesWithParseErrors: result.parseProblems.length,
+    },
+    byLanguage: result.byLanguage,
+    parseProblems: result.parseProblems,
+    oversizedFiles: walk.oversizedFiles,
+    excluded: {
+      patterns: options.exclude ?? [],
+      fileCount: walk.excludedCount,
+      directories: walk.excludedDirectories,
+    },
+    suppressions: result.suppressions,
+    crossFile: result.crossFile,
+    treeMemory: result.treeMemory,
+    // Rebuilt here because only the walker knows which file types it passed
+    // over - the analyzer never saw them.
+    coverage: buildCoverageReport(
+      [...walk.skippedByExtension.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 12)
+        .map(([ext, count]) => `${ext} (${count} file${count === 1 ? '' : 's'})`),
+    ),
+  };
+}