@slicedearth/whoisleuth-cli 1.36.1 → 1.39.1

package/frontend/src/lib/analysis/evidence-coverage-ledger.js

@@ -0,0 +1,328 @@
+const MAX_ENTRIES = 24;
+const MAX_ID_LENGTH = 64;
+const MAX_LABEL_LENGTH = 120;
+const MAX_LIMITATIONS = 8;
+const MAX_LIMITATION_LENGTH = 280;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/gu;
+const COMPLETE_STATES = new Set([
+    'available',
+    'complete',
+    'completed',
+    'observed',
+    'success',
+    'supported',
+]);
+const PARTIAL_STATES = new Set(['incomplete', 'limited', 'partial', 'truncated']);
+const SKIPPED_STATES = new Set(['disabled', 'not_applicable', 'skipped']);
+const UNAVAILABLE_STATES = new Set([
+    'blocked',
+    'error',
+    'failed',
+    'rate_limited',
+    'timeout',
+    'unavailable',
+]);
+function boundedText(value, maximum) {
+    return String(value ?? '')
+        .replace(CONTROL_CHARACTERS, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, maximum);
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function stringList(value) {
+    return Array.isArray(value) ? value.map((item) => String(item)) : [];
+}
+function rdapLimitations(rdapParsed) {
+    if (rdapParsed.serverTruncated !== true)
+        return [];
+    const reasons = stringList(rdapParsed.serverTruncationReasons).slice(0, MAX_LIMITATIONS);
+    return [
+        `The registry reported that some RDAP data was omitted.${reasons.length ? ` ${reasons.join(' · ')}.` : ''}`,
+    ];
+}
+function dnsLimitations(dnsEvidence) {
+    const limitations = stringList(dnsEvidence.limitations);
+    const failures = Object.entries(record(dnsEvidence.diagnostics))
+        .slice(0, 16)
+        .filter(([, value]) => record(value).status === 'error')
+        .map(([name, value]) => `${name.toUpperCase()}: ${record(value).error || 'query failed'}`)
+        .join(' · ');
+    return failures ? [...limitations, failures] : limitations;
+}
+function normalizeStatus(value) {
+    return boundedText(value, 64)
+        .toLowerCase()
+        .replace(/[\s-]+/gu, '_');
+}
+function normalizeLimitations(value) {
+    if (!Array.isArray(value))
+        return [];
+    const output = [];
+    const seen = new Set();
+    for (const item of value) {
+        const text = boundedText(item, MAX_LIMITATION_LENGTH);
+        if (!text || seen.has(text))
+            continue;
+        output.push(text);
+        seen.add(text);
+        if (output.length >= MAX_LIMITATIONS)
+            break;
+    }
+    return output;
+}
+function coverageState(input) {
+    const status = normalizeStatus(input.status);
+    if (status === 'not_found')
+        return 'not_found';
+    if (SKIPPED_STATES.has(status))
+        return 'skipped';
+    if (status === 'unsupported')
+        return 'unsupported';
+    if (UNAVAILABLE_STATES.has(status))
+        return 'unavailable';
+    if (input.truncated === true || input.complete === false || PARTIAL_STATES.has(status))
+        return 'partial';
+    if (COMPLETE_STATES.has(status) || (status === '' && input.complete === true))
+        return 'complete';
+    return 'unknown';
+}
+function statusLabel(state) {
+    return {
+        complete: 'Complete',
+        not_found: 'Not found',
+        partial: 'Partial',
+        skipped: 'Skipped',
+        unavailable: 'Unavailable',
+        unknown: 'Unknown',
+        unsupported: 'Unsupported',
+    }[state];
+}
+export function buildEvidenceCoverageLedger(inputs) {
+    const entries = [];
+    const seen = new Set();
+    for (const input of inputs.slice(0, MAX_ENTRIES)) {
+        const id = boundedText(input.id, MAX_ID_LENGTH).toLowerCase().replace(/[^a-z0-9_-]+/gu, '-');
+        const label = boundedText(input.label, MAX_LABEL_LENGTH);
+        if (!id || !label || seen.has(id))
+            continue;
+        seen.add(id);
+        const state = coverageState(input);
+        entries.push({
+            id,
+            label,
+            category: input.category,
+            state,
+            statusLabel: statusLabel(state),
+            truncated: input.truncated === true,
+            limitations: normalizeLimitations(input.limitations),
+            manualReviewSuggested: state === 'partial' || state === 'unavailable' || state === 'unknown',
+        });
+    }
+    const counts = {
+        complete: 0,
+        not_found: 0,
+        partial: 0,
+        skipped: 0,
+        unavailable: 0,
+        unknown: 0,
+        unsupported: 0,
+    };
+    for (const entry of entries)
+        counts[entry.state] += 1;
+    return {
+        version: 1,
+        entries,
+        counts,
+        completeCount: counts.complete,
+        limitedCount: counts.partial + counts.unavailable + counts.unknown,
+    };
+}
+export function buildLookupEvidenceCoverageLedger(input) {
+    const targetType = boundedText(input.targetType, 20);
+    const availability = record(input.availability);
+    const diagnostics = record(input.diagnostics);
+    const rdapDiagnostic = record(diagnostics.rdap);
+    const whoisDiagnostic = record(diagnostics.whois);
+    const registrarRdap = record(input.registrarRdap);
+    const reverseDns = record(input.reverseDns);
+    const observedNetworkContext = record(input.observedNetworkContext);
+    const dnsEvidence = record(input.dnsEvidence);
+    const httpEvidence = record(input.httpEvidence);
+    const httpResponse = record(input.httpResponse);
+    const tlsEvidence = record(input.tlsEvidence);
+    const pageIdentity = record(input.pageIdentity);
+    const pageRoleProfile = record(input.pageRoleProfile);
+    const clientBehaviorProfile = record(input.clientBehaviorProfile);
+    const technologyProfile = record(input.technologyProfile);
+    const securityPosture = record(input.securityPosture);
+    const securityTxt = record(input.securityTxt);
+    const sslbl = record(input.sslbl);
+    const rdapParsed = record(input.rdapParsed);
+    const whoisParsed = record(input.whoisParsed);
+    const items = [
+        {
+            id: 'rdap',
+            label: targetType === 'domain' ? 'Registry RDAP' : 'RDAP',
+            category: 'registry',
+            status: rdapDiagnostic.status,
+            truncated: rdapParsed.serverTruncated,
+            limitations: rdapLimitations(rdapParsed),
+        },
+        {
+            id: 'whois',
+            label: 'WHOIS',
+            category: 'registry',
+            status: whoisDiagnostic.status,
+            truncated: Array.isArray(whoisParsed.fieldsTruncated) && whoisParsed.fieldsTruncated.length > 0,
+            limitations: stringList(whoisParsed.limitations),
+        },
+        {
+            id: 'availability',
+            label: 'Availability decision',
+            category: 'analysis',
+            status: record(diagnostics.availability).status,
+            complete: availability.complete,
+            limitations: stringList(availability.limitations),
+        },
+    ];
+    if (registrarRdap.status) {
+        items.push({
+            id: 'registrar-rdap',
+            label: 'Registrar RDAP',
+            category: 'registry',
+            status: registrarRdap.status,
+            limitations: stringList(registrarRdap.limitations),
+        });
+    }
+    if (reverseDns.source === 'reverse_dns' || record(diagnostics.reverseDns).status) {
+        items.push({
+            id: 'reverse-dns',
+            label: 'Reverse DNS',
+            category: 'network',
+            status: reverseDns.status || record(diagnostics.reverseDns).status,
+            complete: reverseDns.complete,
+            truncated: reverseDns.truncated,
+            limitations: stringList(reverseDns.limitations),
+        });
+    }
+    if (observedNetworkContext.contextVersion === 1) {
+        items.push({
+            id: 'network-context',
+            label: 'Observed network context',
+            category: 'network',
+            status: observedNetworkContext.status,
+            complete: observedNetworkContext.complete,
+            limitations: stringList(observedNetworkContext.limitations),
+        });
+    }
+    if (targetType === 'domain') {
+        items.push({
+            id: 'dns',
+            label: 'DNS',
+            category: 'network',
+            status: dnsEvidence.status,
+            complete: dnsEvidence.complete,
+            truncated: dnsEvidence.truncated,
+            limitations: dnsLimitations(dnsEvidence),
+        }, {
+            id: 'http',
+            label: 'HTTP',
+            category: 'web',
+            status: httpEvidence.status,
+            complete: httpEvidence.complete,
+            truncated: httpResponse.bodyTruncated,
+            limitations: stringList(httpEvidence.limitations),
+        }, {
+            id: 'tls',
+            label: 'TLS',
+            category: 'web',
+            status: tlsEvidence.status,
+            complete: tlsEvidence.complete,
+            truncated: tlsEvidence.chainTruncated,
+            limitations: stringList(tlsEvidence.limitations),
+        }, {
+            id: 'page-identity',
+            label: 'Page identity',
+            category: 'web',
+            status: pageIdentity.status,
+            complete: pageIdentity.complete,
+            truncated: pageIdentity.truncated,
+            limitations: stringList(pageIdentity.limitations),
+        }, {
+            id: 'technology',
+            label: 'Technology indicators',
+            category: 'analysis',
+            status: technologyProfile.status,
+            complete: technologyProfile.complete,
+            truncated: technologyProfile.truncated,
+            limitations: stringList(technologyProfile.limitations),
+        }, {
+            id: 'page-role',
+            label: 'Page role classification',
+            category: 'analysis',
+            status: pageRoleProfile.status,
+            complete: pageRoleProfile.complete,
+            truncated: pageRoleProfile.truncated,
+            limitations: stringList(pageRoleProfile.limitations),
+        }, {
+            id: 'client-behavior',
+            label: 'Client-side behaviour indicators',
+            category: 'analysis',
+            status: clientBehaviorProfile.status,
+            complete: clientBehaviorProfile.complete,
+            truncated: clientBehaviorProfile.truncated,
+            limitations: stringList(clientBehaviorProfile.limitations),
+        }, {
+            id: 'security-posture',
+            label: 'Security posture',
+            category: 'analysis',
+            status: securityPosture.status,
+            complete: securityPosture.complete,
+            truncated: securityPosture.truncated,
+            limitations: stringList(securityPosture.limitations),
+        });
+    }
+    if (securityTxt.securityTxtVersion === 1) {
+        items.push({
+            id: 'security-txt',
+            label: 'security.txt',
+            category: 'web',
+            status: securityTxt.state,
+            limitations: stringList(securityTxt.limitations),
+        });
+    }
+    if (sslbl.sslblVersion === 1) {
+        items.push({
+            id: 'sslbl-certificate',
+            label: 'SSLBL certificate comparison',
+            category: 'external',
+            status: sslbl.status,
+            complete: sslbl.complete,
+            limitations: stringList(sslbl.limitations),
+        });
+    }
+    const providers = Array.isArray(input.threatIntelligenceProviders)
+        ? input.threatIntelligenceProviders
+        : [];
+    for (const [providerIndex, providerValue] of providers.entries()) {
+        if (items.length >= MAX_ENTRIES)
+            break;
+        const provider = record(providerValue);
+        const identity = record(provider.provider);
+        const fallback = `external-${providerIndex + 1}`;
+        const id = boundedText(identity.id || fallback, MAX_ID_LENGTH);
+        items.push({
+            id: `external-${id}`,
+            label: boundedText(identity.label || `External source ${providerIndex + 1}`, MAX_LABEL_LENGTH),
+            category: 'external',
+            status: provider.state,
+            limitations: [boundedText(provider.detail, MAX_LIMITATION_LENGTH)].filter(Boolean),
+        });
+    }
+    return buildEvidenceCoverageLedger(items);
+}

package/frontend/src/lib/analysis/investigation-capsule.js

@@ -0,0 +1,105 @@
+import { canonicalArtifactJson, sha256ArtifactDigest } from "./artifact-integrity.js";
+export const INVESTIGATION_CAPSULE_SCHEMA = 'whoisleuth.investigation-capsule';
+export const INVESTIGATION_CAPSULE_VERSION = 1;
+function safeVersion(value) {
+    return typeof value === 'string' && /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(value)
+        ? value
+        : '0.0.0';
+}
+function safeSchema(value) {
+    return typeof value === 'string' && /^[a-z0-9.-]{1,120}$/u.test(value) ? value : 'unknown';
+}
+function safeSchemaVersion(value) {
+    return Number.isSafeInteger(value) && Number(value) > 0 && Number(value) <= 10_000 ? Number(value) : 0;
+}
+function iso(value) {
+    if (typeof value !== 'string' || !Number.isFinite(Date.parse(value)))
+        return new Date().toISOString();
+    return new Date(value).toISOString();
+}
+function analystProjection(record) {
+    if (!record)
+        return null;
+    return {
+        caseId: record.id,
+        status: record.status,
+        disposition: record.disposition,
+        decisions: record.decisions.map(({ id, summary, rationale, evidencePinIds, createdAt }) => ({
+            id,
+            summary,
+            rationale,
+            evidencePinIds: [...evidencePinIds],
+            createdAt,
+        })),
+        assertions: record.assertions.map(({ id, kind, statement, rationale, evidencePinIds, state, createdAt, updatedAt }) => ({
+            id,
+            kind,
+            statement,
+            rationale,
+            evidencePinIds: [...evidencePinIds],
+            state,
+            createdAt,
+            updatedAt,
+        })),
+    };
+}
+export async function buildInvestigationCapsule(input) {
+    const analystRecords = input.includeAnalystRecords ? analystProjection(input.caseRecord) : null;
+    const [evidenceDigest, briefDigest, graphDigest, analystRecordsDigest] = await Promise.all([
+        sha256ArtifactDigest(input.lookupEvidence),
+        sha256ArtifactDigest(input.brief),
+        sha256ArtifactDigest(input.graph),
+        analystRecords ? sha256ArtifactDigest(analystRecords) : Promise.resolve(null),
+    ]);
+    const evidenceSchema = safeSchema(input.lookupEvidence.schema);
+    const evidenceVersion = safeSchemaVersion(input.lookupEvidence.schemaVersion);
+    return {
+        schema: INVESTIGATION_CAPSULE_SCHEMA,
+        schemaVersion: INVESTIGATION_CAPSULE_VERSION,
+        generatedAt: iso(input.generatedAt),
+        application: { name: 'WHOISleuth', version: safeVersion(input.applicationVersion) },
+        target: { value: input.brief.target, type: input.brief.targetType },
+        sourceContracts: [
+            { id: 'lookup-evidence', schema: evidenceSchema, version: evidenceVersion, digest: evidenceDigest, embedded: false },
+            { id: 'investigation-brief', schema: input.brief.schema, version: input.brief.schemaVersion, digest: briefDigest, embedded: true },
+            { id: 'asset-graph', schema: 'whoisleuth.lookup-asset-graph', version: input.graph.version, digest: graphDigest, embedded: true },
+            ...(analystRecords && analystRecordsDigest
+                ? [{ id: 'analyst-records', schema: 'whoisleuth.case-analyst-records', version: 1, digest: analystRecordsDigest, embedded: true }]
+                : []),
+        ],
+        investigationBrief: input.brief,
+        graphSnapshot: input.graph,
+        analystRecords,
+        integrity: { algorithm: 'SHA-256', briefDigest, graphDigest, analystRecordsDigest },
+        limitations: [
+            'The Lookup evidence file is linked by digest but is not embedded; keep or share that exact file separately when verification is required.',
+            'Digest verification can detect changed content but does not establish who created the capsule. No digital signature is applied.',
+            'The graph and brief are bounded projections of collected and derived evidence, not attribution, ownership, safety, availability, or maliciousness conclusions.',
+            analystRecords
+                ? 'Analyst decisions and assertions were deliberately included; review them for sensitive or personal information before sharing.'
+                : 'Analyst decisions, assertions, notes, contacts, actions, and raw source payloads are excluded.',
+        ],
+    };
+}
+export async function verifyInvestigationCapsule(capsule) {
+    const [briefDigest, graphDigest, analystRecordsDigest] = await Promise.all([
+        sha256ArtifactDigest(capsule.investigationBrief),
+        sha256ArtifactDigest(capsule.graphSnapshot),
+        capsule.analystRecords ? sha256ArtifactDigest(capsule.analystRecords) : Promise.resolve(null),
+    ]);
+    const brief = briefDigest === capsule.integrity.briefDigest;
+    const graph = graphDigest === capsule.integrity.graphDigest;
+    const analystRecords = capsule.analystRecords
+        ? analystRecordsDigest === capsule.integrity.analystRecordsDigest
+        : capsule.integrity.analystRecordsDigest === null
+            ? null
+            : false;
+    return { valid: brief && graph && analystRecords !== false, brief, graph, analystRecords };
+}
+export function investigationCapsuleFilename(capsule) {
+    const target = capsule.target.value.toLowerCase().replace(/[^a-z0-9.-]+/gu, '-').replace(/^-|-$/gu, '').slice(0, 80) || 'lookup';
+    return `whoisleuth-investigation-capsule-${target}-${capsule.generatedAt.slice(0, 10)}.json`;
+}
+export function serializeInvestigationCapsule(capsule) {
+    return `${canonicalArtifactJson(capsule)}\n`;
+}