@slicedearth/whoisleuth-cli 1.36.1 → 1.39.1

package/cli/lookup-timeline.mjs

@@ -85,7 +85,7 @@ function buildCliLookupTimeline(inputs, generatedAt = new Date().toISOString())
             rawRegistryPayloadsCopied: 0,
         },
         limitations: [
-            'The timeline compares only bounded normalized fields already present in the selected saved Lookup documents and makes no network request.',
+            'The timeline compares only bounded normalised fields already present in the selected saved Lookup documents and makes no network request.',
             'Input filenames and raw registry payloads are not copied into the timeline output.',
             'Missing, unavailable, and not-recorded evidence remain separate from an observed difference.',
             'A difference can reflect a domain change or changed collection conditions and does not by itself establish current state, ownership, intent, safety, or maliciousness.',

package/cli/mail-review.mjs

@@ -213,7 +213,7 @@ function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
             'This review is passive and uses DNS evidence already retained in a WHOISleuth Bulk result; it makes no network request.',
             'Null MX, no explicit MX, receiving mail, authentication gaps, and incomplete evidence remain separate states.',
             'Optional TLSA evidence is compared offline. A DANE match requires separately validated DNSSEC evidence from the same observation.',
-            'SMTP delivery, mailbox existence, catch-all behavior, banner collection, and message acceptance were not tested.',
+            'SMTP delivery, mailbox existence, catch-all behaviour, banner collection, and message acceptance were not tested.',
         ],
     };
 }

package/cli/offline-evidence-review.mjs

@@ -6,6 +6,7 @@ import { normalizeRdapSearchHelp, planRdapReverseSearch, } from "../lib/rdap-sea
 import { reviewRpkiRoute } from "../lib/rpki-evidence.mjs";
 import { analyzeTlsaEvidence } from "../lib/tlsa-evidence.mjs";
 import { CliUsageError } from "./errors.mjs";
+import { LOCAL_MMDB_QUERY_SCHEMA, reviewLocalMmdb } from "./local-mmdb-review.mjs";
 const OFFLINE_EVIDENCE_REVIEW_SCHEMA = 'whoisleuth.cli.offline-evidence-review';
 const OFFLINE_EVIDENCE_REVIEW_VERSION = 1;
 const MAX_OFFLINE_EVIDENCE_INPUT_BYTES = 16 * 1024 * 1024;
@@ -88,7 +89,7 @@ function buildOfflineEvidenceReview(value, generatedAt = new Date().toISOString(
         result = planEncryptedDnsQuery(normalizeEncryptedDnsAdapter(input.adapter), { name: query.name, type: query.type });
     }
     else {
-        throw new CliUsageError('Offline evidence review does not recognize this input schema.');
+        throw new CliUsageError('Offline evidence review does not recognise this input schema.');
     }
     return Object.freeze({
         schema: OFFLINE_EVIDENCE_REVIEW_SCHEMA,
@@ -101,6 +102,23 @@ function buildOfflineEvidenceReview(value, generatedAt = new Date().toISOString(
         ]),
     });
 }
+async function buildOfflineEvidenceReviewWithLocalResources(value, generatedAt = new Date().toISOString(), options = {}) {
+    const input = parseInput(value);
+    if (input.schema !== LOCAL_MMDB_QUERY_SCHEMA)
+        return buildOfflineEvidenceReview(value, generatedAt);
+    if (!options.mmdbPath)
+        throw new CliUsageError('Local MMDB review requires --mmdb <database-file>.');
+    return Object.freeze({
+        schema: OFFLINE_EVIDENCE_REVIEW_SCHEMA,
+        version: OFFLINE_EVIDENCE_REVIEW_VERSION,
+        generatedAt,
+        kind: 'geoip',
+        result: await reviewLocalMmdb(input, options.mmdbPath),
+        limitations: Object.freeze([
+            'The review is local and uses only the supplied query metadata and analyst-supplied database. It does not transmit the address or refresh the database.',
+        ]),
+    });
+}
 function formatOfflineEvidenceReview(document) {
     const result = record(document.result);
     const state = typeof result.state === 'string' ? result.state : 'reviewed';
@@ -138,4 +156,4 @@ function formatOfflineEvidenceReview(document) {
     }
     return `${lines.join('\n')}\n`;
 }
-export { MAX_OFFLINE_EVIDENCE_INPUT_BYTES, OFFLINE_EVIDENCE_REVIEW_SCHEMA, OFFLINE_EVIDENCE_REVIEW_VERSION, buildOfflineEvidenceReview, formatOfflineEvidenceReview, };
+export { MAX_OFFLINE_EVIDENCE_INPUT_BYTES, OFFLINE_EVIDENCE_REVIEW_SCHEMA, OFFLINE_EVIDENCE_REVIEW_VERSION, buildOfflineEvidenceReview, buildOfflineEvidenceReviewWithLocalResources, formatOfflineEvidenceReview, };

package/cli/registry-doctor.mjs

@@ -0,0 +1,125 @@
+import { registryCapabilityFor, REGISTRY_CAPABILITIES_VERSION } from "../lib/registry-capabilities.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { parseSavedLookupDocument } from "./saved-lookup.mjs";
+const REGISTRY_DOCTOR_SCHEMA = 'whoisleuth.cli.registry-doctor';
+const REGISTRY_DOCTOR_VERSION = 1;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function status(value) {
+    return typeof value === 'string'
+        ? value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').trim().toLowerCase().slice(0, 40) || 'unavailable'
+        : 'unavailable';
+}
+function expectedWhois(profile) {
+    if (profile === 'iana-referral')
+        return 'allowed';
+    if (profile === 'registry-policy-restricted' || profile === 'source-ip-authorization-required')
+        return 'permission_required';
+    return 'unsupported';
+}
+function sourceAlignment(expected, observed) {
+    const successful = ['complete', 'partial', 'success'].includes(observed);
+    const constrained = ['disabled', 'skipped', 'unsupported'].includes(observed);
+    if (expected === 'allowed')
+        return successful ? 'observed' : 'investigate';
+    if (successful)
+        return 'unexpected_observation';
+    return constrained ? 'expected_constraint' : 'investigate';
+}
+function normalizedObjectIdentifier(parsed) {
+    const candidate = parsed.handle ?? parsed.objectIdentifier ?? parsed.registryObjectId ?? parsed.id;
+    return typeof candidate === 'string' && candidate.trim() ? 'observed' : 'not_observed';
+}
+function buildRegistryDoctorReport(raw, generatedAt = new Date().toISOString()) {
+    const document = parseSavedLookupDocument(raw, { label: 'Registry doctor input' });
+    const capability = registryCapabilityFor(document.registrableDomain);
+    if (!capability)
+        throw new CliUsageError('Registry doctor could not resolve a capability profile for this domain.');
+    const diagnostics = record(document.diagnostics);
+    const rdap = record(document.rdap);
+    const whois = record(document.whois);
+    const rdapParsed = record(rdap.parsed);
+    const whoisParsed = record(whois.parsed);
+    const sourceInputs = [
+        {
+            source: 'rdap',
+            expected: capability.rdapAccessProfile === 'iana-bootstrap' ? 'allowed' : 'unsupported',
+            observed: status(record(diagnostics.rdap).status),
+            parsed: rdapParsed,
+        },
+        {
+            source: 'whois',
+            expected: expectedWhois(capability.whoisAccessProfile),
+            observed: status(record(diagnostics.whois).status),
+            parsed: whoisParsed,
+        },
+    ];
+    const sources = sourceInputs.map((source) => ({
+        source: source.source,
+        expected: source.expected,
+        observed: source.observed,
+        alignment: sourceAlignment(source.expected, source.observed),
+        normalizedFields: Object.keys(source.parsed).length,
+        objectIdentifier: normalizedObjectIdentifier(source.parsed),
+        limitation: capability.limitation.slice(0, 500),
+    }));
+    const recommendations = [
+        ...sources.filter((source) => source.alignment === 'investigate').map((source) => (source.expected === 'allowed'
+            ? `Review ${source.source.toUpperCase()} source health, transport attempts, and fixture coverage; the catalogue expected collection to be available.`
+            : `Review the ${source.source.toUpperCase()} result and capability profile; the observed state did not match the declared access constraint.`)),
+        ...sources.filter((source) => source.alignment === 'unexpected_observation').map((source) => (`Review why ${source.source.toUpperCase()} produced normalized evidence despite the declared ${source.expected.replaceAll('_', ' ')} access profile.`)),
+        ...sources.filter((source) => source.alignment === 'observed' && source.objectIdentifier === 'not_observed').map((source) => (`${source.source.toUpperCase()} succeeded without a retained registry object identifier; this can be a valid publication omission and should remain unknown rather than an error.`)),
+    ].slice(0, 12);
+    return {
+        schema: REGISTRY_DOCTOR_SCHEMA,
+        version: REGISTRY_DOCTOR_VERSION,
+        generatedAt,
+        domain: document.registrableDomain,
+        suffix: capability.suffixes[0] || document.registrableDomain.split('.').at(-1) || '',
+        catalogueVersion: REGISTRY_CAPABILITIES_VERSION,
+        profile: {
+            id: capability.id,
+            explicitSuffixProfile: capability.explicitSuffixProfile,
+            coverageState: capability.coverageState,
+        },
+        sources,
+        summary: {
+            investigate: sources.filter((source) => source.alignment === 'investigate' || source.alignment === 'unexpected_observation').length,
+            expectedConstraints: sources.filter((source) => source.alignment === 'expected_constraint').length,
+            observed: sources.filter((source) => source.alignment === 'observed').length,
+        },
+        recommendations,
+        limitations: [
+            'This diagnostic compares one saved observation with the local reviewed capability catalogue and makes no registry, registrar, RDAP, or WHOIS request.',
+            'A catalogue alignment does not prove live reachability, parser completeness, current registry policy, registration, availability, ownership, safety, or maliciousness.',
+            'A missing registry object identifier can be a publication characteristic. It remains not observed and is not converted into a collection failure.',
+            'Use fixture-based maintenance checks before changing a registry parser or access profile; automated tests must not contact live registries.',
+        ],
+    };
+}
+function formatRegistryDoctorReport(report) {
+    const output = [
+        'Registry compatibility diagnostic',
+        `Domain             ${report.domain}`,
+        `Profile            ${report.profile.id}${report.profile.explicitSuffixProfile ? ' (explicit)' : ' (default)'}`,
+        `Review items       ${report.summary.investigate}`,
+        '',
+    ];
+    for (const source of report.sources) {
+        output.push(`${source.source.toUpperCase()} [${source.alignment.replaceAll('_', ' ')}]`);
+        output.push(`  Expected: ${source.expected.replaceAll('_', ' ')}`);
+        output.push(`  Observed: ${source.observed.replaceAll('_', ' ')}`);
+        output.push(`  Object identifier: ${source.objectIdentifier.replaceAll('_', ' ')}`);
+    }
+    if (report.recommendations.length) {
+        output.push('', 'Recommendations:');
+        for (const item of report.recommendations)
+            output.push(`  - ${item}`);
+    }
+    output.push('', 'Limitations:');
+    for (const limitation of report.limitations)
+        output.push(`  - ${limitation}`);
+    return `${output.join('\n')}\n`;
+}
+export { REGISTRY_DOCTOR_SCHEMA, REGISTRY_DOCTOR_VERSION, buildRegistryDoctorReport, formatRegistryDoctorReport, };

package/cli/risk-calibration.mjs

@@ -1,11 +1,13 @@
 import { Buffer } from 'node:buffer';
 import { isValidAsciiDomainName } from "../lib/hostname.mjs";
+import { ANALYST_REVIEW_REASON_VALUES, analystInteroperabilityTags } from "../lib/analyst-taxonomy.mjs";
 import { CliUsageError } from "./arguments.mjs";
 import { RISK_MUTATION_TYPES, RISK_REVIEW_THRESHOLD } from "../lib/risk-scoring.mjs";
 export const RISK_CALIBRATION_DATASET_SCHEMA = 'whoisleuth.risk-calibration-dataset';
-export const RISK_CALIBRATION_DATASET_VERSION = 1;
+export const RISK_CALIBRATION_DATASET_VERSION = 2;
+export const SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS = Object.freeze([1, RISK_CALIBRATION_DATASET_VERSION]);
 export const RISK_CALIBRATION_REPORT_SCHEMA = 'whoisleuth.cli.risk-calibration';
-export const RISK_CALIBRATION_REPORT_VERSION = 1;
+export const RISK_CALIBRATION_REPORT_VERSION = 2;
 export const MAX_RISK_CALIBRATION_INPUT_BYTES = 2 * 1024 * 1024;
 export const MAX_RISK_CALIBRATION_RECORDS = 500;
 export const MAX_RISK_CALIBRATION_STRING_LENGTH = 256;
@@ -24,8 +26,10 @@ const AVAILABILITY_STATES = new Set(['registered', 'for_sale', 'expiring', 'avai
 const ACTIVITY_STATES = new Set(['active', 'parked', 'unreachable', 'no_site']);
 const BOOLEAN_FIELDS = [
     'faviconMatch', 'faviconNearMatch', 'reusesOfficialAssets', 'hasPasswordField',
-    'hasMx', 'hasSpf', 'hasDmarc', 'privacyProtected',
+    'hasMx', 'hasSpf', 'hasDmarc', 'privacyProtected', 'hasExternalFormAction',
+    'idnReferenceMatch', 'pageBaselineMatch', 'hasActiveBrandProfile',
 ];
+const REVIEW_REASON_CODES = ANALYST_REVIEW_REASON_VALUES;
 const MUTATION_TYPES = new Set(RISK_MUTATION_TYPES);
 function object(value, field) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -109,6 +113,17 @@ function projectEvidence(value, field) {
             throw new CliUsageError(`${field}.activityStatus is unsupported.`);
         result.activityStatus = activity;
     }
+    if (source.scanDepth !== null && source.scanDepth !== undefined) {
+        const depth = boundedString(source.scanDepth, `${field}.scanDepth`, 16);
+        if (depth !== 'fast' && depth !== 'deep')
+            throw new CliUsageError(`${field}.scanDepth must be fast or deep.`);
+        Object.assign(result, { scanDepth: depth });
+    }
+    if (source.observedAt !== null && source.observedAt !== undefined) {
+        const observedAt = optionalTimestamp(source.observedAt, `${field}.observedAt`);
+        if (observedAt)
+            Object.assign(result, { observedAt });
+    }
     if (source.phishingLanguageMatch !== null && source.phishingLanguageMatch !== undefined) {
         result.phishingLanguageMatch = boundedString(source.phishingLanguageMatch, `${field}.phishingLanguageMatch`);
     }
@@ -164,8 +179,13 @@ export function parseRiskCalibrationDataset(text) {
         throw new CliUsageError('Risk calibration input must be valid JSON.');
     }
     const document = object(parsed, 'Risk calibration input');
-    if (document.schema !== RISK_CALIBRATION_DATASET_SCHEMA || document.version !== RISK_CALIBRATION_DATASET_VERSION) {
-        throw new CliUsageError(`Risk calibration input must use ${RISK_CALIBRATION_DATASET_SCHEMA} version ${RISK_CALIBRATION_DATASET_VERSION}.`);
+    const documentVersion = typeof document.version === 'number' && Number.isInteger(document.version)
+        ? document.version
+        : null;
+    if (document.schema !== RISK_CALIBRATION_DATASET_SCHEMA
+        || documentVersion === null
+        || !SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS.includes(documentVersion)) {
+        throw new CliUsageError(`Risk calibration input must use ${RISK_CALIBRATION_DATASET_SCHEMA} version ${SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS.join(' or ')}.`);
     }
     if (!Array.isArray(document.records) || !document.records.length) {
         throw new CliUsageError('Risk calibration input must contain a non-empty records array.');
@@ -187,22 +207,39 @@ export function parseRiskCalibrationDataset(text) {
         const analystDisposition = boundedString(record.analystDisposition, `${prefix}.analystDisposition`, 32);
         if (!DISPOSITIONS.has(analystDisposition))
             throw new CliUsageError(`${prefix}.analystDisposition is unsupported.`);
+        let reviewReasonCode;
+        if (record.reviewReasonCode !== null && record.reviewReasonCode !== undefined) {
+            reviewReasonCode = boundedString(record.reviewReasonCode, `${prefix}.reviewReasonCode`, 64);
+            if (!REVIEW_REASON_CODES.has(reviewReasonCode))
+                throw new CliUsageError(`${prefix}.reviewReasonCode is unsupported.`);
+        }
         return {
             id,
             domain,
             analystDisposition: analystDisposition,
+            ...(reviewReasonCode ? { reviewReasonCode } : {}),
             evidence: projectEvidence(record.evidence, `${prefix}.evidence`),
         };
     });
     return {
         schema: RISK_CALIBRATION_DATASET_SCHEMA,
-        version: RISK_CALIBRATION_DATASET_VERSION,
+        version: documentVersion,
         records,
     };
 }
 function ratio(numerator, denominator) {
     return denominator ? Number((numerator / denominator).toFixed(4)) : null;
 }
+function wilson95(successes, total) {
+    if (!total)
+        return null;
+    const z = 1.96;
+    const proportion = successes / total;
+    const denominator = 1 + (z * z) / total;
+    const center = (proportion + (z * z) / (2 * total)) / denominator;
+    const margin = (z * Math.sqrt((proportion * (1 - proportion) + (z * z) / (4 * total)) / total)) / denominator;
+    return { lower: Number(Math.max(0, center - margin).toFixed(4)), upper: Number(Math.min(1, center + margin).toFixed(4)) };
+}
 function metricsForThreshold(records, threshold) {
     let truePositive = 0;
     let falsePositive = 0;
@@ -217,16 +254,30 @@ function metricsForThreshold(records, threshold) {
         else
             flagged ? falsePositive += 1 : trueNegative += 1;
     }
+    const precision = ratio(truePositive, truePositive + falsePositive);
+    const recall = ratio(truePositive, truePositive + falseNegative);
+    const specificity = ratio(trueNegative, trueNegative + falsePositive);
     return {
         threshold,
         truePositive,
         falsePositive,
         trueNegative,
         falseNegative,
-        precision: ratio(truePositive, truePositive + falsePositive),
-        recall: ratio(truePositive, truePositive + falseNegative),
-        specificity: ratio(trueNegative, trueNegative + falsePositive),
+        precision,
+        recall,
+        specificity,
         falsePositiveRate: ratio(falsePositive, falsePositive + trueNegative),
+        f1: precision === null || recall === null || precision + recall === 0
+            ? null
+            : Number(((2 * precision * recall) / (precision + recall)).toFixed(4)),
+        balancedAccuracy: recall === null || specificity === null
+            ? null
+            : Number(((recall + specificity) / 2).toFixed(4)),
+        confidence95: {
+            precision: wilson95(truePositive, truePositive + falsePositive),
+            recall: wilson95(truePositive, truePositive + falseNegative),
+            specificity: wilson95(trueNegative, trueNegative + falsePositive),
+        },
     };
 }
 function metricClass(disposition) {
@@ -254,6 +305,8 @@ export function buildRiskCalibrationReport(dataset, explainRiskScore, options) {
             id: record.id,
             domain: record.domain,
             analystDisposition: record.analystDisposition,
+            reviewReasonCode: record.reviewReasonCode ?? null,
+            interoperabilityTags: analystInteroperabilityTags(record.analystDisposition, record.reviewReasonCode),
             metricClass: classification,
             includedInMetrics,
             exclusionReason: includedInMetrics
@@ -273,6 +326,52 @@ export function buildRiskCalibrationReport(dataset, explainRiskScore, options) {
     const positive = records.filter((record) => record.metricClass === 'positive' && record.score !== null).length;
     const negative = records.filter((record) => record.metricClass === 'negative' && record.score !== null).length;
     const excluded = records.length - positive - negative;
+    const strata = [];
+    const appendStrata = (dimension, values) => {
+        for (const [value, members] of [...values].sort(([left], [right]) => left.localeCompare(right))) {
+            const sampleCount = members.filter((member) => member.includedInMetrics).length;
+            strata.push({
+                dimension,
+                value,
+                sampleCount,
+                insufficientSample: sampleCount < 20,
+                metrics: metricsForThreshold(members, options.reviewThreshold),
+            });
+        }
+    };
+    const byDepth = new Map();
+    const byReason = new Map();
+    for (let index = 0; index < dataset.records.length; index += 1) {
+        const source = dataset.records[index];
+        const scored = records[index];
+        if (!source || !scored)
+            continue;
+        const depth = source.evidence.scanDepth === 'deep' || source.evidence.scanDepth === 'fast' ? source.evidence.scanDepth : 'unknown';
+        byDepth.set(depth, [...(byDepth.get(depth) ?? []), scored]);
+        const reason = source.reviewReasonCode ?? 'not_recorded';
+        byReason.set(reason, [...(byReason.get(reason) ?? []), scored]);
+    }
+    appendStrata('scan_depth', byDepth);
+    appendStrata('review_reason', byReason);
+    let scoresChanged = 0;
+    let bandsChanged = 0;
+    let thresholdClassificationsChanged = 0;
+    if (options.explainPreviousRiskScore) {
+        for (let index = 0; index < dataset.records.length; index += 1) {
+            const source = dataset.records[index];
+            const current = records[index];
+            if (!source || !current)
+                continue;
+            const previous = options.explainPreviousRiskScore(source.evidence);
+            if (previous?.score !== current.score)
+                scoresChanged += 1;
+            if (scoreBand(previous?.score ?? null) !== current.band)
+                bandsChanged += 1;
+            if (((previous?.score ?? -1) >= options.reviewThreshold) !== ((current.score ?? -1) >= options.reviewThreshold)) {
+                thresholdClassificationsChanged += 1;
+            }
+        }
+    }
     return {
         schema: RISK_CALIBRATION_REPORT_SCHEMA,
         version: RISK_CALIBRATION_REPORT_VERSION,
@@ -282,6 +381,15 @@ export function buildRiskCalibrationReport(dataset, explainRiskScore, options) {
         currentReviewThreshold: options.reviewThreshold,
         summary: { total: records.length, positive, negative, excluded, scoreBands: bands },
         thresholds: RISK_CALIBRATION_THRESHOLDS.map((threshold) => metricsForThreshold(records, threshold)),
+        strata,
+        modelComparison: {
+            available: Boolean(options.explainPreviousRiskScore),
+            previousModelVersion: options.explainPreviousRiskScore ? options.previousModelVersion ?? null : null,
+            currentModelVersion: options.modelVersion,
+            scoresChanged,
+            bandsChanged,
+            thresholdClassificationsChanged,
+        },
         records,
         interpretation: {
             authority: 'analyst_context_only',