WhisperGraph Cypher Query

Instructions

Implementation Reference

• src/tools/query-tool.ts:20-62 (handler)

  QueryTool class — the core handler for the 'query' tool. Its run() method validates Cypher via CypherQueryValidator, executes it against the backend, and classifies errors.

  export class QueryTool {
    constructor(
      private readonly backend: GraphBackend,
      private readonly validator: CypherQueryValidator,
      private readonly queryTimeoutMs: number,
    ) {}
  
    async run(cypher: string, credential: Credential | null): Promise<QueryResult> {
      const validation = this.validator.validate(cypher);
      if (!validation.valid) {
        return QueryResultFactory.error(
          validation.errorMessage,
          validation.suggestion,
          "VALIDATION_REJECTED",
          false,
        );
      }
  
      try {
        const raw = await this.backend.execute(cypher, undefined, credential);
        return transformRawResponse(raw);
      } catch (error) {
        if (error instanceof CypherExecutionException) {
          const classification = classifyExecutionError(error.message, this.queryTimeoutMs);
          return QueryResultFactory.error(
            error.message,
            classification.suggestion,
            classification.errorCode,
            classification.retryable,
          );
        }
        if (error instanceof WhisperDbException) {
          return QueryResultFactory.error(
            "Database temporarily unavailable",
            "Try again in a few seconds. If the problem persists, the database may be under maintenance.",
            "DB_UNAVAILABLE",
            true,
          );
        }
        throw error;
      }
    }
  }

• src/server.ts:57-66 (schema)

  queryOutputShape — defines the output schema for the 'query' tool (success, columns, rows, statistics, error, suggestion, errorCode, retryable).

  const queryOutputShape = {
    success: z.boolean(),
    columns: z.array(z.string()),
    rows: z.array(rowSchema),
    statistics: z.object({ rowCount: z.number(), executionTimeMs: z.number() }).optional(),
    error: z.string().optional(),
    suggestion: z.string().optional(),
    errorCode: z.string().optional(),
    retryable: z.boolean().optional(),
  };

• src/server.ts:101-122 (registration)

  Registration of the 'query' tool on the MCP server via server.registerTool('query', ...), including input schema (cypher string), output schema, and the async handler that calls queryTool.run().

  server.registerTool(
    "query",
    {
      title: "WhisperGraph Cypher Query",
      description: QUERY_TOOL_DESCRIPTION,
      inputSchema: {
        cypher: z
          .string()
          .describe(
            "Cypher query string. Must include LIMIT for exploration queries. " +
              'Use {name: "value"} property syntax for lookups.',
          ),
      },
      outputSchema: queryOutputShape,
      annotations: { ...READ_ONLY_ANNOTATIONS, openWorldHint: true },
    },
    async (args, extra) => {
      const credential = resolveCredential(extra.requestInfo?.headers, config.apiKey);
      const result = await queryTool.run(args.cypher, credential);
      return toolResult(result, !result.success);
    },
  );

• src/query/cypher-query-validator.ts:20-56 (helper)

  CypherQueryValidator — validates Cypher queries against safety rules (shortestPath, limit exceeded, unlabeled match, etc.) before execution.

  export class CypherQueryValidator {
    private readonly rules: readonly QueryValidationRule[];
  
    constructor(rules: readonly QueryValidationRule[] = DEFAULT_RULES) {
      this.rules = rules;
    }
  
    validate(cypher: string | null | undefined): ValidationResult {
      if (cypher == null || cypher.trim() === "") {
        return ValidationResult.invalid("Query is empty.", "Provide a valid Cypher query.");
      }
  
      const normalized = cypher.trim();
  
      if (normalized.toUpperCase().startsWith("EXPLAIN")) {
        return ValidationResult.ok();
      }
  
      const stripped = stripStringLiterals(normalized);
  
      for (const rule of this.rules) {
        const result = rule.validate(normalized, stripped);
        if (!result.valid) {
          if (result.ruleName === undefined) {
            return ValidationResult.invalid(result.errorMessage, result.suggestion, rule.name);
          }
          return result;
        }
      }
  
      return ValidationResult.ok();
    }
  
    getRules(): readonly QueryValidationRule[] {
      return this.rules;
    }
  }

• src/tools/descriptions.ts:1-37 (helper)

  QUERY_TOOL_DESCRIPTION — the natural-language description of the query tool (schema, labels, edges, traversal chains, rules, examples).

  export const QUERY_TOOL_DESCRIPTION = `Execute a Cypher query against WhisperGraph — the internet's largest infrastructure graph database (7.39B nodes, 39B edges, 5.6M threat intel edges). Returns JSON with columns, rows, and statistics.
  
  Use this tool for any question involving domains, hostnames, IPs, DNS, BGP, GeoIP, web links, email infrastructure, WHOIS, DNSSEC, or threat intelligence.
  
  NODE LABELS (20): HOSTNAME (2.6B), IPV4 (619M), IPV6 (820K), PREFIX (2.5M), ASN (116K), ASN_NAME (108K), ORGANIZATION (119M), CITY (54K), TLD (1.7K), COUNTRY (424), RIR (5), DNSSEC_ALGORITHM (8), TLD_OPERATOR (737), REGISTRAR (51K), EMAIL (237M), PHONE (60M), REGISTERED_PREFIX (326K, virtual), ANNOUNCED_PREFIX (1.4M, virtual), FEED_SOURCE (40, virtual), CATEGORY (18, virtual). All nodes have a "name" property. Threat-listed IPV4/IPV6/HOSTNAME nodes also carry: threatScore (Double), threatLevel (NONE/INFO/LOW/MEDIUM/HIGH/CRITICAL), threatSources, threatFirstSeen/threatLastSeen (epoch ms), and 13 boolean flags: isThreat, isAnonymizer, isC2, isMalware, isPhishing, isSpam, isBruteforce, isScanner, isBlacklist, isTor, isProxy, isVpn, isWhitelist. ANNOUNCED_PREFIX adds BGP-enrichment: isMoas, isAnycast, isWithdrawn, wasMoas, hasOriginChanged, threatScore, threatLevel, threatSourceCount, firstSeen, lastSeen. LISTED_IN edges carry firstSeen, lastSeen, weight.
  
  KEY EDGES: RESOLVES_TO (HOSTNAME→IPV4/IPV6, forward only), CHILD_OF (child→parent: HOSTNAME→HOSTNAME→TLD), ALIAS_OF (CNAME), NAMESERVER_FOR / MAIL_FOR (NS/MX → domain — to list a domain's MX use (domain)<-[:MAIL_FOR]-(mx)), SPF_INCLUDE/SPF_IP/SPF_A/SPF_MX/SPF_EXISTS/SPF_REDIRECT (SPF policy; SPF_IP targets IPV4|IPV6|PREFIX), LINKS_TO (web hyperlinks, 10.8B), BELONGS_TO (3 semantics: IPV4/IPV6→PREFIX, PREFIX→RIR, FEED_SOURCE→CATEGORY), LOCATED_IN (IPV4/IPV6→CITY only — for country, chain through HAS_COUNTRY), HAS_COUNTRY (ASN/CITY/IPV4/HOSTNAME/PHONE/ANNOUNCED_PREFIX/REGISTERED_PREFIX→COUNTRY), ANNOUNCED_BY (IPV4/IPV6→ANNOUNCED_PREFIX, then ROUTES→ASN), ROUTES (ASN/ANNOUNCED_PREFIX→PREFIX/ASN, virtual), PEERS_WITH (ASN↔ASN, bidirectional, virtual), HAS_NAME (ASN→ASN_NAME, virtual; asn.name is the AS number — the network name lives on the ASN_NAME node), REGISTERED_BY (HOSTNAME/ASN/PREFIX→ORGANIZATION), HAS_REGISTRAR / PREV_REGISTRAR / HAS_EMAIL / HAS_PHONE (WHOIS), LISTED_IN (indicator→feed; threat intel for IPV4/IPV6/HOSTNAME), CONFLICTS_WITH (PREFIX/ANNOUNCED_PREFIX↔ASN, MOAS, bidirectional), OPERATES (TLD_OPERATOR→TLD).
  
  TRAVERSAL CHAINS:
  DNS: HOSTNAME→RESOLVES_TO→IPV4→BELONGS_TO→PREFIX←ROUTES←ASN→HAS_NAME→ASN_NAME
  BGP-direct: IPV4→ANNOUNCED_BY→ANNOUNCED_PREFIX→ROUTES→ASN
  GeoIP: HOSTNAME→RESOLVES_TO→IPV4→LOCATED_IN→CITY→HAS_COUNTRY→COUNTRY
  WHOIS: HOSTNAME→HAS_REGISTRAR→REGISTRAR, HOSTNAME→HAS_EMAIL→EMAIL
  Threat: IPV4/HOSTNAME→LISTED_IN→FEED_SOURCE→BELONGS_TO→CATEGORY
  
  RULES:
  - Use {name: "value"} or WHERE n.name = "value" for lookups — both indexed
  - Always include LIMIT on exploration queries (max 500)
  - shortestPath requires bounded depth: [*1..6]
  - Never scan FEED_SOURCE or CATEGORY directly — access via LISTED_IN from anchored nodes
  - STARTS WITH, ENDS WITH ".x", CONTAINS on .name are all indexed and fast
  - SIGNED_WITH currently returns 0 rows on live data (DNSSEC layer empty)
  
  PROCEDURES: CALL explain("indicator") for threat assessment, CALL whisper.history("indicator") for historical WHOIS/BGP data, CALL whisper.variants("name") for typosquatting / brand-protection variant generation, CALL whisper.quota() for rate limits, CALL db.labels() / db.relationshipTypes() / db.schema("json") for schema introspection.
  
  EXAMPLES:
  MATCH (h:HOSTNAME {name: "www.google.com"})-[:RESOLVES_TO]->(ip:IPV4) RETURN h.name, ip.name
  MATCH (ip:IPV4 {name: "8.8.8.8"})<-[:RESOLVES_TO]-(h:HOSTNAME) RETURN h.name LIMIT 20
  MATCH (h:HOSTNAME {name: "google.com"})-[:RESOLVES_TO]->(ip:IPV4)-[:LOCATED_IN]->(c:CITY) RETURN ip.name, c.name
  MATCH (a:ASN {name: "AS15169"})-[:HAS_NAME]->(n:ASN_NAME) RETURN n.name
  MATCH (h:HOSTNAME) WHERE h.name ENDS WITH ".google.com" RETURN h.name LIMIT 20
  MATCH (ip:IPV4 {name: "185.220.101.1"})-[:LISTED_IN]->(f:FEED_SOURCE) RETURN f.name, ip.threatScore
  
  DOCUMENTATION:
  API reference: https://www.whisper.security/docs/cypher-api-reference
  Cypher query guide: https://www.whisper.security/docs/cypher-query-guide
  Cypher functions: https://www.whisper.security/docs/cypher-functions`;