Controlling Schema Exposure

Introspection as Reconnaissance

Introspection is a feature you ship to attackers for free. One query returns the whole type graph:

{
  __schema {
    queryType { name }
    types {
      name
      fields {
        name
        args { name type { name } }
      }
    }
  }
}

What that hands over:

None of this is a vulnerability on its own — it is reconnaissance that shortens everything after it. The same machinery powers GraphiQL, code generation, and schema-aware linting, which is why the answer is rarely "delete introspection everywhere." The pragmatic split: enabled in development and staging where tooling lives, restricted in production where the schema is already published to your own clients through documentation.

From map to exploit

The map compresses everything that follows it into minutes:

1. Choose targets. Filter the field list for admin, internal, impersonate, export — names no user interface will ever offer.
2. Learn the shape. Argument types and nullability show which inputs are required and whether a field can return partial data, so the first crafted request is valid instead of one of twenty guesses.
3. Check the defenses. Seeing @hasRole on a field confirms the defenders considered it sensitive, which makes it a more interesting target, not a safer one.

Without the map an attacker does the same work by guessing against validation errors — slower, and noisy in your logs. That asymmetry, minutes versus hours, is the actual trade: production introspection control raises the cost of reconnaissance while staging keeps it open for GraphiQL, code generation, and schema-aware linting.

Check what your gateway exposes too: introspection may be disabled on the API server while an analytics subgraph or a public explorer endpoint still answers __schema. For the mechanics of the query itself, see introspection mechanics.

Turning Off the Map Without Fooling Yourself

The standard control is a validation rule that rejects introspection documents before execution:

const { specifiedRules, NoSchemaIntrospectionCustomRule } = require('graphql');

const server = new ApolloServer({
  schema,
  validationRules: [
    ...specifiedRules,
    ...(process.env.NODE_ENV === 'production'
      ? [NoSchemaIntrospectionCustomRule]
      : []),
  ],
});

Running it as a validation rule means the document fails before a single resolver executes, and gating it on environment keeps GraphiQL and codegen working against non-production endpoints.

Now the part teams skip. Disabling introspection is not authorization. It removes free documentation; it does not remove anything else:

1. Queries still execute. An attacker who guesses { admin { secrets } } gets an answer if the field exists and has no check. Field-level authorization is a separate control — see role-based field access.
2. Validation errors still describe your schema. With introspection off, Cannot query field "invoices" on type "Query" still confirms or denies the existence of a field, and a well-formed error naming the containing type leaks structure. Do not treat "unknown field" errors as harmless noise in your logs; they are a probing signal worth rate-limiting.
3. The schema is probably already public. Type names live in your client bundle, your error messages, your docs, and your git history.

Treat it as one layer in a stack: hide the map, authorize every field, watch for probing patterns, and bound what a document may ask for. Controls stack honestly only when each one is honest about what it stops — query depth limits bound shape, authorization bounds identity, and introspection control bounds convenience for the attacker.

Allowlists, Depth Rules, and Edge Controls

Once the schema is not the contract, the documents can be. A persisted-query allowlist accepts only pre-registered operations, which shrinks the attack surface to behavior you have reviewed:

// manifest.json: sha256 -> operation, shipped with each client release
const { createHash } = require('crypto');

function isAllowed(document) {
  const hash = createHash('sha256').update(document, 'utf8').digest('hex');
  return allowlist.has(hash);            // unknown hash -> reject before parsing
}

Know which variant you are buying:

APQ with an open fallback is a cache, not a control; the allowlist is the security property. Ship the manifest with the client, fail closed on unknown hashes, and keep a server-side path for operations your own tooling needs.

Depth and cost rules bound the shape of whatever documents are allowed — a depth cap stops recursive relationship crawls, a cost budget prices aliases and list arguments. See cost analysis budgets for pricing a document. Then push checks to where they are cheapest: an edge or WAF layer can reject oversized bodies, deep documents, and probing patterns before origin compute is spent, while rate limits absorb volume.

Ordering matters when you assemble these: reject at the edge (shape, allowlist, rate), validate at the server (schema rules, depth, introspection), authorize at the field (roles and tenant scope). Each layer assumes the one above may have been bypassed — which is the honest way to stack controls.