GraphQL Schema support

This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

We currently support scanning GraphQL endpoints, but need a HAR file or Postman collection in order to scan it. In order to expand our support for GraphQL, we need to be able to support defining GraphQL endpoints through a GraphQL schema. We should support defining the endpoints via the GraphQL SDL, by allowing them to provide the path to a schema file.

Proposal

Open Questions:

Can we implement this w/o some form of parameter dependency resolution.
Should we create multiple exchanges per item? For example if their are optional inputs.

The GraphQL endpoint can also provide the full schema. This schema defines all of the things API Security will want to test, both for DAST and API Fuzzing. The proposed method of supporting the GraphQL schema for automatic testing is the following:

Add a new variable _GRAPHQL, allowing the user to provide a GraphQL endpoint address or schema file
Refactor the IReader readers to produce Operation+Request instead of just Request.
Create a new IReader for GraphQL that provides each query/mutation as an Operation

Refactor Readers to produce Operations and Request pairs

The current reader implementation produces Request instances which are then converted into Operation instances by the RunnerService. Unfortunately that causes information loss for API specifications that include information about the parameters such as type or constraints.

This work will be required prior to creating the GraphQlSchemaReader.

Proposed new IReader interface:

namespace Peach.Web.Runner.Interfaces
{
    public interface IReader
    {
        IEnumerable<(Operation Operation, Request Request)> GetOperations(IRunnerOptions runnerOptions);
    }
}

Questions:

For existing readers, do they use WebApiService.OperationFromRequest to create the Operation to pair with the Request they are already returning?

GraphQlSChemaReader (Peach.Web.Runner.Services.Readers)

Implement a new reader that creates a series of exchanges that provide coverage of all parameterized queries and mutations.

Use our existing GraphQL.NET dependency to parse schema
1. When schema is provided as a file, read file parse schema
2. When schema is provided as a url:
  1. Get schema by running the query provided below
    1. Make sure to use overrides when making this request so it's authenticated
    2. The example query assumes max 10 levels of nested types. What do we do if the target schema is deeper? Should we pick a limit and say anything beyond that is not supported? Can we detect if there are more types that we didn't receive and issue a new query to get them?
  2. Extract schema from query result
Iterate over the Queries and Mutations section of the Schema instance, generating (Operation, Request) pairs
1. Generate an Operation with a GraphQLBody
  1. Option: Create a GraphQL AST doc directly, or create a GraphQL query and parse it.
    1. We have some concern that building the AST may be complex or fiddly, but initial investigation suggests it won't be too bad. It would be nice to have a library that was specifically designed to dynamically build GraphQL queries, but the only ones we can find assume that there is a statically-typed model.
    2. If we end up parsing a request, we need to ensure that we still end up with the correct type information
2. Convert the Operation into a Request
  1. Is WebApiService.OperationIntoRequest sufficient for this?

Interpreting the schema response

Interesting part is data, __schema, types object
- Query root name is __schema[queryType][name]
- Mutation root name is __schema[mutationType][name]
- Queries are listed as types[query root][fields]
- Mutations as types[mutation root][fields]
So far unable to find a way to read json response into the Schema instance
- might need to construct by hand

Testing

API Security GraphQL Target

Implementation Checklist

Appendix

Utilities

GitLab GraphQL Explorer
Example of variables separate from query inputs

Schema Query

This is the query used by the interactive GraphQL web thing:

Click this to show/hide query.

query IntrospectionQuery {
  __schema {
    queryType {
      name
    }
    mutationType {
      name
    }
    subscriptionType {
      name
    }
    types {
      ...FullType
    }
    directives {
      name
      description
      locations
      args {
        ...InputValue
      }
    }
  }
}

fragment FullType on __Type {
  kind
  name
  description
  fields(includeDeprecated: true) {
    name
    description
    args {
      ...InputValue
    }
    type {
      ...TypeRef
    }
    isDeprecated
    deprecationReason
  }
  inputFields {
    ...InputValue
  }
  interfaces {
    ...TypeRef
  }
  enumValues(includeDeprecated: true) {
    name
    description
    isDeprecated
    deprecationReason
  }
  possibleTypes {
    ...TypeRef
  }
}

fragment InputValue on __InputValue {
  name
  description
  type {
    ...TypeRef
  }
  defaultValue
}

fragment TypeRef on __Type {
  kind
  name
  ofType {
    kind
    name
    ofType {
      kind
      name
      ofType {
        kind
        name
        ofType {
          kind
          name
          ofType {
            kind
            name
            ofType {
              kind
              name
              ofType {
                kind
                name
              }
            }
          }
        }
      }
    }
  }
}

Edited Sep 21, 2022 by Michael Eddington