Query configuration

The queryConfig object is an optional, top-level field in your meshConfig that lets you harden your mesh against oversized, abusive, or schema-probing GraphQL queries. It exposes a set of controls that protect both the mesh and your backend sources from common GraphQL attack patterns.

All protections are disabled by default. Each protection must be explicitly turned on by setting enabled: true. When a protection is enabled but its specific limit value is omitted, the graphql-armor default is used.

Configuration

Add queryConfig as a sibling of sources in your meshConfig:

{
  "meshConfig": {
    "disableIntrospection":true,
    "sources": [
      {
        "name": "Commerce",
        "handler": {
          "graphql": {
            "endpoint": "https://your-store.example.com/graphql"
          }
        }
      }
    ],
    "queryConfig": {
      "blockFieldSuggestion": { "enabled": true },
      "costLimit":            { "enabled": true, "maxCost": 5000 },
      "maskErrors":           { "enabled": true, "message": "Unexpected error." },
      "maxAliases":           { "enabled": true, "limit": 15 },
      "maxDepth":             { "enabled": true, "limit": 6 },
      "maxDirectives":        { "enabled": true, "limit": 50 },
      "maxTokens":            { "enabled": true, "limit": 1000 }
    }
  }
}

You can enable any combination of these protections. Any configurations that are not included in the queryConfig object are not applied.

data-variant=help

data-slots=text

queryConfig properties

The following sections describe each queryConfig property and its values.

blockFieldSuggestion

Suppresses the Did you mean "<field name>"? hints that GraphQL adds to error responses when a field name is misspelled. Removing these hints prevents an attacker from enumerating your schema by sending intentionally invalid queries.

blockFieldSuggestion disabled:

{
  "errors": [
    { "message": "Cannot query field \"productz\" on type \"Query\". Did you mean \"products\"?" }
  ]
}

blockFieldSuggestion enabled:

{
  "errors": [
    { "message": "Cannot query field \"productz\" on type \"Query\"." }
  ]
}

costLimit

Rejects queries with a computed cost that exceeds the configured maximum. Cost accounts for fields, depth, and complexity, providing a more nuanced limit than depth or token counts alone.

data-variant=info

data-slots=text

maskErrors

Replaces unintentional resolver errors with a generic message so that internal error details, such as stack traces or backend information, are not leaked to clients.

Errors that explicitly set extensions.code (intentional, structured errors thrown by your resolvers or sources) are passed through unchanged. Only unintentional errors are masked.

maxAliases

Limits the number of aliases that a single query can use. Use this to prevent alias-based amplification attacks, where the same expensive field is requested many times under different aliases.

maxDepth

Limits the maximum nesting depth of incoming queries. Use this to block deeply nested queries that can amplify load on your sources.

data-variant=info

data-slots=text

maxDirectives

Limits the number of directives a single query can apply. Use this to prevent abusive use of directives such as @include or @skip.

maxTokens

Limits the total number of GraphQL tokens parsed per query. Use this to reject overly large query documents.

data-variant=info

data-slots=text