blackveil-dns 1.4.2 → 2.0.6

package/README.md

@@ -9,7 +9,7 @@ Open-source DNS & email security scanner for Claude, Cursor, VS Code, and MCP cl
 [![GitHub stars](https://img.shields.io/github/stars/MadaBurns/bv-mcp?style=flat&logo=github)](https://github.com/MadaBurns/bv-mcp/stargazers)
 [![npm version](https://img.shields.io/npm/v/blackveil-dns)](https://www.npmjs.com/package/blackveil-dns)
 [![npm downloads](https://img.shields.io/npm/dm/blackveil-dns)](https://www.npmjs.com/package/blackveil-dns)
-[![Tests](https://img.shields.io/badge/Tests-1097-brightgreen)](https://github.com/MadaBurns/bv-mcp/actions)
+[![Tests](https://img.shields.io/badge/Tests-1469-brightgreen)](https://github.com/MadaBurns/bv-mcp/actions)
 [![Coverage](https://img.shields.io/badge/Coverage-~90%25-brightgreen)](https://github.com/MadaBurns/bv-mcp/actions)
 [![BUSL-1.1 License](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](LICENSE)
 [![MCP](https://img.shields.io/badge/MCP-2025--03--26-blue)](https://modelcontextprotocol.io/)
@@ -61,9 +61,14 @@ Transport support:
 - **57+ checks across 20 categories** — SPF, DMARC, DKIM, DNSSEC, SSL/TLS, MTA-STS, NS, CAA, MX, BIMI, TLS-RPT, subdomain takeover, lookalike domains, HTTP security headers, DANE, shadow domains, TXT hygiene, MX reputation, SRV, zone hygiene
 - **Maturity staging** — Stage 0-4 classification (Unprotected to Hardened) with next steps
 - **Trust surface analysis** — detects shared SaaS platforms (Google, M365, SendGrid) and cross-references DMARC enforcement to determine real exposure
-- **Plain-English remediation** — `explain_finding` turns findings into guidance anyone can understand
+- **Guided remediation** — `generate_fix_plan` produces prioritized actions; record generators output ready-to-publish SPF, DMARC, DKIM, and MTA-STS records
+- **Spoofability scoring** — `assess_spoofability` computes a composite 0-100 email spoofability score from SPF trust surface, DMARC enforcement, and DKIM coverage with interaction multipliers
+- **Intelligence layer** — `get_benchmark` and `get_provider_insights` expose anonymized aggregate insights from scan telemetry: percentile rankings, provider cohort comparisons, and 7-day trend analysis
+- **Multi-resolver consistency** — `check_resolver_consistency` queries 4 public DoH resolvers to detect GeoDNS, split-horizon DNS, or poisoning
+- **Interaction scoring** — correlated weaknesses (e.g., weak DKIM + permissive DMARC) receive additional penalties beyond individual finding scores
 - **Self-tuning scoring** — adaptive weights adjust category importance based on patterns seen across scans, so scores reflect real-world failure distributions rather than static assumptions
 - **Provider intelligence** — inbound/outbound email provider inference from MX, SPF, DKIM
+- **Context-optimized** — tool schemas, prompts, and resources are tuned for minimal token consumption in LLM clients
 - **Passive and read-only** — all checks use public Cloudflare DNS-over-HTTPS; no authorization required from the target
 
 Full scope and limitations in the coverage table below.
@@ -72,7 +77,7 @@ Full scope and limitations in the coverage table below.
   scan_domain("anthropic.com")
 
   ████████████████████████████████████████░░░░░  85 / 100
-  Grade: A  ·  Maturity: Intermediate
+  Grade: A  ·  Maturity: Enforcing
 
   SPF ·········· 80     MTA-STS ····· 85
   DMARC ········ 90     NS ·········· 95
@@ -95,7 +100,7 @@ Full scope and limitations in the coverage table below.
 ## Tools
 
 ```
-  22 MCP tools
+  33 MCP tools · 7 prompts · 6 resources
 
   Email Auth           Infrastructure        Brand & Threats       Meta
  ────────────         ────────────────       ─────────────────    ──────────────
@@ -104,17 +109,25 @@ Full scope and limitations in the coverage table below.
   check_dkim           check_caa              check_lookalikes     compare_baseline
   check_mta_sts        check_ssl              check_shadow_domains
   check_mx             check_http_security
-  check_mx_reputation  check_dane
-                       check_srv
-  DNS Hygiene          check_zone_hygiene
- ────────────
-  check_txt_hygiene
+  check_mx_reputation  check_dane             Intelligence         Remediation
+                       check_dane_https      ──────────────       ──────────────
+  DNS Hygiene          check_svcb_https       get_benchmark         generate_fix_plan
+ ────────────          check_srv              get_provider_         generate_spf_record
+  check_txt_hygiene    check_zone_hygiene       insights            generate_dmarc_record
+                       check_resolver_        assess_spoofability   generate_dkim_config
+                         consistency                                generate_mta_sts_policy
 
   + check_subdomain_takeover (internal — runs inside scan_domain)
 ```
 
 `explain_finding` takes any finding and returns: what it means, potential impact, adverse consequences, specific steps to fix, and relevant RFCs.
 
+`generate_fix_plan` scans a domain and produces a prioritized remediation plan with effort, impact, and dependency metadata. The record generators (`generate_spf_record`, `generate_dmarc_record`, `generate_dkim_config`, `generate_mta_sts_policy`) produce ready-to-publish DNS records based on detected configuration.
+
+`get_benchmark` and `get_provider_insights` expose anonymized aggregate data from scan telemetry — percentile rankings, provider cohort scores, and 7-day trend analysis. `assess_spoofability` computes a composite email spoofability score (0-100) from SPF, DMARC, and DKIM with interaction multipliers.
+
+`check_resolver_consistency` queries Cloudflare, Google, Quad9, and OpenDNS in parallel to detect GeoDNS, split-horizon DNS, or potential poisoning.
+
 **Confidence labels:**
 `deterministic` — direct protocol/record validation | `heuristic` — signal-based inference, may need manual validation | `verified` — high-confidence validation signal
 
@@ -125,6 +138,8 @@ Full scope and limitations in the coverage table below.
 
 ## Client setup
 
+The free tier requires no authentication. If you have an API key, see the **With API key** tabs below to bypass rate limits.
+
 <details>
 <summary><b>VS Code / Copilot</b></summary>
 
@@ -140,6 +155,30 @@ Full scope and limitations in the coverage table below.
   }
 }
 ```
+
+**With API key:**
+
+```json
+{
+  "servers": {
+    "blackveil-dns": {
+      "type": "http",
+      "url": "https://dns-mcp.blackveilsecurity.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${input:bv-api-key}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "id": "bv-api-key",
+      "type": "promptString",
+      "description": "Blackveil DNS API key",
+      "password": true
+    }
+  ]
+}
+```
 </details>
 
 <details>
@@ -163,6 +202,33 @@ Or via CLI:
 ```bash
 claude mcp add --transport http blackveil-dns https://dns-mcp.blackveilsecurity.com/mcp
 ```
+
+**With API key** — use `mcp-remote` to reliably forward the auth header:
+
+```json
+{
+  "mcpServers": {
+    "blackveil-dns": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://dns-mcp.blackveilsecurity.com/mcp",
+        "--header",
+        "Authorization: Bearer YOUR_API_KEY"
+      ]
+    }
+  }
+}
+```
+
+Or via CLI:
+
+```bash
+claude mcp add-json blackveil-dns \
+  '{"command":"npx","args":["mcp-remote","https://dns-mcp.blackveilsecurity.com/mcp","--header","Authorization: Bearer YOUR_API_KEY"]}'
+```
+
+> **Why `mcp-remote`?** Claude Code's native HTTP transport does not currently forward custom `headers` from config files. The `mcp-remote` bridge reliably passes the `Authorization` header to the server. Restart Claude Code after adding the server.
 </details>
 
 <details>
@@ -170,7 +236,25 @@ claude mcp add --transport http blackveil-dns https://dns-mcp.blackveilsecurity.
 
 **Recommended:** Open [claude.ai](https://claude.ai) → **Settings → Connectors → Add custom connector** → paste `https://dns-mcp.blackveilsecurity.com/mcp`.
 
-**Advanced fallback:** If you want first-party local stdio instead of the hosted HTTP connector, open **Settings → Developer → Edit Config** (`claude_desktop_config.json`) and add:
+**With API key** — open **Settings → Developer → Edit Config** (`claude_desktop_config.json`) and add:
+
+```json
+{
+  "mcpServers": {
+    "blackveil-dns": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://dns-mcp.blackveilsecurity.com/mcp",
+        "--header",
+        "Authorization: Bearer YOUR_API_KEY"
+      ]
+    }
+  }
+}
+```
+
+**Without API key (local stdio):** If you want first-party local stdio instead of the hosted HTTP connector:
 
 ```json
 {
@@ -184,8 +268,6 @@ claude mcp add --transport http blackveil-dns https://dns-mcp.blackveilsecurity.
 }
 ```
 
-> Prefer the direct custom connector above when possible. The stdio route runs the server locally and depends on Node.js being available to Claude Desktop.
->
 > On macOS GUI apps, `npx` may not resolve from `PATH`; if Homebrew is installed elsewhere, replace `/opt/homebrew/bin/npx` with your actual `npx` path. After editing the config, fully restart Claude Desktop. If you already have other servers, merge `"blackveil-dns"` into your existing `"mcpServers"` object — don't paste a second `{ }` wrapper.
 
 </details>
@@ -204,6 +286,52 @@ claude mcp add --transport http blackveil-dns https://dns-mcp.blackveilsecurity.
   }
 }
 ```
+
+**With API key:**
+
+```json
+{
+  "mcpServers": {
+    "blackveil-dns": {
+      "url": "https://dns-mcp.blackveilsecurity.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+`~/.codeium/windsurf/mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "blackveil-dns": {
+      "serverUrl": "https://dns-mcp.blackveilsecurity.com/mcp"
+    }
+  }
+}
+```
+
+**With API key:**
+
+```json
+{
+  "mcpServers": {
+    "blackveil-dns": {
+      "serverUrl": "https://dns-mcp.blackveilsecurity.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
 </details>
 
 For hosted MCP setup, stdio usage, and legacy fallback endpoints, see `docs/client-setup.md`.
@@ -231,6 +359,30 @@ Get weekly DNS security reports in Slack or Discord. See [`examples/slack-discor
 
 ---
 
+## Pricing
+
+Full API and MCP access at every tier — no enterprise gatekeeping.
+
+| | **Free** | **Pro** | **Enterprise** |
+|---|---|---|---|
+| **Price** | $0 | $39/mo ($29/mo annual) | [Contact us](https://blackveilsecurity.com) |
+| **Scans/day** | 75 | 500 | 10,000+ |
+| **Checks/day** (per tool) | 200 | 5,000 | Unlimited |
+| **Lookalike / Shadow scans** | 20/day | 200/day | Unlimited |
+| **Rate limit** | 50 req/min | None | None |
+| **API access** | Yes | Yes | Yes |
+| **MCP access** | Yes | Yes | Yes |
+| **GitHub Action** | Yes | Yes | Yes |
+| **Batch API** | — | — | Up to 500 domains/call |
+| **SLA** | Best effort | 99.5% | 99.9% + custom |
+| **Support** | Community | Email | Dedicated |
+
+The free tier is generous by design — use it for personal projects, evaluations, and AI agent integrations with no strings attached. Upgrade when you need higher throughput.
+
+Get an API key at [blackveilsecurity.com](https://blackveilsecurity.com).
+
+---
+
 ## npm package
 
 Install from npm when you want to call the scanner from your own Node.js app, script, or service. If you are connecting from VS Code, Claude, Cursor, or another MCP client, use the MCP endpoint configuration above instead.
@@ -365,9 +517,9 @@ Run `explain_finding` on any result for plain-English remediation.
 | `POST` | `/internal/tools/call` | Service binding: single tool call (no auth/rate limits) |
 | `POST` | `/internal/tools/batch` | Service binding: bulk scan up to 500 domains |
 
-Supported methods: `initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/read`.
+Supported methods: `initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`.
 
-Prompt methods (`prompts/list`, `prompts/get`) return `-32601 Method not found`.
+7 pre-built prompts guide common workflows: `full-security-audit`, `email-auth-check`, `policy-compliance-check`, `remediation-workflow`, `email-hardening-guide`, `provider-benchmark`, `attack-surface-assessment`.
 
 </details>
 
@@ -390,7 +542,7 @@ Prompt methods (`prompts/list`, `prompts/get`) return `-32601 Method not found`.
       │
   ┌───▼──────────────────────┐
   │  Tool Handlers           │
-  │  14 checks in parallel   │
+  │  16 checks in parallel   │
   └───┬──────────────────────┘
       │
   ┌───▼──────────────────────┐
@@ -406,6 +558,9 @@ Prompt methods (`prompts/list`, `prompts/get`) return `-32601 Method not found`.
 - `scan_domain` capped at 75/day per IP (results cached 5 min)
 - Scan result caching (KV + in-memory fallback)
 - Adaptive scoring via Durable Object telemetry (graceful fallback to static weights)
+- Intelligence layer: score histograms, provider cohort benchmarks, hourly trend snapshots (ProfileAccumulator DO)
+- Category interaction scoring: correlated weaknesses receive additional penalties
+- Context-optimized schemas: tool descriptions, prompts, and resources tuned for minimal LLM token consumption
 - Structured JSON logging
 
 Implementation details in `CLAUDE.md`.
@@ -422,10 +577,18 @@ Full details in `CLAUDE.md` (security and observability sections).
 - SSRF protections block unsafe/private targets
 - Error responses sanitized — only known validation errors surface
 - DNS via Cloudflare DoH with optional secondary confirmation
-- Rate limits: `50/min` and `300/hr` per IP for `tools/call`
+- Constant-time auth comparison (XOR accumulation on SHA-256 digests)
+- DNS data sanitized at ingestion — HTML/markdown injection stripped before findings are created
+- Outbound response body caps (64 KB for tool checks, 1 MB for provider signatures)
+- Tool parameter validation with allowlists and per-element type/length checks
+- Rate limits: `50/min` and `300/hr` per IP for `tools/call` (free tier; Pro and Enterprise bypass)
 - Control-plane traffic: `60/min` and `600/hr` per IP
 - Global daily cap: `500,000` unauthenticated tool calls/day (cost ceiling)
-- Session creation: `60/min` per IP
+- Authenticated requests: per-tier daily quotas keyed by API key hash (see [Pricing](#pricing))
+- Session creation: `60/min` per IP (enforced on both modern and legacy transports)
+- Session TTL: 2 hours idle, dual-write (KV + in-memory) for cross-isolate resilience
+- SSE notification stream exempt from rate limiting (prevents `mcp-remote` reconnection storms)
+- Client IPs redacted in structured logs
 
 **Natural-language convenience:**
 `tools/call` supports `scan` as an alias for `scan_domain`. In chat clients, say `scan example.com`. Raw JSON-RPC expects `params.name` to be `scan` or `scan_domain`.
@@ -464,7 +627,7 @@ npm run dev       # localhost:8787/mcp
 ```
 
 ```bash
-npm test          # 1090+ tests, ~90% coverage
+npm test          # 1469 tests
 npm run typecheck
 ```
 
@@ -512,6 +675,6 @@ Featured in [SecurityBrief](https://securitybrief.co.nz/story/exclusive-how-cybe
 
 Want continuous monitoring? [BLACKVEIL](https://blackveilsecurity.com) provides real-time alerting and Buck AI to help you fix what this scanner finds.
 
-MIT License
+BUSL-1.1 License (converts to MIT on 2030-03-17)
 
 </div>

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import { CheckResult, ScoringConfig, ScanScore, DomainContext } from '@blackveil/dns-checks/scoring';
+export { CATEGORY_DISPLAY_WEIGHTS, CheckCategory, CheckResult, DomainContext, DomainProfile, Finding, FindingConfidence, SEVERITY_PENALTIES, ScanScore, Severity, buildCheckResult, computeCategoryScore, computeScanScore, createFinding, detectDomainContext, getProfileWeights, inferFindingConfidence, scoreToGrade } from '@blackveil/dns-checks/scoring';
+export { parseDmarcTags } from '@blackveil/dns-checks';
+
 /** Standard DNS record type codes */
 declare const RecordType: {
     readonly A: 1;
@@ -14,6 +18,7 @@ declare const RecordType: {
     readonly RRSIG: 46;
     readonly PTR: 12;
     readonly SRV: 33;
+    readonly HTTPS: 65;
 };
 type RecordTypeName = keyof typeof RecordType;
 /** A single DNS answer record from the DoH JSON response */
@@ -128,124 +133,6 @@ declare function queryMxRecords(domain: string, opts?: QueryDnsOptions): Promise
     exchange: string;
 }>>;
 
-type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
-type FindingConfidence = 'deterministic' | 'heuristic' | 'verified';
-type CheckCategory = 'spf' | 'dmarc' | 'dkim' | 'dnssec' | 'ssl' | 'mta_sts' | 'ns' | 'caa' | 'subdomain_takeover' | 'mx' | 'bimi' | 'tlsrpt' | 'lookalikes' | 'shadow_domains' | 'txt_hygiene' | 'http_security' | 'dane' | 'mx_reputation' | 'srv' | 'zone_hygiene';
-interface Finding {
-    category: CheckCategory;
-    title: string;
-    severity: Severity;
-    detail: string;
-    metadata?: Record<string, unknown>;
-}
-interface CheckResult {
-    category: CheckCategory;
-    passed: boolean;
-    score: number;
-    findings: Finding[];
-}
-interface ScanScore {
-    overall: number;
-    grade: string;
-    categoryScores: Record<CheckCategory, number>;
-    findings: Finding[];
-    summary: string;
-}
-/** Display/UI weight distribution for categories. NOT used in scoring — see IMPORTANCE_WEIGHTS for actual scoring weights. Exists for category registry and display purposes only. */
-declare const CATEGORY_DISPLAY_WEIGHTS: Record<CheckCategory, number>;
-/** Severity penalty multipliers applied to the category score */
-declare const SEVERITY_PENALTIES: Record<Severity, number>;
-/**
- * Infer how strongly a finding can be trusted based on available evidence.
- * - verified: explicit proof (currently only supported on takeover checks)
- * - heuristic: signal-based or partial-evidence checks
- * - deterministic: direct record/protocol validation
- */
-declare function inferFindingConfidence(finding: Finding): FindingConfidence;
-/**
- * Compute the score for a single check category based on its findings.
- * Starts at 100 and deducts points based on finding severities.
- */
-declare function computeCategoryScore(findings: Finding[]): number;
-/**
- * Build a CheckResult from a category and its findings.
- */
-declare function buildCheckResult(category: CheckCategory, findings: Finding[]): CheckResult;
-/**
- * Create a finding object with the given parameters.
- */
-declare function createFinding(category: CheckCategory, title: string, severity: Severity, detail: string, metadata?: Record<string, unknown>): Finding;
-
-/**
- * Runtime scoring configuration.
- *
- * All scoring weights, thresholds, and tuning constants are configurable
- * via the `SCORING_CONFIG` environment variable (JSON string). The open-source
- * codebase ships with reasonable defaults; production deployments can override
- * any subset of values.
- *
- * Parse once at request entry and thread through the call chain — never
- * re-parse per tool call.
- */
-
-/** All tunable scoring parameters. */
-interface ScoringConfig {
-    /** Base importance weights per check category (used when no profile context). */
-    weights: Record<CheckCategory, number>;
-    /** Per-profile importance weights. */
-    profileWeights: Record<DomainProfile, Record<CheckCategory, number>>;
-    /** Scoring thresholds and constants. */
-    thresholds: {
-        emailBonusImportance: number;
-        spfStrongThreshold: number;
-        criticalOverallPenalty: number;
-        criticalGapCeiling: number;
-    };
-    /** Grade boundaries (minimum score for each grade). */
-    grades: {
-        aPlus: number;
-        a: number;
-        bPlus: number;
-        b: number;
-        cPlus: number;
-        c: number;
-        dPlus: number;
-        d: number;
-        e: number;
-    };
-    /** Baseline failure rates for adaptive weight computation. */
-    baselineFailureRates: Record<string, number>;
-}
-
-type DomainProfile = 'mail_enabled' | 'enterprise_mail' | 'non_mail' | 'web_only' | 'minimal';
-interface DomainContext {
-    profile: DomainProfile;
-    signals: string[];
-    weights: Record<CheckCategory, ImportanceProfile>;
-    detectedProvider: string | null;
-}
-interface ImportanceProfile {
-    importance: number;
-}
-/**
- * Detect domain context from completed check results.
- * Pure function — reads findings metadata only, no DNS queries.
- */
-declare function detectDomainContext(results: CheckResult[]): DomainContext;
-/** Look up the weight table for a given profile, optionally from runtime config. */
-declare function getProfileWeights(profile: DomainProfile, config?: ScoringConfig): Record<CheckCategory, ImportanceProfile>;
-
-/** Map numeric score to letter grade */
-declare function scoreToGrade(score: number, config?: ScoringConfig): string;
-/**
- * Compute the overall scan score from individual check results.
- * Uses weighted average of category scores.
- *
- * When a `DomainContext` is provided, uses profile-specific weights,
- * critical gap categories, and email bonus eligibility instead of defaults.
- */
-declare function computeScanScore(results: CheckResult[], context?: DomainContext, config?: ScoringConfig): ScanScore;
-
 /**
  * Input sanitization and validation utilities for the DNS Security MCP Server.
  * Handles domain validation, input cleaning, and MCP error response helpers.
@@ -272,7 +159,7 @@ declare function sanitizeDomain(input: string): string;
 declare function sanitizeInput(input: string, maxLength?: number): string;
 
 /** Server version — keep in sync with package.json */
-declare const SERVER_VERSION = "1.4.2";
+declare const SERVER_VERSION = "2.0.6";
 
 /**
  * Check BIMI records for a domain.
@@ -294,9 +181,6 @@ declare function checkCaa(domain: string, dnsOptions?: QueryDnsOptions): Promise
  */
 declare function checkDkim(domain: string, selector?: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
 
-/** Parse DMARC tag-value pairs from a DMARC record string. */
-declare function parseDmarcTags(record: string): Map<string, string>;
-
 /**
  * Check DMARC records for a domain.
  * Queries _dmarc.<domain> TXT records and validates policy configuration.
@@ -323,12 +207,6 @@ declare function checkLookalikes(domain: string): Promise<CheckResult>;
  */
 declare function checkMtaSts(domain: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
 
-/**
- * MX record check tool for MCP server.
- * Validates presence and quality of MX records for a domain.
- * Returns CheckResult with findings including RFC compliance, redundancy, and provider detection.
- */
-
 interface CheckMxOptions {
     providerSignaturesUrl?: string;
     providerSignaturesAllowedHosts?: string[];
@@ -350,25 +228,12 @@ declare function checkNs(domain: string, dnsOptions?: QueryDnsOptions): Promise<
  */
 declare function checkSpf(domain: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
 
-/**
- * SSL/TLS certificate check tool.
- * Validates SSL certificate by attempting HTTPS connection,
- * checks HSTS configuration,
- * and verifies HTTP→HTTPS redirect.
- * Workers-compatible: uses fetch API only (cert expiry/chain require external APIs).
- */
-
 /**
  * Check SSL/TLS configuration for a domain.
  * Validates HTTPS connectivity, HSTS headers, and HTTP→HTTPS redirect.
  */
 declare function checkSsl(domain: string): Promise<CheckResult>;
 
-/**
- * Subdomain Takeover / Dangling CNAME Detection Tool
- * Scans known/active subdomains for orphaned CNAME records pointing to deleted/unresolved third-party services.
- */
-
 /**
  * Check for dangling CNAME records on known/active subdomains.
  * Flags orphaned records and potential takeover vectors.
@@ -381,6 +246,8 @@ declare function checkSubdomainTakeover(domain: string, dnsOptions?: QueryDnsOpt
  */
 declare function checkTlsrpt(domain: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
 
+type OutputFormat = 'full' | 'compact';
+
 interface ImpactNarrative {
     impact?: string;
     adverseConsequences?: string;
@@ -417,7 +284,22 @@ declare function resolveImpactNarrative(params: {
     detail?: string;
 }): ImpactNarrative;
 declare function explainFinding(checkType: string, status: string, details?: string): ExplanationResult;
-declare function formatExplanation(result: ExplanationResult): string;
+declare function formatExplanation(result: ExplanationResult, format?: OutputFormat): string;
+
+/**
+ * Category interaction scoring — post-scoring adjustments for correlated weaknesses.
+ *
+ * Applied after computeScanScore() as a separate penalty layer.
+ * Does NOT modify categoryScores — only adjusts the overall score.
+ * Existing compare_baseline CI/CD workflows continue to work identically.
+ */
+
+/** Result of applying interaction rules to a scan score. */
+interface InteractionEffect {
+    ruleId: string;
+    penalty: number;
+    narrative: string;
+}
 
 interface ScanRuntimeOptions {
     providerSignaturesUrl?: string;
@@ -431,6 +313,8 @@ interface ScanRuntimeOptions {
     cacheTtlSeconds?: number;
     /** Custom secondary DoH resolver config (bv-dns). Threaded to scanDns but only active when skipSecondaryConfirmation is false. */
     secondaryDoh?: SecondaryDohConfig;
+    /** Bypass cache and run a fresh scan. Useful for troubleshooting after DNS changes. */
+    forceRefresh?: boolean;
 }
 
 /**
@@ -465,12 +349,27 @@ interface StructuredScanResult {
     scoringSignals: string[];
     scoringNote: string | null;
     adaptiveWeightDeltas: Record<string, number> | null;
+    /** Percentile rank within the scoring profile population (0–100). Null when insufficient benchmark data. */
+    percentileRank: number | null;
+    /** Composite email spoofability score (0–100, higher = more spoofable). Null when not computed. */
+    spoofabilityScore: number | null;
+    /** Category interaction effects applied as post-scoring adjustments. */
+    interactionEffects: Array<{
+        ruleId: string;
+        penalty: number;
+        narrative: string;
+    }>;
     timestamp: string;
     cached: boolean;
 }
+/** Optional enrichment data for structured scan results. */
+interface ScanResultEnrichment {
+    percentileRank?: number | null;
+    spoofabilityScore?: number | null;
+}
 /** Build a machine-readable structured result from a scan. */
-declare function buildStructuredScanResult(result: ScanDomainResult): StructuredScanResult;
-declare function formatScanReport(result: ScanDomainResult): string;
+declare function buildStructuredScanResult(result: ScanDomainResult, enrichment?: ScanResultEnrichment): StructuredScanResult;
+declare function formatScanReport(result: ScanDomainResult, format?: OutputFormat): string;
 
 /**
  * scan-domain orchestrator tool.
@@ -492,6 +391,8 @@ interface ScanDomainResult {
     timestamp: string;
     scoringNote: string | null;
     adaptiveWeightDeltas: Record<string, number> | null;
+    /** Category interaction effects applied as post-scoring adjustments. Empty when no interactions triggered. */
+    interactionEffects: InteractionEffect[];
 }
 /**
  * Run a full DNS security scan on a domain.
@@ -503,4 +404,4 @@ interface ScanDomainResult {
  */
 declare function scanDomain(domain: string, kv?: KVNamespace, runtimeOptions?: ScanRuntimeOptions): Promise<ScanDomainResult>;
 
-export { CATEGORY_DISPLAY_WEIGHTS, type CaaRecord, type CheckCategory, type CheckMxOptions, type CheckResult, type DnsAnswer, type DnsAuthority, DnsQueryError, type DohResponse, type DomainContext, type DomainProfile, type ExplanationResult, type Finding, type FindingConfidence, type MaturityStage, type QueryDnsOptions, RecordType, type RecordTypeName, SERVER_VERSION, SEVERITY_PENALTIES, type ScanDomainResult, type ScanRuntimeOptions, type ScanScore, type Severity, type StructuredScanResult, buildCheckResult, buildStructuredScanResult, checkBimi, checkCaa, checkDkim, checkDmarc, checkDnssec, checkLookalikes, checkMtaSts, checkMx, checkNs, checkSpf, checkSsl, checkSubdomainTakeover, checkTlsrpt, computeCategoryScore, computeScanScore, createFinding, detectDomainContext, explainFinding, formatExplanation, formatScanReport, getProfileWeights, inferFindingConfidence, parseCaaRecord, parseDmarcTags, queryCaaRecords, queryDns, queryDnsRecords, queryMxRecords, queryTxtRecords, resolveImpactNarrative, sanitizeDomain, sanitizeInput, scanDomain, scoreToGrade, validateDomain };
+export { type CaaRecord, type CheckMxOptions, type DnsAnswer, type DnsAuthority, DnsQueryError, type DohResponse, type ExplanationResult, type MaturityStage, type QueryDnsOptions, RecordType, type RecordTypeName, SERVER_VERSION, type ScanDomainResult, type ScanRuntimeOptions, type StructuredScanResult, buildStructuredScanResult, checkBimi, checkCaa, checkDkim, checkDmarc, checkDnssec, checkLookalikes, checkMtaSts, checkMx, checkNs, checkSpf, checkSsl, checkSubdomainTakeover, checkTlsrpt, explainFinding, formatExplanation, formatScanReport, parseCaaRecord, queryCaaRecords, queryDns, queryDnsRecords, queryMxRecords, queryTxtRecords, resolveImpactNarrative, sanitizeDomain, sanitizeInput, scanDomain, validateDomain };