@slicedearth/whoisleuth-cli 1.45.0 → 2.0.0

package/DISCLOSURE

@@ -8,9 +8,13 @@ can have both legitimate and potentially harmful uses.
 WHOISleuth is intended for authorised defensive investigation, abuse response,
 threat research, domain acquisition due diligence, asset review, and education.
 Network collection is initiated explicitly by the operator, uses bounded
-requests, and keeps source provenance and incomplete results visible. The tool
-does not exploit targets, bypass access controls, submit credentials, execute
-remote page scripts, or automate enforcement actions.
+requests, and keeps source provenance and incomplete results visible. Hosted
+and distributable collection does not exploit targets, bypass access controls,
+submit credentials, execute remote page scripts, or automate enforcement
+actions. The separate repo-local rendered-capture package is an explicit
+authorised exception: it executes page JavaScript in a disposable,
+network-bounded browser and writes only a local screenshot plus sanitised
+digest and manifest artefacts for operator-controlled review and deletion.
 
 Operators are responsible for using WHOISleuth only on systems and data they
 are authorised to examine and in accordance with applicable laws, provider

package/NOTICE

@@ -32,10 +32,11 @@ warning-lists are available under CC0 1.0 Universal or the BSD 2-Clause
 "Simplified" License. Source:
 https://github.com/MISP/misp-warninglists
 
-The exact locked production-dependency inventory and the licence documents
-distributed by those packages are retained in
-frontend/static/third-party-notices.txt. The same file is served by the static
-website at /third-party-notices.txt and is checked for lockfile drift in CI.
+The exact locked production-dependency inventories and licence documents are
+distributed as third-party-notices.txt. The website inventory is served at
+/third-party-notices.txt; the installed CLI contains its own notice file for
+only the CLI runtime dependency closure. Both are generated from the reviewed
+lockfile, and the website inventory is checked for lockfile drift in CI.
 
 The generated Unicode confusable projection is derived from Unicode UTS #39
 data file confusables.txt, Unicode version 17.0.0.

package/README.md

@@ -1,14 +1,13 @@
 # WHOISleuth CLI
 
-WHOISleuth's command-line interface runs the same bounded WHOIS, RDAP, DNS,
-HTTP, TLS, certificate-transparency, domain-posture, and lookalike analysis
-used by the self-hosted application. Network commands run directly from the
-operator's machine. Offline evidence commands do not contact the hosted site.
+WHOISleuth's command-line interface runs local WHOIS, RDAP, DNS, HTTP, TLS,
+certificate, posture and lookalike investigation commands. Networked commands
+run from the operator's machine; offline commands read only selected local input.
+It does not use the hosted WHOISleuth login or workspace.
 
 ## Install
 
-WHOISleuth requires Node.js 24 or later. Run the reviewed public package without
-a global installation:
+WHOISleuth requires Node.js 24 or later. Run the public package directly:
 
 ```bash
 npm exec --yes --ignore-scripts --package=@slicedearth/whoisleuth-cli -- whoisleuth --help
@@ -21,136 +20,87 @@ npm install --global --ignore-scripts @slicedearth/whoisleuth-cli
 whoisleuth doctor
 ```
 
-Update an existing global installation and confirm the installed release with:
+The package has no dependency lifecycle scripts. Its version follows the
+application version.
+
+## Quick start
+
+Inspect the installed command set and plan a Lookup:
 
 ```bash
-npm install --global --ignore-scripts @slicedearth/whoisleuth-cli@latest
-whoisleuth --version
+whoisleuth --help
+whoisleuth commands --common
+whoisleuth lookup example.test --plan --json
 ```
 
-The package version follows the application version. Each release is assembled
-from the executable's bounded dependency closure and retains the project
-licence, notices, trademark terms, source location, and provenance metadata.
-The generated package manifest pins each direct runtime dependency to the exact
-version exercised by the reviewed repository lockfile.
+Run common commands:
+
+```bash
+whoisleuth example.test
+whoisleuth lookup example.test --deep --summary
+whoisleuth bulk domains.txt --csv
+whoisleuth discover example.test --preset common --jsonl
+whoisleuth compare lookup.json --json
+whoisleuth verify-artifact lookup.json --json --strict-exit
+```
+
+One strict domain, IP address or ASN can occupy command position as Lookup
+shorthand. URL-like or ambiguous input requires the explicit `lookup` command;
+only `bulk` accepts multiple targets.
+
+## Command groups
+
+| Group | Common commands |
+| --- | --- |
+| Investigate | `lookup`, `bulk`, `discover`, `ct-search`, `posture`, `http`, `tls`, `compare`, `brief` |
+| Respond | `case-pack`, `change-packet`, `sharing-review`, `export` |
+| Assure | `dnssec-validate`, `mail-transport`, `domain-control`, `assurance`, `workflow-plan`, `diff`, `inspect-archive`, `verify-artifact` |
+| Utilities | `doctor`, `commands`, `completion`, `manual`, `registry-scaffold` |
+
+Use the installed registry for the complete inventory:
+
+```bash
+whoisleuth commands --group investigate
+whoisleuth commands --group respond --mode offline
+whoisleuth commands --json
+whoisleuth manual | man -l -
+```
+
+`registry-scaffold` has a separate fixture contract: its `--profile` selects a
+fixed fixture profile and it rejects shared `--config` profiles. It creates
+sanitised local fixture material.
+
+## Collection and output
+
+Fast Lookup is registration-first. Deep Lookup explicitly adds the applicable
+WHOIS, DNS, website, TLS, registrar-RDAP and observed-network sources. Compact
+Deep Bulk retains only the fields needed for comparison. Authorised active
+commands require their dedicated command and per-run acknowledgement.
+
+Focused `whoisleuth <command> --help` states the exact target, request, input and
+output limits. `lookup --plan` lists planned sources before collection.
+
+Terminal text is the default. Commands expose JSON, JSONL, CSV, Markdown, HTML
+or domain-only output only where declared. `--output` writes a private local
+file atomically and refuses an existing path unless `--force` is selected.
+`--strict-exit` and `--fail-on` expose selected evidence states to automation.
 
-The package has no install, postinstall, or other lifecycle scripts. Network
-access begins only when an analyst runs a networked command. Offline commands
-may read deliberately selected local evidence or configuration files, but do
-not upload them or invoke a hosted WHOISleuth deployment. The installation
-examples disable lifecycle scripts for the package and its dependency tree;
-WHOISleuth does not require them.
+Exit codes are 0 for completion, 2 for invalid input, 3 for collection or
+comparison failure, 4 for a partial result or unmet selected evidence policy,
+70 for internal bootstrap failure, 130 for cancellation and 143 for SIGTERM.
 
 ## Repository checkout
 
-Contributors can run the same source command without installing the package:
+Contributors can run the source command without installing the package:
 
 ```bash
 node bin/whoisleuth.mts --help
-node bin/whoisleuth.mts lookup example.test
-node bin/whoisleuth.mts lookup example.test --deep --summary
-node bin/whoisleuth.mts lookup example.test --deep --plan --json
-node bin/whoisleuth.mts lookup example.test --deep --observer workstation-a --vantage office-egress --json
-node bin/whoisleuth.mts lookup example.test --deep --markdown --output lookup.md
-node bin/whoisleuth.mts bulk domains.txt --deep --checkpoint bulk-checkpoint.json
-node bin/whoisleuth.mts bulk domains.txt --csv --registered-only
-node bin/whoisleuth.mts bulk domains.txt --queries --errors-only
-node bin/whoisleuth.mts discover example.test --dictionary private-terms.txt --snapshot discovery-state.json --json
-node bin/whoisleuth.mts discover-scan example.test --scan-limit 50 --checkpoint candidate-scan.json --json
-node bin/whoisleuth.mts page-compare official.json candidate.json --json
-node bin/whoisleuth.mts mail-review bulk.json --json
-node bin/whoisleuth.mts domain-control domain-control-input.json --json
-node bin/whoisleuth.mts assurance domain-assurance-input.json --json
-node bin/whoisleuth.mts sharing-review response-packet.json --marking amber --recipient-scope organization --purpose 'Reviewed handoff' --human-reviewed --personal-data-reviewed --redactions-confirmed --json
-node bin/whoisleuth.mts workflow-plan domain-triage example.test --json
-node bin/whoisleuth.mts diff first-lookup.json second-lookup.json --json
-node bin/whoisleuth.mts reconcile office.json mobile.json external.json --json
-node bin/whoisleuth.mts timeline first-observation.json second-observation.json latest-observation.json --json
-node bin/whoisleuth.mts registry-support example.test --json
-node bin/whoisleuth.mts registry-doctor lookup.json --json
-node bin/whoisleuth.mts registry-cohort saved-lookups.jsonl --json
-node bin/whoisleuth.mts brief lookup.json
-node bin/whoisleuth.mts case-pack cases.json --audience trusted --reviewed --json
-node bin/whoisleuth.mts monitor-once control-manifest.json --json
-node bin/whoisleuth.mts workflow-run domain-triage example.test --approve-network --json --output run.json
-node bin/whoisleuth.mts lookalike-calibrate reviewed-candidates.json --json
-node bin/whoisleuth.mts doctor
-node bin/whoisleuth.mts commands --json
-node bin/whoisleuth.mts completion zsh
-node bin/whoisleuth.mts completion powershell
-node bin/whoisleuth.mts manual | man -l -
+node bin/whoisleuth.mts lookup example.test --plan --json
+npm run cli:package:check
 ```
 
-Fast lookup is the default. Deep collection must be requested explicitly and
-can disclose the target to additional authoritative or first-party network
-sources. Missing, partial, rate-limited, and unsupported sources remain
-explicit and are never interpreted as evidence of safety or absence.
-`lookup --plan` classifies a target and explains the selected source families
-and disclosures without making a network request. `commands --json` exposes the
-installed command contracts for local wrappers without running collection.
-Focused command help and the generated manual label every operation as offline
-or networked and state its target, input, and concurrency boundaries. The
-packaged [dual-use disclosure](https://github.com/slicedearth/whoisleuth/blob/main/DISCLOSURE)
-defines the supported defensive use of those capabilities.
-
-Interactive output uses restrained semantic colour, width-aware wrapping, and
-stderr-only progress for slower collection. Redirected and machine-readable
-output stays free of ANSI and progress text. Lookup also provides `--summary`
-and `--verbose` terminal views without changing what is collected. `doctor` is
-offline unless `--network` is explicitly supplied, and completion scripts are
-printed without modifying shell configuration. Commands can use atomic private
-`--output` files, Lookup can emit strict automation exits and target-free
-versioned progress events, and Bulk can resume an exact validated compact
-checkpoint. Checkpoint schema 2 preserves each current row's observation time;
-legacy schema-1 rows remain readable with unknown observation time rather than
-being restamped on resume. Bulk machine output schema 3 distinguishes current
-and resumed rows. A checkpoint write failure preserves completed output and returns
-the partial-result exit code. Ctrl-C suppresses partial final output and
-returns exit code 130. SIGTERM uses the same graceful cleanup path and returns
-143; a second interrupt performs best-effort temporary-file
-cleanup before exiting immediately.
-Strict local profiles can supply only safe presentation, Fast-mode,
-concurrency, and observer defaults; command-line options override them.
-Supported automation commands can emit JUnit or SARIF and apply explicit
-failure policies without changing their collection result.
-
-The offline `timeline` command orders 2 to 20 saved Lookup documents for one
-domain and compares each adjacent observation. It retains observation times and
-normalised field states but no input filenames or raw registry payloads.
-Observed differences remain separate from missing, unavailable, and changed
-collection conditions.
-
-Optional bounded observer and vantage labels let analysts distinguish saved
-collection contexts without changing collection. `reconcile` compares 2 to 5
-same-domain observations while keeping agreement, disagreement, and
-non-comparable evidence separate; the labels are context, not proof of
-independence. `registry-doctor`, `assurance`, `sharing-review`, and
-`lookalike-calibrate` add offline compatibility, change/recovery, sharing, and
-review-yield workflows without contacting the hosted application.
-`registry-cohort` aggregates target-free publication-quality counts from saved
-Lookups, while `registry-scaffold` produces a sanitised synthetic contributor
-fixture. `brief` and `case-pack` create bounded local handoffs, `monitor-once`
-runs one explicit control review rather than a daemon, and `workflow-run`
-executes only installed fixed-recipe steps with per-run network approval and
-analyst-selection pauses.
-
-Bulk also supports fixed-column CSV, domain-only or exact-query output,
-registered, inconclusive, and hard-failure output filters, and bounded A, AAAA,
-NS, and MX summaries. Discover
-supports local custom dictionaries and private snapshot comparison suitable
-for an operator-managed scheduler. The separate networked `discover-scan`
-command can collect a deterministic bounded subset in chunks, retain mutation
-provenance, apply a non-destructive analyst allowlist, group exact shared DNS
-observations, and compare a private component-aware material-change snapshot.
-The full allowlist is not emitted, but matching scanned candidates are labelled
-as suppressed so the review decision remains explainable. Saved Deep
-lookups can be compared across static page, parse5-tokenized DOM structure,
-favicon, technology, and TLS evidence, while saved Bulk output can be reviewed
-for passive MX, null MX, SPF, DMARC, and shared-provider context.
-
-See `docs/cli.md` in the package for installation and first use, and
-`docs/cli-reference.md` for the complete command, privacy, output, and
-evidence-contract reference. Report suspected vulnerabilities through the
-private channel described in `SECURITY.md`.
+The package includes `docs/cli.md` for usage and `docs/cli-reference.md` for
+compatibility, privacy and evidence contracts. Report suspected vulnerabilities
+through the private channel in `SECURITY.md`.
 
 Copyright 2026 slicedearth. Licensed under AGPL-3.0-only.

package/SECURITY.md

@@ -26,9 +26,12 @@ weakness can use the public issue tracker.
 
 Reports are assessed against WHOISleuth's documented trust boundaries,
 including its local-first workspace, bounded network collection, shared
-deployment password, and optional hosted monitoring. A source outage, partial
-registry response, or heuristic disagreement is not by itself a security
-vulnerability, but unsafe handling of those states may be.
+deployment password, and optional hosted monitoring. The accepted
+[product boundary](https://github.com/slicedearth/whoisleuth/blob/main/docs/product-boundary.md) and
+[threat model](https://github.com/slicedearth/whoisleuth/blob/main/docs/threat-model.md) describe those boundaries, principal abuse
+cases, controls, residual risks, and deliberate non-goals. A source outage,
+partial registry response, or heuristic disagreement is not by itself a
+security vulnerability, but unsafe handling of those states may be.
 
 Confirmed reports will be handled through a private advisory until a fix and
 coordinated disclosure are ready. No bounty or guaranteed response time is

package/bin/whoisleuth.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
 import EXIT_CODES from "../cli/exit-codes.mjs";
+import { metaActionDefinition } from "../cli/command-reference.mjs";
 for (const stream of [process.stdout, process.stderr]) {
     stream.on('error', (error) => {
         if (error.code === 'EPIPE')
@@ -9,7 +10,7 @@ for (const stream of [process.stdout, process.stderr]) {
     });
 }
 const argv = process.argv.slice(2);
-if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-V')) {
+if (argv.length === 1 && metaActionDefinition('version').aliases.includes(argv[0] ?? '')) {
     const require = createRequire(import.meta.url);
     const metadata = require('../package.json');
     if (typeof metadata.version !== 'string' || !metadata.version) {
@@ -28,12 +29,14 @@ else {
         import("../cli/runner.mjs"),
     ]);
     let resolvedArgv;
+    let profileResolutionFailed = false;
     try {
         resolvedArgv = await configModule.resolveCliProfileArguments(argv);
     }
     catch (error) {
         process.stderr.write(`Usage error: ${errorsModule.boundedCliErrorMessage(error, 'Invalid CLI profile')}\n`);
         process.exitCode = EXIT_CODES.USAGE;
+        profileResolutionFailed = true;
         resolvedArgv = [];
     }
     const cancellation = new AbortController();
@@ -54,9 +57,9 @@ else {
     const onSigterm = () => interrupt('SIGTERM');
     process.on('SIGINT', onSigint);
     process.on('SIGTERM', onSigterm);
-    const execution = resolvedArgv.length
-        ? runnerModule.runCli(resolvedArgv, { signal: cancellation.signal })
-        : Promise.resolve(process.exitCode || EXIT_CODES.USAGE);
+    const execution = profileResolutionFailed
+        ? Promise.resolve(process.exitCode || EXIT_CODES.USAGE)
+        : runnerModule.runCli(resolvedArgv, { signal: cancellation.signal });
     execution.then((code) => {
         if (code === 130) {
             process.removeListener('SIGINT', onSigint);

package/cli/archive-inspect.mjs

@@ -1,10 +1,12 @@
 import { Buffer } from 'node:buffer';
 import { createHash } from 'node:crypto';
 import { domainToASCII } from 'node:url';
-import { decryptWorkspaceArchive, isEncryptedWorkspaceArchive, } from "../frontend/src/lib/analysis/workspace-archive-crypto.js";
-import { WORKSPACE_ARCHIVE_SCHEMA, readWorkspaceArchive, } from "../frontend/src/lib/analysis/workspace-archive.js";
-import { canonicalArtifactJson } from "../frontend/src/lib/analysis/artifact-integrity.js";
+import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { decryptWorkspaceArchive, isEncryptedWorkspaceArchive, } from "../packages/workspace/workspace-archive-crypto.mjs";
+import { WORKSPACE_ARCHIVE_SCHEMA, readWorkspaceArchive, } from "../packages/workspace/workspace-archive.mjs";
+import { canonicalArtifactJson } from "../packages/evidence/artifact-integrity.mjs";
 import { MAX_OFFLINE_ARTIFACT_BYTES, verifyOfflineArtifact, } from "./artifact-verify.mjs";
+import { safeTerminalValue } from "./formatters/terminal.mjs";
 export const ARCHIVE_INSPECTION_SCHEMA = 'whoisleuth.workspace-archive-inspection';
 export const ARCHIVE_INSPECTION_VERSION = 2;
 export const MAX_ARCHIVE_SEARCH_LENGTH = 253;
@@ -35,10 +37,11 @@ function parseJson(raw) {
     }
     let parsed;
     try {
+        scanBoundedJson(raw);
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new TypeError('Archive input must be valid JSON.');
+        throw new TypeError('Archive input must be valid bounded JSON without duplicate keys.');
     }
     const value = record(parsed);
     if (!value)
@@ -96,8 +99,12 @@ function searchSection(section, value, search, reveal, results, state) {
     const stack = [{ value, depth: 0 }];
     while (stack.length && results.length < MAX_ARCHIVE_SEARCH_MATCHES) {
         const current = stack.pop();
-        if (!current || current.depth > 16)
+        if (!current)
             continue;
+        if (current.depth > 16) {
+            state.truncated = true;
+            continue;
+        }
         if (state.visited >= MAX_ARCHIVE_SEARCH_NODES) {
             state.truncated = true;
             return;
@@ -105,7 +112,10 @@ function searchSection(section, value, search, reveal, results, state) {
         state.visited += 1;
         const object = record(current.value);
         if (object) {
-            for (const [field, child] of Object.entries(object).slice(0, 300)) {
+            const entries = Object.entries(object);
+            if (entries.length > 300)
+                state.truncated = true;
+            for (const [field, child] of entries.slice(0, 300)) {
                 if (SEARCHABLE_FIELDS.has(field) && typeof child === 'string') {
                     const normalized = canonicalSearchValue(child);
                     if (normalized === search) {
@@ -116,7 +126,7 @@ function searchSection(section, value, search, reveal, results, state) {
                             ...(reveal ? { value: child.slice(0, MAX_ARCHIVE_SEARCH_LENGTH) } : {}),
                         }));
                         if (results.length >= MAX_ARCHIVE_SEARCH_MATCHES) {
-                            state.truncated = stack.length > 0;
+                            state.truncated = true;
                             return;
                         }
                     }
@@ -126,6 +136,8 @@ function searchSection(section, value, search, reveal, results, state) {
             }
         }
         else if (Array.isArray(current.value)) {
+            if (current.value.length > 5_000)
+                state.truncated = true;
             for (const child of current.value.slice(0, 5_000)) {
                 if (child && typeof child === 'object')
                     stack.push({ value: child, depth: current.depth + 1 });
@@ -165,6 +177,9 @@ export async function inspectWorkspaceArchive(raw, options = {}) {
         }
     }
     if (options.requireMatch === true && search && results.length === 0) {
+        if (searchState.truncated) {
+            throw new TypeError('Archive search reached a configured bound before an exact canonical match could be established.');
+        }
         throw new TypeError('Archive search found no exact canonical match.');
     }
     return Object.freeze({
@@ -207,6 +222,9 @@ export async function inspectWorkspaceArchive(raw, options = {}) {
             ...(reveal
                 ? ['Search values were revealed only because the operator supplied --reveal; handle the output as sensitive evidence.']
                 : ['Search results contain field names and digests only. A digest does not authenticate or establish the accuracy of a retained value.']),
+            ...(searchState.truncated
+                ? ['Archive search reached a configured traversal or result boundary; zero retained matches is inconclusive.']
+                : []),
         ]),
     });
 }
@@ -219,15 +237,15 @@ export function formatArchiveInspection(report) {
         `Content digest: ${report.summary.contentDigestSha256}`,
     ];
     for (const section of report.sections) {
-        lines.push(`${section.label}: ${section.recordCount} records · ${section.status} · ${section.bytes} bytes`);
+        lines.push(`${safeTerminalValue(section.label)}: ${section.recordCount} records · ${safeTerminalValue(section.status)} · ${section.bytes} bytes`);
     }
     if (report.search.requested) {
         lines.push(`Search matches: ${report.search.matchCount}${report.search.truncated ? ' (truncated)' : ''}`);
         for (const match of report.search.results) {
-            lines.push(`${match.section}.${match.field}: ${match.value ?? `sha256:${match.valueDigestSha256}`}`);
+            lines.push(`${safeTerminalValue(match.section)}.${safeTerminalValue(match.field)}: ${safeTerminalValue(match.value ?? `sha256:${match.valueDigestSha256}`)}`);
         }
     }
     for (const limitation of report.limitations)
-        lines.push(`Limitation: ${limitation}`);
+        lines.push(`Limitation: ${safeTerminalValue(limitation)}`);
     return `${lines.join('\n')}\n`;
 }