GraphQL introspection по умолчанию включена во многих реализациях API. Это позволяет клиенту запрашивать полную схему данных через специальный запрос __typename или директиву @introspection. Если защита не настроена, злоумышленник может получить детальную карту вашей базы данных, логику бизнес-процессов и имена внутренних таблиц. В зависимости от среды развертывания (облако, VPS, контейнеры) подход к защите меняется: в публичных API отключение обязательно, во внутренних — ограничивается доступом по ролям.
Защита GraphQL introspection: базовые принципы и риски
По умолчанию GraphQL-серверы (например, Apollo Server, Express-graphql) разрешают запросы на получение схемы. Это удобно для разработки, но опасно в продакшене. Атакующий может отправить запрос типа { __schema { queryType { fields { name } } } }, чтобы узнать структуру API.
Риски включают утечку имен полей, типов данных и связей между сущностями. Зная схему, хакер строит более точные SQL-инъекции или XSS-атаки через поля, которые он считает безопасными, но на самом деле уязвимыми.
В среде развертывания облачных провайдеров (AWS, GCP) часто используются WAF (Web Application Firewall). Они могут блокировать подозрительные запросы по сигнатуре. Однако полагаться только на WAF недостаточно: нужно отключать introspection на уровне приложения или ограничивать доступ к нему через аутентификацию.
В локальных средах (Docker, Kubernetes) защита строится на сетевых политиках (NetworkPolicies), которые запрещают доступ извне к порту GraphQL-сервера, если он не является публичным API.
Методы отключения introspection в популярных фреймворках
Для Apollo Server (Node.js) используется флаг disableIntrospection. В версии 3.x и выше это делается через опцию schemaOptions: { disableIntrospection: true }. Важно проверить версию пакета, так как в старых версиях этот параметр мог называться иначе или отсутствовать.
В Express-graphql настройка происходит при создании сервера. Параметр enableIntrospection по умолчанию равен true. Нужно явно установить его в false: const server = new GraphQLServer({ schema, enableIntrospection: false }).
Для Hasura (GraphQL на базе PostgreSQL) отключение introspection не поддерживается напрямую в ядре, но можно реализовать обход через кастомные правила доступа или использование плагинов аутентификации, которые блокируют запросы без токена.
В Python (Ariadne, Strawberry) аналогично: нужно явно отключить introspection в конфигурации схемы. Например, в Ariadne используется опция disable_introspection=True при создании ApolloServer.
Если вы используете GraphQL-серверы на основе Go или Rust, проверьте документацию конкретного пакета. Часто там есть флаг —no-introspection или аналогичный параметр командной строки.
Интеграция с WAF и сетевыми правилами для блокировки запросов на рефлексии
WAF (например, Cloudflare, AWS WAF) могут блокировать запросы, содержащие ключевые слова __schema или __typename. Настройте правила для фильтрации таких строк в заголовках или теле запроса.
В среде Kubernetes используйте NetworkPolicy для ограничения доступа к GraphQL-серверу только из доверенных подов (например, frontend-приложений). Это предотвращает доступ извне даже если introspection не отключена на уровне приложения.
Для облачных провайдеров настройте группы безопасности (Security Groups), которые разрешают трафик только с IP-адресов администраторов или корпоративной сети. Остальные запросы будут отклоняться на сетевом уровне.
В локальных средах используйте фаерволы (iptables, firewalld) для блокирования портов GraphQL-сервера из внешних сетей. Это снижает нагрузку на приложение и ускоряет обработку запросов.
Использование аутентификации как барьера перед доступом к схеме
Настройте обязательную аутентификацию для всех запросов к GraphQL-серверу. Используйте JWT, OAuth2 или другие механизмы. Если у пользователя нет токена, сервер должен возвращать ошибку 401 вместо схемы.
В Apollo Server добавьте middleware для проверки токена перед обработкой запроса. Если токен отсутствует или недействителен, завершите обработку и верните ошибку.
Для внутренних API используйте ролевую модель доступа (RBAC). Разрешите доступ к схеме только пользователям с ролью admin или developer. Обычные пользователи должны видеть только свои данные.
В среде развертывания облачных провайдеров интегрируйте аутентификацию через сервисы идентификации (например, Auth0, Okta). Это упрощает управление доступом и снижает риск утечки данных.
Настройка лимитов (rate limiting) для предотвращения DoS через introspection
Запросы на получение схемы могут быть ресурсоемкими. Если злоумышленник будет отправлять много таких запросов, это может привести к отказу в обслуживании (DoS). Настройте лимиты на количество запросов за единицу времени.
В Express-graphql используйте middleware rate-limit для ограничения количества запросов от одного IP. Например, разрешите максимум 10 запросов в минуту с одного адреса.
Для Apollo Server настройте плагин rateLimiting или используйте внешние сервисы (например, Redis) для отслеживания частоты запросов.
В среде развертывания облачных провайдеров используйте встроенные функции WAF для ограничения количества запросов. Это снижает нагрузку на приложение и предотвращает перегрузку сервера.
Мониторинг и логирование попыток доступа к схеме
Включите детальное логирование всех запросов к GraphQL-серверу. Записывайте IP-адрес клиента, тип запроса, время обработки и результат. Это поможет выявить подозрительную активность.
Используйте системы мониторинга (например, Prometheus, Grafana) для отслеживания количества запросов на получение схемы. Резкий рост таких запросов может указывать на атаку.
Настройте алерты в системах мониторинга. Если количество запросов на introspection превышает порог, отправьте уведомление администратору безопасности.
В среде развертывания облачных провайдеров используйте встроенные инструменты логирования (например, CloudWatch Logs). Это упрощает анализ событий и выявление аномалий.
Ошибки при защите: когда отключение не работает или блокирует легитимный трафик
Если вы отключили introspection, но клиенты все еще получают схему, проверьте кэширование. Некоторые серверы могут кэшировать результат запроса на получение схемы и возвращать его повторно. Очистите кэш или настройте политику инвалидации.
При использовании WAF убедитесь, что правила фильтрации не блокируют легитимные запросы от разработчиков или тестовых инструментов. Используйте исключения для доверенных IP-адресов.
Если вы используете ролевую модель доступа, проверьте права пользователей. Возможно, некоторые роли имеют доступ к схеме, хотя этого не должно быть. Пересмотрите настройки RBAC.
В среде развертывания облачных провайдеров убедитесь, что сетевые правила (NetworkPolicies) не разрешают доступ из внутренних подов, которые не должны иметь права на чтение схемы.
Проверка конфигурации на тестовом окружении перед продакшеном
Перед развертыванием в продакшен протестируйте настройки защиты на тестовом сервере. Отправьте запросы на получение схемы и убедитесь, что они возвращают ошибку 401 или 403.
Используйте инструменты автоматизированного тестирования (например, Postman, curl) для проверки работы лимитов и правил WAF. Это поможет выявить ошибки до запуска в продакшене.
В среде развертывания облачных провайдеров используйте функции sandbox или staging-окружения для тестирования новых конфигураций безопасности.
Документируйте все изменения в конфигурации безопасности. Это упростит поддержку и аудит системы в будущем.
Вопросы и ответы
Можно ли использовать introspection для отладки в продакшене?
Нет. Даже временное включение introspection в продакшене создает риск утечки данных. Для отладки используйте тестовое окружение или локальный сервер.
Как проверить, что introspection отключена?
Отправьте запрос { __schema { queryType { fields { name } } } } через curl или Postman. Если вы получаете ответ со схемой — защита не работает. Если ошибка 401/403 — всё настроено правильно.
Нужно ли отключать introspection для внутренних API?
Да, если внутренние API доступны извне или имеют доступ к чувствительным данным. Для полностью изолированных систем можно оставить включенной, но это не рекомендуется.
