blackveil-dns 1.4.0

package/dist/index.d.ts

@@ -0,0 +1,506 @@
+/** Standard DNS record type codes */
+declare const RecordType: {
+    readonly A: 1;
+    readonly AAAA: 28;
+    readonly CNAME: 5;
+    readonly MX: 15;
+    readonly TXT: 16;
+    readonly NS: 2;
+    readonly SOA: 6;
+    readonly CAA: 257;
+    readonly TLSA: 52;
+    readonly DNSKEY: 48;
+    readonly DS: 43;
+    readonly RRSIG: 46;
+    readonly PTR: 12;
+    readonly SRV: 33;
+};
+type RecordTypeName = keyof typeof RecordType;
+/** A single DNS answer record from the DoH JSON response */
+interface DnsAnswer {
+    name: string;
+    type: number;
+    TTL: number;
+    data: string;
+}
+/** A single DNS authority record */
+interface DnsAuthority {
+    name: string;
+    type: number;
+    TTL: number;
+    data: string;
+}
+/** Cloudflare DoH JSON wire-format response */
+interface DohResponse {
+    Status: number;
+    TC: boolean;
+    RD: boolean;
+    RA: boolean;
+    AD: boolean;
+    CD: boolean;
+    Question: Array<{
+        name: string;
+        type: number;
+    }>;
+    Answer?: DnsAnswer[];
+    Authority?: DnsAuthority[];
+}
+/** Configuration for a custom secondary DoH resolver (e.g., bv-dns on Oracle Cloud). */
+interface SecondaryDohConfig {
+    /** DoH endpoint URL (e.g. https://harlan.blackveilsecurity.com/dns-query) */
+    endpoint: string;
+    /** Optional auth token sent as X-BV-Token header */
+    token?: string;
+}
+interface QueryDnsOptions {
+    timeoutMs?: number;
+    retries?: number;
+    confirmWithSecondaryOnEmpty?: boolean;
+    /** When true, skip secondary resolver confirmation on empty results. Used in scan context for speed. */
+    skipSecondaryConfirmation?: boolean;
+    /** Scan-scoped DNS query cache. Stores Promises keyed by `domain:type:dnssecCheck` to deduplicate concurrent and sequential identical queries within a single scan. */
+    queryCache?: Map<string, Promise<DohResponse>>;
+    /** Custom secondary DoH resolver. When set, used instead of Google DoH for empty-result confirmation. Falls back to Google if this resolver fails. */
+    secondaryDoh?: SecondaryDohConfig;
+}
+
+/** Error thrown when a DNS query fails */
+declare class DnsQueryError extends Error {
+    readonly domain: string;
+    readonly recordType: string;
+    readonly status?: number | undefined;
+    constructor(message: string, domain: string, recordType: string, status?: number | undefined);
+}
+/**
+ * Query Cloudflare DoH for DNS records.
+ *
+ * When `opts.queryCache` is provided, deduplicates concurrent and sequential
+ * identical queries within a single scan by caching the Promise keyed by
+ * `domain:type:dnssecCheck`. Failed queries are evicted so retries can re-attempt.
+ *
+ * @param domain - The domain name to query
+ * @param type - DNS record type name (e.g. "TXT", "MX", "A")
+ * @param dnssecCheck - If true, sets the CD=0 flag to request DNSSEC validation
+ * @returns The full DoH JSON response
+ */
+declare function queryDns(domain: string, type: RecordTypeName, dnssecCheck?: boolean, opts?: QueryDnsOptions): Promise<DohResponse>;
+
+/** Parsed CAA record with flags, tag, and value */
+interface CaaRecord {
+    flags: number;
+    tag: string;
+    value: string;
+}
+/**
+ * Query DNS and return just the answer data strings.
+ * Returns an empty array if no answers are found.
+ */
+declare function queryDnsRecords(domain: string, type: RecordTypeName, opts?: QueryDnsOptions): Promise<string[]>;
+/**
+ * Query TXT records, concatenate multi-string values, and unescape DNS
+ * presentation-format backslash sequences.
+ *
+ * Cloudflare DoH returns TXT data with surrounding quotes and multiple
+ * strings separated by `" "`.  Per RFC 7208 §3.3, multi-string TXT records
+ * MUST be concatenated without adding spaces.  Some nameservers also emit
+ * RFC 1035 §5.1 backslash escapes (e.g. `\;` for a literal semicolon);
+ * we unescape both `\X` (single-char) and `\DDD` (decimal octet) forms.
+ */
+declare function queryTxtRecords(domain: string, opts?: QueryDnsOptions): Promise<string[]>;
+/**
+ * Parse a single CAA record data string.
+ * Handles both human-readable format (e.g. `0 issue "letsencrypt.org"`)
+ * and Cloudflare DoH hex wire format (e.g. `\# 19 00 05 69 73 73 75 65...`).
+ *
+ * Wire format bytes: flags(1) + tag_length(1) + tag(tag_length) + value(rest)
+ */
+declare function parseCaaRecord(data: string): CaaRecord | null;
+/**
+ * Query CAA records and parse them into structured objects.
+ * Handles both human-readable and hex wire format from DoH.
+ */
+declare function queryCaaRecords(domain: string, opts?: QueryDnsOptions): Promise<CaaRecord[]>;
+/**
+ * Query MX records and parse them into priority + exchange pairs.
+ */
+declare function queryMxRecords(domain: string, opts?: QueryDnsOptions): Promise<Array<{
+    priority: number;
+    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.
+ * Compatible with Cloudflare Workers runtime (no Node.js APIs).
+ */
+interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate and sanitize a domain name for DNS queries.
+ * Rejects localhost, private/reserved TLDs, IP addresses, and malformed domains.
+ */
+declare function validateDomain(input: string): ValidationResult;
+/**
+ * Sanitize a domain string: trim, lowercase, remove trailing dot.
+ * Call validateDomain first to ensure the domain is valid.
+ */
+declare function sanitizeDomain(input: string): string;
+/**
+ * Sanitize arbitrary text input for safe logging/display.
+ * Removes control characters except newlines and tabs, and truncates length.
+ */
+declare function sanitizeInput(input: string, maxLength?: number): string;
+
+/** Server version — keep in sync with package.json */
+declare const SERVER_VERSION = "1.4.0";
+
+/**
+ * Check BIMI records for a domain.
+ * Validates the presence and configuration of BIMI TXT records,
+ * including logo URL format and VMC authority evidence.
+ */
+declare function checkBimi(domain: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
+
+/**
+ * Check CAA records for a domain.
+ * Validates that CAA records exist and are properly configured.
+ */
+declare function checkCaa(domain: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
+
+/**
+ * Check DKIM records for a domain.
+ * Probes common selectors at <selector>._domainkey.<domain>.
+ * Optionally accepts a specific selector to check.
+ */
+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.
+ */
+declare function checkDmarc(domain: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
+
+/**
+ * Check DNSSEC configuration for a domain.
+ * Verifies the AD (Authenticated Data) flag, checks for DNSKEY/DS records,
+ * and audits algorithm and digest type security.
+ */
+declare function checkDnssec(domain: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
+
+/**
+ * Detect registered lookalike/typosquat domains with DNS or mail infrastructure.
+ * Generates domain permutations and checks for active registrations using adaptive batching.
+ * Filters out false positives from wildcard DNS on parent domains and null MX records.
+ */
+declare function checkLookalikes(domain: string): Promise<CheckResult>;
+
+/**
+ * Check MTA-STS configuration for a domain.
+ * Queries _mta-sts.<domain> TXT records and optionally fetches the policy file.
+ */
+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[];
+    providerSignaturesSha256?: string;
+}
+/** Check MX record configuration for a domain */
+declare function checkMx(domain: string, options?: CheckMxOptions, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
+
+/**
+ * Check nameserver configuration for a domain.
+ * Validates NS records exist, checks for diversity, and verifies responsiveness.
+ */
+declare function checkNs(domain: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
+
+/**
+ * Check SPF records for a domain.
+ * Looks for v=spf1 TXT records and validates their configuration.
+ * Recursively expands include chains to compute true DNS lookup count.
+ */
+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.
+ */
+declare function checkSubdomainTakeover(domain: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
+
+/**
+ * Check TLS-RPT records for a domain.
+ * Validates the presence and configuration of SMTP TLS Reporting records.
+ */
+declare function checkTlsrpt(domain: string, dnsOptions?: QueryDnsOptions): Promise<CheckResult>;
+
+interface ImpactNarrative {
+    impact?: string;
+    adverseConsequences?: string;
+}
+
+/**
+ * Explain Finding tool.
+ * Provides static explanations for DNS security findings.
+ * No AI binding required - uses a built-in knowledge base.
+ */
+
+interface ExplanationResult {
+    checkType: string;
+    status: string;
+    details?: string;
+    title: string;
+    severity: string;
+    explanation: string;
+    impact?: string;
+    adverseConsequences?: string;
+    recommendation: string;
+    references: string[];
+}
+/**
+ * Resolve impact/adverse-consequence narrative for a finding context.
+ * Uses explicit explanation entries first, then category, then severity fallback.
+ */
+declare function resolveImpactNarrative(params: {
+    checkType?: string;
+    category?: string;
+    status?: string;
+    severity?: string;
+    title?: string;
+    detail?: string;
+}): ImpactNarrative;
+declare function explainFinding(checkType: string, status: string, details?: string): ExplanationResult;
+declare function formatExplanation(result: ExplanationResult): string;
+
+interface ScanRuntimeOptions {
+    providerSignaturesUrl?: string;
+    providerSignaturesAllowedHosts?: string[];
+    providerSignaturesSha256?: string;
+    profile?: 'mail_enabled' | 'enterprise_mail' | 'non_mail' | 'web_only' | 'minimal' | 'auto';
+    profileAccumulator?: DurableObjectNamespace;
+    waitUntil?: (promise: Promise<unknown>) => void;
+    scoringConfig?: ScoringConfig;
+    /** Override cache TTL in seconds (default: 300). Clamped to [60, 3600]. */
+    cacheTtlSeconds?: number;
+    /** Custom secondary DoH resolver config (bv-dns). Threaded to scanDns but only active when skipSecondaryConfirmation is false. */
+    secondaryDoh?: SecondaryDohConfig;
+}
+
+/**
+ * Email Security Maturity Staging.
+ * Classifies a domain's email security posture into a maturity stage (0-4)
+ * based on the results of individual DNS security checks.
+ */
+
+interface MaturityStage {
+    stage: number;
+    label: string;
+    description: string;
+    nextStep: string;
+}
+
+/** Structured scan result for machine-readable consumption (e.g., CI/CD actions). */
+interface StructuredScanResult {
+    domain: string;
+    score: number;
+    grade: string;
+    passed: boolean;
+    maturityStage: number | null;
+    maturityLabel: string | null;
+    categoryScores: Record<string, number>;
+    findingCounts: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+    };
+    scoringProfile: string;
+    scoringSignals: string[];
+    scoringNote: string | null;
+    adaptiveWeightDeltas: Record<string, number> | null;
+    timestamp: string;
+    cached: boolean;
+}
+/** Build a machine-readable structured result from a scan. */
+declare function buildStructuredScanResult(result: ScanDomainResult): StructuredScanResult;
+declare function formatScanReport(result: ScanDomainResult): string;
+
+/**
+ * scan-domain orchestrator tool.
+ * Runs all DNS security checks in parallel via Promise.all
+ * and computes an overall security score.
+ *
+ * Uses KV-backed cache with 5-minute TTL for scan results when available,
+ * with in-memory fallback when KV is not configured.
+ * Compatible with Cloudflare Workers runtime (no Node.js APIs).
+ */
+
+interface ScanDomainResult {
+    domain: string;
+    score: ScanScore;
+    checks: CheckResult[];
+    maturity: MaturityStage;
+    context: DomainContext;
+    cached: boolean;
+    timestamp: string;
+    scoringNote: string | null;
+    adaptiveWeightDeltas: Record<string, number> | null;
+}
+/**
+ * Run a full DNS security scan on a domain.
+ * Executes all checks in parallel and computes an overall score.
+ *
+ * @param domain - The domain to scan (must already be validated and sanitized by the caller)
+ * @param kv - Optional KV namespace for persistent scan result caching
+ * @returns Full scan result with score, individual check results, and metadata
+ */
+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 };