@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/docs/infrastructure-observations.md

@@ -0,0 +1,126 @@
+# Source-qualified infrastructure snapshots
+
+The retained infrastructure inventory combines admitted browser-local evidence,
+not all infrastructure belonging to an organisation. It makes no requests on
+import, opening a view, filtering, selecting a host or comparing history.
+
+Import a `whoisleuth.infrastructure-observation` version 1 document through the
+existing external-findings import. The exact bounded snapshot is retained as one
+Case evidence pin. Review the preview before confirming the mutation. The source
+descriptions are supplied provenance, not authenticated source identities.
+Legacy DNS and certificate imports remain readable: an old Case-domain DNS pin
+does not acquire a precise queried hostname or complete collection scope.
+
+The document records an explicit target, selected full hostnames and DNS types,
+collection mode, observation time and coverage. Each DNS response retains its
+queried name, response owner, type, outcome and source. An alias link uses its
+record owner; an address returned after an alias belongs to the returned address
+owner, not automatically to the initial query. Only retained alias links are
+drawn. Links from different dates do not prove one contemporaneous alias chain.
+No-data, NXDOMAIN, failed and not-checked outcomes remain different observations
+and do not decide registration availability.
+
+Certificate-log and TLS observations keep distinct sources and exact SHA-256
+identities. Full names remain visible; `*.example.test` is a wildcard pattern,
+not an enumerated hostname, and cannot be selected for Lookup or Bulk.
+Certificate names alone do not establish current resolution or activity.
+
+DNS operator, observed edge/CDN/proxy, application platform, runtime, embedded
+dependency, address registration, routing origin and independently observed
+origin are distinct source-qualified roles. Routing requires a routing source;
+IP-registration data cannot substitute for it. Edge indicators cannot identify
+a hidden origin. Multiple providers and conflicting observations remain separate.
+The snapshot reader does not derive physical location, responsibility, ownership,
+safety or maliciousness from these roles.
+
+## Review and deliberately act
+
+Open the inventory from saved-work search. Type, source and date filters apply to
+the admitted set before pagination. Inspect one snapshot to review every retained
+DNS outcome, certificate name and provider role, or select two snapshots in
+chronological order to compare. Export preserves the exact snapshot format.
+Topology search applies to the complete admitted one-hop relationship set, not
+the current source page. Its diagram has a 50-relationship budget; the paginated
+source list and exact snapshot review retain access to evidence beyond the diagram.
+
+Lookup links fill the selected target for review without submitting it. Explicitly
+selected hostnames can be prepared in existing Bulk. That handoff does not scan,
+recursively expand targets, change a watchlist or enrol a host in monitoring.
+Use the existing reviewed Lookup/Bulk/Monitor collection plans and explicit
+save actions to collect or retain another observation.
+
+## Historical comparison and CLI
+
+Source, mode and exact selection scope must match, and the later snapshot must
+have a strictly later observation time. Newly observed means newly present in
+retained evidence, not newly created. A value not returned by a complete,
+comparable selected collection is labelled **not returned**, never confirmed
+absence or disappearance. Failed, partial, limited, changed-source and
+incomparable snapshots cannot generate removal findings. Equal-time observations
+have no temporal order. Provider-reported history stays labelled separately from
+supplied local observations.
+
+Comparison rows retain the exact DNS query, response owner and record type, or
+the certificate SHA-256, alongside their source and observation clocks. Labels
+are presentation only: relationship groups and graph exports use canonical
+entity identities, including when long nameserver-set labels look identical.
+
+Derived relationship-group, graph-node and cluster IDs can change when their
+identity calculation changes, including for short labels. They are not durable
+cross-export keys; use the canonical `entityId` where provided. Historical groups
+without it use their complete retained value. Graph fields named `canonical`
+and `value` are bounded display text, not a replacement for that identity. Inspect
+the contributing Case evidence for full nameserver members. Component selections
+and cluster adjustments are transient and are not persisted review history.
+
+In GraphML and GEXF, the display label for `node_canonical` is now
+`Bounded display value` (previously `Canonical value`). The field key, JSON
+property, entity identities and values are unchanged; XML consumers should use
+the field key rather than its display label.
+
+The existing offline command shares the website reader and comparison owner:
+
+```sh
+whoisleuth review-evidence infrastructure-observation.json --json
+whoisleuth review-evidence infrastructure-comparison.json --json
+```
+
+The comparison input is exactly:
+
+```json
+{
+  "schema": "whoisleuth.infrastructure-comparison.input",
+  "version": 1,
+  "earlier": { "...": "complete version-1 snapshot" },
+  "later": { "...": "complete version-1 snapshot" }
+}
+```
+
+The placeholders above are illustrative, not valid evidence. See the reserved
+fixture in `test/fixtures/infrastructure-observations/` for an exact snapshot.
+The CLI performs no DNS, registry, BGP, TLS, HTTP or provider request.
+
+Changed or incomplete latest retained pairs surface as existing local Review
+Items with supporting Case navigation. Complete earlier snapshots remain
+available as stronger baselines; later failures do not rewrite them. There is no
+new history store or scheduling engine.
+
+## Resource and compatibility boundary
+
+One snapshot is limited to 128 KiB, 128 selected hostnames, six DNS types, 16
+source identities, 512 DNS response rows with at most 32 values each, 32
+certificate observations with at most 128 exact names each, 128 role observations
+and 12 bounded limitations. Bounds reject oversized documents rather than
+silently prune accepted snapshot evidence. Existing Case/workspace quotas still
+apply. Projection/diagram budgets may admit a smaller disposable view, with
+incomplete coverage disclosed; exact snapshot review/export remains available.
+
+Version 1 has exact keys and refuses future versions. Existing external-findings
+version 4 and typed version-1 row imports preserve their historical meaning;
+version 5 adds the optional exact infrastructure snapshot. No external discovery
+API, new provider, dependency, collector or automatic request is required.
+Current snapshot and version-5 findings exports use compact UTF-8 JSON with a
+terminal line feed so the emitted representation stays within its parser ceiling.
+An offline comparison input is bounded to two snapshot budgets plus 1 KiB of
+framing. Historical version-4 fixture bytes and reader meaning remain unchanged;
+new typed row conversions emit version 5.

package/docs/offline-intake-context.md

@@ -0,0 +1,213 @@
+# Selected-input indicators and internal containment
+
+Message intake remains local and inert. It does not resolve indicators, open
+links, consult reputation services, execute attachments or apply controls.
+
+## Source-linked indicator review
+
+Version 2 of `whoisleuth.message-intake` adds literal IPv4/IPv6 observations and
+explicitly labelled MD5, SHA-1 and SHA-256 strings from selected plain text,
+message body text, supported calendar fields and extracted document text.
+Private and reserved addresses are valid textual observations, not permission
+to contact them. A labelled hash string is a supplied claim, not proof that a
+file has that digest. Bare opaque hexadecimal values are not interpreted.
+
+Each indicator identifies its input/message/document part and page when known.
+The review retains the source-byte and part digests separately. Identical values
+from different parts remain separately attributed; repeated identical values
+within one part are deduplicated. The UI can copy a source citation. Indicators
+are not added to Lookup targets and do not become a risk score or finding.
+
+Complete URL spans, address local parts, recognised credential-bearing lines,
+message headers and QR payloads are not scanned for indicators. MIME HTML
+extraction also excludes script and style nodes. Explicit plaintext is literal
+supplied text: an IP inside a pasted code snippet can be an inert observation;
+the code is never executed. Phone candidates have their own stricter markup
+exclusions. HAR and identity-event imports keep their existing restricted
+projections: no broad scan of their original fields occurs. Extraction is
+limited to 512 observations, 4,096 candidate checks and 2,097,152 text code
+units across an input. Reached bounds are partial coverage, never proof that
+no further indicators exist.
+
+Version-1 reports remain readable without invented indicator coverage. Their
+original source digests do not acquire new observations retrospectively.
+
+### Supplied phone candidates
+
+Plain-text intake can also identify possible telephone numbers, including a
+support number in a supplied snippet with no link. Candidates are review leads:
+they do not authenticate a caller, identify an operator or establish wrongdoing.
+No number is dialled, resolved or checked against a reputation service.
+
+Review and select each observation deliberately before including it in a saved
+review. Unselected candidates remain transient. The selected observation keeps
+its original spelling, source digest and exact text range, not the surrounding
+snippet. Text ranges use zero-based, end-exclusive UTF-16 code-unit offsets;
+supplementary characters occupy two units. A declared source time is separate
+from the local review time. Identify manual transcription or OCR-derived text
+when that is how the supplied text was obtained.
+
+The browser provides a shared declaration for selected occurrences. Open
+**Declaration for candidate** to override a source label, role, observation time
+or text basis for one occurrence. Apply or clear edits before saving or
+downloading; only equivalent numbers with equivalent declarations share a group.
+
+An advertised support contact and a sender or caller-ID claim describe different
+roles; neither verifies ownership. International formatting can be compared only
+where its prefix and supported separators permit a defensible normalisation.
+National-format numbers, conflicting country context and unsupported characters
+remain uncertain. Extensions are separate, not appended to the destination.
+Dates, identifiers and unsupported forms must not be treated as verified numbers.
+
+Selected numbers can still be private contacts. Review the selected content
+before saving or sharing it. Ordinary public/trusted Case projections do not
+include the private intake attachment; domain-focused interchange does not invent
+a telephone mapping. A missing exported phone observation is not evidence that
+none was supplied.
+
+### Compare a displayed claim with a supplied destination
+
+Use the intake's manual destination comparison when supplied ad, search or
+screenshot material shows one destination and a separate source supplies another.
+Identify each source, any known observation time, and whether its text is a claim,
+transcription or supplied observation. The comparison uses the same safe hostname
+parsing as an HTML link's displayed-host comparison.
+
+Review the exact hostname and registrable boundary. A hostname such as
+`store.example.test.attacker.invalid` is not `store.example.test`. Legitimate
+tracking destinations can also differ. Missing, malformed or credential-bearing
+input leaves insufficient evidence rather than inventing a redirect chain.
+
+Exact entered URLs stay in the private transient view. Retained output uses the
+minimised hostname/origin projection and supplied qualifications, not private
+paths, query values or fragments. Comparing the pair never follows either URL
+and does not establish that a redirect occurred.
+
+## Optional distribution declarations
+
+After reviewing input in Lookup or a Case, open **Declare distribution
+context**. Supply a channel, non-sensitive source label and optional declared
+time, reference, observer and vantage labels. Apply or clear changed declarations
+before saving or downloading. These are analyst claims, not verified delivery,
+capture conditions, network location or independent collection. The local review
+time remains separate from a declared observation time.
+
+The CLI accepts the same explicit declaration:
+
+```sh
+whoisleuth intake text selected.txt --intake-context context.json --json
+```
+
+```json
+{
+  "schema": "whoisleuth.intake-context",
+  "version": 1,
+  "context": {
+    "channel": "sms",
+    "observedAt": "2026-01-02T03:04:05.000Z",
+    "sourceLabel": "Reported message",
+    "reference": "CASE-17",
+    "observerLabel": "Reviewer A",
+    "vantageLabel": "Selected device"
+  }
+}
+```
+
+The separate context file is limited to 8 KiB; stdin is not accepted for it.
+Use `null` for unknown optional values. Channels are `email`, `sms`, `messaging`,
+`social`, `advertisement`, `website`, `document`, `other` and `unknown`.
+Do not supply credentials, recipients, personal account identifiers or exact
+URLs in labels. All declarations are included in the downloaded or deliberately
+retained review. The Case summary pin contains counts and the report identity,
+not the indicator values or declaration text. Retaining original input remains
+a separate choice.
+
+### Select phone observations in the CLI
+
+First run `whoisleuth intake text selected.txt --json`. Standard error shows a
+candidate count, the full source digest, UTF-16 ranges and uncertainty, but not
+the numbers themselves. JSON output excludes unselected candidates. `--quiet`
+suppresses this discovery guidance. Inspect the corresponding text in your
+selected file before choosing a range.
+
+A version-2 context file binds selections to those exact input bytes. For
+example, a file containing `Support: +1 202 555 0107` followed by one LF newline
+has this selection:
+
+```json
+{
+  "schema": "whoisleuth.intake-context",
+  "version": 2,
+  "context": null,
+  "review": {
+    "sourceDigestSha256": "sha256:4ff4224ff4ed496fb67fa2ccb25f87b284d1d291f8e79b57646d6c32700eeb52",
+    "phones": [{
+      "start": 9,
+      "end": 24,
+      "declaration": {
+        "sourceLabel": "Selected support snippet",
+        "observedAt": null,
+        "basis": "supplied_text",
+        "role": "advertised_support_contact",
+        "countryCallingCode": null
+      }
+    }],
+    "destinationPair": null
+  }
+}
+```
+
+Run the earlier `--intake-context context.json` command to include that selected
+observation. A changed file or incorrect range is rejected; obtain its current
+digest and review it again. `context` can also carry the existing distribution
+declaration. Version-1 context files remain supported.
+
+## Selected internal containment handoff
+
+In **Case → Response → Account and device recovery**, open **Prepare an internal
+containment handoff**. Select retained next-step assertions and, independently,
+their linked evidence pins. Choose security operations, identity response,
+endpoint response or network response for tailored review guidance.
+
+The preview displays the selected statements, rationale, recorded state,
+times, pin values and source metadata. **Exact JSON disclosure** exposes the
+complete download, including selected pin scope, provenance and recheck fields.
+Supports, contradicts, unresolved and
+unrecorded relationships remain distinct. A linked pin that is not selected is
+not silently included; an unavailable referenced pin remains unavailable.
+The handoff is limited to 20 requests, 40 pins and 128 KiB, with no silent
+truncation. No original file bytes or unrelated Case notes, title, contacts,
+recipient values, assertions or pins are included.
+
+Review the audience disclosure before copy, download or explicit retention.
+Internal and trusted audiences use the existing Case disclosure policy. Public
+preview excludes internal requests and supporting pins and cannot produce a
+containment export. Selected analyst text may still be sensitive: minimisation
+does not provide anonymisation. Saving uses an ordinary retained Case file and
+a source-hashed summary pin, not another task or state store.
+
+The existing `review-evidence` CLI command accepts an equivalent selected input:
+
+```json
+{
+  "schema": "whoisleuth.internal-containment.input",
+  "version": 1,
+  "caseExport": { "version": 18, "cases": [] },
+  "caseId": "selected-case-id",
+  "selection": {
+    "audience": "internal",
+    "recipientRole": "identity_response",
+    "assertionIds": ["selected-next-step-id"],
+    "evidencePinIds": ["selected-linked-pin-id"]
+  },
+  "disclosureReviewed": true
+}
+```
+
+Replace the empty example with a supported ordinary Case export and exact
+retained IDs after reviewing its selected content. The CLI does not write the
+Case; `--strict-exit` returns 4 when selected supporting context is incomplete.
+Output uses `whoisleuth.internal-containment` version 1 inside the existing
+offline-review envelope. Neither external resolution nor a resolved Case closes
+an open internal request. The handoff performs no assignment, notification,
+blocking, credential change, isolation or other containment action.

package/lib/analyst-taxonomy.mjs

@@ -1,40 +1,2 @@
-// Deliberately small interoperability projection over reviewed MISP
-// taxonomies. WHOISleuth retains its own bounded workflow vocabulary and
-// derives machine tags only when an analyst-owned disposition and reason make
-// the mapping unambiguous. These tags never alter collection or scoring.
-const ANALYST_REVIEW_REASONS = Object.freeze([
-    Object.freeze({ value: '', label: 'Not recorded' }),
-    Object.freeze({ value: 'authorized_or_owned', label: 'Authorised or owned domain' }),
-    Object.freeze({ value: 'shared_infrastructure', label: 'Shared infrastructure explained the signal' }),
-    Object.freeze({ value: 'generic_platform_or_template', label: 'Generic platform or template' }),
-    Object.freeze({ value: 'parked_or_reseller', label: 'Parking or reseller page' }),
-    Object.freeze({ value: 'insufficient_evidence', label: 'Insufficient evidence' }),
-    Object.freeze({ value: 'legitimate_third_party', label: 'Legitimate third party' }),
-    Object.freeze({ value: 'confirmed_credential_abuse', label: 'Confirmed credential abuse' }),
-    Object.freeze({ value: 'confirmed_malware', label: 'Confirmed malware' }),
-    Object.freeze({ value: 'other_reviewed', label: 'Other reviewed reason' }),
-]);
-const ANALYST_REVIEW_REASON_VALUES = new Set(ANALYST_REVIEW_REASONS.map(({ value }) => value).filter(Boolean));
-const MISP_TAXONOMY_REFERENCES = Object.freeze([
-    Object.freeze({ namespace: 'domain-abuse', version: 2, sourceSha256: '5fcfb44742daac97061726faaaadd2ce6b7eac55306acaae3d30c3882d18f991', sourceUrl: 'https://github.com/MISP/misp-taxonomies/blob/main/domain-abuse/machinetag.json' }),
-    Object.freeze({ namespace: 'estimative-language', version: 5, sourceSha256: '1010927d396f66f7cc58a229ebb8af6ad2cdc0250ad5f8ce3b1bd9aacf5ab4da', sourceUrl: 'https://github.com/MISP/misp-taxonomies/blob/main/estimative-language/machinetag.json' }),
-    Object.freeze({ namespace: 'event-assessment', version: 2, sourceSha256: '39291bdd50e1b2975a93e33e396f42b398178015580a84402bc3d8d549dd721e', sourceUrl: 'https://github.com/MISP/misp-taxonomies/blob/main/event-assessment/machinetag.json' }),
-    Object.freeze({ namespace: 'false-positive', version: 7, sourceSha256: 'ffc8d35ae36eb1d39f33611d1090793021f2bfe3b4b31ae41631e22cf544a2fb', sourceUrl: 'https://github.com/MISP/misp-taxonomies/blob/main/false-positive/machinetag.json' }),
-    Object.freeze({ namespace: 'phishing', version: 5, sourceSha256: '8628ebe4d5935216a7b006a4d975669c4ae1a554ef8ed78ffaadd62f763d7263', sourceUrl: 'https://github.com/MISP/misp-taxonomies/blob/main/phishing/machinetag.json' }),
-]);
-function analystInteroperabilityTags(disposition, reviewReasonCode) {
-    const tags = new Set();
-    if (disposition === 'false_positive')
-        tags.add('false-positive:confirmed="true"');
-    if ((disposition === 'false_positive' || disposition === 'expected')
-        && ['authorized_or_owned', 'shared_infrastructure', 'generic_platform_or_template', 'parked_or_reseller', 'legitimate_third_party'].includes(String(reviewReasonCode)))
-        tags.add('false-positive:risk="high"');
-    if (reviewReasonCode === 'insufficient_evidence') {
-        tags.add('estimative-language:confidence-in-analytic-judgment="low"');
-    }
-    if (disposition === 'confirmed_abuse' && reviewReasonCode === 'confirmed_credential_abuse') {
-        tags.add('phishing:techniques="fake-website"');
-    }
-    return [...tags].sort();
-}
-export { ANALYST_REVIEW_REASONS, ANALYST_REVIEW_REASON_VALUES, MISP_TAXONOMY_REFERENCES, analystInteroperabilityTags, };
+// Retained public import; the runtime-neutral implementation lives in the domain layer.
+export * from "../packages/analysis/analyst-taxonomy.mjs";

package/lib/application-version.mjs

@@ -1,3 +1,3 @@
 import packageDocument from '../package.json' with { type: 'json' };
-import { normalizeBoundedSemanticVersion } from "./semantic-version.mjs";
+import { normalizeBoundedSemanticVersion } from "../packages/analysis/semantic-version.mjs";
 export const WHOISLEUTH_APPLICATION_VERSION = normalizeBoundedSemanticVersion(packageDocument.version, 'Application manifest');