GraphQL内省禁用与白名单治理最佳实践

---

title: GraphQL内省禁用与白名单治理最佳实践

keywords:

• Introspection
• 白名单
• 内省禁用
• 受控头
• 查询校验

description: 通过禁用内省与白名单治理、受控头校验与查询检查，阻断模式泄露与恶意探测，提升GraphQL接口安全性。

categories:

• 文章资讯
• 技术教程

---

背景与价值

内省泄露Schema信息，易被恶意利用。禁用内省并采用白名单治理，可减少攻击面。

统一规范

• 受控头：仅在受控环境与受控头下启用内省（默认禁用）。
• 白名单：只允许注册查询哈希或名称执行。
• 检查与拒绝：命中 __schema/__type 的查询默认拒绝。

核心实现

受控头与查询检查

type Req = { headers: Record<string, string | undefined>; body: { query?: string; operationName?: string; hash?: string } }

function introspectionAllowed(req: Req): boolean { return (req.headers['x-allow-introspection'] || '') === 'true' }

function containsIntrospection(q: string): boolean { return /__schema|__type/.test(q) }

const allowOps = new Set(['GetUser','ListPosts'])
const allowHashes = new Set<string>([])

function whitelistOk(req: Req): boolean {
  if (req.body.hash) return allowHashes.has(req.body.hash)
  if (req.body.operationName) return allowOps.has(req.body.operationName)
  return false
}

function gate(req: Req): boolean {
  const q = String(req.body.query || '')
  if (containsIntrospection(q) && !introspectionAllowed(req)) return false
  return whitelistOk(req)
}

落地建议

• 默认禁用内省，仅在受控环境开启；同时采用持久化查询或名称白名单执行。
• 对命中内省的请求进行拒绝并记录审计事件。

验证清单

• 是否禁用内省且仅在受控头下开启；白名单是否生效；拒绝事件是否审计。