httpsec

Documentation

Overview

Package httpsec defines is the HTTP instrumentation API and contract for AppSec. It defines an abstract representation of HTTP handlers, along with helper functions to wrap (aka. instrument) standard net/http handlers. HTTP integrations must use this package to enable AppSec features for HTTP, which listens to this package's operation events.

Index

• func ClientIPTags(headers map[string][]string, hasCanonicalHeaders bool, remoteAddr string) (tags map[string]string, clientIP netip.Addr)
• func ExecuteSDKBodyOperation(parent dyngo.Operation, args SDKBodyOperationArgs) error
• func MonitorParsedBody(ctx context.Context, body interface{}) error
• func NewMonitoringError(msg string) error
• func NormalizeHTTPHeaders(headers map[string][]string) (normalized map[string]string)
• func SetSecurityEventsTags(span instrumentation.TagSetter, events []any)
• func WrapHandler(handler http.Handler, span ddtrace.Span, pathParams map[string]string, ...) http.Handler
• type HandlerOperationArgs
  • func MakeHandlerOperationArgs(r *http.Request, clientIP netip.Addr, pathParams map[string]string) HandlerOperationArgs
• type HandlerOperationRes
  • func MakeHandlerOperationRes(w http.ResponseWriter) HandlerOperationRes
• type MonitoringError
  • func (e *MonitoringError) Error() string
• 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 OnSDKBodyOperationFinish
  • func (f OnSDKBodyOperationFinish) Call(op dyngo.Operation, v interface{})
  • func (OnSDKBodyOperationFinish) ListenedType() reflect.Type
• type OnSDKBodyOperationStart
  • func (f OnSDKBodyOperationStart) Call(op dyngo.Operation, v interface{})
  • func (OnSDKBodyOperationStart) ListenedType() reflect.Type
• type Operation
  • func StartOperation(ctx context.Context, args HandlerOperationArgs, ...) (context.Context, *Operation)
  • func (op *Operation) Finish(res HandlerOperationRes) []any
• type SDKBodyOperation
  • func (op *SDKBodyOperation) Finish()
• type SDKBodyOperationArgs
• type SDKBodyOperationRes

Functions

func ClientIPTags

func ClientIPTags(headers map[string][]string, hasCanonicalHeaders bool, remoteAddr string) (tags map[string]string, clientIP netip.Addr)

ClientIPTags returns the resulting Datadog span tags `http.client_ip` containing the client IP and `network.client.ip` containing the remote IP. The tags are present only if a valid ip address has been returned by ClientIP().

func ExecuteSDKBodyOperation

func ExecuteSDKBodyOperation(parent dyngo.Operation, args SDKBodyOperationArgs) error

ExecuteSDKBodyOperation starts and finishes the SDK Body operation by emitting a dyngo start and finish events An error is returned if the body associated to that operation must be blocked

func MonitorParsedBody

func MonitorParsedBody(ctx context.Context, body interface{}) error

MonitorParsedBody starts and finishes the SDK body operation. This function should not be called when AppSec is disabled in order to get preciser error logs.

func NewMonitoringError

func NewMonitoringError(msg string) error

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

func NormalizeHTTPHeaders

func NormalizeHTTPHeaders(headers map[string][]string) (normalized map[string]string)

NormalizeHTTPHeaders returns the HTTP headers following Datadog's normalization format.

func SetSecurityEventsTags

func SetSecurityEventsTags(span instrumentation.TagSetter, events []any)

SetSecurityEventsTags sets the AppSec-specific span tags when a security event occurred into the service entry span.

func WrapHandler

func WrapHandler(handler http.Handler, span ddtrace.Span, pathParams map[string]string, onBlock ...func()) http.Handler

WrapHandler wraps the given HTTP handler with the abstract HTTP operation defined by HandlerOperationArgs and HandlerOperationRes. The onBlock params are used to cleanup the context when needed. It is a specific patch meant for Gin, for which we must abort the context since it uses a queue of handlers and it's the only way to make sure other queued handlers don't get executed. TODO: this patch must be removed/improved when we rework our actions/operations system

Types

type HandlerOperationArgs

type HandlerOperationArgs struct {
	// Method is the http method verb of the request, address is `server.request.method`
	Method string
	// RequestURI corresponds to the address `server.request.uri.raw`
	RequestURI string
	// Headers corresponds to the address `server.request.headers.no_cookies`
	Headers map[string][]string
	// Cookies corresponds to the address `server.request.cookies`
	Cookies map[string][]string
	// Query corresponds to the address `server.request.query`
	Query map[string][]string
	// PathParams corresponds to the address `server.request.path_params`
	PathParams map[string]string
	// ClientIP corresponds to the address `http.client_ip`
	ClientIP netip.Addr
}

HandlerOperationArgs is the HTTP handler operation arguments.

func MakeHandlerOperationArgs

func MakeHandlerOperationArgs(r *http.Request, clientIP netip.Addr, pathParams map[string]string) HandlerOperationArgs

MakeHandlerOperationArgs creates the HandlerOperationArgs value.

type HandlerOperationRes

type HandlerOperationRes struct {
	// Status corresponds to the address `server.response.status`.
	Status int
}

HandlerOperationRes is the HTTP handler operation results.

func MakeHandlerOperationRes

func MakeHandlerOperationRes(w http.ResponseWriter) HandlerOperationRes

MakeHandlerOperationRes creates the HandlerOperationRes value.

type MonitoringError

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

MonitoringError is used to vehicle an HTTP error, usually resurfaced through Appsec SDKs.

func (*MonitoringError) Error

func (e *MonitoringError) Error() string

Error implements the Error interface

type OnHandlerOperationFinish

type OnHandlerOperationFinish func(*Operation, HandlerOperationRes)

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

func (OnHandlerOperationFinish) Call

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

Call calls 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(*Operation, HandlerOperationArgs)

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

func (OnHandlerOperationStart) Call

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

Call calls 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 OnSDKBodyOperationFinish

type OnSDKBodyOperationFinish func(*SDKBodyOperation, SDKBodyOperationRes)

OnSDKBodyOperationFinish function type, called when an SDK body operation finishes.

func (OnSDKBodyOperationFinish) Call

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

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

func (OnSDKBodyOperationFinish) ListenedType

func (OnSDKBodyOperationFinish) ListenedType() reflect.Type

ListenedType returns the type a OnSDKBodyOperationFinish event listener listens to, which is the SDKBodyOperationRes type.

type OnSDKBodyOperationStart

type OnSDKBodyOperationStart func(*SDKBodyOperation, SDKBodyOperationArgs)

OnSDKBodyOperationStart function type, called when an SDK body operation starts.

func (OnSDKBodyOperationStart) Call

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

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

func (OnSDKBodyOperationStart) ListenedType

func (OnSDKBodyOperationStart) ListenedType() reflect.Type

ListenedType returns the type a OnSDKBodyOperationStart event listener listens to, which is the SDKBodyOperationStartArgs type.

type Operation

type Operation struct {
	dyngo.Operation
	instrumentation.TagsHolder
	instrumentation.SecurityEventsHolder
	// contains filtered or unexported fields
}

Operation type representing an HTTP operation. It must be created with StartOperation() and finished with its Finish().

func StartOperation

func StartOperation(ctx context.Context, args HandlerOperationArgs, listeners ...dyngo.DataListener) (context.Context, *Operation)

StartOperation starts an HTTP handler operation, along with the given context and arguments and emits a start event up in the operation stack. The operation is linked to the global root operation since an HTTP operation is always expected to be first in the operation stack.

func (*Operation) Finish

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

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

type SDKBodyOperation

type SDKBodyOperation struct {
	dyngo.Operation
}

SDKBodyOperation type representing an SDK body

func (*SDKBodyOperation) Finish

func (op *SDKBodyOperation) Finish()

Finish finishes the SDKBody operation and emits a finish event

type SDKBodyOperationArgs

type SDKBodyOperationArgs struct {
	// Body corresponds to the address `server.request.body`.
	Body interface{}
}

SDKBodyOperationArgs is the SDK body operation arguments.

type SDKBodyOperationRes

type SDKBodyOperationRes struct{}

SDKBodyOperationRes is the SDK body operation results.