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 graphql 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.

Package graphql 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

• func FromContext[T dyngo.Operation](ctx context.Context) T
• type ExecutionOperation
  • func StartExecutionOperation(ctx context.Context, parent *RequestOperation, span trace.TagSetter, ...) (context.Context, *ExecutionOperation)
  • func (q *ExecutionOperation) Finish(res ExecutionOperationRes)
• type ExecutionOperationArgs
• type ExecutionOperationRes
• type OnExecutionOperationFinish
  • func (f OnExecutionOperationFinish) Call(op dyngo.Operation, v interface{})
  • func (OnExecutionOperationFinish) ListenedType() reflect.Type
• type OnExecutionOperationStart
  • func (f OnExecutionOperationStart) Call(op dyngo.Operation, v interface{})
  • func (OnExecutionOperationStart) ListenedType() reflect.Type
• type OnRequestOperationFinish
  • func (f OnRequestOperationFinish) Call(op dyngo.Operation, v interface{})
  • func (OnRequestOperationFinish) ListenedType() reflect.Type
• type OnRequestOperationStart
  • func (f OnRequestOperationStart) Call(op dyngo.Operation, v interface{})
  • func (OnRequestOperationStart) ListenedType() reflect.Type
• type OnResolveOperationFinish
  • func (f OnResolveOperationFinish) Call(op dyngo.Operation, v interface{})
  • func (OnResolveOperationFinish) ListenedType() reflect.Type
• type OnResolveOperationStart
  • func (f OnResolveOperationStart) Call(op dyngo.Operation, v interface{})
  • func (OnResolveOperationStart) ListenedType() reflect.Type
• type RequestOperation
  • func StartRequestOperation(ctx context.Context, parent dyngo.Operation, span trace.TagSetter, ...) (context.Context, *RequestOperation)
  • func (q *RequestOperation) Finish(res RequestOperationRes)
• type RequestOperationArgs
• type RequestOperationRes
• type ResolveOperation
  • func StartResolveOperation(ctx context.Context, parent *ExecutionOperation, span trace.TagSetter, ...) (context.Context, *ResolveOperation)
  • func (q *ResolveOperation) Finish(res ResolveOperationRes)
• type ResolveOperationArgs
• type ResolveOperationRes

Functions

func FromContext

func FromContext[T dyngo.Operation](ctx context.Context) T

FromContext returns the operation of the given type from the context. Returns the zero-value of T if no such operation is found.

Types

type ExecutionOperation

type ExecutionOperation struct {
	dyngo.Operation
	trace.TagSetter
	trace.SecurityEventsHolder
}

func StartExecutionOperation

func StartExecutionOperation(ctx context.Context, parent *RequestOperation, span trace.TagSetter, args ExecutionOperationArgs, listeners ...dyngo.DataListener) (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.

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
}

type OnExecutionOperationFinish

type OnExecutionOperationFinish func(*ExecutionOperation, ExecutionOperationRes)

func (OnExecutionOperationFinish) Call

func (f OnExecutionOperationFinish) Call(op dyngo.Operation, v interface{})

func (OnExecutionOperationFinish) ListenedType

func (OnExecutionOperationFinish) ListenedType() reflect.Type

type OnExecutionOperationStart

type OnExecutionOperationStart func(*ExecutionOperation, ExecutionOperationArgs)

func (OnExecutionOperationStart) Call

func (f OnExecutionOperationStart) Call(op dyngo.Operation, v interface{})

func (OnExecutionOperationStart) ListenedType

func (OnExecutionOperationStart) ListenedType() reflect.Type

type OnRequestOperationFinish

type OnRequestOperationFinish func(*RequestOperation, RequestOperationRes)

func (OnRequestOperationFinish) Call

func (f OnRequestOperationFinish) Call(op dyngo.Operation, v interface{})

func (OnRequestOperationFinish) ListenedType

func (OnRequestOperationFinish) ListenedType() reflect.Type

type OnRequestOperationStart

type OnRequestOperationStart func(*RequestOperation, RequestOperationArgs)

func (OnRequestOperationStart) Call

func (f OnRequestOperationStart) Call(op dyngo.Operation, v interface{})

func (OnRequestOperationStart) ListenedType

func (OnRequestOperationStart) ListenedType() reflect.Type

type OnResolveOperationFinish

type OnResolveOperationFinish func(*ResolveOperation, ResolveOperationRes)

func (OnResolveOperationFinish) Call

func (f OnResolveOperationFinish) Call(op dyngo.Operation, v interface{})

func (OnResolveOperationFinish) ListenedType

func (OnResolveOperationFinish) ListenedType() reflect.Type

type OnResolveOperationStart

type OnResolveOperationStart func(*ResolveOperation, ResolveOperationArgs)

func (OnResolveOperationStart) Call

func (f OnResolveOperationStart) Call(op dyngo.Operation, v interface{})

func (OnResolveOperationStart) ListenedType

func (OnResolveOperationStart) ListenedType() reflect.Type

type RequestOperation

type RequestOperation struct {
	dyngo.Operation
	trace.TagSetter
	trace.SecurityEventsHolder
}

func StartRequestOperation

func StartRequestOperation(ctx context.Context, parent dyngo.Operation, span trace.TagSetter, 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 (q *RequestOperation) Finish(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.

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
}

type ResolveOperation

type ResolveOperation struct {
	dyngo.Operation
	trace.TagSetter
	trace.SecurityEventsHolder
}

func StartResolveOperation

func StartResolveOperation(ctx context.Context, parent *ExecutionOperation, span trace.TagSetter, 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.

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
}