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 NormalizeHTTPHeaders(headers map[string][]string) (normalized map[string]string)
• func SetAppSecTags(span ddtrace.Span)
• func SetSecurityEventTags(span ddtrace.Span, events json.RawMessage, remoteIP string, ...)
• func WrapHandler(handler http.Handler, span ddtrace.Span, pathParams map[string]string) http.Handler
• type HandlerOperationArgs
  • func MakeHandlerOperationArgs(r *http.Request, pathParams map[string]string) HandlerOperationArgs
• type HandlerOperationRes
• 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 Operation
  • func StartOperation(args HandlerOperationArgs, parent dyngo.Operation) *Operation
  • func (op *Operation) AddSecurityEvent(event json.RawMessage)
  • func (op *Operation) Finish(res HandlerOperationRes) json.RawMessage

Functions

func NormalizeHTTPHeaders

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

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

func SetAppSecTags

func SetAppSecTags(span ddtrace.Span)

SetAppSecTags sets the AppSec-specific span tags that are expected to be in the web service entry span (span of type `web`) when AppSec is enabled.

func SetSecurityEventTags

func SetSecurityEventTags(span ddtrace.Span, events json.RawMessage, remoteIP string, headers, respHeaders map[string][]string)

SetSecurityEventTags 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) http.Handler

WrapHandler wraps the given HTTP handler with the abstract HTTP operation defined by HandlerOperationArgs and HandlerOperationRes.

Types

type HandlerOperationArgs

type HandlerOperationArgs struct {
	// 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 []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
}

HandlerOperationArgs is the HTTP handler operation arguments.

func MakeHandlerOperationArgs

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

MakeHandlerOperationArgs creates the HandlerOperationArgs out of a standard http.Request along with the given current span. It returns an empty structure when appsec is disabled.

type HandlerOperationRes

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

HandlerOperationRes is the HTTP handler operation results.

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 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 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 Operation

type Operation struct {
	dyngo.Operation
	// 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(args HandlerOperationArgs, parent dyngo.Operation) *Operation

StartOperation starts an HTTP 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 (*Operation) AddSecurityEvent

func (op *Operation) AddSecurityEvent(event json.RawMessage)

AddSecurityEvent adds the security event to the list of events observed during the operation lifetime.

func (*Operation) Finish

func (op *Operation) Finish(res HandlerOperationRes) json.RawMessage

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