# 💡 Techniques

You may want to use Escape in different ways, depending on your needs.

You can detect and configure specific behavior for requests coming from our scanner.


# Identifying requests comming from the scanner on your server

You might need to identify when the request you receive is coming from the security scanner.

For instance, you probably don't want the many requests being sent to your server from the scanner to appear in your monitoring tool, or, you might want to enable the introspection of your server only to the security scanner on your staging environmet.

For this purpose, the scanner of Escape sends a specific header attached to every requests it sends. The header name is x-escape-identifier and its value is an identification token attached to your application.

x-escape-identifier: {{your-escape-identifier}}

Thanks to this header you can detect incoming requests from the scanner in your server, to add any custom handling logic you might want on top of this.

You can find this token on your scan page in the CI/CD section as ESCAPE_APPLICATION_ID.

# Enabling the introspection on your application

# Using Apollo

When creating a new instance of the ApolloServer, you have to provide an object describing your resolvers, and types definitions. This object can also include an introspection parameter.

const server = new ApolloServer({
  typeDefs,
  resolvers,
  introspection: true
});

This option is documented in the ApolloServer reference (opens new window)

# Fine-tuning

Using Apollo plugins (opens new window), you can also have a better access control over this query. Here is an example of plugin that prevents the access to the introspection query if the request does not feature the CLI header.

const secureIntrospection = {
  requestDidStart: ({ request }) => {
    if (
      request.query.includes('__schema') ||
      request.query.includes('__type')
    ) {
      if (process.env.ESCAPE_IDENTIFIER) {
        const introspectionSecureKeyHeader = request.http.headers.get(
          'x-escape-identifier'
        );
        if (
          introspectionSecureKeyHeader !== process.env.ESCAPE_IDENTIFIER
        ) {
          throw new ForbiddenError('GraphQL introspection is disabled.');
        }
      }
    }
  }
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
  introspection: true,
  plugins: [secureIntrospection]
});

The value of the variable ESCAPE_IDENTIFIER could be contained in your environment or any secure storage you'd like.

# Using NestJs

NestJs provides a GraphQL module through the @nestjs/graphql package. The package is a wrapper around the Apollo GraphQL server, and it's usage is documented in the NestJs related documentation (opens new window).

Starting from now, we will assume that you have a basic GraphQL module setup in your application like so:

@Module({
  imports: [
    ...
    GraphQLModule.forRoot({
      autoSchemaFile: 'schema.gql'
    }),
    ...
  ],
  providers: []
})
export class AppModule {}

By default, the introspection is enabled as long as the NODE_ENV is not production. To change this behavior, you can just set the introspection parameter to true in the module declaration.

@Module({
  imports: [
    ...
    GraphQLModule.forRoot({
      autoSchemaFile: 'schema.gql',
      introspection: true
    }),
    ...
  ],
  providers: []
})
export class AppModule {}

For instance, you might want to manually define where to enable or not the introspection based on your environment. To do so, you can add a DISABLE_INTROSPECTION env variable (provided by a .env file or through an shell environment variable) and use it like so:

@Module({
  imports: [
    ...
    GraphQLModule.forRoot({
      autoSchemaFile: 'schema.gql',
      introspection: !process.env.DISABLE_INTROSPECTION
    }),
    ...
  ],
  providers: []
})
export class AppModule {}

This will enable introspection by default, and disable it in every environment you decide to.

# Fine-tuning

Any of the options you pass to the GraphQLModule.forRoot method is part of the Apollo configuration object. Thus, you can re-use the Apollo plugin method for a fine-tuned access control.

const secureIntrospection = ... // see the apollo technique documentation

@Module({
  imports: [
    ...
    GraphQLModule.forRoot({
      autoSchemaFile: 'schema.gql',
      introspection: !process.env.DISABLE_INTROSPECTION,
      plugins: [secureIntrospection]
    }),
    ...
  ],
  providers: []
})
export class AppModule {}

# Using Yoga

Yoga plugin system is built with Envelop. Refer to the Envelop section for more information.

# Using Envelop

Envelop provides a plugin disable-introspection that allows you to disable the introspection query. You can find more information about this plugin in the Envelop documentation (opens new window).

import { envelop } from '@envelop/core'
import { useDisableIntrospection } from '@envelop/disable-introspection'

const getEnveloped = envelop({
  plugins: [useDisableIntrospection({
    disableIf: ({ context }) => {
      return context.request.headers.get('x-escape-identifier') !== process.env.ESCAPE_IDENTIFIER;
    }
  })]
})