@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/lib/domain-posture-analysis.mjs

@@ -2,7 +2,50 @@
 // injected so every traversal can be fixture-tested and the caller retains the
 // existing DNS timeout and missing/error semantics.
 import { parse as parseDomain } from 'tldts';
+import { isValidAsciiHostname } from "../packages/contracts/domain-name.mjs";
 import { parseDmarcRecords, parseDmarcReportingAuthorization, parseReportingDestination, parseSpfRecords } from "./domain-posture-parsers.mjs";
+const SPF_PERMISSIVE_PATH_ISSUE = 'Observed permissive +all evidence on a potentially reachable positive SPF include or redirect path; review sender authorisation.';
+// This is a conservative universal-result check for unconditional all/include
+// chains, not a sender evaluator. Conditional mechanisms remain unknown.
+function spfStaticResult(policy) {
+    const parsed = policy.parsed;
+    if (!parsed?.valid)
+        return { everySender: null, permissive: false };
+    let uncertain = false, permissive = false;
+    const finish = (result) => ({
+        everySender: !uncertain ? result : null,
+        permissive,
+    });
+    for (const mechanism of parsed.mechanisms) {
+        if (mechanism.kind === 'all') {
+            if (mechanism.qualifier === '+')
+                permissive = true;
+            return finish(mechanism.qualifier);
+        }
+        if (mechanism.kind === 'include') {
+            const child = policy.children.get(mechanism.includeIndex);
+            const result = child ? spfStaticResult(child) : { everySender: null, permissive: false };
+            if (mechanism.qualifier === '+' && result.permissive)
+                permissive = true;
+            if (result.everySender === '+')
+                return finish(mechanism.qualifier);
+            if (result.everySender !== null)
+                continue; // Only child pass matches include.
+            uncertain = true;
+        }
+        else {
+            // Without sender evaluation, even a literal mechanism remains conditional.
+            uncertain = true;
+        }
+    }
+    if (parsed.redirect) {
+        const child = policy.children.get(parsed.includes.length);
+        const result = child ? spfStaticResult(child) : { everySender: null, permissive: false };
+        permissive ||= result.permissive;
+        return result.everySender === null ? { everySender: null, permissive } : finish(result.everySender);
+    }
+    return { everySender: null, permissive };
+}
 const SPF_LOOKUP_LIMIT = 10;
 const SPF_VOID_LOOKUP_LIMIT = 2;
 const SPF_MAX_DEPTH = 5;
@@ -40,6 +83,7 @@ function branchFor(item, state, terminalPolicy, dnsLookupTerms, issues) {
     };
 }
 async function expandSpfPolicy(rootDomain, rootQuery, resolveTxt) {
+    const rootPolicy = { parsed: null, children: new Map() };
     const queue = [{
             domain: rootDomain,
             parent: null,
@@ -48,6 +92,7 @@ async function expandSpfPolicy(rootDomain, rootQuery, resolveTxt) {
             path: [rootDomain],
             records: rootQuery.records,
             error: rootQuery.error,
+            policy: rootPolicy,
         }];
     const branches = [];
     const issues = [];
@@ -99,6 +144,7 @@ async function expandSpfPolicy(rootDomain, rootQuery, resolveTxt) {
         branches.push(branchFor(item, parsed.valid ? 'success' : 'invalid', parsed.terminalPolicy, parsed.dnsLookupTerms, parsed.issues));
         if (!parsed.valid)
             continue;
+        item.policy.parsed = parsed;
         if (dnsLookupTerms > SPF_LOOKUP_LIMIT) {
             boundReached = true;
             issues.push(`The expanded policy declares more than ${SPF_LOOKUP_LIMIT} DNS-querying terms.`);
@@ -110,7 +156,9 @@ async function expandSpfPolicy(rootDomain, rootQuery, resolveTxt) {
             ...parsed.includes.map((domain) => ({ relation: 'include', domain })),
             ...(parsed.redirect ? [{ relation: 'redirect', domain: parsed.redirect }] : []),
         ];
-        for (const dependency of dependencies) {
+        for (const [dependencyIndex, dependency] of dependencies.entries()) {
+            const policy = { parsed: null, children: new Map() };
+            item.policy.children.set(dependencyIndex, policy);
             const normalized = strictHostname(dependency.domain);
             if (!normalized) {
                 branches.push(branchFor({
@@ -119,6 +167,7 @@ async function expandSpfPolicy(rootDomain, rootQuery, resolveTxt) {
                     relation: dependency.relation,
                     depth: item.depth + 1,
                     path: item.path,
+                    policy,
                 }, 'invalid', null, 0, ['The SPF dependency is not a literal public hostname; macros are not expanded by this audit.']));
                 continue;
             }
@@ -128,6 +177,7 @@ async function expandSpfPolicy(rootDomain, rootQuery, resolveTxt) {
                 relation: dependency.relation,
                 depth: item.depth + 1,
                 path: [...item.path, normalized],
+                policy,
             });
         }
     }
@@ -144,6 +194,8 @@ async function expandSpfPolicy(rootDomain, rootQuery, resolveTxt) {
             : incomplete
                 ? 'partial'
                 : 'complete';
+    if (rootPolicy.parsed?.terminalPolicy !== 'pass' && spfStaticResult(rootPolicy).permissive)
+        issues.unshift(SPF_PERMISSIVE_PATH_ISSUE);
     return {
         version: 1,
         state,
@@ -166,9 +218,10 @@ function reportDestinationDomain(value) {
     if (/[!,;]/u.test(uri))
         return null;
     const destination = parseReportingDestination(uri);
-    return destination?.scheme === 'mailto' ? strictHostname(destination.host) : null;
+    const domain = destination?.scheme === 'mailto' ? strictHostname(destination.host) : null;
+    return domain && isValidAsciiHostname(domain) ? domain : null;
 }
-async function validateDmarcExternalReporting(ownerDomain, dmarcQuery, resolveTxt) {
+async function validateDmarcExternalReporting(ownerDomain, dmarcQuery, resolveTxt, resolveOrganisationalDomain) {
     if (dmarcQuery.error)
         return [];
     const parsed = parseDmarcRecords(dmarcQuery.records);
@@ -192,7 +245,7 @@ async function validateDmarcExternalReporting(ownerDomain, dmarcQuery, resolveTx
             });
             continue;
         }
-        if (destinationDomain === ownerDomain || destinationDomain.endsWith(`.${ownerDomain}`)) {
+        if (destinationDomain === ownerDomain) {
             results.push({
                 destination: destinationDomain,
                 reportType: item.reportType,
@@ -202,6 +255,20 @@ async function validateDmarcExternalReporting(ownerDomain, dmarcQuery, resolveTx
             });
             continue;
         }
+        const ownerOrganisation = resolveOrganisationalDomain ? await resolveOrganisationalDomain(ownerDomain) : null;
+        const recipientOrganisation = ownerOrganisation && resolveOrganisationalDomain ? await resolveOrganisationalDomain(destinationDomain) : null;
+        if (ownerOrganisation && ownerOrganisation === recipientOrganisation) {
+            results.push({ destination: destinationDomain, reportType: item.reportType, recordName: null, state: 'self', error: null });
+            continue;
+        }
+        const externalConfirmed = Boolean(ownerOrganisation && recipientOrganisation);
+        // Descendant reporting previously made no authorisation request. Do not
+        // broaden default collection to resolve its unknown organisational scope.
+        if (!resolveOrganisationalDomain && destinationDomain.endsWith(`.${ownerDomain}`)) {
+            results.push({ destination: destinationDomain, reportType: item.reportType, recordName: null, state: 'unavailable',
+                error: 'The organisational boundary was not checked. Select the additional DNS review to determine whether external reporting authorisation is required.' });
+            continue;
+        }
         const recordName = `${ownerDomain}._report._dmarc.${destinationDomain}`;
         if (recordName.length > 253) {
             results.push({ destination: destinationDomain, reportType: item.reportType, recordName: null, state: 'unavailable', error: 'The reporting authorisation query exceeds the DNS name limit.' });
@@ -223,8 +290,9 @@ async function validateDmarcExternalReporting(ownerDomain, dmarcQuery, resolveTx
             destination: destinationDomain,
             reportType: item.reportType,
             recordName,
-            state: query.error ? 'unavailable' : authorized ? 'authorized' : 'not_found',
-            error: query.error,
+            state: query.error ? 'unavailable' : authorized ? 'authorized' : externalConfirmed ? 'not_found' : 'unavailable',
+            error: query.error ?? (!authorized && !externalConfirmed
+                ? 'The organisational boundary is unknown; no authorisation requirement can be inferred from the missing record.' : null),
         });
     }
     return results;
@@ -276,4 +344,4 @@ function buildExternalDependencies({ domain, nameservers, mx, spfExpansion, dmar
         || left.target.localeCompare(right.target)
         || left.source.localeCompare(right.source)));
 }
-export { SPF_LOOKUP_LIMIT, SPF_MAX_DEPTH, SPF_VOID_LOOKUP_LIMIT, buildExternalDependencies, expandSpfPolicy, reportDestinationDomain, validateDmarcExternalReporting, };
+export { SPF_PERMISSIVE_PATH_ISSUE, SPF_LOOKUP_LIMIT, SPF_MAX_DEPTH, SPF_VOID_LOOKUP_LIMIT, buildExternalDependencies, expandSpfPolicy, reportDestinationDomain, validateDmarcExternalReporting, };

package/lib/domain-posture-parsers.mjs

@@ -48,6 +48,7 @@ function parseSpfRecords(records) {
         terminalPolicy: null,
         redirect: null,
         includes: [],
+        mechanisms: [],
         authorizingTerms: [],
         dnsLookupTerms: 0,
         issues: [],
@@ -175,6 +176,14 @@ function parseSpfRecords(records) {
     result.includes = terms
         .map((term) => term.match(/^[+?~-]?include:(.+)$/i)?.[1] || '')
         .filter(Boolean);
+    let includeIndex = 0;
+    result.mechanisms = terms.filter(term => !/^[+?~-]?[a-z][a-z0-9_.-]*=/iu.test(term)).map(term => {
+        const qualifier = (/^[+?~-]/u.test(term) ? term[0] : '+');
+        const body = /^[+?~-]/u.test(term) ? term.slice(1) : term;
+        const include = body.match(/^include:(.+)$/iu);
+        return { kind: /^all$/iu.test(body) ? 'all' : include ? 'include' : 'other', qualifier,
+            includeIndex: include ? includeIndex++ : null };
+    });
     if (terms.some((term) => /^[+?~-]?ptr(?::|$)/i.test(term))) {
         result.issues.push('The deprecated ptr mechanism should not be used.');
     }

package/lib/domain-posture.mjs

@@ -7,12 +7,12 @@ import { nonEmptyErrorMessage } from "./error-detail.mjs";
 import { safeFetch, readTextCapped } from "./safe-fetch.mjs";
 import { whoisleuthRequestHeaders } from "./outbound-identity.mjs";
 import { classifyMxRecords } from "./dns-mx.mjs";
-import { collectDnsInheritanceChecks } from "./dns-inheritance-review.mjs";
+import { collectDnsInheritanceReview } from "./dns-inheritance-review.mjs";
 import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 import { DOMAIN_POSTURE_COMPARISON_VERSION, MAX_POSTURE_CHECK_RECORDS, POSTURE_CHECK_SOURCES } from "../packages/evidence/domain-posture-context.mjs";
 import { canonicalPostureRecords } from "../packages/evidence/domain-control-runtime.mjs";
 import { parseSpfRecords, parseDmarcRecords, parseMtaStsDnsRecords, parseMtaStsPolicy, parseTlsRptRecords, parseBimiRecords, parseDkimRecords, } from "./domain-posture-parsers.mjs";
-import { buildExternalDependencies, expandSpfPolicy, validateDmarcExternalReporting, } from "./domain-posture-analysis.mjs";
+import { SPF_PERMISSIVE_PATH_ISSUE, buildExternalDependencies, expandSpfPolicy, validateDmarcExternalReporting, } from "./domain-posture-analysis.mjs";
 const DNS_TIMEOUT_MS = 6000;
 const POLICY_TIMEOUT_MS = 7000;
 const MAX_POLICY_BYTES = 64 * 1024;
@@ -156,7 +156,8 @@ function spfCheck(query, expansion) {
             remediation: 'Replace +all with an explicit sender allowlist and a restrictive terminal policy.',
         });
     }
-    if (parsed.terminalPolicy === 'fail' && parsed.issues.length === 0 && (!expansion || expansion.state === 'complete')) {
+    const permissiveExpansion = expansion?.issues.includes(SPF_PERMISSIVE_PATH_ISSUE) ?? false;
+    if (parsed.terminalPolicy === 'fail' && parsed.issues.length === 0 && !permissiveExpansion && (!expansion || expansion.state === 'complete')) {
         return check('spf', 'SPF', 'pass', 'Restrictive fail-all policy', { detail: details.join(' '), records: parsed.records });
     }
     if (expansion && expansion.state !== 'complete') {
@@ -166,6 +167,12 @@ function spfCheck(query, expansion) {
             remediation: 'Review unresolved, invalid, cyclic, or budget-limited include and redirect branches before treating the policy as complete.',
         });
     }
+    if (permissiveExpansion) {
+        return check('spf', 'SPF', 'warning', 'SPF authorisation needs review', {
+            detail: details.join(' '), records: parsed.records,
+            remediation: 'Review the positive include or redirect path containing +all; complete collection does not establish restrictive sender authorisation.',
+        });
+    }
     if (parsed.terminalPolicy === 'redirect') {
         return check('spf', 'SPF', 'info', 'Policy delegates evaluation with redirect', {
             detail: details.join(' '), records: parsed.records,
@@ -202,16 +209,18 @@ function dmarcCheck(query, authorizations = []) {
         parsed.failureReporting ? 'Failure reporting is configured.' : 'No failure reporting destination is configured.',
         ...parsed.issues,
     ];
-    const external = authorizations.filter((authorization) => authorization.state !== 'self');
-    const unresolvedExternal = external.filter((authorization) => authorization.state !== 'authorized');
+    const unresolvedExternal = authorizations.filter((authorization) => !['self', 'authorized'].includes(authorization.state));
     const intendedDestinations = parsed.aggregateDestinations.length + parsed.failureDestinations.length;
     const omittedDestinations = Math.max(0, intendedDestinations - authorizations.length);
     if (omittedDestinations) {
         details.push(`Reporting authorisation coverage: ${authorizations.length} of ${intendedDestinations} destinations reviewed; ${omittedDestinations} not checked within the bounded collection. Omitted destinations are not assumed authorised.`);
     }
-    if (external.length > 0) {
-        details.push(`${external.length} external reporting destination${external.length === 1 ? '' : 's'} checked; `
-            + `${unresolvedExternal.length} could not be authorized.`);
+    if (authorizations.length > 0) {
+        details.push(`${authorizations.length} reporting destination${authorizations.length === 1 ? '' : 's'} reviewed; `
+            + `${unresolvedExternal.length} need further evidence.`);
+    }
+    if (unresolvedExternal.some(item => item.state === 'unavailable')) {
+        details.push('An unknown organisational boundary or unavailable query does not establish a missing authorisation requirement.');
     }
     if (parsed.testMode) {
         return check('dmarc', 'DMARC', 'warning', 'Policy is in test mode (t=y)', {
@@ -235,9 +244,7 @@ function dmarcCheck(query, authorizations = []) {
         return check('dmarc', 'DMARC', 'warning', `Enforced at p=${parsed.policy}; reporting authorisation is incomplete`, {
             detail: `${details.join(' ')} ${unresolvedExternal.map((authorization) => `${authorization.destination}: ${authorization.state}.`).join(' ')}`,
             records: parsed.records,
-            remediation: omittedDestinations > 0
-                ? 'Review the unchecked destinations and confirm any required external reporting authorisation before relying on delivery.'
-                : 'Publish the required external reporting authorisation record or remove the unavailable destination.',
+            remediation: 'Review unresolved destinations and their organisational boundaries, then confirm any required external reporting authorisation before relying on delivery.',
         });
     }
     if (!parsed.aggregateReporting) {
@@ -301,6 +308,11 @@ function dnssecDelegationConsistencyCheck(input, registry) {
     }
     const value = String(input.value || '').toLowerCase();
     const hasDsRecords = registry.dsRecordCount > 0;
+    if (registry.dsDataTruncated) {
+        return check('dnssec_delegation_consistency', 'DNSSEC delegation consistency', 'info', 'Retained DS evidence is incomplete', {
+            detail: 'The normalised registry response reported truncated DS data, so delegation consistency is inconclusive.',
+        });
+    }
     if (value === 'signed' && hasDsRecords) {
         return check('dnssec_delegation_consistency', 'DNSSEC delegation consistency', 'pass', 'Signed state and retained DS records agree', {
             detail: `${registry.dsRecordCount} registry DS record${registry.dsRecordCount === 1 ? '' : 's'} retained.`,
@@ -311,11 +323,6 @@ function dnssecDelegationConsistencyCheck(input, registry) {
             detail: 'This is a consistency result, not a recommendation to leave DNSSEC disabled.',
         });
     }
-    if (registry.dsDataTruncated) {
-        return check('dnssec_delegation_consistency', 'DNSSEC delegation consistency', 'info', 'Retained DS evidence is incomplete', {
-            detail: 'The normalised registry response reported truncated DS data, so apparent disagreement is inconclusive.',
-        });
-    }
     if (value === 'signed' && !hasDsRecords) {
         return check('dnssec_delegation_consistency', 'DNSSEC delegation consistency', 'warning', 'Signed state reported without retained DS records', {
             detail: 'This can reflect registry publication differences or incomplete upstream data and should be reviewed before changing delegation.',
@@ -360,13 +367,25 @@ function matchesMtaPattern(host, pattern) {
     }
     return normalizedHost === normalizedPattern;
 }
+function mailPolicyApplicability(mxQuery) {
+    if (mxQuery.error)
+        return { hasMx: false, detail: 'Receiving-mail applicability is unknown because the MX lookup failed.' };
+    const records = completeMxRecords(mxQuery.records);
+    if (!records)
+        return { hasMx: false, detail: 'Receiving-mail applicability is unknown because the MX evidence is incomplete.' };
+    const { hasMx, hasNullMx } = classifyMxRecords(records);
+    return { hasMx, detail: hasMx ? '' : hasNullMx
+            ? 'Null MX explicitly declares that this domain does not accept inbound mail.'
+            : 'No MX records were observed. This alone does not establish that the domain cannot receive mail.' };
+}
 function mtaStsCheck(dnsQuery, policyFetch, mxQuery) {
     if (dnsQuery.error)
         return queryFailureCheck('mta_sts', 'MTA-STS', dnsQuery.error);
     const dnsPolicy = parseMtaStsDnsRecords(dnsQuery.records);
-    const hasMx = !mxQuery.error && classifyMxRecords(asMxRecords(mxQuery.records)).hasMx;
     if (dnsPolicy.records.length === 0) {
+        const { hasMx, detail } = mailPolicyApplicability(mxQuery);
         return check('mta_sts', 'MTA-STS', hasMx ? 'warning' : 'info', 'No MTA-STS policy advertised', {
+            detail,
             remediation: hasMx ? 'Publish _mta-sts and serve a valid policy over HTTPS to require authenticated TLS for inbound mail.' : '',
         });
     }
@@ -436,9 +455,9 @@ function tlsRptCheck(query, mxQuery) {
         return queryFailureCheck('tls_rpt', 'TLS-RPT', query.error);
     const parsed = parseTlsRptRecords(query.records);
     if (parsed.records.length === 0) {
-        const hasMx = !mxQuery.error && classifyMxRecords(asMxRecords(mxQuery.records)).hasMx;
+        const { hasMx, detail } = mailPolicyApplicability(mxQuery);
         return check('tls_rpt', 'TLS-RPT', hasMx ? 'warning' : 'info', 'No SMTP TLS reporting policy', {
-            detail: hasMx ? '' : 'The domain has no receiving mail exchanger, so SMTP TLS reporting is not currently actionable.',
+            detail,
             remediation: hasMx ? 'Publish a v=TLSRPTv1 record at _smtp._tls with a monitored rua destination.' : '',
         });
     }
@@ -785,17 +804,18 @@ async function collectDomainPosture(domain, { dkimSelectors = [], retiredDkimSel
     const enrichment = [
         parsedMtaDns?.valid ? dependencies.fetchMtaStsPolicy(domain, signal) : Promise.resolve(null),
         expandSpfPolicy(domain, spf, resolveEnrichmentTxt),
-        validateDmarcExternalReporting(domain, dmarc, resolveEnrichmentTxt),
         includeInheritedDns === true
-            ? (dependencies.collectDnsInheritanceChecks
-                ? dependencies.collectDnsInheritanceChecks(domain, dmarc, nameservers, signal ? { signal } : {})
+            ? (dependencies.collectDnsInheritanceReview
+                ? dependencies.collectDnsInheritanceReview(domain, dmarc, nameservers, signal ? { signal } : {})
                 : Promise.reject(new TypeError('The explicit DNS review collector is unavailable.')))
-            : Promise.resolve([]),
+            : validateDmarcExternalReporting(domain, dmarc, resolveEnrichmentTxt)
+                .then(dmarcAuthorizations => ({ checks: [], dmarcAuthorizations })),
     ];
     // A rejected policy request must not release the operation's capacity while
     // other started enrichment collectors are still settling.
-    const [mtaStsPolicy, spfExpansion, dmarcAuthorizations, inheritanceChecks] = await Promise.all(enrichment)
+    const [mtaStsPolicy, spfExpansion, dnsReview] = await Promise.all(enrichment)
         .finally(() => Promise.allSettled(enrichment));
+    const { dmarcAuthorizations, checks: inheritanceChecks } = dnsReview;
     signal?.throwIfAborted();
     const dnssec = !rdap
         ? { value: null, error: 'RDAP did not return a domain record.' }
@@ -884,7 +904,7 @@ async function checkDomainPosture(domain, options = {}, dependencies) {
             now: () => new Date(),
             setTimer: (callback, milliseconds) => setTimeout(callback, milliseconds),
             clearTimer: handle => clearTimeout(handle),
-            collectDnsInheritanceChecks,
+            collectDnsInheritanceReview,
         });
     }
     finally {