@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/src/core/paths.ts

@@ -0,0 +1,59 @@
+/**
+ * PATH HELPERS WITH NO PLATFORM ATTACHED
+ *
+ * `node:path` was the last thing standing between the analysis code and a
+ * browser. The import graph needs to join and normalise paths, and Node's
+ * version of that pulls in a runtime the browser does not have.
+ *
+ * These are the four operations the resolver actually uses, written in plain
+ * JavaScript over forward slashes. Windows paths are normalised on the way in,
+ * so `C:\\src\\db.ts` and `C:/src/db.ts` compare equal - which matters, because
+ * a path that fails to match is an import edge silently not resolved.
+ */
+
+/** Backslashes to forward slashes. Everything else here assumes this ran. */
+export function toPosix(filePath: string): string {
+  return filePath.replace(/\\/g, '/');
+}
+
+/** Collapse `.` and `..` segments. Keeps a leading `/` or a `C:` drive. */
+export function normalizePath(filePath: string): string {
+  const posix = toPosix(filePath);
+  const absolute = posix.startsWith('/');
+  const parts: string[] = [];
+
+  for (const segment of posix.split('/')) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') {
+      const last = parts[parts.length - 1];
+      if (parts.length > 0 && last !== '..') parts.pop();
+      else if (!absolute) parts.push('..');
+      continue;
+    }
+    parts.push(segment);
+  }
+  return (absolute ? '/' : '') + parts.join('/');
+}
+
+export function dirnameOf(filePath: string): string {
+  const posix = toPosix(filePath);
+  const cut = posix.lastIndexOf('/');
+  if (cut < 0) return '';
+  return cut === 0 ? '/' : posix.slice(0, cut);
+}
+
+export function basenameOf(filePath: string): string {
+  const posix = toPosix(filePath);
+  return posix.slice(posix.lastIndexOf('/') + 1);
+}
+
+export function joinPath(...parts: readonly string[]): string {
+  return normalizePath(parts.filter(Boolean).join('/'));
+}
+
+/** Resolve a relative specifier against a directory. */
+export function resolveFrom(directory: string, relative: string): string {
+  const posix = toPosix(relative);
+  if (posix.startsWith('/')) return normalizePath(posix);
+  return normalizePath(`${toPosix(directory)}/${posix}`);
+}

package/src/core/score.ts

@@ -0,0 +1,353 @@
+/**
+ * THE GAUGES
+ * ==========
+ *
+ * Three needles. They are never added together, and this file will not let
+ * them be - there is no `overallScore` export, and there never should be.
+ *
+ * WHY THAT MATTERS. The comment at the top of finding.ts says it best:
+ *
+ *   "Severity = how bad is this if it turns out to be real? Deliberately
+ *    separate from confidence, which is how sure are we it's real?
+ *    Conflating those two numbers is the single most common lie in SAST
+ *    tooling: a tool shows one 'risk' bar and you cannot tell whether it
+ *    means 'probably harmless but catastrophic if not' or 'definitely real
+ *    but minor'."
+ *
+ * A single 0-500 risk dial IS that bar. So the dial got split along the exact
+ * line the project already draws:
+ *
+ *   VERIFIED EXPOSURE    severity, over findings we PROVED reach a sink
+ *   UNVERIFIED SURFACE   severity, over findings we only pattern-matched
+ *   ANALYSIS COVERAGE    how much of the code we could actually reason about
+ *
+ * Two of those are the same weights over two different confidence levels, kept
+ * side by side so you can see the shape of what is proven against the shape of
+ * what is merely suspected. Reading them together is the point; averaging them
+ * would destroy it.
+ *
+ * Every reading carries its own arithmetic in `working`, so the number can be
+ * CHECKED rather than believed. That is the whole standard here: a score you
+ * cannot recompute by hand is a vibe with a decimal point on it.
+ */
+
+import type { Finding, Severity } from './finding.js';
+import type { AnalysisResult } from './analyze.js';
+
+/**
+ * How much one finding contributes, by severity.
+ *
+ * These are a judgement, not a measurement, and calling them anything else
+ * would be the first lie. What makes them defensible is that they are FIXED,
+ * PUBLISHED and applied identically to both severity gauges - so while the
+ * absolute number is arbitrary, every comparison made with it is real: two
+ * criticals always outweigh three mediums, in both directions, in both shells.
+ */
+export const SEVERITY_WEIGHT: Readonly<Record<Severity, number>> = {
+  critical: 25,
+  high: 15,
+  medium: 7,
+  low: 3,
+  info: 1,
+};
+
+/** The top of the severity dials. A sum past this is reported, not hidden. */
+export const GAUGE_MAX = 500;
+
+export interface GaugeReading {
+  readonly id: 'verified-exposure' | 'unverified-surface' | 'analysis-coverage';
+  readonly label: string;
+  /** Where the needle sits. Already clamped to [0, max]. */
+  readonly value: number;
+  readonly max: number;
+  readonly unit: '' | '%';
+  /** One line under the needle: what it means, and what it does NOT mean. */
+  readonly meaning: string;
+  /** The arithmetic. Anyone can recompute the value from these lines. */
+  readonly working: readonly string[];
+  /**
+   * The raw total before clamping. Equal to `value` unless the scan blew past
+   * the top of the dial, in which case the dial is pinned and this is the
+   * truth. A pinned needle that quietly stops counting is a lie by omission.
+   */
+  readonly rawTotal: number;
+  readonly capped: boolean;
+  /**
+   * True when there was nothing to measure, as distinct from measuring zero.
+   *
+   * These are not the same fact and must never be drawn the same way. A scan of
+   * an empty file and a scan of ten lines of careful, correctly parameterised
+   * code both produced "0 findings, 94% coverage, no blind spots" - identical
+   * dashboards for "we checked and found nothing" and "there was nothing to
+   * check". The second is a result; the first is the absence of one.
+   */
+  readonly noReading: boolean;
+  /**
+   * What the total is MADE OF, largest severity first.
+   *
+   * A single needle throws this away, and on real code it throws away almost
+   * everything: across the corpus the severity dials sit between 0% and 24% of
+   * their scale, so the arc is a stub and the stub is all you get. "75" cannot
+   * tell you whether that is three criticals or twenty-five lows, and those are
+   * different afternoons.
+   *
+   * Empty for the coverage gauge, which is a ratio and has no composition.
+   */
+  readonly segments: readonly {
+    readonly severity: Severity;
+    readonly count: number;
+    readonly weight: number;
+    /** Share of this gauge's own total, 0-1. Zero when the total is zero. */
+    readonly share: number;
+  }[];
+}
+
+export interface ScoreReport {
+  readonly gauges: readonly GaugeReading[];
+  /**
+   * Nothing in this scan could be analysed - no statement, call or assignment
+   * ever reached a rule. Every reading below is vacuous when this is true, and
+   * any surface showing them has to say so rather than printing zeroes.
+   */
+  readonly examinedNothing: boolean;
+  /** Code constructs the rules actually looked at. The denominator of trust. */
+  readonly shapesExamined: number;
+  /**
+   * Places this scan is known to have stopped early. Not a gauge, because a
+   * count of blind spots is not a measurement of risk - but printed beside the
+   * gauges, because it is what tells you how much of the dial to trust.
+   */
+  readonly blindSpots: readonly { readonly label: string; readonly count: number }[];
+  /**
+   * How many attacker-controlled SOURCES the tracer recognised in this scan.
+   *
+   * Reported ALWAYS, including - especially - when it is zero, which is why it
+   * cannot live in blindSpots above: that list drops anything with a count of
+   * zero, and zero is the interesting reading here.
+   *
+   * Elasticsearch is why. 3,999 Java files, a REST API over the network, and
+   * zero flow-verified findings. It contains 0 `@RequestParam` and 0
+   * `getParameter()` - it has its own REST layer, which the dictionaries do not
+   * model, so there was never a source to start a trace from. "0 flows proven"
+   * read like good news and was actually "we could not begin".
+   *
+   * Every flow number in a report is downstream of this one.
+   */
+  readonly sourcesFound: number;
+}
+
+function weigh(findings: readonly Finding[]): { total: number; bySeverity: Map<Severity, number> } {
+  const bySeverity = new Map<Severity, number>();
+  let total = 0;
+  for (const finding of findings) {
+    bySeverity.set(finding.severity, (bySeverity.get(finding.severity) ?? 0) + 1);
+    total += SEVERITY_WEIGHT[finding.severity];
+  }
+  return { total, bySeverity };
+}
+
+const ORDER: readonly Severity[] = ['critical', 'high', 'medium', 'low', 'info'];
+
+function showWorking(bySeverity: Map<Severity, number>, total: number): string[] {
+  const lines = ORDER.filter((s) => bySeverity.get(s)).map((s) => {
+    const n = bySeverity.get(s) ?? 0;
+    return `${n} ${s} x ${SEVERITY_WEIGHT[s]} = ${n * SEVERITY_WEIGHT[s]}`;
+  });
+  if (lines.length === 0) return ['nothing in this category'];
+  if (lines.length > 1) lines.push(`total = ${total}`);
+  return lines;
+}
+
+function severityGauge(
+  id: 'verified-exposure' | 'unverified-surface',
+  label: string,
+  meaning: string,
+  findings: readonly Finding[],
+  examinedNothing: boolean,
+): GaugeReading {
+  const { total, bySeverity } = weigh(findings);
+  const working = showWorking(bySeverity, total);
+  if (total > GAUGE_MAX) {
+    working.push(`past the top of the dial by ${total - GAUGE_MAX} - needle pinned at ${GAUGE_MAX}`);
+  }
+  const segments = ORDER.filter((s) => bySeverity.get(s)).map((severity) => {
+    const count = bySeverity.get(severity) ?? 0;
+    const weight = count * SEVERITY_WEIGHT[severity];
+    return { severity, count, weight, share: total > 0 ? weight / total : 0 };
+  });
+
+  return {
+    id,
+    label,
+    value: Math.min(total, GAUGE_MAX),
+    max: GAUGE_MAX,
+    unit: '',
+    meaning,
+    working,
+    rawTotal: total,
+    capped: total > GAUGE_MAX,
+    noReading: examinedNothing,
+    segments,
+  };
+}
+
+/**
+ * How much of the analysis actually completed.
+ *
+ * This is the gauge no other scanner shows, and it is the one that tells you
+ * how to read the other two. A verified-exposure of 0 means something very
+ * different at 95% coverage than at 30%: the first is reassuring, the second
+ * means we barely looked.
+ *
+ * It is an average of the ratios we can genuinely compute, and each one is
+ * listed in `working` so an average that hides a bad component cannot pass
+ * unnoticed. Ratios we cannot compute are OMITTED rather than assumed to be
+ * 100% - an unmeasured thing is not a passing thing.
+ */
+function coverageGauge(result: AnalysisResult, filesFound: number, examinedNothing: boolean): GaugeReading {
+  const working: string[] = [];
+  const parts: number[] = [];
+
+  const found = filesFound || result.stats.filesParsed;
+  if (found > 0) {
+    const rate = result.stats.filesParsed / found;
+    parts.push(rate);
+    working.push(`files read: ${result.stats.filesParsed}/${found} = ${Math.round(rate * 100)}%`);
+  }
+
+  const { rules, languages, implemented, partial } = result.coverage.counts;
+  const cells = rules * languages;
+  if (cells > 0) {
+    // A partial rule counts as half. It does something; it does not do the job.
+    const rate = (implemented + partial * 0.5) / cells;
+    parts.push(rate);
+    working.push(
+      `rules available: ${implemented} full + ${partial} partial of ${cells} = ${Math.round(rate * 100)}%`,
+    );
+  }
+
+  if (result.crossFile.enabled) {
+    /*
+     * A local import that resolved to nothing is a module the analysis never
+     * entered. Leaving it out of the mean let a scan that linked 0 of 31 imports
+     * read 82%, because no call could even be attempted across the gap.
+     */
+    const imports = result.crossFile.importEdges + result.crossFile.importsUnresolved;
+    if (imports > 0) {
+      const rate = result.crossFile.importEdges / imports;
+      parts.push(rate);
+      working.push(
+        `local imports resolved: ${result.crossFile.importEdges}/${imports} = ${Math.round(rate * 100)}%`,
+      );
+    }
+    const attempts = result.crossFile.resolved + result.crossFile.ambiguous;
+    if (attempts > 0) {
+      const rate = result.crossFile.resolved / attempts;
+      parts.push(rate);
+      working.push(
+        `cross-file calls followed: ${result.crossFile.resolved}/${attempts} = ${Math.round(rate * 100)}%`,
+      );
+    } else {
+      working.push('cross-file calls followed: none attempted, so not counted');
+    }
+  } else {
+    working.push('cross-file resolution was OFF, so it is not counted here');
+  }
+
+  // Stated first, because it is the denominator everything else divides into.
+  // "94% of the analysis completed" is not a useful sentence when the analysis
+  // had nothing to run on.
+  working.unshift(`code constructs examined: ${result.stats.shapesExamined}`);
+
+  const value = parts.length > 0 ? Math.round((parts.reduce((a, b) => a + b, 0) / parts.length) * 100) : 0;
+  if (parts.length > 1) working.push(`mean of ${parts.length} measured ratios = ${value}%`);
+
+  return {
+    id: 'analysis-coverage',
+    label: 'Analysis coverage',
+    value,
+    max: 100,
+    unit: '%',
+    meaning: examinedNothing
+      ? 'Nothing in this scan could be analysed - not one statement, call or ' +
+        'assignment reached a rule. There is no coverage figure to give, because ' +
+        'there was nothing to cover. This is not a clean result; it is no result.'
+      : 'How much of the analysis actually completed. This is not a security score - ' +
+        'it is how much weight the other two dials can carry. Low coverage with no ' +
+        'findings means we barely looked, not that the code is fine.',
+    working,
+    rawTotal: value,
+    capped: false,
+    noReading: examinedNothing,
+    // A ratio has no composition to show. Empty rather than faked.
+    segments: [],
+  };
+}
+
+/**
+ * Build all three readings.
+ *
+ * `filesFound` comes from the walker (Node) or the drop handler (browser), so
+ * it is passed in rather than read off the result - the analyzer only ever
+ * sees the files that made it that far.
+ */
+export function scoreAnalysis(result: AnalysisResult, filesFound = 0): ScoreReport {
+  const verified = result.findings.filter((f) => f.confidence === 'flow-verified');
+  const signature = result.findings.filter((f) => f.confidence === 'signature-based');
+  // Not one statement, call or assignment reached a rule. Parsing a file is not
+  // the same as analysing it: a file of whitespace parses perfectly.
+  const examinedNothing = result.stats.shapesExamined === 0;
+
+  const gauges: GaugeReading[] = [
+    severityGauge(
+      'verified-exposure',
+      'Verified exposure',
+      'Severity weight of findings where attacker data was TRACED into the sink. ' +
+        'Every point here is backed by a printed path. Zero means no flow was proven - ' +
+        'it does not mean none exists.',
+      verified,
+      examinedNothing,
+    ),
+    severityGauge(
+      'unverified-surface',
+      'Unverified surface',
+      'The same weights over findings we only pattern-matched. Deliberately a ' +
+        'separate needle: these may be real or may be false positives, and averaging ' +
+        'them into the proven ones would hide which is which.',
+      signature,
+      examinedNothing,
+    ),
+    coverageGauge(result, filesFound, examinedNothing),
+  ];
+
+  // These are SCAN-WIDE counts, not a tally of what appears in the findings
+  // above. A trace can pass through an unmodelled function and then never reach
+  // a sink, so this number is legitimately larger than the unmodelled hops you
+  // can see in the printed paths. Saying "3" while the paths show 2 looks like
+  // an error until the label admits which population it is counting.
+  const blindSpots = [
+    {
+      label: 'expressions too deeply nested to walk (generated or minified code)',
+      count: result.traceLimits.astTruncations,
+    },
+    { label: 'call chains cut at the depth limit', count: result.traceLimits.depthTruncations },
+    { label: 'recursive calls not re-entered', count: result.traceLimits.recursionStops },
+    {
+      label: 'unmodelled functions stepped through (scan-wide, not only on reported paths)',
+      count: result.traceLimits.unmodelledHops,
+    },
+    {
+      label: 'cross-file calls declined as ambiguous',
+      count: result.crossFile.enabled ? result.crossFile.ambiguous : 0,
+    },
+    { label: 'files that did not fully parse', count: result.parseProblems.length },
+  ].filter((spot) => spot.count > 0);
+
+  return {
+    gauges,
+    examinedNothing,
+    shapesExamined: result.stats.shapesExamined,
+    blindSpots,
+    sourcesFound: result.traceLimits.sourcesFound,
+  };
+}

package/src/dast/targets.ts

@@ -0,0 +1,121 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { Finding } from '../core/finding.js';
+
+export const ZAP_RULE: Record<string, string> = {
+    'sql-injection': '40018',
+    'xss': '40012',
+    'command-injection': '90020',
+    'code-injection': '90019',
+    'ssrf': '40046',
+    'path-traversal': '6',
+};
+
+export interface Target {
+    id: string;
+    rule: string;
+    zapRule: string;
+    file: string;
+    url: string;
+    cookie: string;
+    from: string;
+    param: string;
+    trigger?: string; // extra form fields this page needs before its code runs
+    untestable?: string; // why ZAP cannot reach this page's code at all
+}
+
+// Where the site runs, where its code sits on disk, and which file is served at which address.
+// Each rule is [pattern, url, cookie?, fields?] on the file path; the first rule that matches wins.
+// A pattern should match the WHOLE path (^...$): the url, cookie and fields are built by replacing what it matched.
+// fields is what the page checks for before its code runs (DVWA's brute page wants Login=Login, not
+// the config-wide trigger), or {untestable: reason} when that check is one the scan cannot pass.
+export type Fields = string | { untestable: string };
+export interface UrlConfig {
+    base: string;
+    root: string;
+    rules: [string, string, string?, Fields?][];
+}
+
+export interface BuiltTargets {
+    targets: Target[];
+    skipped: number; // proven findings with no ZAP rule or no named request input
+    noUrl: number; // proven, testable findings whose file matched no URL rule
+}
+
+// No matching rule means no URL: a file that is only included by other files has no address of its own.
+function toAddress(
+    config: UrlConfig,
+    file: string,
+): { url: string; cookie: string; trigger?: string; untestable?: string } | undefined {
+    const relative = path.relative(config.root, file).replaceAll('\\', '/');
+    for (const [pattern, url, cookie, fields] of config.rules) {
+        const rule = new RegExp(pattern);
+        if (rule.test(relative)) {
+            return {
+                url: new URL(relative.replace(rule, url), config.base).href,
+                cookie: cookie === undefined ? '' : relative.replace(rule, cookie),
+                ...(typeof fields === 'string' ? { trigger: relative.replace(rule, fields) } : {}),
+                ...(typeof fields === 'object' ? { untestable: fields.untestable } : {}),
+            };
+        }
+    }
+    return undefined;
+}
+
+// Defuse's proven findings -> the list of addresses ZAP should try. A finding is a target only
+// when it is flow-verified, has a ZAP rule, names a request input, and its file has a URL.
+export function buildTargets(report: { findings: Finding[] }, config: UrlConfig): BuiltTargets {
+    const targets: Target[] = [];
+    let skipped = 0;
+    let noUrl = 0;
+
+    for (const f of report.findings) {
+        if (f.confidence !== 'flow-verified') continue;
+        const zapRule = ZAP_RULE[f.ruleId];
+        const source = f.flowPath.find((step) => step.kind === 'source');
+        const match = source && /\$_(GET|POST|REQUEST|COOKIE)\[\s*['"]([^'"]+)['"]\s*\]/.exec(source.location.snippet);
+        if (zapRule === undefined || !match) {
+            skipped++;
+            continue;
+        }
+        const address = toAddress(config, f.location.file);
+        if (address === undefined) {
+            noUrl++;
+            continue;
+        }
+        targets.push({
+            id: `${f.ruleId}:${f.location.file}:${f.location.startLine}`,
+            rule: f.ruleId,
+            zapRule,
+            file: f.location.file,
+            url: address.url,
+            cookie: address.cookie,
+            from: match[1] ?? '',
+            param: match[2] ?? '',
+            ...(address.trigger !== undefined ? { trigger: address.trigger } : {}),
+            ...(address.untestable !== undefined ? { untestable: address.untestable } : {}),
+        });
+    }
+
+    return { targets, skipped, noUrl };
+}
+
+function main(): void {
+    const [reportPath, configPath] = process.argv.slice(2);
+    if (reportPath === undefined || configPath === undefined) {
+        console.error('usage: node dist/src/dast/targets.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 UrlConfig;
+    const { targets, skipped, noUrl } = buildTargets(report, config);
+    console.log(JSON.stringify(targets, null, 2));
+    console.error(
+        `${targets.length} targets; ${skipped} proven findings skipped (no ZAP rule or no named request input); ${noUrl} skipped (no URL rule matched the file)`,
+    );
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main();
+}