grpcsec

Documentation

Overview

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

Index

• func NewMonitoringError(msg string, code uint32) error
• func SetRequestMetadataTags(span ddtrace.Span, md map[string][]string)
• func SetSecurityEventsTags(span ddtrace.Span, events []any)
• type HandlerOperation
  • func StartHandlerOperation(ctx context.Context, args HandlerOperationArgs, parent dyngo.Operation, ...) (context.Context, *HandlerOperation)
  • func (op *HandlerOperation) Finish(res HandlerOperationRes) []any
• type HandlerOperationArgs
• type HandlerOperationRes
• type MonitoringError
  • func (e *MonitoringError) Error() string
  • func (e *MonitoringError) GRPCStatus() uint32
• type OnHandlerOperationFinish
  • func (f OnHandlerOperationFinish) Call(op dyngo.Operation, v interface{})
  • func (OnHandlerOperationFinish) ListenedType() reflect.Type
• type OnHandlerOperationStart
  • func (f OnHandlerOperationStart) Call(op dyngo.Operation, v interface{})
  • func (OnHandlerOperationStart) ListenedType() reflect.Type
• type OnReceiveOperationFinish
  • func (f OnReceiveOperationFinish) Call(op dyngo.Operation, v interface{})
  • func (OnReceiveOperationFinish) ListenedType() reflect.Type
• type OnReceiveOperationStart
  • func (f OnReceiveOperationStart) Call(op dyngo.Operation, v interface{})
  • func (OnReceiveOperationStart) ListenedType() reflect.Type
• type ReceiveOperation
  • func StartReceiveOperation(args ReceiveOperationArgs, parent dyngo.Operation) ReceiveOperation
  • func (op ReceiveOperation) Finish(res ReceiveOperationRes)
• type ReceiveOperationArgs
• type ReceiveOperationRes

Functions

func NewMonitoringError

func NewMonitoringError(msg string, code uint32) error

NewMonitoringError creates and returns a new gRPC monitoring error, wrapped under sharedesec.MonitoringError

func SetRequestMetadataTags

func SetRequestMetadataTags(span ddtrace.Span, md map[string][]string)

SetRequestMetadataTags sets the gRPC request metadata span tags.

func SetSecurityEventsTags

func SetSecurityEventsTags(span ddtrace.Span, events []any)

SetSecurityEventsTags sets the AppSec events span tags.

Types

type HandlerOperation

type HandlerOperation struct {
	dyngo.Operation
	instrumentation.TagsHolder
	instrumentation.SecurityEventsHolder
	Error error
}

HandlerOperation represents a gRPC server handler operation. It must be created with StartHandlerOperation() and finished with its Finish() method. Security events observed during the operation lifetime should be added to the operation using its AddSecurityEvent() method.

func StartHandlerOperation

func StartHandlerOperation(ctx context.Context, args HandlerOperationArgs, parent dyngo.Operation, listeners ...dyngo.DataListener) (context.Context, *HandlerOperation)

StartHandlerOperation starts an gRPC server handler operation, along with the given arguments and parent operation, and emits a start event up in the operation stack. When parent is nil, the operation is linked to the global root operation.

func (*HandlerOperation) Finish

func (op *HandlerOperation) Finish(res HandlerOperationRes) []any

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

type HandlerOperationArgs

type HandlerOperationArgs struct {
	// Message received by the gRPC handler.
	// Corresponds to the address `grpc.server.request.metadata`.
	Metadata map[string][]string
	ClientIP netip.Addr
}

HandlerOperationArgs is the grpc handler arguments.

type HandlerOperationRes

type HandlerOperationRes struct{}

HandlerOperationRes is the grpc handler results. Empty as of today.

type MonitoringError

type MonitoringError struct {
	// contains filtered or unexported fields
}

MonitoringError is used to vehicle a gRPC error that also embeds a request status code

func (*MonitoringError) Error

func (e *MonitoringError) Error() string

Error implements the error interface

func (*MonitoringError) GRPCStatus

func (e *MonitoringError) GRPCStatus() uint32

GRPCStatus returns the gRPC status code embedded in the error

type OnHandlerOperationFinish

type OnHandlerOperationFinish func(*HandlerOperation, HandlerOperationRes)

OnHandlerOperationFinish function type, called when an gRPC handler operation finishes.

func (OnHandlerOperationFinish) Call

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

Call the underlying event listener function by performing the type-assertion on v whose type is the one returned by ListenedType().

func (OnHandlerOperationFinish) ListenedType

func (OnHandlerOperationFinish) ListenedType() reflect.Type

ListenedType returns the type a OnHandlerOperationFinish event listener listens to, which is the HandlerOperationRes type.

type OnHandlerOperationStart

type OnHandlerOperationStart func(*HandlerOperation, HandlerOperationArgs)

OnHandlerOperationStart function type, called when an gRPC handler operation starts.

func (OnHandlerOperationStart) Call

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

Call the underlying event listener function by performing the type-assertion on v whose type is the one returned by ListenedType().

func (OnHandlerOperationStart) ListenedType

func (OnHandlerOperationStart) ListenedType() reflect.Type

ListenedType returns the type a OnHandlerOperationStart event listener listens to, which is the HandlerOperationArgs type.

type OnReceiveOperationFinish

type OnReceiveOperationFinish func(ReceiveOperation, ReceiveOperationRes)

OnReceiveOperationFinish function type, called when a grpc receive operation finishes.

func (OnReceiveOperationFinish) Call

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

Call the underlying event listener function by performing the type-assertion on v whose type is the one returned by ListenedType().

func (OnReceiveOperationFinish) ListenedType

func (OnReceiveOperationFinish) ListenedType() reflect.Type

ListenedType returns the type a OnHandlerOperationFinish event listener listens to, which is the HandlerOperationRes type.

type OnReceiveOperationStart

type OnReceiveOperationStart func(ReceiveOperation, ReceiveOperationArgs)

OnReceiveOperationStart function type, called when a gRPC receive operation starts.

func (OnReceiveOperationStart) Call

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

Call the underlying event listener function by performing the type-assertion on v whose type is the one returned by ListenedType().

func (OnReceiveOperationStart) ListenedType

func (OnReceiveOperationStart) ListenedType() reflect.Type

ListenedType returns the type a OnHandlerOperationStart event listener listens to, which is the HandlerOperationArgs type.

type ReceiveOperation

type ReceiveOperation struct {
	dyngo.Operation
}

ReceiveOperation type representing an gRPC server handler operation. It must be created with StartReceiveOperation() and finished with its Finish().

func StartReceiveOperation

func StartReceiveOperation(args ReceiveOperationArgs, parent dyngo.Operation) ReceiveOperation

StartReceiveOperation starts a receive operation of a gRPC handler, along with the given arguments and parent operation, and emits a start event up in the operation stack. When parent is nil, the operation is linked to the global root operation.

func (ReceiveOperation) Finish

func (op ReceiveOperation) Finish(res ReceiveOperationRes)

Finish the gRPC handler operation, along with the given results, and emits a finish event up in the operation stack.

type ReceiveOperationArgs

type ReceiveOperationArgs struct{}

ReceiveOperationArgs is the gRPC handler receive operation arguments Empty as of today.

type ReceiveOperationRes

type ReceiveOperationRes struct {
	// Message received by the gRPC handler.
	// Corresponds to the address `grpc.server.request.message`.
	Message interface{}
}

ReceiveOperationRes is the gRPC handler receive operation results which contains the message the gRPC handler received.