security: bound scan fan-out with a shared DNS budget + overall deadline

Orchestrator-level DoS umbrella for GHSA-f828-8wf8-vqp2. scan()/scanStreaming()
previously awaited Promise.all across all analyzers with only a per-query 3s DNS
timeout — no aggregate cap on total DNS queries or wall-clock. A single request
combining a large DKIM selector list with a rua/ruf-stuffed _dmarc record on an
attacker-controlled domain could drive a large outbound-DNS burst and long
wall-clock on one rate-limit token.

Adds two backstops, both threaded through every analyzer:
- ScanBudget (src/dns/scan-budget.ts): one shared per-scan DNS-query pool that
  every queryTxt/queryMx/queryDoh draws from; exhaustion throws a DnsLookupError
  subclass so analyzers degrade to "could not verify" instead of crashing.
- Overall deadline: one AbortController + setTimeout; each settled analyzer is
  raced against it, degrading to its synthetic fallback on a breach. The budget
  also holds the signal, so no new query is issued past the deadline.

Defaults (DEFAULT_SCAN_LIMITS): 150 queries / 12s — generous for real
multi-analyzer scans, overridable via an optional `limits` param (tests).
Preserves the #378 per-analyzer settle contract and scanStreaming SSE semantics
(every protocol still streams exactly once). DnsLookupError moved to
src/dns/errors.ts so the budget can subclass it without depending on the DNS
client (which tests mock).

Refs GHSA-f828-8wf8-vqp2. Umbrella over the per-analyzer caps in #539.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: schmug <38227427+schmug@users.noreply.github.com>

Author: schmug

CLAUDE.md

@@ -27,7 +27,8 @@ Live at dmarc.mx | Repo: github.com/schmug/dmarcheck
 - `src/index.ts` — Hono routes, content negotiation, rate limiting middleware
 - `src/dns/client.ts` — DNS abstraction over node:dns (NXDOMAIN returns null)
 - `src/analyzers/` — One module per protocol (dmarc, spf, dkim, bimi, mta-sts, mx, security-txt)
-- `src/orchestrator.ts` — Runs all analyzers in parallel and isolates each one: a single analyzer rejection surfaces as a synthetic `status: "fail"` result (with an `analyzer_error` validation; `lookup_error.code` on the types that carry it) instead of aborting the whole scan. Implemented via a per-analyzer `settle` wrapper so one failure never takes down its siblings, for both `scan` and `scanStreaming` (#378).
+- `src/orchestrator.ts` — Runs all analyzers in parallel and isolates each one: a single analyzer rejection surfaces as a synthetic `status: "fail"` result (with an `analyzer_error` validation; `lookup_error.code` on the types that carry it) instead of aborting the whole scan. Implemented via a per-analyzer `settle` wrapper so one failure never takes down its siblings, for both `scan` and `scanStreaming` (#378). Both entrypoints also enforce two DoS backstops (GHSA-f828-8wf8-vqp2): a single overall deadline (one `AbortController` + `setTimeout`; each settled analyzer is raced against it via `raceDeadline`, degrading to its synthetic fallback on a breach) and one shared per-scan DNS-query budget (`ScanBudget`, threaded into every analyzer's DNS calls), so neither total outbound queries nor wall-clock can scale with attacker input. Limits come from `src/dns/scan-budget.ts` (`DEFAULT_SCAN_LIMITS`); both are overridable via the optional `limits` parameter (used by tests). A breach degrades gracefully — partial results with a note, never a throw — and `scanStreaming` still streams every protocol exactly once.
+- `src/dns/scan-budget.ts` — `ScanBudget` (shared per-scan DNS-query pool + deadline-`AbortSignal`) and `DEFAULT_SCAN_LIMITS` (`maxDnsQueries`, `deadlineMs`). `queryTxt`/`queryMx`/`queryDoh` call `budget?.consume()` before any outbound query; exhaustion/deadline throw `ScanBudgetError`/`ScanDeadlineError` (both subclass `DnsLookupError`, so analyzers surface them as "could not verify" rather than a false "not configured"). `DnsLookupError` itself lives in `src/dns/errors.ts` (re-exported from `client.ts`) so the budget can subclass it without depending on the DNS client, which tests frequently mock.
 - `src/shared/scoring.ts` — Grade computation (F if no DMARC or p=none). Knobs are configurable per-deploy via the `SCORING_CONFIG` env var (`src/shared/scoring-config.ts` parses/validates it; absent/invalid → shipped defaults, so hosted dmarc.mx is unaffected). `computeGrade`/`computeGradeBreakdown` take an optional `Partial<ScoringConfig>`; `scan`/`scanStreaming` require it (compile-time enforcement that every call site threads the active config)
 - `src/shared/learn-anchors.ts` — Single source of truth for validation→learn-page "How to fix" deep links (#524): analyzers set the optional `Validation.learnAnchor`, `src/views/learn.ts` renders the matching `id=` attributes from the same constants, and `test/learn-anchors.test.ts` asserts both sides so anchor ids can't drift
 - `src/cache.ts` — SSE result caching
@@ -85,6 +86,7 @@ Live at dmarc.mx | Repo: github.com/schmug/dmarcheck
 - **Branch protection:** `main` is governed by the `main-protection` repository ruleset: requires a PR, requires the `check` status check, and blocks deletions and non-fast-forward pushes. CodeQL (`Analyze (actions)`, `Analyze (javascript-typescript)`) still runs on every PR but must **NOT** be re-added as a required status check — requiring those contexts deadlocked all merges (the "ruleset merge trap"); they were deliberately removed. `required_approving_review_count` is **0** by design — autonomous Claude Code routines (see the `claude-routines` repo) open and auto-merge PRs unattended. The human-review gate is **path-scoped**, not blanket: `require_code_owner_review` is on, so any PR touching a path in `.github/CODEOWNERS` (CI, lockfiles, security invariants, input validation, redirect posture, rate limiting, DB migrations, analyzer modules, orchestration, scoring) requires a code-owner approval before merge. This hybrid keeps routine PRs autonomous while forcing a human on the security-sensitive minority. **CODEOWNERS scope decision (issue #300):** `src/analyzers/**`, `src/orchestrator.ts`, and `src/shared/scoring.ts` are intentionally gated — a malicious-issue-driven PR adding a new analyzer or modifying orchestration/scoring could exfiltrate DNS data or manipulate grades without this gate. Enforcement is only live once the bot-identity split (#299) lands (routines currently run as admin, which bypasses CODEOWNERS). The repo Admin role bypasses the ruleset (`bypass_actors`, mode `always`) — **the autonomous bot must run as a distinct non-admin identity, never the admin account**, or the ruleset is advisory for it and CODEOWNERS cannot be satisfied (no self-approval).
 - **Secret scanning:** Secret scanning, push protection, non-provider patterns, and validity checks are all enabled in repo settings. Never commit `.env`, tokens, or wrangler secrets.
 - **Input validation:** User-supplied domains are restricted to `[a-z0-9.-]` in `normalizeDomain` (`src/index.ts`). DKIM selectors are restricted to `[A-Za-z0-9._-]` in `parseSelectors`. HTML output never interpolates raw user input into inline `<script>` blocks — use `data-*` attributes via `esc()` instead.
+- **Scan fan-out cap (DoS, GHSA-f828-8wf8-vqp2):** the orchestrator bounds every scan with one overall deadline AND one shared per-scan DNS-query budget (`ScanBudget` from `src/dns/scan-budget.ts`, threaded through every analyzer into `queryTxt`/`queryMx`/`queryDoh`). This is the umbrella over the per-analyzer caps (DKIM selectors, MTA-STS body, DMARC rua/ruf): combining a large selector list with a rua/ruf-stuffed `_dmarc` record on an attacker-controlled domain cannot drive total outbound DNS or wall-clock past the limits, all on one rate-limit token. Do NOT remove the budget threading or the deadline race when editing the orchestrator or analyzers; keep DNS query calls drawing from the shared pool. A breach degrades gracefully (partial results + a note), never throws.
 - **MTA-STS fetch redirect mode:** `src/analyzers/mta-sts.ts` uses `redirect: "manual"` for the policy fetch. Do NOT change it to `"error"` — that throws in the Cloudflare Workers fetch runtime and breaks every scan (regressed twice via PRs #58 and #92). `"manual"` is RFC 8461 §3.3-compliant: redirects yield an opaque-redirect `Response` rejected by the existing `resp.type === "opaqueredirect"` / `!resp.ok` guards.
 - **security.txt fetch redirect mode:** `src/analyzers/security-txt.ts` deliberately uses `redirect: "follow"` (not `"manual"`) — RFC 9116 §3 does not forbid following redirects, and real-world deployments commonly redirect (e.g. gov.uk → www.gov.uk → vdp.cabinetoffice.gov.uk). MTA-STS's `manual` posture is a security requirement of RFC 8461 §3.3 specifically; security.txt has no equivalent rule, so the user-friendly choice is to follow.
 - **DCO sign-off & squash-merge default:** `.github/workflows/dco.yml` enforces a `Signed-off-by:` trailer on every non-bot PR commit (OSPS LE-01.01). The commit that lands on `main` keeps those trailers because the repo's squash default is `squash_merge_commit_message = COMMIT_MESSAGES` (GitHub pre-fills the squash body with the concatenated commit messages). **Do not change that setting to `PR_BODY`** — it would move the sign-off requirement to the PR description and reopen the gap. Bots are identified by `[bot]` in their author name, the `github-actions` author name, or the `cursoragent@cursor.com` author email (Cursor's cloud agent authors as "Cursor Agent" with no `[bot]` suffix); all other commits — including those using GitHub's privacy noreply email (`12345678+alice@users.noreply.github.com`) — are subject to DCO enforcement (#434).

src/analyzers/bimi.ts

@@ -1,4 +1,5 @@
 import { DnsLookupError, queryTxt } from "../dns/client.js";
+import type { ScanBudget } from "../dns/scan-budget.js";
 import type { TxtRecord } from "../dns/types.js";
 import { LEARN_ANCHORS, learnAnchorHref } from "../shared/learn-anchors.js";
 import { parseTags } from "../shared/parse-tags.js";
@@ -17,8 +18,11 @@ const LOGO_MAX_BYTES = 1 * 1024 * 1024; // 1 MB
 const CERT_TIMEOUT_MS = 30_000;
 const CERT_MAX_BYTES = 100 * 1024; // 100 KB
 
-export function prefetchBimiDns(domain: string): Promise<TxtRecord | null> {
-  return queryTxt(`default._bimi.${domain}`).catch((err) => {
+export function prefetchBimiDns(
+  domain: string,
+  budget?: ScanBudget,
+): Promise<TxtRecord | null> {
+  return queryTxt(`default._bimi.${domain}`, budget).catch((err) => {
     if (err instanceof DnsLookupError) return null;
     throw err;
   });
@@ -183,11 +187,12 @@ export async function analyzeBimi(
   domain: string,
   dmarcPolicy: string | null,
   prefetchedDns?: TxtRecord | null,
+  budget?: ScanBudget,
 ): Promise<BimiResult> {
   const txt =
     prefetchedDns !== undefined
       ? prefetchedDns
-      : await queryTxt(`default._bimi.${domain}`);
+      : await queryTxt(`default._bimi.${domain}`, budget);
 
   if (!txt) {
     const validations: Validation[] = [

src/analyzers/dane.ts

@@ -1,4 +1,5 @@
 import { DnsLookupError, queryDoh } from "../dns/client.js";
+import type { ScanBudget } from "../dns/scan-budget.js";
 import type {
   DaneHostResult,
   DaneResult,
@@ -54,6 +55,7 @@ function parseTlsaRecord(data: string): DaneTlsaRecord | null {
 export async function analyzeDane(
   _domain: string,
   mxExchanges: string[],
+  budget?: ScanBudget,
 ): Promise<DaneResult> {
   const validations: Validation[] = [];
 
@@ -74,7 +76,7 @@ export async function analyzeDane(
   await Promise.all(
     mxExchanges.map(async (exchange) => {
       try {
-        const response = await queryDoh(`_25._tcp.${exchange}`, "TLSA");
+        const response = await queryDoh(`_25._tcp.${exchange}`, "TLSA", budget);
         successfulQueries++;
         if (!response) {
           hosts.push({ exchange, tlsaRecords: [], dnssecValidated: false });

src/analyzers/dkim.ts

@@ -1,4 +1,5 @@
 import { queryTxt } from "../dns/client.js";
+import type { ScanBudget } from "../dns/scan-budget.js";
 import { LEARN_ANCHORS, learnAnchorHref } from "../shared/learn-anchors.js";
 import { parseTags } from "../shared/parse-tags.js";
 import type { DkimResult, DkimSelectorResult, Validation } from "./types.js";
@@ -55,6 +56,7 @@ export async function analyzeDkim(
   domain: string,
   customSelectors: string[] = [],
   providerNames: string[] = [],
+  budget?: ScanBudget,
 ): Promise<DkimResult> {
   const unique = [...new Set([...COMMON_SELECTORS, ...customSelectors])];
   const prioritized = providerNames.flatMap(
@@ -67,7 +69,7 @@ export async function analyzeDkim(
   ];
 
   const results = await Promise.allSettled(
-    allSelectors.map((sel) => probeSelector(domain, sel)),
+    allSelectors.map((sel) => probeSelector(domain, sel, budget)),
   );
 
   const selectors: Record<string, DkimSelectorResult> = {};
@@ -162,8 +164,9 @@ export async function analyzeDkim(
 async function probeSelector(
   domain: string,
   selector: string,
+  budget?: ScanBudget,
 ): Promise<DkimSelectorResult> {
-  const txt = await queryTxt(`${selector}._domainkey.${domain}`);
+  const txt = await queryTxt(`${selector}._domainkey.${domain}`, budget);
   if (!txt) return { found: false };
 
   const dkimRecord = txt.entries.find(

src/analyzers/dmarc.ts

@@ -1,4 +1,5 @@
 import { DnsLookupError, queryTxt } from "../dns/client.js";
+import type { ScanBudget } from "../dns/scan-budget.js";
 import { LEARN_ANCHORS, learnAnchorHref } from "../shared/learn-anchors.js";
 import { parseTags } from "../shared/parse-tags.js";
 import type { DmarcResult, Validation } from "./types.js";
@@ -58,30 +59,36 @@ async function checkReportingAuthorization(
   tagValue: string,
   tagName: "rua" | "ruf",
   validations: Validation[],
-  budget: ReportAuthBudget,
+  // Two distinct budgets: `authBudget` is the per-analyzer rua/ruf cap
+  // (GHSA-vcw3-wvwx-6fg5), shared across the rua+ruf passes; `scanBudget` is the
+  // orchestrator-wide shared DNS-query pool (GHSA-f828-8wf8-vqp2) passed down to
+  // queryTxt. The auth cap bounds this analyzer's fan-out; the scan budget bounds
+  // the whole scan's combined fan-out across all analyzers.
+  authBudget: ReportAuthBudget,
+  scanBudget?: ScanBudget,
 ): Promise<void> {
   const uris = parseReportUris(tagValue);
   for (const uri of uris) {
     const reportingDomain = extractMailtoDomain(uri);
     if (!reportingDomain) continue;
     // Same domain — no external authorization needed
     if (reportingDomain === localDomain.toLowerCase()) continue;
-    // External lookup required — enforce the shared cap before querying.
-    if (budget.remaining <= 0) {
-      if (!budget.capReported) {
+    // External lookup required — enforce the per-analyzer cap before querying.
+    if (authBudget.remaining <= 0) {
+      if (!authBudget.capReported) {
         validations.push({
           status: "warn",
           message: `More than ${MAX_REPORT_AUTH_LOOKUPS} external report destinations configured (rua/ruf) — additional destinations were not verified for report authorization`,
         });
-        budget.capReported = true;
+        authBudget.capReported = true;
       }
       break;
     }
-    budget.remaining--;
+    authBudget.remaining--;
     const authName = `${localDomain}._report._dmarc.${reportingDomain}`;
     let authRecord: Awaited<ReturnType<typeof queryTxt>>;
     try {
-      authRecord = await queryTxt(authName);
+      authRecord = await queryTxt(authName, scanBudget);
     } catch (err) {
       if (err instanceof DnsLookupError) {
         validations.push({
@@ -104,10 +111,13 @@ async function checkReportingAuthorization(
   }
 }
 
-export async function analyzeDmarc(domain: string): Promise<DmarcResult> {
+export async function analyzeDmarc(
+  domain: string,
+  budget?: ScanBudget,
+): Promise<DmarcResult> {
   let txt: Awaited<ReturnType<typeof queryTxt>>;
   try {
-    txt = await queryTxt(`_dmarc.${domain}`);
+    txt = await queryTxt(`_dmarc.${domain}`, budget);
   } catch (err) {
     if (err instanceof DnsLookupError) {
       return {
@@ -231,6 +241,7 @@ export async function analyzeDmarc(domain: string): Promise<DmarcResult> {
       "rua",
       validations,
       reportAuthBudget,
+      budget,
     );
   } else {
     validations.push({
@@ -251,6 +262,7 @@ export async function analyzeDmarc(domain: string): Promise<DmarcResult> {
       "ruf",
       validations,
       reportAuthBudget,
+      budget,
     );
   }
 

src/analyzers/dnssec.ts

@@ -1,7 +1,11 @@
 import { DnsLookupError, queryDoh } from "../dns/client.js";
+import type { ScanBudget } from "../dns/scan-budget.js";
 import type { DnssecResult, Validation } from "./types.js";
 
-export async function analyzeDnssec(domain: string): Promise<DnssecResult> {
+export async function analyzeDnssec(
+  domain: string,
+  budget?: ScanBudget,
+): Promise<DnssecResult> {
   const validations: Validation[] = [];
 
   let response: Awaited<ReturnType<typeof queryDoh>>;
@@ -10,7 +14,7 @@ export async function analyzeDnssec(domain: string): Promise<DnssecResult> {
     // signal that the parent has signed the delegation — the presence of DS
     // records (plus the AD flag from a validating resolver) is the standard
     // way to determine DNSSEC status without doing a full chain-of-trust walk.
-    response = await queryDoh(domain, "DS");
+    response = await queryDoh(domain, "DS", budget);
   } catch (err) {
     if (err instanceof DnsLookupError) {
       validations.push({

src/analyzers/mta-sts.ts

@@ -1,9 +1,13 @@
 import { queryTxt } from "../dns/client.js";
+import type { ScanBudget } from "../dns/scan-budget.js";
 import type { MtaStsPolicy, MtaStsResult, Validation } from "./types.js";
 
-export async function analyzeMtaSts(domain: string): Promise<MtaStsResult> {
+export async function analyzeMtaSts(
+  domain: string,
+  budget?: ScanBudget,
+): Promise<MtaStsResult> {
   const [dnsResult, policyResult] = await Promise.allSettled([
-    queryTxt(`_mta-sts.${domain}`),
+    queryTxt(`_mta-sts.${domain}`, budget),
     fetchPolicy(domain),
   ]);
 

src/analyzers/mx.ts

@@ -1,4 +1,5 @@
 import { DnsLookupError, queryMx } from "../dns/client.js";
+import type { ScanBudget } from "../dns/scan-budget.js";
 import type { EmailProvider, MxRecord, MxResult, Validation } from "./types.js";
 
 interface ProviderSignature {
@@ -112,10 +113,13 @@ export function detectProviders(
   return providers;
 }
 
-export async function analyzeMx(domain: string): Promise<MxResult> {
+export async function analyzeMx(
+  domain: string,
+  budget?: ScanBudget,
+): Promise<MxResult> {
   let rawRecords: Awaited<ReturnType<typeof queryMx>>;
   try {
-    rawRecords = await queryMx(domain);
+    rawRecords = await queryMx(domain, budget);
   } catch (err) {
     if (err instanceof DnsLookupError) {
       return {

src/analyzers/spf.ts

@@ -1,10 +1,14 @@
 import { DnsLookupError, queryTxt } from "../dns/client.js";
+import type { ScanBudget } from "../dns/scan-budget.js";
 import { LEARN_ANCHORS, learnAnchorHref } from "../shared/learn-anchors.js";
 import type { SpfIncludeNode, SpfResult, Validation } from "./types.js";
 
 const MAX_LOOKUPS = 10;
 
-export async function analyzeSpf(domain: string): Promise<SpfResult> {
+export async function analyzeSpf(
+  domain: string,
+  budget?: ScanBudget,
+): Promise<SpfResult> {
   const ctx: ResolutionContext = {
     lookups: 0,
     visited: new Set(),
@@ -15,7 +19,7 @@ export async function analyzeSpf(domain: string): Promise<SpfResult> {
 
   let tree: SpfIncludeNode | null;
   try {
-    tree = await resolveSpfTree(domain, ctx, 0);
+    tree = await resolveSpfTree(domain, ctx, 0, budget);
   } catch (err) {
     if (err instanceof DnsLookupError) {
       return {
@@ -176,6 +180,7 @@ async function resolveSpfTree(
   domain: string,
   ctx: ResolutionContext,
   depth: number,
+  budget?: ScanBudget,
 ): Promise<SpfIncludeNode | null> {
   if (depth > 10) return null; // Prevent infinite recursion
   if (ctx.lookups > MAX_LOOKUPS) return null; // Prevent excessive DNS queries
@@ -187,7 +192,7 @@ async function resolveSpfTree(
   }
   ctx.visited.add(normalizedDomain);
 
-  const txt = await queryTxt(domain);
+  const txt = await queryTxt(domain, budget);
   if (!txt) {
     // NXDOMAIN/NODATA. For include:/redirect= targets (depth > 0) this is a
     // void lookup under RFC 7208 §4.6.4; the root domain returning null just
@@ -243,7 +248,7 @@ async function resolveSpfTree(
       ? []
       : await Promise.allSettled(
           includeTargets.map((target) =>
-            resolveSpfTree(target, ctx, depth + 1),
+            resolveSpfTree(target, ctx, depth + 1, budget),
           ),
         );
 
@@ -255,7 +260,7 @@ async function resolveSpfTree(
 
   // Handle redirect (processed after all mechanisms)
   if (redirect && ctx.lookups <= MAX_LOOKUPS) {
-    const redirectNode = await resolveSpfTree(redirect, ctx, depth + 1);
+    const redirectNode = await resolveSpfTree(redirect, ctx, depth + 1, budget);
     if (redirectNode) {
       includes.push(redirectNode);
     }

src/analyzers/tls-rpt.ts

@@ -1,4 +1,5 @@
 import { DnsLookupError, queryTxt } from "../dns/client.js";
+import type { ScanBudget } from "../dns/scan-budget.js";
 import { parseTags } from "../shared/parse-tags.js";
 import type { TlsRptResult, Validation } from "./types.js";
 
@@ -7,10 +8,13 @@ import type { TlsRptResult, Validation } from "./types.js";
 // MTAs where to send TLS failure reports, but its presence or absence does
 // not change the enforcement posture.
 
-export async function analyzeTlsRpt(domain: string): Promise<TlsRptResult> {
+export async function analyzeTlsRpt(
+  domain: string,
+  budget?: ScanBudget,
+): Promise<TlsRptResult> {
   let txt: Awaited<ReturnType<typeof queryTxt>>;
   try {
-    txt = await queryTxt(`_smtp._tls.${domain}`);
+    txt = await queryTxt(`_smtp._tls.${domain}`, budget);
   } catch (err) {
     if (err instanceof DnsLookupError) {
       return {