@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/cli/collection-arguments.mjs

@@ -0,0 +1,123 @@
+import {} from "./command-argument-grammar.mjs";
+import {} from "./fail-policy.mjs";
+import { commandDefaultNumber, commandDefaultText } from "./command-reference.mjs";
+import { COLLECTION_COMMAND_DEFINITIONS } from "./collection-command-definitions.mjs";
+import { terminalOptions, normalizedLabel, failPolicies, parseOutput, } from "./argument-values.mjs";
+function parseLookupArguments(parsed) {
+    const output = parseOutput(parsed, COLLECTION_COMMAND_DEFINITIONS.lookup);
+    const selectedFailPolicies = failPolicies(parsed, 'lookup');
+    return {
+        action: 'lookup',
+        query: parsed.positionalValue('target'),
+        output,
+        deep: parsed.hasOption('--deep'),
+        detail: parsed.hasOption('--summary')
+            ? 'summary'
+            : parsed.hasOption('--verbose')
+                ? 'verbose'
+                : 'standard',
+        strictExit: parsed.hasOption('--strict-exit'),
+        events: parsed.hasOption('--events'),
+        plan: parsed.hasOption('--plan'),
+        includeAttribution: !parsed.hasOption('--no-attribution'),
+        observerLabel: normalizedLabel(parsed, '--observer', 80),
+        vantageLabel: normalizedLabel(parsed, '--vantage', 80),
+        ...terminalOptions(parsed),
+        ...(parsed.hasOption('--browse') ? { browse: true } : {}),
+        ...(parsed.hasOption('--exact-url') ? { exactUrl: true } : {}),
+        ...(parsed.optionValue('--save-lookup')
+            ? { saveLookup: parsed.optionValue('--save-lookup') }
+            : {}),
+        ...(selectedFailPolicies ? { failOn: selectedFailPolicies } : {}),
+    };
+}
+function parseBulkArguments(parsed) {
+    const deep = parsed.hasOption('--deep');
+    const selectedFailPolicies = failPolicies(parsed, 'bulk');
+    const output = parseOutput(parsed, COLLECTION_COMMAND_DEFINITIONS.bulk);
+    const filter = parsed.hasOption('--registered-only')
+        ? 'registered'
+        : parsed.hasOption('--inconclusive-only')
+            ? 'inconclusive'
+            : parsed.hasOption('--errors-only')
+                ? 'errors'
+                : 'all';
+    return {
+        action: 'bulk',
+        source: parsed.positionalValue('source'),
+        output,
+        deep,
+        concurrency: parsed.integerOption('--concurrency') ?? commandDefaultNumber('bulk', '--concurrency', deep),
+        checkpoint: parsed.optionValue('--checkpoint'),
+        resume: parsed.hasOption('--resume'),
+        events: parsed.hasOption('--events'),
+        plan: parsed.hasOption('--plan'),
+        filter,
+        ...terminalOptions(parsed),
+        ...(selectedFailPolicies ? { failOn: selectedFailPolicies } : {}),
+    };
+}
+function parseDiscoverArguments(parsed) {
+    return {
+        action: 'discover',
+        seed: parsed.positionalValue('subject'),
+        output: parseOutput(parsed, COLLECTION_COMMAND_DEFINITIONS.discover),
+        ...discoveryValues(parsed),
+        snapshotSource: parsed.optionValue('--snapshot'),
+        ...terminalOptions(parsed),
+    };
+}
+function discoveryValues(parsed) {
+    const familyText = parsed.optionValue('--families');
+    return {
+        preset: (familyText
+            ? 'custom'
+            : (parsed.optionValue('--preset') ?? commandDefaultText('discover', '--preset'))),
+        keyboardLayout: (parsed.optionValue('--keyboard') ??
+            commandDefaultText('discover', '--keyboard')),
+        tldText: parsed.optionValue('--tlds'),
+        dictionarySource: parsed.optionValue('--dictionary'),
+        familyText,
+    };
+}
+function parseDiscoverScanArguments(parsed) {
+    const deep = parsed.hasOption('--deep');
+    const selectedFailPolicies = failPolicies(parsed, 'discover-scan');
+    const filter = parsed.hasOption('--registered-only')
+        ? 'registered'
+        : parsed.hasOption('--inconclusive-only')
+            ? 'inconclusive'
+            : parsed.hasOption('--acquisition-only')
+                ? 'acquisition'
+                : parsed.hasOption('--suppressed-only')
+                    ? 'suppressed'
+                    : 'all';
+    return {
+        action: 'discover-scan',
+        seed: parsed.positionalValue('subject'),
+        output: parseOutput(parsed, COLLECTION_COMMAND_DEFINITIONS['discover-scan']),
+        ...discoveryValues(parsed),
+        deep,
+        scanLimit: parsed.integerOption('--scan-limit') ??
+            commandDefaultNumber('discover-scan', '--scan-limit', deep),
+        chunkSize: parsed.integerOption('--chunk-size') ?? commandDefaultNumber('discover-scan', '--chunk-size'),
+        concurrency: parsed.integerOption('--concurrency') ??
+            commandDefaultNumber('discover-scan', '--concurrency', deep),
+        checkpoint: parsed.optionValue('--checkpoint'),
+        resume: parsed.hasOption('--resume'),
+        resolverText: parsed.optionValue('--resolver'),
+        observationSnapshot: parsed.optionValue('--observation-snapshot'),
+        allowlistSource: parsed.optionValue('--allowlist'),
+        filter,
+        events: parsed.hasOption('--events'),
+        plan: parsed.hasOption('--plan'),
+        ...terminalOptions(parsed),
+        ...(selectedFailPolicies ? { failOn: selectedFailPolicies } : {}),
+    };
+}
+export const COLLECTION_ARGUMENT_PARSERS = Object.freeze({
+    lookup: parseLookupArguments,
+    bulk: parseBulkArguments,
+    discover: parseDiscoverArguments,
+    'discover-scan': parseDiscoverScanArguments,
+});

package/cli/collection-command-definitions.mjs

@@ -0,0 +1,330 @@
+import { positional, OPTIONAL_FILE_POSITIONAL, OPTIONAL_TEXT_POSITIONAL, constraint, commandSeed, } from "./command-definition.mjs";
+import { bulkQueryLimit, bulkConcurrencyLimit } from "../lib/bulk-limits.mjs";
+const COLLECTION_CEILINGS = `${bulkQueryLimit('fast')} fast or ${bulkQueryLimit('deep')} deep`;
+const CONCURRENCY_CEILINGS = `${bulkConcurrencyLimit('fast')} fast or ${bulkConcurrencyLimit('deep')} deep`;
+export const COLLECTION_COMMAND_DEFINITIONS = Object.freeze({
+    lookup: commandSeed({
+        reference: {
+            description: 'Collect registration evidence for one domain, IP, or ASN.',
+            example: 'whoisleuth lookup example.test --deep --browse',
+            boundary: 'Fast is the default. An ICANN-recognised public domain, reserved documentation domain, IP, or ASN may occupy command position as shorthand; it delegates to this same parser and URL-like input requires the explicit lookup command. Deep mode adds bounded WHOIS, DNS, HTTP, TLS, technology, posture, and network context where applicable. --deep --exact-url explicitly sends the input URL path and query to the website, without its fragment; ordinary URL input sends only the hostname. --plan remains offline and omits the selected URL. Retained paths and page-derived text require review before sharing. A full Deep homepage observation can derive fixed publication and delivery/cache summaries from the same response without retaining raw metadata values or making another request. --browse opens before collection, shows aggregate Fast progress or independently settled planned Deep sources, and then navigates allowlisted retained fields in the completed document. Press ? for help and / to search rendered panel text only. Closing during collection cancels without a partial document. --save-lookup writes the exact completed private JSON only after a normal browser close; it can contain normalised evidence omitted from panels and refuses an existing path.',
+        },
+        collection: {
+            scope: 'Accepts one target. Fast is the default; deep collection must be selected explicitly.',
+        },
+        summary: 'Collect one domain, IP, or ASN',
+        options: [
+            '--json',
+            '--junit',
+            '--markdown',
+            '--html',
+            '--no-attribution',
+            '--fast',
+            '--deep',
+            '--exact-url',
+            '--observer',
+            '--vantage',
+            '--plan',
+            '--summary',
+            '--verbose',
+            '--browse',
+            '--save-lookup',
+            '--strict-exit',
+            '--fail-on',
+            '--events',
+            '--quiet',
+            '--no-color',
+        ],
+        positionals: Object.freeze([
+            positional('target', 'text', 0, 1, [], 'argv_or_stdin', ['--browse']),
+        ]),
+        constraints: Object.freeze([
+            constraint({
+                kind: 'mutually_exclusive',
+                options: ['--json', '--junit', '--markdown', '--html'],
+            }),
+            constraint({ kind: 'mutually_exclusive', options: ['--fast', '--deep'] }),
+            constraint({ kind: 'mutually_exclusive', options: ['--summary', '--verbose'] }),
+            constraint({ kind: 'requires_all', option: '--save-lookup', requiredOptions: ['--browse'] }),
+            constraint({ kind: 'requires_all', option: '--exact-url', requiredOptions: ['--deep'] }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--summary',
+                excludedOptions: ['--json', '--junit', '--markdown', '--html'],
+            }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--verbose',
+                excludedOptions: ['--json', '--junit', '--markdown', '--html'],
+            }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--browse',
+                excludedOptions: [
+                    '--json',
+                    '--junit',
+                    '--markdown',
+                    '--html',
+                    '--summary',
+                    '--verbose',
+                    '--events',
+                    '--plan',
+                    '--quiet',
+                ],
+            }),
+            constraint({
+                kind: 'requires_any',
+                option: '--no-attribution',
+                requiredOptions: ['--markdown', '--html'],
+            }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--plan',
+                excludedOptions: [
+                    '--junit',
+                    '--markdown',
+                    '--html',
+                    '--summary',
+                    '--verbose',
+                    '--strict-exit',
+                    '--events',
+                    '--quiet',
+                    '--fail-on',
+                ],
+            }),
+        ]),
+        handlerOwner: 'lookup',
+        networkEffect: 'conditional_network',
+        common: true,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.lookup', 'whoisleuth.cli.lookup-plan']),
+        primaryArtefacts: Object.freeze(['Source-qualified Lookup', 'Lookup request plan']),
+        planSupport: true,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    bulk: commandSeed({
+        reference: {
+            description: 'Triage newline-delimited domains, IPs, or ASNs with bounded concurrency.',
+            example: 'cat domains.txt | whoisleuth bulk --jsonl',
+            boundary: 'Fast and deep jobs use separate concurrency ceilings. Filters affect output only; collection failures and inconclusive authority states remain explicit in JSON, JSONL, and CSV. --csv-with-metadata adds source versions, separate observation and report times, collection origin and diagnostic states; --csv retains the compact columns.',
+        },
+        collection: {
+            scope: `Accepts at most ${COLLECTION_CEILINGS} targets, with concurrency capped at ${CONCURRENCY_CEILINGS}.`,
+        },
+        summary: 'Run bounded multi-target collection',
+        options: [
+            '--json',
+            '--jsonl',
+            '--junit',
+            '--csv',
+            '--csv-with-metadata',
+            '--domains',
+            '--queries',
+            '--registered-only',
+            '--inconclusive-only',
+            '--errors-only',
+            '--fast',
+            '--deep',
+            '--concurrency',
+            '--checkpoint',
+            '--resume',
+            '--events',
+            '--plan',
+            '--fail-on',
+            '--quiet',
+            '--no-color',
+        ],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({
+                kind: 'mutually_exclusive',
+                options: [
+                    '--json',
+                    '--jsonl',
+                    '--junit',
+                    '--csv',
+                    '--csv-with-metadata',
+                    '--domains',
+                    '--queries',
+                ],
+            }),
+            constraint({
+                kind: 'mutually_exclusive',
+                options: ['--registered-only', '--inconclusive-only', '--errors-only'],
+            }),
+            constraint({ kind: 'mutually_exclusive', options: ['--fast', '--deep'] }),
+            constraint({ kind: 'requires_all', option: '--resume', requiredOptions: ['--checkpoint'] }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--plan',
+                excludedOptions: [
+                    '--jsonl',
+                    '--junit',
+                    '--csv',
+                    '--csv-with-metadata',
+                    '--domains',
+                    '--queries',
+                    '--events',
+                    '--checkpoint',
+                    '--resume',
+                    '--quiet',
+                    '--fail-on',
+                ],
+            }),
+        ]),
+        handlerOwner: 'bulk',
+        networkEffect: 'conditional_network',
+        common: true,
+        schemaIdentifiers: Object.freeze([
+            'whoisleuth.cli.bulk',
+            'whoisleuth.cli.bulk.item',
+            'whoisleuth.cli.bulk-checkpoint',
+        ]),
+        primaryArtefacts: Object.freeze(['Bulk result', 'Bulk checkpoint']),
+        planSupport: true,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    discover: commandSeed({
+        reference: {
+            description: 'Generate bounded lookalike-domain candidates from a brand or registrable domain, including multi-part public suffixes.',
+            example: 'whoisleuth discover example.test --preset common --jsonl',
+            boundary: 'Generation and optional local snapshot comparison are offline. Candidates are leads only and are not resolved, registered, or classified as malicious.',
+        },
+        collection: {
+            scope: 'Generates a bounded candidate set from local rules, dictionaries, and optional saved snapshots.',
+        },
+        summary: 'Generate lookalike candidates offline',
+        options: [
+            '--tlds',
+            '--preset',
+            '--families',
+            '--keyboard',
+            '--dictionary',
+            '--snapshot',
+            '--json',
+            '--jsonl',
+            '--domains',
+            '--quiet',
+            '--no-color',
+        ],
+        positionals: OPTIONAL_TEXT_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({ kind: 'mutually_exclusive', options: ['--json', '--jsonl', '--domains'] }),
+            constraint({ kind: 'mutually_exclusive', options: ['--preset', '--families'] }),
+            constraint({
+                kind: 'value_excludes',
+                option: '--preset',
+                value: 'common',
+                excludedOptions: ['--dictionary'],
+            }),
+        ]),
+        handlerOwner: 'discovery',
+        networkEffect: 'offline',
+        common: true,
+        schemaIdentifiers: Object.freeze([
+            'whoisleuth.cli.discover',
+            'whoisleuth.cli.discover.item',
+            'whoisleuth.cli.discovery-snapshot',
+        ]),
+        primaryArtefacts: Object.freeze(['Candidate set', 'Discovery snapshot']),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    'discover-scan': commandSeed({
+        reference: {
+            description: 'Generate a bounded candidate set, collect a selected subset, and produce a supervised review queue.',
+            example: 'whoisleuth discover-scan example.test --scan-limit 50 --checkpoint scan.json --json',
+            boundary: `This command performs network collection. Fast compact lookup is the default; deep mode is capped at ${bulkQueryLimit('deep')} candidates. Allowlisting changes review priority only and shared infrastructure remains a lead, not attribution. --csv-with-metadata adds source versions, separate observation and report times, collection origin and diagnostic states; --csv retains the compact columns.`,
+        },
+        collection: {
+            scope: `Scans at most ${COLLECTION_CEILINGS} candidates, with concurrency capped at ${CONCURRENCY_CEILINGS}.`,
+        },
+        summary: 'Collect a supervised candidate review queue',
+        options: [
+            '--tlds',
+            '--preset',
+            '--families',
+            '--keyboard',
+            '--dictionary',
+            '--fast',
+            '--deep',
+            '--scan-limit',
+            '--chunk-size',
+            '--concurrency',
+            '--resolver',
+            '--allowlist',
+            '--checkpoint',
+            '--resume',
+            '--observation-snapshot',
+            '--registered-only',
+            '--inconclusive-only',
+            '--acquisition-only',
+            '--suppressed-only',
+            '--events',
+            '--plan',
+            '--fail-on',
+            '--json',
+            '--jsonl',
+            '--csv',
+            '--csv-with-metadata',
+            '--domains',
+            '--quiet',
+            '--no-color',
+        ],
+        positionals: OPTIONAL_TEXT_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({
+                kind: 'mutually_exclusive',
+                options: ['--json', '--jsonl', '--csv', '--csv-with-metadata', '--domains'],
+            }),
+            constraint({ kind: 'mutually_exclusive', options: ['--preset', '--families'] }),
+            constraint({ kind: 'mutually_exclusive', options: ['--fast', '--deep'] }),
+            constraint({
+                kind: 'mutually_exclusive',
+                options: [
+                    '--registered-only',
+                    '--inconclusive-only',
+                    '--acquisition-only',
+                    '--suppressed-only',
+                ],
+            }),
+            constraint({ kind: 'requires_all', option: '--resume', requiredOptions: ['--checkpoint'] }),
+            constraint({
+                kind: 'value_excludes',
+                option: '--preset',
+                value: 'common',
+                excludedOptions: ['--dictionary'],
+            }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--plan',
+                excludedOptions: [
+                    '--jsonl',
+                    '--csv',
+                    '--csv-with-metadata',
+                    '--domains',
+                    '--events',
+                    '--checkpoint',
+                    '--resume',
+                    '--observation-snapshot',
+                    '--quiet',
+                    '--fail-on',
+                ],
+            }),
+        ]),
+        handlerOwner: 'discovery_scan',
+        networkEffect: 'conditional_network',
+        common: true,
+        schemaIdentifiers: Object.freeze([
+            'whoisleuth.cli.discovery-scan',
+            'whoisleuth.cli.discovery-scan.item',
+            'whoisleuth.cli.discovery-observation-snapshot',
+        ]),
+        primaryArtefacts: Object.freeze(['Reviewed candidate queue', 'Observation snapshot']),
+        planSupport: true,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+});

package/cli/collection-preflight.mjs

@@ -1,3 +1,4 @@
+import { bulkQueryLimit } from "../lib/bulk-limits.mjs";
 export const CLI_COLLECTION_PREFLIGHT_SCHEMA = 'whoisleuth.cli.collection-preflight';
 export const CLI_COLLECTION_PREFLIGHT_VERSION = 1;
 export function buildCollectionPreflight(options) {
@@ -12,7 +13,7 @@ export function buildCollectionPreflight(options) {
         networkRequestsMade: false,
         scope: Object.freeze({
             selectedTargets: options.targetCount,
-            commandTargetLimit: options.targetLimit,
+            commandTargetLimit: bulkQueryLimit(options.deep ? 'deep' : 'fast'),
             concurrency: options.concurrency,
             sourceFamilies: Object.freeze(sourceFamilies),
             exactRequestCountKnown: false,
@@ -53,6 +54,12 @@ export function formatCollectionPreflight(document) {
         ...document.scope.sourceFamilies.map((source) => `  ${source}`),
         '',
         ...document.disclosure.map((item) => `Disclosure: ${item}`),
+        '',
+        `Output format: ${document.persistence.output}`,
+        `Checkpoint: ${document.persistence.checkpoint ? 'enabled' : 'not written'}. ${document.persistence.note}`,
+        ...(document.review.allowlistAffectsPriorityOnly ? ['Allowlist: affects review priority only; it does not exclude targets from collection.'] : []),
+        'Enforcement: none. This plan does not report, block or remove a target.',
+        '',
         ...document.limitations.map((item) => `Limitation: ${item}`),
         '',
     ].join('\n');