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 NormalizeHTTPHeaders(headers map[string][]string) (normalized map[string]string)
• func SetSecurityEventsTags(span instrumentation.TagSetter, events []json.RawMessage)
• func WrapHandler(handler http.Handler, span ddtrace.Span, pathParams map[string]string, ...) http.Handler
• type Action
• type ActionsHandler
  • func NewActionsHandler() *ActionsHandler
  • func (h *ActionsHandler) Apply(id string, op *Operation) bool
  • func (h *ActionsHandler) RegisterAction(id string, a Action)
• type BlockRequestAction
  • func NewBlockRequestAction(status int, template string) BlockRequestAction
• type BodyMonitoringError
  • func NewBodyMonitoringError(msg string) *BodyMonitoringError
• type HandlerOperationArgs
  • func MakeHandlerOperationArgs(r *http.Request, clientIP netip.Addr, pathParams map[string]string) HandlerOperationArgs
• type HandlerOperationRes
  • func MakeHandlerOperationRes(w http.ResponseWriter) 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 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) Actions() []Action
  • func (op *Operation) AddAction(a Action)
  • func (op *Operation) ClearActions()
  • func (op *Operation) Finish(res HandlerOperationRes) []json.RawMessage
• type SDKBodyOperation
  • func StartSDKBodyOperation(parent *Operation, args SDKBodyOperationArgs) *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 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 []json.RawMessage)

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 Action

type Action interface {
	// contains filtered or unexported methods
}

Action is used to identify any action kind

type ActionsHandler

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

ActionsHandler handles actions registration and their application to operations

func NewActionsHandler

func NewActionsHandler() *ActionsHandler

NewActionsHandler returns an action handler holding the default ASM actions. Currently, only the default "block" action is supported

func (*ActionsHandler) Apply

func (h *ActionsHandler) Apply(id string, op *Operation) bool

Apply applies the action identified by `id` for the given operation Returns true if the applied action will interrupt the request flow (block, redirect, etc...)

func (*ActionsHandler) RegisterAction

func (h *ActionsHandler) RegisterAction(id string, a Action)

RegisterAction registers a specific action to the handler. If the action kind is unknown the action will not be registered

type BlockRequestAction

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

BlockRequestAction is the action that holds the HTTP handler to use to block the request

func NewBlockRequestAction

func NewBlockRequestAction(status int, template string) BlockRequestAction

NewBlockRequestAction creates, initializes and returns a new BlockRequestAction

type BodyMonitoringError

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

BodyMonitoringError wraps an error interface to decorate it with additional appsec data, if needed

func NewBodyMonitoringError

func NewBodyMonitoringError(msg string) *BodyMonitoringError

NewBodyMonitoringError creates a new body sdk monitoring error that returns `msg` upon calling `Error()`

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 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) (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) Actions

func (op *Operation) Actions() []Action

Actions returns the actions linked to the operation

func (*Operation) AddAction

func (op *Operation) AddAction(a Action)

AddAction adds an action to the operation

func (*Operation) ClearActions

func (op *Operation) ClearActions()

ClearActions clears all the actions linked to the operation

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.

type SDKBodyOperation

type SDKBodyOperation struct {
	dyngo.Operation
	Error error
}

SDKBodyOperation type representing an SDK body. It must be created with StartSDKBodyOperation() and finished with its Finish() method.

func StartSDKBodyOperation

func StartSDKBodyOperation(parent *Operation, args SDKBodyOperationArgs) *SDKBodyOperation

StartSDKBodyOperation starts the SDKBody operation and emits a start event

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.