@slicedearth/whoisleuth-cli 2.4.0 → 2.5.1

package/packages/interchange/managed-indicator-set.mjs

@@ -0,0 +1,210 @@
+import { array, digest, domain, enumeration, exact, exactOptional, integer, iso, text, validateIntegrity } from "../evidence/artifact-structure.mjs";
+import { canonicalArtifactJsonV2, sha256ArtifactDigestV2, SORTED_JSON_V2 } from "../evidence/artifact-integrity.mjs";
+import { assertWorkspaceInputGraph } from "../workspace/hostile-input.mjs";
+import { parseBoundedJson, boundedJsonLimitsForBytes } from "../analysis/bounded-json.mjs";
+import { MANAGED_INDICATOR_SET_SCHEMA, MANAGED_INDICATOR_SET_VERSION, MAX_MANAGED_INDICATOR_SET_BYTES, MAX_MANAGED_INDICATOR_PLAN_BYTES } from "../contracts/analyst-interchange.mjs";
+import { defensiveIndicatorProvenance, prepareDefensiveIndicatorExport, MAX_DEFENSIVE_INDICATOR_INPUTS } from "./defensive-indicator-export.mjs";
+import { MAX_STIX_INDICATORS } from "./stix-indicator-export.mjs";
+export const MAX_MANAGED_INDICATORS = MAX_STIX_INDICATORS;
+export const MAX_INDICATOR_REVIEW_BASIS = 1_000;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const AVAILABILITY = ['registered', 'for_sale', 'expiring'];
+function uuid(value) {
+    if (typeof value !== 'string' || !UUID.test(value))
+        throw new TypeError('Indicator identities must be lowercase version-4 UUIDs.');
+    return value;
+}
+function timestamp(value, label) { iso(value, label); return value; }
+function basis(value) {
+    const result = text(value, 'Indicator review basis', MAX_INDICATOR_REVIEW_BASIS).trim();
+    if (!result)
+        throw new TypeError('Explain the indicator revision.');
+    return result;
+}
+function bounded(value, maximumBytes) {
+    assertWorkspaceInputGraph(value, 'Indicator input', { maximumBytes });
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > maximumBytes)
+        throw new TypeError('Indicator input exceeds its byte limit.');
+}
+/** Structural validation is independent of digest verification and author trust. */
+export function validateManagedIndicatorSet(value) {
+    bounded(value, MAX_MANAGED_INDICATOR_SET_BYTES);
+    const root = exact(value, ['schema', 'version', 'id', 'producerId', 'revisionId', 'name', 'revision', 'createdAt', 'modifiedAt', 'previous', 'entries', 'integrity'], 'Managed indicator set');
+    if (root.schema !== MANAGED_INDICATOR_SET_SCHEMA || root.version !== MANAGED_INDICATOR_SET_VERSION)
+        throw new TypeError('Unsupported managed indicator set schema or version.');
+    const identities = [uuid(root.id), uuid(root.producerId), uuid(root.revisionId)];
+    if (!text(root.name, 'Indicator set name', 120).trim())
+        throw new TypeError('Name the indicator set.');
+    const revision = integer(root.revision, 'Indicator revision', 1);
+    const created = Date.parse(timestamp(root.createdAt, 'Set creation time')), modified = Date.parse(timestamp(root.modifiedAt, 'Set modification time'));
+    if (modified < created || (revision === 1 && modified !== created))
+        throw new TypeError('Indicator revision times are inconsistent.');
+    if (revision === 1) {
+        if (root.previous !== null)
+            throw new TypeError('An initial indicator revision has no predecessor.');
+    }
+    else {
+        const previous = exact(root.previous, ['revisionId', 'digestSha256'], 'Preceding indicator revision');
+        identities.push(uuid(previous.revisionId));
+        digest(previous.digestSha256, 'Preceding revision digest');
+    }
+    const activeDomains = new Set();
+    for (const item of array(root.entries, 'Managed indicators', MAX_MANAGED_INDICATORS, 1)) {
+        const entry = exact(item, ['id', 'domain', 'createdAt', 'modifiedAt', 'expiresAt', 'basis', 'reviewBasis', 'observation', 'withdrawal'], 'Managed indicator');
+        identities.push(uuid(entry.id));
+        domain(entry.domain, 'Managed indicator domain');
+        const first = Date.parse(timestamp(entry.createdAt, 'Indicator creation time'));
+        const last = Date.parse(timestamp(entry.modifiedAt, 'Indicator modification time'));
+        const expires = Date.parse(timestamp(entry.expiresAt, 'Indicator review expiry'));
+        if (first < created || last < first || last > modified || expires <= first || (entry.withdrawal === null && expires <= last))
+            throw new TypeError('Indicator entry times are inconsistent.');
+        basis(entry.basis);
+        basis(entry.reviewBasis);
+        const observation = exact(entry.observation, ['availability', 'riskScore', 'riskModelVersion', 'scanDepth', 'observedAt'], 'Indicator observation');
+        enumeration(observation.availability, AVAILABILITY, 'Indicator registration observation');
+        if (observation.riskScore !== null)
+            integer(observation.riskScore, 'Retained risk score', 0, 100);
+        if (observation.riskModelVersion !== null)
+            integer(observation.riskModelVersion, 'Retained risk model', 1, 1_000);
+        enumeration(observation.scanDepth, ['fast', 'deep', 'unknown'], 'Retained scan depth');
+        iso(observation.observedAt, 'Retained observation time', true);
+        if (entry.withdrawal === null) {
+            if (activeDomains.has(entry.domain))
+                throw new TypeError('Only one active identity per domain is allowed in a managed set.');
+            activeDomains.add(entry.domain);
+        }
+        else {
+            const withdrawal = exact(entry.withdrawal, ['at', 'reason'], 'Indicator withdrawal');
+            if (timestamp(withdrawal.at, 'Withdrawal time') !== entry.modifiedAt)
+                throw new TypeError('Withdrawal must be the final indicator modification.');
+            basis(withdrawal.reason);
+        }
+    }
+    if (new Set(identities).size !== identities.length)
+        throw new TypeError('Managed indicator identities must be distinct.');
+    validateIntegrity(root.integrity, 'Managed indicator integrity', root.version, MANAGED_INDICATOR_SET_VERSION);
+    return value;
+}
+export async function readManagedIndicatorSet(value) {
+    const checked = structuredClone(validateManagedIndicatorSet(value));
+    const { integrity, ...unsigned } = checked;
+    if (await sha256ArtifactDigestV2(unsigned) !== integrity.digestSha256)
+        throw new TypeError('Managed indicator content does not match its recorded digest.');
+    return checked;
+}
+export function parseManagedIndicatorJson(raw, plan = false) {
+    const maximumBytes = plan ? MAX_MANAGED_INDICATOR_PLAN_BYTES : MAX_MANAGED_INDICATOR_SET_BYTES;
+    return parseBoundedJson(raw, { maximumBytes, label: 'Managed indicator input', limits: boundedJsonLimitsForBytes(maximumBytes) });
+}
+export function managedIndicatorState(entry, at) {
+    iso(at, 'Review time');
+    return entry.withdrawal ? 'withdrawn' : Date.parse(entry.expiresAt) <= Date.parse(at) ? 'expired' : 'active';
+}
+/** A known predecessor detects removal, rollback and edits to original observations. */
+export function compareManagedIndicatorRevisions(previous, next) {
+    validateManagedIndicatorSet(previous);
+    validateManagedIndicatorSet(next);
+    if (previous.id !== next.id || previous.producerId !== next.producerId || previous.name !== next.name || previous.createdAt !== next.createdAt
+        || next.revision !== previous.revision + 1 || next.previous?.revisionId !== previous.revisionId || next.previous.digestSha256 !== previous.integrity.digestSha256
+        || Math.floor(Date.parse(next.modifiedAt) / 1000) <= Math.floor(Date.parse(previous.modifiedAt) / 1000)) {
+        throw new TypeError('This is not the next revision of the selected indicator set. Keep both files and review the predecessor.');
+    }
+    const old = new Map(previous.entries.map(entry => [entry.id, entry]));
+    const changes = [];
+    for (const entry of next.entries) {
+        const retained = old.get(entry.id);
+        if (!retained) {
+            if (entry.createdAt !== next.modifiedAt || entry.modifiedAt !== next.modifiedAt || entry.withdrawal)
+                throw new TypeError('A new indicator must start in the new revision.');
+            changes.push({ id: entry.id, domain: entry.domain, kind: 'added' });
+            continue;
+        }
+        old.delete(entry.id);
+        if (canonicalArtifactJsonV2(retained) === canonicalArtifactJsonV2(entry))
+            continue;
+        if (retained.withdrawal || entry.modifiedAt !== next.modifiedAt || retained.domain !== entry.domain || retained.createdAt !== entry.createdAt
+            || retained.basis !== entry.basis || canonicalArtifactJsonV2(retained.observation) !== canonicalArtifactJsonV2(entry.observation)
+            || (entry.withdrawal && retained.expiresAt !== entry.expiresAt))
+            throw new TypeError('A revision cannot rewrite observations or modify a withdrawn identity.');
+        changes.push({ id: entry.id, domain: entry.domain, kind: entry.withdrawal ? 'withdrawn' : 'renewed' });
+    }
+    if (old.size)
+        throw new TypeError('A revision cannot remove retained indicator history.');
+    if (!changes.length)
+        throw new TypeError('No indicator change was selected.');
+    return changes;
+}
+export async function buildManagedIndicatorRevision(input, now = new Date().toISOString()) {
+    bounded(input, MAX_MANAGED_INDICATOR_PLAN_BYTES);
+    const plan = exactOptional(structuredClone(input), ['basis'], ['name', 'previous', 'rows', 'selectedDomains', 'officialDomains', 'allowlistedDomains', 'commonInfrastructureDomains', 'renewIds', 'withdrawIds', 'reintroduceDomains', 'expiresAt'], 'Indicator revision plan');
+    const previous = plan.previous === undefined ? null : await readManagedIndicatorSet(plan.previous);
+    const generatedAt = timestamp(now, 'Revision time');
+    const reviewBasis = basis(plan.basis);
+    const name = plan.name === undefined && previous ? previous.name : text(plan.name, 'Indicator set name', 120).trim();
+    if (!name || (previous && name !== previous.name))
+        throw new TypeError('A revision retains the original set name.');
+    function values(key, maximum, read) {
+        const result = array(plan[key] ?? [], key, maximum).map(read);
+        if (new Set(result).size !== result.length)
+            throw new TypeError('Revision selections must not contain duplicates.');
+        return result;
+    }
+    const domains = (key) => values(key, MAX_DEFENSIVE_INDICATOR_INPUTS, item => { domain(item, 'Selected domain'); return item; });
+    const selectedDomains = domains('selectedDomains');
+    const preflight = prepareDefensiveIndicatorExport(array(plan.rows ?? [], 'Reviewed rows', MAX_DEFENSIVE_INDICATOR_INPUTS), {
+        selectedDomains, officialDomains: domains('officialDomains'), allowlistedDomains: domains('allowlistedDomains'), commonInfrastructureDomains: domains('commonInfrastructureDomains'),
+    }, MAX_MANAGED_INDICATORS);
+    if (preflight.truncated)
+        throw new TypeError('The selected revision exceeds the managed-set entry limit; no partial revision was created.');
+    const renew = new Set(values('renewIds', MAX_MANAGED_INDICATORS, uuid));
+    const withdraw = new Set(values('withdrawIds', MAX_MANAGED_INDICATORS, uuid));
+    const reintroduce = new Set(domains('reintroduceDomains'));
+    if ([...renew].some(id => withdraw.has(id)))
+        throw new TypeError('An indicator cannot be renewed and withdrawn in one revision.');
+    const entries = structuredClone(previous?.entries ?? []);
+    const known = new Map(entries.map(entry => [entry.id, entry]));
+    for (const id of [...renew, ...withdraw])
+        if (!known.has(id) || known.get(id).withdrawal)
+            throw new TypeError('Select an existing, non-withdrawn indicator identity.');
+    const active = new Set(entries.filter(entry => !entry.withdrawal).map(entry => entry.domain));
+    const withdrawn = new Set(entries.filter(entry => entry.withdrawal).map(entry => entry.domain));
+    const additions = preflight.entries.filter(entry => !active.has(entry.domain));
+    if ([...reintroduce].some(value => !withdrawn.has(value) || !additions.some(entry => entry.domain === value)))
+        throw new TypeError('Reintroduction must select a withdrawn domain being added with a new identity.');
+    for (const entry of additions)
+        if (withdrawn.has(entry.domain) && !reintroduce.has(entry.domain))
+            throw new TypeError('Explicitly approve a new identity before reintroducing a withdrawn domain.');
+    let expiresAt = null;
+    if (additions.length || renew.size) {
+        expiresAt = timestamp(plan.expiresAt, 'New review expiry');
+        if (Date.parse(expiresAt) <= Date.parse(generatedAt))
+            throw new TypeError('The new review expiry must be in the future.');
+    }
+    else if (plan.expiresAt !== undefined)
+        timestamp(plan.expiresAt, 'New review expiry');
+    for (const entry of entries) {
+        if (renew.has(entry.id)) {
+            entry.expiresAt = expiresAt;
+            entry.modifiedAt = generatedAt;
+            entry.reviewBasis = reviewBasis;
+        }
+        if (withdraw.has(entry.id)) {
+            entry.withdrawal = { at: generatedAt, reason: reviewBasis };
+            entry.modifiedAt = generatedAt;
+            entry.reviewBasis = reviewBasis;
+        }
+    }
+    const randomId = () => globalThis.crypto.randomUUID();
+    for (const entry of additions)
+        entries.push({ id: randomId(), domain: entry.domain, createdAt: generatedAt, modifiedAt: generatedAt, expiresAt: expiresAt, basis: reviewBasis, reviewBasis,
+            observation: { availability: entry.source.availability, ...defensiveIndicatorProvenance(entry.source) }, withdrawal: null });
+    if (!additions.length && !renew.size && !withdraw.size)
+        throw new TypeError('No eligible addition, renewal or withdrawal was selected.');
+    const unsigned = { schema: MANAGED_INDICATOR_SET_SCHEMA, version: MANAGED_INDICATOR_SET_VERSION,
+        id: previous?.id ?? randomId(), producerId: previous?.producerId ?? randomId(), revisionId: randomId(), name,
+        revision: (previous?.revision ?? 0) + 1, createdAt: previous?.createdAt ?? generatedAt, modifiedAt: generatedAt,
+        previous: previous ? { revisionId: previous.revisionId, digestSha256: previous.integrity.digestSha256 } : null, entries };
+    const manifest = validateManagedIndicatorSet({ ...unsigned, integrity: { algorithm: 'SHA-256', canonicalization: SORTED_JSON_V2, digestSha256: await sha256ArtifactDigestV2(unsigned) } });
+    const changes = previous ? compareManagedIndicatorRevisions(previous, manifest) : manifest.entries.map(entry => ({ id: entry.id, domain: entry.domain, kind: 'added' }));
+    return { manifest, changes, unchanged: manifest.entries.length - changes.length, exclusions: preflight.exclusions };
+}

package/packages/interchange/misp-indicator-export.mjs

@@ -0,0 +1,93 @@
+// Pure MISP event JSON for local analyst import. The event stays unpublished,
+// organization-only, non-IDS, and non-correlating until a MISP user reviews it.
+import { collectDefensiveIndicatorCandidates, defensiveIndicatorProvenance, MAX_DEFENSIVE_INDICATORS, } from "./defensive-indicator-export.mjs";
+import { MISP_INDICATOR_EXPORT_VERSION } from "../contracts/analyst-interchange.mjs";
+export { MISP_INDICATOR_EXPORT_VERSION } from "../contracts/analyst-interchange.mjs";
+export const MAX_MISP_ATTRIBUTES = MAX_DEFENSIVE_INDICATORS;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const CONTROL_RE = /[\x00-\x1f\x7f]/;
+const WARNING = 'Review before operational use; false positives are possible.';
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function isoTimestamp(value) {
+    if (typeof value !== 'string' || value.length > 64 || CONTROL_RE.test(value))
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+function defaultUuidFactory() {
+    const uuid = globalThis.crypto?.randomUUID?.();
+    if (!uuid)
+        throw new Error('Secure random identifiers are unavailable for the MISP export.');
+    return uuid;
+}
+function nextUuid(uuidFactory, used) {
+    const value = uuidFactory();
+    if (typeof value !== 'string' || !UUID_RE.test(value)) {
+        throw new Error('The MISP identifier factory returned an invalid UUID.');
+    }
+    const uuid = value.toLowerCase();
+    if (used.has(uuid))
+        throw new Error('The MISP identifier factory returned a duplicate UUID.');
+    used.add(uuid);
+    return uuid;
+}
+function attributeComment(availability, provenance) {
+    const { riskScore: score, riskModelVersion: modelVersion, scanDepth, observedAt } = provenance;
+    return [
+        'Heuristic Bulk finding',
+        `availability=${availability}`,
+        `risk=${score ?? 'unknown'}`,
+        ...(modelVersion === null ? [] : [`risk-model=v${modelVersion}`]),
+        `scan-depth=${scanDepth}`,
+        `observed-at=${observedAt ?? 'unknown'}`,
+        `timestamp-basis=${observedAt ? 'scan' : 'unknown'}`,
+        WARNING,
+    ].join('; ');
+}
+export function mispIndicatorAttribute(domain, availability, provenance, uuid, modifiedAt) {
+    return {
+        uuid, type: 'domain', category: 'Network activity', value: domain,
+        to_ids: false, distribution: '5', timestamp: String(Math.floor(Date.parse(modifiedAt) / 1000)),
+        ...(provenance.observedAt ? { first_seen: provenance.observedAt, last_seen: provenance.observedAt } : {}),
+        comment: attributeComment(availability, provenance), disable_correlation: true, deleted: false,
+    };
+}
+export function mispIndicatorEvent(uuid, generatedAt, attributes) {
+    return { uuid, date: generatedAt.slice(0, 10),
+        info: `WHOISleuth heuristic defensive-domain candidates for analyst review (export v${MISP_INDICATOR_EXPORT_VERSION})`,
+        threat_level_id: '4', analysis: '0', distribution: '0', published: false,
+        timestamp: String(Math.floor(Date.parse(generatedAt) / 1000)), publish_timestamp: '0', disable_correlation: true, Attribute: attributes };
+}
+export function buildMispIndicatorExport(records, options = {}) {
+    const generatedAt = isoTimestamp(options.generatedAt) || new Date().toISOString();
+    const uuidFactory = typeof options.uuidFactory === 'function'
+        ? options.uuidFactory
+        : defaultUuidFactory;
+    let collected;
+    try {
+        collected = collectDefensiveIndicatorCandidates(records, MAX_MISP_ATTRIBUTES);
+    }
+    catch (cause) {
+        if (cause instanceof TypeError)
+            throw new TypeError('MISP indicator export requires an array of Bulk results.');
+        throw cause;
+    }
+    const used = new Set();
+    const eventUuid = nextUuid(uuidFactory, used);
+    const attributes = collected.entries.map(({ domain, source }) => mispIndicatorAttribute(domain, record(source).availability, defensiveIndicatorProvenance(source), nextUuid(uuidFactory, used), generatedAt));
+    const payload = { Event: mispIndicatorEvent(eventUuid, generatedAt, attributes) };
+    return {
+        version: MISP_INDICATOR_EXPORT_VERSION,
+        format: 'misp',
+        generatedAt,
+        domains: collected.domains,
+        truncated: collected.truncated,
+        filename: `whoisleuth-defensive-domains-${generatedAt.slice(0, 10)}.misp.json`,
+        mimeType: 'application/json;charset=utf-8',
+        content: `${JSON.stringify(payload, null, 2)}\n`,
+    };
+}

package/packages/interchange/sharing-policy.mjs

@@ -0,0 +1,56 @@
+/** Sharing declarations are not encryption, redaction or an authority to disclose. */
+export const TLP_MARKINGS = ['clear', 'green', 'amber', 'amber-strict', 'red'];
+export const RECIPIENT_SCOPES = ['public', 'community', 'organization', 'named-recipients'];
+const RISKY_KEYS = new Set([
+    'authorization', 'cookie', 'cookies', 'credential', 'credentials', 'email', 'emails',
+    'entities', 'password', 'phone', 'raw', 'rawrdap', 'rawwhois', 'registrant', 'session', 'token',
+]);
+const MARKING_KEYS = new Set([
+    'informationmarking', 'marking', 'markings', 'sharingmarking',
+    'tlp', 'tlplabel', 'tlpmarking', 'trafficlightprotocol',
+]);
+export function markingFromText(value) {
+    const normalized = value.toUpperCase().replace(/\s+/gu, '').replace('TLP:', '').replace('+STRICT', '-STRICT').toLowerCase();
+    return TLP_MARKINGS.includes(normalized) ? normalized : null;
+}
+export function expectedScope(marking) {
+    if (marking === 'clear')
+        return 'public';
+    if (marking === 'green')
+        return 'community';
+    if (marking === 'red')
+        return 'named-recipients';
+    return 'organization';
+}
+export function tlpLabel(marking) {
+    return `TLP:${marking === 'amber-strict' ? 'AMBER+STRICT' : marking.toUpperCase()}`;
+}
+/** Scan an already admitted, byte/node/depth-bounded JSON tree, not arbitrary objects. */
+export function scanSharingMetadata(root) {
+    const stack = [{ value: root, marking: false }];
+    const markings = new Set();
+    let riskyKeyCount = 0;
+    while (stack.length) {
+        const next = stack.pop();
+        if (typeof next.value === 'string') {
+            if (next.marking) {
+                const marking = markingFromText(next.value);
+                if (marking)
+                    markings.add(marking);
+            }
+        }
+        else if (Array.isArray(next.value)) {
+            for (const value of next.value)
+                stack.push({ value, marking: next.marking });
+        }
+        else if (next.value && typeof next.value === 'object') {
+            for (const [key, value] of Object.entries(next.value)) {
+                const normalized = key.toLowerCase().replace(/[^a-z0-9]/gu, '');
+                if (RISKY_KEYS.has(normalized))
+                    riskyKeyCount++;
+                stack.push({ value, marking: MARKING_KEYS.has(normalized) });
+            }
+        }
+    }
+    return { importedMarkings: [...markings], riskyKeyCount };
+}

package/packages/interchange/stix-indicator-export.mjs

@@ -0,0 +1,129 @@
+// Pure STIX 2.1 interchange for locally reviewed Bulk candidates. Direct
+// observations and heuristic inferences remain separate objects so consumers
+// do not mistake a Risk score for confirmed maliciousness.
+import { collectDefensiveIndicatorCandidates, defensiveIndicatorProvenance, } from "./defensive-indicator-export.mjs";
+import { STIX_INDICATOR_EXPORT_VERSION } from "../contracts/analyst-interchange.mjs";
+export { STIX_INDICATOR_EXPORT_VERSION } from "../contracts/analyst-interchange.mjs";
+export const MAX_STIX_INDICATORS = 1000;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const CONTROL_RE = /[\x00-\x1f\x7f]/;
+const WARNING = 'Heuristic finding; review before operational use because false positives are possible.';
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function isoTimestamp(value) {
+    if (typeof value !== 'string' || value.length > 64 || CONTROL_RE.test(value))
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+function defaultIdFactory(type) {
+    const uuid = globalThis.crypto?.randomUUID?.();
+    if (!uuid)
+        throw new Error('Secure random identifiers are unavailable for the STIX export.');
+    return `${type}--${uuid}`;
+}
+function stixId(type, idFactory) {
+    const value = idFactory(type);
+    const prefix = `${type}--`;
+    if (typeof value !== 'string' || !value.startsWith(prefix) || !UUID_RE.test(value.slice(prefix.length))) {
+        throw new Error(`The STIX identifier factory returned an invalid ${type} identifier.`);
+    }
+    return value.toLowerCase();
+}
+export function stixIndicatorProducer(producerId, generatedAt) {
+    return {
+        type: 'identity', spec_version: '2.1', id: producerId,
+        created: generatedAt, modified: generatedAt,
+        name: 'WHOISleuth', identity_class: 'system',
+        description: 'Producer of locally generated defensive-domain observations and heuristic inferences.',
+        x_whoisleuth_export_version: STIX_INDICATOR_EXPORT_VERSION,
+        x_whoisleuth_generated_at: generatedAt,
+        x_whoisleuth_false_positive_warning: WARNING,
+    };
+}
+/** The caller owns validated candidates and either fresh or retained identities. */
+export function stixIndicatorObjects(domain, availability, provenance, generatedAt, producerId, nextId) {
+    const { observedAt, riskScore: score, riskModelVersion: modelVersion } = provenance;
+    const domainId = nextId('domain-name');
+    const observationId = nextId(observedAt ? 'observed-data' : 'note');
+    const indicatorId = nextId('indicator');
+    const observationContext = {
+        created_by_ref: producerId, created: generatedAt, modified: generatedAt,
+        x_whoisleuth_observed_at_basis: observedAt ? 'scan' : 'unknown',
+        x_whoisleuth_source: 'bulk', x_whoisleuth_availability: availability,
+        x_whoisleuth_scan_depth: provenance.scanDepth,
+    };
+    const objects = [
+        { type: 'domain-name', spec_version: '2.1', id: domainId, value: domain },
+        observedAt ? {
+            type: 'observed-data', spec_version: '2.1', id: observationId, ...observationContext,
+            first_observed: observedAt, last_observed: observedAt, number_observed: 1, object_refs: [domainId],
+            x_whoisleuth_evidence_kind: 'direct-observation',
+        } : {
+            type: 'note', spec_version: '2.1', id: observationId, ...observationContext,
+            content: 'Observation time was not retained. This candidate is supplied for heuristic review; its export time is not a sighting time.',
+            object_refs: [domainId, indicatorId], x_whoisleuth_evidence_kind: 'observation-context',
+        },
+        {
+            type: 'indicator', spec_version: '2.1', id: indicatorId,
+            created_by_ref: producerId, created: generatedAt, modified: generatedAt,
+            name: `Heuristic domain candidate: ${domain}`, description: WARNING,
+            pattern: `[domain-name:value = '${domain}']`, pattern_type: 'stix', pattern_version: '2.1',
+            valid_from: generatedAt, x_whoisleuth_validity_basis: 'export',
+            labels: ['heuristic', 'defensive-review'], x_whoisleuth_evidence_kind: 'heuristic-inference',
+            x_whoisleuth_risk_score: score,
+            ...(modelVersion === null ? {} : { x_whoisleuth_risk_model_version: modelVersion }),
+            x_whoisleuth_false_positive_warning: WARNING,
+        },
+    ];
+    if (observedAt)
+        objects.push({
+            type: 'relationship', spec_version: '2.1', id: nextId('relationship'),
+            created_by_ref: producerId, created: generatedAt, modified: generatedAt,
+            relationship_type: 'based-on', source_ref: indicatorId, target_ref: observationId,
+            description: 'The heuristic Indicator is based on the separately represented domain observation.',
+        });
+    return objects;
+}
+export function buildStixIndicatorExport(records, options = {}) {
+    const generatedAt = isoTimestamp(options.generatedAt) || new Date().toISOString();
+    const idFactory = typeof options.idFactory === 'function'
+        ? options.idFactory
+        : defaultIdFactory;
+    let collected;
+    try {
+        collected = collectDefensiveIndicatorCandidates(records, MAX_STIX_INDICATORS);
+    }
+    catch (cause) {
+        if (cause instanceof TypeError)
+            throw new TypeError('STIX indicator export requires an array of Bulk results.');
+        throw cause;
+    }
+    const usedIds = new Set();
+    const nextId = (type) => {
+        const id = stixId(type, idFactory);
+        if (usedIds.has(id))
+            throw new Error('The STIX identifier factory returned a duplicate identifier.');
+        usedIds.add(id);
+        return id;
+    };
+    const producerId = nextId('identity');
+    const objects = [stixIndicatorProducer(producerId, generatedAt)];
+    for (const { domain, source } of collected.entries) {
+        objects.push(...stixIndicatorObjects(domain, record(source).availability, defensiveIndicatorProvenance(source), generatedAt, producerId, nextId));
+    }
+    const bundle = { type: 'bundle', id: nextId('bundle'), objects };
+    return {
+        version: STIX_INDICATOR_EXPORT_VERSION,
+        format: 'stix',
+        generatedAt,
+        domains: collected.domains,
+        truncated: collected.truncated,
+        filename: `whoisleuth-defensive-domains-${generatedAt.slice(0, 10)}.stix.json`,
+        mimeType: 'application/stix+json;charset=utf-8',
+        content: `${JSON.stringify(bundle, null, 2)}\n`,
+    };
+}

package/packages/interchange/web-capture-import.mjs

@@ -1,7 +1,8 @@
-import { normalizeDomain } from "../cases/case-model.mjs";
-import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_SUMMARY_LENGTH, parseExternalFindingsDocument, } from "./external-findings-import.mjs";
-import { MAX_WEB_CAPTURE_DOM_DIGEST_BYTES, MAX_WEB_CAPTURE_SCREENSHOT_BYTES, WEB_CAPTURE_MANIFEST_SCHEMA, WEB_CAPTURE_MANIFEST_VERSION, WEB_CAPTURE_SUMMARY_SCHEMA, WEB_CAPTURE_SUMMARY_VERSION, } from "../contracts/web-capture.mjs";
+import { normalizeDomain } from "../evidence/domain-name.mjs";
+import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_SUMMARY_LENGTH, parseExternalFindingsDocument, retainExternalFindingLimitations, } from "./external-findings-import.mjs";
+import { MAX_WEB_CAPTURE_DOM_DIGEST_BYTES, MAX_WEB_CAPTURE_SCREENSHOT_BYTES, WEB_CAPTURE_MANIFEST_SCHEMA, WEB_CAPTURE_MANIFEST_VERSION, WEB_CAPTURE_MANIFEST_SUPPORTED_VERSIONS, WEB_CAPTURE_SUMMARY_SCHEMA, WEB_CAPTURE_SUMMARY_VERSION, } from "../contracts/web-capture.mjs";
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { readManifestPageBehaviour } from "../investigation/page-behaviour.mjs";
 import { readCaptureConditions, readObservationLabel } from "../comparison/capture-context.mjs";
 export { WEB_CAPTURE_MANIFEST_SCHEMA, WEB_CAPTURE_MANIFEST_VERSION, WEB_CAPTURE_SUMMARY_SCHEMA, WEB_CAPTURE_SUMMARY_VERSION, } from "../contracts/web-capture.mjs";
 export const MAX_WEB_CAPTURE_SUMMARIES = 50;
@@ -25,6 +26,7 @@ const CAPTURE_KEYS = new Set([
     'networkOrigins',
 ]);
 const MANIFEST_CAPTURE_KEYS = new Set([
+    'pageBehaviour',
     'conditions', 'observerLabel', 'vantageLabel',
     'domain',
     'capturedAt',
@@ -151,17 +153,17 @@ export function parseWebCaptureSummary(value) {
         ].filter(Boolean);
         if (!summaries.length)
             throw new Error(`Web capture ${index + 1} contains no supported summary evidence.`);
+        const retainedLimitations = retainExternalFindingLimitations(limitations, [
+            'Imported sanitised capture summary; WHOISleuth did not collect or independently verify this observation.',
+        ]);
         findings.push({
             domain,
             category: technologies.length && summaries.length === 1 ? 'http' : 'page',
             evidenceClass: 'deployment_observation',
             summary: summaries.join(' '),
             observedAt,
-            completeness,
-            limitations: [
-                'Imported sanitised capture summary; WHOISleuth did not collect or independently verify this observation.',
-                ...limitations,
-            ].slice(0, 8),
+            completeness: limitations.every((item) => retainedLimitations.includes(item)) ? completeness : 'partial',
+            limitations: retainedLimitations,
             reference: sourceReference,
         });
     }
@@ -230,7 +232,7 @@ export function readWebCaptureManifest(value) {
     if (!root
         || !onlyKeys(root, ROOT_KEYS)
         || root.schema !== WEB_CAPTURE_MANIFEST_SCHEMA
-        || root.schemaVersion !== WEB_CAPTURE_MANIFEST_VERSION) {
+        || !WEB_CAPTURE_MANIFEST_SUPPORTED_VERSIONS.includes(root.schemaVersion)) {
         throw new Error(`Web capture manifests must use ${WEB_CAPTURE_MANIFEST_SCHEMA} schema version ${WEB_CAPTURE_MANIFEST_VERSION}.`);
     }
     const source = record(root.source);
@@ -270,7 +272,10 @@ export function readWebCaptureManifest(value) {
             ? capture.completeness
             : 'unknown';
         const limitations = stringList(capture.limitations, 8, 240, `Web capture manifest ${index + 1} limitations`);
-        contexts.push({ domain, observedAt, completeness: String(completeness), conditions, observerLabel, vantageLabel });
+        const pageBehaviour = readManifestPageBehaviour(capture.pageBehaviour, root.schemaVersion);
+        if (pageBehaviour?.state === 'partial' && completeness === 'complete')
+            throw new Error('Partial page observations cannot declare a complete capture.');
+        contexts.push({ domain, observedAt, completeness: String(completeness), conditions, observerLabel, vantageLabel, pageBehaviour });
         const page = record(capture.page);
         if (page && !onlyKeys(page, PAGE_KEYS))
             throw new Error(`Web capture manifest ${index + 1} page metadata contains unsupported fields.`);
@@ -334,6 +339,8 @@ export function readWebCaptureManifest(value) {
                 : '',
             ...listSummaryFragments('Observed technology labels', technologies),
             ...listSummaryFragments('Observed request domains', requestDomains),
+            ...(pageBehaviour ? [`Page observations: ${pageBehaviour.requests.length} navigation/script/frame responses; ${pageBehaviour.elements.length} script/frame/form elements; ${pageBehaviour.clipboardWriteAttempts} blocked Clipboard API write attempts. State: ${pageBehaviour.state}. Full observations remain in the selected manifest.`,
+                ...listSummaryFragments('Requested-action wording in body text', pageBehaviour.actionHints)] : []),
             ...artifactSummaries,
         ].filter(Boolean);
         const summaries = partitionSummary(summaryFragments);
@@ -342,6 +349,9 @@ export function readWebCaptureManifest(value) {
             throw new Error(`Web capture manifests exceed the ${MAX_EXTERNAL_FINDINGS_PER_DOMAIN}-finding per-domain import limit after preserving bounded metadata.`);
         }
         findingCounts.set(domain, priorFindingCount + summaries.length);
+        const retainedLimitations = retainExternalFindingLimitations(limitations, [
+            'Imported capture metadata, not independently collected website evidence; artefact bytes and separate byte checks are not retained in these findings.',
+        ]);
         for (const summary of summaries) {
             findings.push({
                 domain,
@@ -349,11 +359,8 @@ export function readWebCaptureManifest(value) {
                 evidenceClass: 'deployment_observation',
                 summary,
                 observedAt,
-                completeness,
-                limitations: [
-                    'Imported capture metadata, not independently collected website evidence; artefact bytes and separate byte checks are not retained in these findings.',
-                    ...limitations,
-                ].slice(0, 8),
+                completeness: limitations.every((item) => retainedLimitations.includes(item)) ? completeness : 'partial',
+                limitations: retainedLimitations,
                 reference: sourceReference,
             });
         }

package/packages/investigation/acquisition-decision-packet.mjs

@@ -1,6 +1,6 @@
 import { SORTED_JSON_V2, sha256ArtifactDigestV2 } from "../evidence/artifact-integrity.mjs";
 import { ACQUISITION_DECISION_PACKET_SCHEMA, ACQUISITION_DECISION_PACKET_VERSION, } from "../contracts/investigation-portability.mjs";
-import { isValidAsciiDomainName } from "../../lib/hostname.mjs";
+import { isValidAsciiDomainName } from "../contracts/domain-name.mjs";
 export { ACQUISITION_DECISION_PACKET_SCHEMA, ACQUISITION_DECISION_PACKET_VERSION };
 export const ACQUISITION_DECISIONS = [
     'unresolved',