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.

Abstract gRPC server handler operation definitions. It is based on two operations allowing to describe every type of RPC: the HandlerOperation type which represents the RPC handler, and the ReceiveOperation type which represents the messages the RPC handler receives during its lifetime. This means that the ReceiveOperation(s) will happen within the HandlerOperation. Every type of RPC, unary, client streaming, server streaming, and bidirectional streaming RPCs, can be all represented with a HandlerOperation having one or several ReceiveOperation. The send operation is not required for now and therefore not defined, which means that server and bidirectional streaming RPCs currently have the same run-time representation as unary and client streaming RPCs.

Index

• func MonitorRequestMessage(ctx context.Context, msg any) error
• func MonitorResponseMessage(ctx context.Context, msg any) error
• type HandlerOperation
  • func StartHandlerOperation(ctx context.Context, args HandlerOperationArgs) (context.Context, *HandlerOperation, *atomic.Pointer[actions.BlockGRPC])
  • func (op *HandlerOperation) Finish(span trace.TagSetter, res HandlerOperationRes)
• type HandlerOperationArgs
  • func (HandlerOperationArgs) IsArgOf(*HandlerOperation)
• type HandlerOperationRes
  • func (HandlerOperationRes) IsResultOf(*HandlerOperation)

Functions

func MonitorRequestMessage

func MonitorRequestMessage(ctx context.Context, msg any) error

MonitorRequestMessage monitors the gRPC request message body as the WAF address `grpc.server.request.message`.

func MonitorResponseMessage

func MonitorResponseMessage(ctx context.Context, msg any) error

MonitorResponseMessage monitors the gRPC response message body as the WAF address `grpc.server.response.message`.

Types

type HandlerOperation

type HandlerOperation struct {
	dyngo.Operation
	*waf.ContextOperation
}

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) (context.Context, *HandlerOperation, *atomic.Pointer[actions.BlockGRPC])

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(span trace.TagSetter, res HandlerOperationRes)

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 {
	// Method is the gRPC method name.
	// Corresponds to the address `grpc.server.method`.
	Method string

	// RPC metadata received by the gRPC handler.
	// Corresponds to the address `grpc.server.request.metadata`.
	Metadata map[string][]string

	// RemoteAddr is the IP address of the client that initiated the gRPC request.
	// May be used as the address `http.client_ip`.
	RemoteAddr string
}

HandlerOperationArgs is the grpc handler arguments.

func (HandlerOperationArgs) IsArgOf

func (HandlerOperationArgs) IsArgOf(*HandlerOperation)

type HandlerOperationRes

type HandlerOperationRes struct {
	// Raw gRPC status code.
	// Corresponds to the address `grpc.server.response.status`.
	StatusCode int
}

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

func (HandlerOperationRes) IsResultOf

func (HandlerOperationRes) IsResultOf(*HandlerOperation)