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 BeforeHandle(w http.ResponseWriter, r *http.Request, span ddtrace.Span, ...) (http.ResponseWriter, *http.Request, func(), bool)
• func MonitorParsedBody(ctx context.Context, body any) error
• func ProtectRoundTrip(ctx context.Context, url string) error
• func WrapHandler(handler http.Handler, span ddtrace.Span, pathParams map[string]string, ...) http.Handler
• type Config
• type HandlerOperation
  • func StartOperation(ctx context.Context, args HandlerOperationArgs) (*HandlerOperation, *atomic.Pointer[actions.BlockHTTP], context.Context)
  • func (op *HandlerOperation) Finish(res HandlerOperationRes, span ddtrace.Span)
• type HandlerOperationArgs
  • func (HandlerOperationArgs) IsArgOf(*HandlerOperation)
• type HandlerOperationRes
  • func (HandlerOperationRes) IsResultOf(*HandlerOperation)
• type RoundTripOperation
• type RoundTripOperationArgs
  • func (RoundTripOperationArgs) IsArgOf(*RoundTripOperation)
• type RoundTripOperationRes
  • func (RoundTripOperationRes) IsResultOf(*RoundTripOperation)

Functions

func BeforeHandle

func BeforeHandle(
	w http.ResponseWriter,
	r *http.Request,
	span ddtrace.Span,
	pathParams map[string]string,
	opts *Config,
) (http.ResponseWriter, *http.Request, func(), bool)

BeforeHandle contains the appsec functionality that should be executed before a http.Handler runs. It returns the modified http.ResponseWriter and http.Request, an additional afterHandle function that should be executed after the Handler runs, and a handled bool that instructs if the request has been handled or not - in case it was handled, the original handler should not run.

func MonitorParsedBody

func MonitorParsedBody(ctx context.Context, body any) 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 ProtectRoundTrip

func ProtectRoundTrip(ctx context.Context, url string) error

func WrapHandler

func WrapHandler(handler http.Handler, span ddtrace.Span, pathParams map[string]string, opts *Config) 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 Config

type Config struct {
	// OnBlock is a list of callbacks to be invoked when a block decision is made.
	OnBlock []func()
	// ResponseHeaderCopier provides a way to access response headers for reading
	// purposes (the value may be provided by copy). This allows customers to
	// apply synchronization if they allow http.ResponseWriter objects to be
	// accessed by multiple goroutines.
	ResponseHeaderCopier func(http.ResponseWriter) http.Header
}

type HandlerOperation

type HandlerOperation struct {
	dyngo.Operation
	*waf.ContextOperation
	// contains filtered or unexported fields
}

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

func (*HandlerOperation) Finish

func (op *HandlerOperation) Finish(res HandlerOperationRes, span ddtrace.Span)

Finish the HTTP handler operation and its children operations and write everything to the service entry span.

type HandlerOperationArgs

type HandlerOperationArgs struct {
	Method      string
	RequestURI  string
	Host        string
	RemoteAddr  string
	Headers     map[string][]string
	Cookies     map[string][]string
	QueryParams map[string][]string
	PathParams  map[string]string
}

HandlerOperationArgs is the HTTP handler operation arguments.

func (HandlerOperationArgs) IsArgOf

func (HandlerOperationArgs) IsArgOf(*HandlerOperation)

type HandlerOperationRes

type HandlerOperationRes struct {
	Headers    map[string][]string
	StatusCode int
}

HandlerOperationRes is the HTTP handler operation results.

func (HandlerOperationRes) IsResultOf

func (HandlerOperationRes) IsResultOf(*HandlerOperation)

type RoundTripOperation

type RoundTripOperation struct {
	dyngo.Operation
}

type RoundTripOperationArgs

type RoundTripOperationArgs struct {
	// URL corresponds to the address `server.io.net.url`.
	URL string
}

RoundTripOperationArgs is the round trip operation arguments.

func (RoundTripOperationArgs) IsArgOf

func (RoundTripOperationArgs) IsArgOf(*RoundTripOperation)

type RoundTripOperationRes

type RoundTripOperationRes struct{}

RoundTripOperationRes is the round trip operation results.

func (RoundTripOperationRes) IsResultOf

func (RoundTripOperationRes) IsResultOf(*RoundTripOperation)