graphqlsec

README

GraphQL Threat Monitoring

This package provides dyngo support for GraphQL operations, which are listened to according to the following sequence diagram:

sequenceDiagram
  participant Root
  participant Request
  participant Execution
  participant Field

  Root ->>+ Request: graphqlsec.StartRequest(...)

  Request ->>+ Execution: grapgqlsec.StartExecution(...)

  par for each field
  Execution ->>+ Field: graphqlsec.StartField(...)
  Field -->>- Execution: field.Finish(...)
  end

  Execution -->>- Request: execution.Finish(...)

  Request -->>- Root: request.Finish(...)

Documentation

Overview

Package graphqlsec is the GraphQL instrumentation API and contract for AppSec defining an abstract run-time representation of AppSec middleware. GraphQL integrations must use this package to enable AppSec features for GraphQL, which listens to this package's operation events.

Index

• type ExecutionOperation
  • func StartExecutionOperation(ctx context.Context, args ExecutionOperationArgs) (context.Context, *ExecutionOperation)
  • func (q *ExecutionOperation) Finish(res ExecutionOperationRes)
• type ExecutionOperationArgs
  • func (ExecutionOperationArgs) IsArgOf(*ExecutionOperation)
• type ExecutionOperationRes
  • func (ExecutionOperationRes) IsResultOf(*ExecutionOperation)
• type RequestOperation
  • func StartRequestOperation(ctx context.Context, args RequestOperationArgs) (context.Context, *RequestOperation)
  • func (op *RequestOperation) Finish(span trace.TagSetter, res RequestOperationRes)
• type RequestOperationArgs
  • func (RequestOperationArgs) IsArgOf(*RequestOperation)
• type RequestOperationRes
  • func (RequestOperationRes) IsResultOf(*RequestOperation)
• type ResolveOperation
  • func StartResolveOperation(ctx context.Context, args ResolveOperationArgs) (context.Context, *ResolveOperation)
  • func (q *ResolveOperation) Finish(res ResolveOperationRes)
• type ResolveOperationArgs
  • func (ResolveOperationArgs) IsArgOf(*ResolveOperation)
• type ResolveOperationRes
  • func (ResolveOperationRes) IsResultOf(*ResolveOperation)

Types

type ExecutionOperation

type ExecutionOperation struct {
	dyngo.Operation
}

func StartExecutionOperation

func StartExecutionOperation(ctx context.Context, args ExecutionOperationArgs) (context.Context, *ExecutionOperation)

StartExecutionOperation starts a new GraphQL query operation, along with the given arguments, and emits a start event up in the operation stack. The operation is tracked on the returned context, and can be extracted later on using FromContext.

func (*ExecutionOperation) Finish

func (q *ExecutionOperation) Finish(res ExecutionOperationRes)

Finish the GraphQL query operation, along with the given results, and emit a finish event up in the operation stack.

type ExecutionOperationArgs

type ExecutionOperationArgs struct {
	// Variables is the user-provided variables object for the query.
	Variables map[string]any
	// Query is the query that is being executed.
	Query string
	// OperationName is the user-provided operation name for the query.
	OperationName string
}

ExecutionOperationArgs describes arguments passed to a GraphQL query operation.

func (ExecutionOperationArgs) IsArgOf

func (ExecutionOperationArgs) IsArgOf(*ExecutionOperation)

type ExecutionOperationRes

type ExecutionOperationRes struct {
	// Data is the data returned from processing the GraphQL operation.
	Data any
	// Error is the error returned by processing the GraphQL Operation, if any.
	Error error
}

func (ExecutionOperationRes) IsResultOf

func (ExecutionOperationRes) IsResultOf(*ExecutionOperation)

type RequestOperation

type RequestOperation struct {
	dyngo.Operation
	// used in case we don't have a parent operation
	*waf.ContextOperation
}

func StartRequestOperation

func StartRequestOperation(ctx context.Context, args RequestOperationArgs) (context.Context, *RequestOperation)

StartRequestOperation starts a new GraphQL request operation, along with the given arguments, and emits a start event up in the operation stack. The operation is usually linked to tge global root operation. The operation is tracked on the returned context, and can be extracted later on using FromContext.

func (*RequestOperation) Finish

func (op *RequestOperation) Finish(span trace.TagSetter, res RequestOperationRes)

Finish the GraphQL query operation, along with the given results, and emit a finish event up in the operation stack.

type RequestOperationArgs

type RequestOperationArgs struct {
	RawQuery      string         // The raw, not-yet-parsed GraphQL query
	OperationName string         // The user-provided operation name for the query
	Variables     map[string]any // The user-provided variables object for this request
}

RequestOperationArgs describes arguments passed to a GraphQL request.

func (RequestOperationArgs) IsArgOf

func (RequestOperationArgs) IsArgOf(*RequestOperation)

type RequestOperationRes

type RequestOperationRes struct {
	// Data is the data returned from processing the GraphQL operation.
	Data any
	// Error is the error returned by processing the GraphQL Operation, if any.
	Error error
}

func (RequestOperationRes) IsResultOf

func (RequestOperationRes) IsResultOf(*RequestOperation)

type ResolveOperation

type ResolveOperation struct {
	dyngo.Operation
}

func StartResolveOperation

func StartResolveOperation(ctx context.Context, args ResolveOperationArgs) (context.Context, *ResolveOperation)

StartResolveOperation starts a new GraphQL Resolve operation, along with the given arguments, and emits a start event up in the operation stack. The operation is tracked on the returned context, and can be extracted later on using FromContext.

func (*ResolveOperation) Finish

func (q *ResolveOperation) Finish(res ResolveOperationRes)

Finish the GraphQL Field operation, along with the given results, and emit a finish event up in the operation stack.

type ResolveOperationArgs

type ResolveOperationArgs struct {
	// TypeName is the name of the field's type
	TypeName string
	// FieldName is the name of the field
	FieldName string
	// Arguments is the arguments provided to the field resolver
	Arguments map[string]any
	// Trivial determines whether the resolution is trivial or not. Leave as false if undetermined.
	Trivial bool
}

ResolveOperationArgs describes arguments passed to a GraphQL field operation.

func (ResolveOperationArgs) IsArgOf

func (ResolveOperationArgs) IsArgOf(*ResolveOperation)

type ResolveOperationRes

type ResolveOperationRes struct {
	// Data is the data returned from processing the GraphQL operation.
	Data any
	// Error is the error returned by processing the GraphQL Operation, if any.
	Error error
}

func (ResolveOperationRes) IsResultOf

func (ResolveOperationRes) IsResultOf(*ResolveOperation)