Documentation ¶
Index ¶
Constants ¶
const ( AppsecFieldTag = "ddwaf" AppsecFieldTagValueIgnore = "ignore" )
const ErrTimeout = wafErrors.ErrTimeout
ErrTimeout is the error returned when the WAF times out while processing a request. Deprecated: use github.com/DataDog/go-libddwaf/errors.ErrTimeout instead.
Variables ¶
This section is empty.
Functions ¶
func Health ¶ added in v2.2.0
Health returns true if the waf is usable, false otherwise. At the same time it can return an error if the waf is not usable, but the error is not blocking if true is returned, otherwise it is. The following conditions are checked: - The Waf library has been loaded successfully (you need to call `Load()` first for this case to be taken into account) - The Waf library has not been manually disabled with the `datadog.no_waf` go build tag - The Waf library is not in an unsupported OS/Arch - The Waf library is not in an unsupported Go version
func Load ¶
Load loads libddwaf's dynamic library. The dynamic library is opened only once by the first call to this function and internally stored globally, and no function is currently provided in this API to close the opened handle. Calling this function is not mandatory and is automatically performed by calls to NewHandle, the entrypoint of libddwaf, but Load is useful in order to explicitly check libddwaf's general health where calling NewHandle doesn't necessarily apply nor is doable. The function returns ok when libddwaf was successfully loaded, along with a non-nil error if any. Note that both ok and err can be set, meaning that libddwaf is usable but some non-critical errors happened, such as failures to remove temporary files. It is safe to continue using libddwaf in such case.
func SupportsTarget ¶
SupportsTarget returns true and a nil error when the target host environment is supported by this package and can be further used. Otherwise, it returns false along with an error detailing why.
Types ¶
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context is a WAF execution context. It allows running the WAF incrementally when calling it multiple times to run its rules every time new addresses become available. Each request must have its own Context.
func NewContext ¶
NewContext returns a new WAF context of to the given WAF handle. A nil value is returned when the WAF handle was released or when the WAF context couldn't be created. handle. A nil value is returned when the WAF handle can no longer be used or the WAF context couldn't be created.
func NewContextWithBudget ¶ added in v2.4.0
NewContextWithBudget returns a new WAF context of to the given WAF handle. A nil value is returned when the WAF handle was released or when the WAF context couldn't be created. handle. A nil value is returned when the WAF handle can no longer be used or the WAF context couldn't be created.
func (*Context) Close ¶
func (context *Context) Close()
Close the underlying `ddwaf_context` and releases the associated internal data. Also decreases the reference count of the `ddwaf_hadnle` which created this context, possibly releasing it completely (if this was the last context created from this handle & it was released by its creator).
func (*Context) Run ¶
Run encodes the given addressData values and runs them against the WAF rules within the given timeout value. If a given address is present both as persistent and ephemeral, the persistent value takes precedence. It returns the matches as a JSON string (usually opaquely used) along with the corresponding actions in any. In case of an error, matches and actions can still be returned, for instance in the case of a timeout error. Errors can be tested against the RunError type. Struct fields having the tag `ddwaf:"ignore"` will not be encoded and sent to the WAF if the output of TotalTime() exceeds the value of Timeout, the function will immediately return with errors.ErrTimeout The second parameter is deprecated and should be passed to NewContextWithBudget instead.
func (*Context) Stats ¶ added in v2.4.0
Stats returns the cumulative time spent in various parts of the WAF, all in nanoseconds and the timeout value used
func (*Context) TotalRuntime ¶
TotalRuntime returns the cumulated WAF runtime across various run calls within the same WAF context. Returned time is in nanoseconds. Deprecated: use Timings instead
func (*Context) TotalTimeouts ¶
TotalTimeouts returns the cumulated amount of WAF timeouts across various run calls within the same WAF context.
type DiagnosticAddresses ¶
DiagnosticAddresses stores the information - provided by the WAF - about the known addresses and whether they are required or optional. Addresses used by WAF rules are always required. Addresses used by WAF exclusion filters may be required or (rarely) optional. Addresses used by WAF processors may be required or optional.
type DiagnosticEntry ¶
type DiagnosticEntry struct { Addresses *DiagnosticAddresses Errors map[string][]string // Item-level errors (map of error message to entity identifiers or index:#) Error string // If the entire entry was in error (e.g: invalid format) Loaded []string // Successfully loaded entity identifiers (or index:#) Failed []string // Failed entity identifiers (or index:#) }
DiagnosticEntry stores the information - provided by the WAF - about loaded and failed rules for a specific entry in the WAF ruleset
type Diagnostics ¶
type Diagnostics struct { Rules *DiagnosticEntry CustomRules *DiagnosticEntry Exclusions *DiagnosticEntry RulesOverrides *DiagnosticEntry RulesData *DiagnosticEntry Processors *DiagnosticEntry Scanners *DiagnosticEntry Version string }
Diagnostics stores the information - provided by the WAF - about WAF rules initialization.
func (*Diagnostics) TopLevelError ¶ added in v2.2.0
func (d *Diagnostics) TopLevelError() error
TopLevelErrors returns the list of top-level errors reported by the WAF on any of the Diagnostics entries, rolled up into a single error value. Returns nil if no top-level errors were reported. Individual, item-level errors might still exist.
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle represents an instance of the WAF for a given ruleset.
func NewHandle ¶
NewHandle creates and returns a new instance of the WAF with the given security rules and configuration of the sensitive data obfuscator. The returned handle is nil in case of an error. Rules-related metrics, including errors, are accessible with the `RulesetInfo()` method.
func (*Handle) Close ¶
func (handle *Handle) Close()
Close puts the handle in termination state, when all the contexts are closed the handle will be destroyed
func (*Handle) Diagnostics ¶
func (handle *Handle) Diagnostics() Diagnostics
Diagnostics returns the rules initialization metrics for the current WAF handle
type Result ¶
type Result struct { // Events is the list of events the WAF detected, together with any relevant // details. Events []any // Derivatives is the set of key-value pairs generated by the WAF, and which // need to be reported on the trace to provide additional data to the backend. Derivatives map[string]any // Actions is the set of actions the WAF decided on when evaluating rules // against the provided address data. Actions []string // TimeSpent is the time the WAF self-reported as spent processing the call to ddwaf_run TimeSpent time.Duration }
Result stores the multiple values returned by a call to ddwaf_run
func (*Result) HasActions ¶
HasActions return true if the result holds at least 1 action
func (*Result) HasDerivatives ¶
HasDerivatives return true if the result holds at least 1 derivative
type RunAddressData ¶
type RunAddressData struct { // Persistent address data is scoped to the lifetime of a given Context, and subsquent calls to Context.Run with the // same address name will be silently ignored. Persistent map[string]any // Ephemeral address data is scoped to a given Context.Run call and is not persisted across calls. This is used for // protocols such as gRPC client/server streaming or GraphQL, where a single request can incur multiple subrequests. Ephemeral map[string]any }
RunAddressData provides address data to the Context.Run method. If a given key is present in both RunAddressData.Persistent and RunAddressData.Ephemeral, the value from RunAddressData.Persistent will take precedence.
type Stats ¶ added in v2.4.0
type Stats struct { // Timers returns a map of metrics and their durations. Timers map[string]time.Duration // Timeout TimeoutCount uint64 // Truncations provides details about truncations that occurred while // encoding address data for WAF execution. Truncations map[TruncationReason][]int }
Stats stores the metrics collected by the WAF.
type TruncationReason ¶ added in v2.3.0
type TruncationReason uint8
TruncationReason is a flag representing reasons why some input was not encoded in full.
const ( // StringTooLong indicates a string exceeded the maximum string length configured. The truncation // values indicate the actual length of truncated strings. StringTooLong TruncationReason = 1 << iota // ContainerTooLarge indicates a container (list, map, struct) exceeded the maximum number of // elements configured. The truncation values indicate the actual number of elements in the // truncated container. ContainerTooLarge // ObjectTooDeep indicates an overall object exceeded the maximum encoding depths configured. The // truncation values indicate an estimated actual depth of the truncated object. The value is // guaranteed to be less than or equal to the actual depth (it may not be more). ObjectTooDeep )
func (TruncationReason) String ¶ added in v2.4.0
func (reason TruncationReason) String() string