🛡️ Dead-simple, yet highly customizable security middleware for Apollo GraphQL servers and Envelop 🛡️

Escape – GraphQL Security

Last update: Jan 9, 2023

Overview

GraphQL Armor 🛡️

GraphQL Armor is a dead-simple yet highly customizable security middleware for various GraphQL server engines.

Contents
Supported GraphQL Engines
Getting Started
Getting Started with configuration
Per plugin configuration
Contributing

Supported GraphQL Engines

We support the following engines :

We additionnaly support the following engines through the Envelop plugin system :

GraphQL-Helix
Node.js HTTP
GraphQL-WS
GraphQL-SSE
Azure Functions
Cloudflare Workers
Google Cloud Functions
Lambda AWS
type-graphql
nexus
express-graphql

See here for more information about Envelop compatibility.

Getting Started

Refer to the Examples directory for specific implementation examples. (such as NestJS with Apollo Server)

Apollo Server

import { ApolloArmor } from '@escape.tech/graphql-armor';

const armor = new ApolloArmor();

const server = new ApolloServer({
  typeDefs,
  resolvers,
  ...armor.protect()
});

If you already have some plugins or validation rules, proceed this way:

import { ApolloArmor } from '@escape.tech/graphql-armor';

const armor = new ApolloArmor();
const protection = armor.protect()

const server = new ApolloServer({
  typeDefs,
  resolvers,
  ...protection,
  plugins: [...protection.plugins, myPlugin1, myPlugin2 ]
  validationRules: [, ...protection.validationRules, myRule1, myRule2 ]
});

GraphQL Yoga

import { EnvelopArmor } from '@escape.tech/graphql-armor';

const armor = new EnvelopArmor();
const protection = armor.protect()

async function main() {
  const server = createServer({
    schema,
    plugins: [...protection.plugins],
  });
  await server.start();
}

main();

Envelop

import { EnvelopArmor } from '@escape.tech/graphql-armor';

const armor = new EnvelopArmor();
const protection = armor.protect()

const getEnveloped = envelop({
  plugins: [otherPlugins, ...protection.plugins],
});

Getting Started with configuration

GraphQL Armor is fully configurable in a per-plugin fashion.

View the per plugin configuration section for more information about how to configure each plugin separately.

import { ApolloArmor } from '@escape.tech/graphql-armor';

const armor = new ApolloArmor({
    costAnalysis: {
        maxCost: 1000,
    },
    characterLimit: {
        maxLength: 15000,
    }
  }
});

Per plugin configuration

The provided values are the default values.

This section describes how to configure each plugin individually.

Stacktraces (Apollo Only)
Batched queries (Apollo Only)
Character Limit
Cost Analysis
Field Suggestion
Aliases Limit
Directives Limit
Depth Limit

Stacktraces (Apollo Only)

This plugin is for Apollo Server only, and is enabled by default.

Stacktraces are managed by the Apollo configuration parameter debug which may have true as a default value in some setups. GraphQL Armor changes this default value to false.

For rolling back to Apollo's default parameter, you can use the following code:

import { ApolloArmor } from '@escape.tech/graphql-armor';

const armor = new ApolloArmor();
const server = new ApolloServer({
  typeDefs,
  resolvers,
  ...armor.protect(),
  debug: true // Ignore Armor's recommandation
});

Batched queries (Apollo Only)

This plugin is for Apollo Server only, and is enabled by default.

Batched queries are enabled by default, which makes DoS attacks easier by stacking expensive requests. We make them disabled by default.

For rolling back to Apollo's default parameter, you can use the following code:

import { ApolloArmor } from '@escape.tech/graphql-armor';

const armor = new ApolloArmor();
const server = new ApolloServer({
  typeDefs,
  resolvers,
  ...armor.protect(),
  allowBatchedHttpRequests: true // Ignore Armor's recommandations
});