Typosquat / Brand-Protection Variants

Instructions

Implementation Reference

• src/tools/indicator-tools.ts:119-177 (handler)

  The domainVariants() method on IndicatorTools class. Validates the variant name and label patterns, then calls `CALL whisper.variants($name, $label, $checkExisting)` via the GraphBackend. Truncates results at MAX_VARIANT_ROWS (500). On failure, returns a structured error row.

  async domainVariants(
    name: string | null | undefined,
    label: string | null | undefined,
    includeNonExistent: boolean,
    credential: Credential | null,
  ): Promise<{ rows: Row[] }> {
    if (!isValidVariantName(name)) {
      return {
        rows: [
          {
            name: name ?? "",
            available: false,
            error: "invalid_name",
            explanation:
              "Name must be a domain or hostname. Allowed characters: letters " +
              "(including Unicode, for homoglyph detection), digits, '.', '-', '_'.",
          },
        ],
      };
    }
  
    const resolvedLabel =
      label == null || label.trim() === "" ? "HOSTNAME" : label.trim().toUpperCase();
    if (!LABEL_PATTERN.test(resolvedLabel)) {
      return {
        rows: [
          {
            name,
            available: false,
            error: "invalid_label",
            explanation:
              "Label must be uppercase letters and underscores only (e.g. HOSTNAME, MAIL_SERVER).",
          },
        ],
      };
    }
  
    try {
      const raw = await this.backend.execute(
        "CALL whisper.variants($name, $label, $checkExisting)",
        { name, label: resolvedLabel, checkExisting: !includeNonExistent },
        credential,
      );
      const rows = raw.rows ?? [];
      return { rows: rows.length > MAX_VARIANT_ROWS ? rows.slice(0, MAX_VARIANT_ROWS) : rows };
    } catch (error) {
      log.warn(`domain_variants failed for "${name}": ${describeError(error)}`);
      return {
        rows: [
          {
            name,
            available: false,
            error: "lookup_failed",
            explanation: "Variant generation is temporarily unavailable. Try again in a moment.",
          },
        ],
      };
    }
  }

• src/server.ts:206-241 (registration)

  Registration of the 'domain_variants' tool on the MCP server via server.registerTool(). Defines inputSchema with Zod for 'name' (required string), 'label' (optional string default HOSTNAME), and 'includeNonExistent' (optional boolean default false). Output is an array of rows. The handler calls indicatorTools.domainVariants() with the extracted args.

  server.registerTool(
    "domain_variants",
    {
      title: "Typosquat / Brand-Protection Variants",
      description: DOMAIN_VARIANTS_DESCRIPTION,
      inputSchema: {
        name: z
          .string()
          .describe(
            'Domain or brand to generate variants for. Examples: "google.com", "paypal.com". Unicode allowed.',
          ),
        label: z
          .string()
          .optional()
          .describe("Optional node label to check existence against. Default: HOSTNAME."),
        includeNonExistent: z
          .boolean()
          .optional()
          .describe(
            "Optional. When true, also return generated variants that do not exist in the graph. Default: false.",
          ),
      },
      outputSchema: { rows: z.array(rowSchema) },
      annotations: READ_ONLY_ANNOTATIONS,
    },
    async (args, extra) => {
      const credential = resolveCredential(extra.requestInfo?.headers, config.apiKey);
      const result = await indicatorTools.domainVariants(
        args.name,
        args.label,
        args.includeNonExistent ?? false,
        credential,
      );
      return toolResult(result);
    },
  );

• src/tools/descriptions.ts:76-87 (helper)

  DOMAIN_VARIANTS_DESCRIPTION constant providing the full documentation for the tool. Describes the 14 mutation algorithms, return shape (variant, method, exists, nodeId, label, confidence, confidenceLabel), and argument details.

  export const DOMAIN_VARIANTS_DESCRIPTION = `Generate typosquatting / brand-protection variants of a domain or brand name and check which ones actually exist in WhisperGraph.
  
  Runs 14 mutation algorithms — character omission, repetition, transposition, QWERTY-adjacent replacement/insertion, vowel-swap, bitsquatting, homoglyph / Unicode confusables, hyphenation, dot insertion/omission, TLD-swap, TLD-addition, and subdomain-add. Unicode input is accepted (and expected) so IDN homoglyph lookalikes resolve correctly.
  
  Returns { rows: [...] }. Each row: { variant, method, exists, nodeId, label, confidence (0.3-0.9), confidenceLabel (low/medium/high) }. By default only variants that EXIST as nodes are returned — the registered lookalikes worth investigating. Note that "exists" means registered/observed, NOT malicious: pivot each hit through explain_indicator for a threat verdict.
  
  Arguments:
    - name (string, required) — the domain or brand to mutate, e.g. "google.com". Allowed characters: letters (including Unicode), digits, '.', '-', '_'.
    - label (string, optional, default HOSTNAME) — node label to check existence against.
    - includeNonExistent (boolean, optional, default false) — when true, also return generated variants that do NOT exist in the graph (larger, noisier result set).
  
  Performance: typically <150ms. Results are capped at 500 rows.`;

• src/tools/indicator-tools.ts:31-33 (helper)

  The isValidVariantName() helper function that validates the variant name using VARIANT_NAME_PATTERN (Unicode letters, digits, dot, dash, underscore, 1-255 chars). Used by domainVariants() to reject invalid input before making the backend call.

  function isValidVariantName(name: string | null | undefined): name is string {
    return name != null && VARIANT_NAME_PATTERN.test(name);
  }

• src/tools/indicator-tools.ts:14-25 (helper)

  Constants used by domainVariants: VARIANT_NAME_PATTERN (Unicode-enabled regex for domain names), LABEL_PATTERN (uppercase letters/underscores for labels), and MAX_VARIANT_ROWS (500 cap on results).

  /**
   * Variant-name whitelist for `whisper.variants()`. Admits Unicode letters and
   * digits — homoglyph / IDN detection feeds on confusable scripts — while still
   * excluding Cypher-special characters. Capped at a domain name's RFC limit.
   */
  const VARIANT_NAME_PATTERN = /^[\p{L}\p{N}._-]{1,255}$/u;
  
  /** Node label names: uppercase ASCII letters and underscores. */
  const LABEL_PATTERN = /^[A-Z_]{1,40}$/;
  
  /** Hard cap on variant rows returned — mirrors the validator's LIMIT ceiling. */
  const MAX_VARIANT_ROWS = 500;