Documentation
¶
Index ¶
- Constants
- func IsEnabledByEnvironment() (enabled bool, set bool, err error)
- func RASPEnabled() bool
- func RateLimitFromEnv() (rate int64)
- func RulesFromEnv() ([]byte, error)
- func WAFTimeoutFromEnv() (timeout time.Duration)
- type APISecConfig
- type APISecOption
- type AddressSet
- type Config
- type EnablementMode
- type ObfuscatorConfig
- type StartConfig
- type StartOption
- func WithAPISecOptions(opts ...APISecOption) StartOption
- func WithBlockingUnavailable(unavailable bool) StartOption
- func WithEnablementMode(mode EnablementMode) StartOption
- func WithMetaStructAvailable(available bool) StartOption
- func WithProxyEnvironment() StartOption
- func WithRCConfig(cfg remoteconfig.ClientConfig) StartOption
- type WAFManager
- func (m *WAFManager) AddOrUpdateConfig(path string, fragment any) (libddwaf.Diagnostics, error)
- func (m *WAFManager) Close()
- func (m *WAFManager) ConfigPaths(filter string) []string
- func (m *WAFManager) NewHandle() (*libddwaf.Handle, string)
- func (m *WAFManager) RemoveConfig(path string)
- func (m *WAFManager) RemoveDefaultConfig() bool
- func (m *WAFManager) Reset() error
- func (m *WAFManager) RestoreDefaultConfig() error
Constants ¶
const ( // EnvEnabled controls ASM Threats Protection's enablement. EnvEnabled = "DD_APPSEC_ENABLED" // EnvSCAEnabled controls ASM Software Composition Analysis (SCA)'s enablement. EnvSCAEnabled = "DD_APPSEC_SCA_ENABLED" )
The following environment variables dictate the enablement of different the ASM products.
const ( // EnvAPISecEnabled is the env var used to enable API Security EnvAPISecEnabled = "DD_API_SECURITY_ENABLED" // EnvAPISecSampleRate is the env var used to set the sampling rate of API Security schema extraction. // Deprecated: a new [APISecConfig.Sampler] is now used instead of this. EnvAPISecSampleRate = "DD_API_SECURITY_REQUEST_SAMPLE_RATE" // EnvAPISecProxySampleRate is the env var used to set the sampling rate of API Security schema extraction for proxies. // The value represents the number of schemas extracted per minute (samples per minute). EnvAPISecProxySampleRate = "DD_API_SECURITY_PROXY_SAMPLE_RATE" // EnvAPISecDownstreamRequestBodyAnalysisSampleRate Defines the probability of a downstream request body being sampled, // or said differently, defines the overall number of requests for which the request and response body should be sampled / analysed (50%). EnvAPISecDownstreamRequestBodyAnalysisSampleRate = "DD_API_SECURITY_DOWNSTREAM_REQUEST_BODY_ANALYSIS_SAMPLE_RATE" // EnvAPISecMaxDownstreamRequestBodyAnalysis The maximum number of downstream requests per request for which the request and response body should be analysed. EnvAPISecMaxDownstreamRequestBodyAnalysis = "DD_API_SECURITY_MAX_DOWNSTREAM_REQUEST_BODY_ANALYSIS" // EnvObfuscatorKey is the env var used to provide the WAF key obfuscation regexp EnvObfuscatorKey = "DD_APPSEC_OBFUSCATION_PARAMETER_KEY_REGEXP" // EnvObfuscatorValue is the env var used to provide the WAF value obfuscation regexp EnvObfuscatorValue = "DD_APPSEC_OBFUSCATION_PARAMETER_VALUE_REGEXP" // EnvWAFTimeout is the env var used to specify the timeout value for a WAF run EnvWAFTimeout = "DD_APPSEC_WAF_TIMEOUT" // EnvTraceRateLimit is the env var used to set the ASM trace limiting rate EnvTraceRateLimit = "DD_APPSEC_TRACE_RATE_LIMIT" // EnvRules is the env var used to provide a path to a local security rule file EnvRules = "DD_APPSEC_RULES" // EnvRASPEnabled is the env var used to enable/disable RASP functionalities for ASM EnvRASPEnabled = "DD_APPSEC_RASP_ENABLED" )
Configuration environment variables
const ( // DefaultAPISecSampleRate is the default rate at which API Security schemas are extracted from requests DefaultAPISecSampleRate = .1 // DefaultAPISecSampleInterval is the default interval between two samples being taken. DefaultAPISecSampleInterval = 30 * time.Second // DefaultAPISecProxySampleRate is the default rate (schemas per minute) at which API Security schemas are extracted from requests DefaultAPISecProxySampleRate = 300 // DefaultAPISecProxySampleInterval is the default time window for the API Security proxy sampler rate limiter. DefaultAPISecProxySampleInterval = time.Minute // DefaultDownstreamRequestBodyAnalysisSampleRate is the default sample rate for downstream request body analysis per incoming request. DefaultDownstreamRequestBodyAnalysisSampleRate = 0.5 // DefaultMaxDownstreamRequestBodyAnalysis is the default maximum size in bytes of downstream request body to be analyzed. DefaultMaxDownstreamRequestBodyAnalysis = 1 // DefaultObfuscatorKeyRegex is the default regexp used to obfuscate keys DefaultObfuscatorKeyRegex = `` /* 190-byte string literal not displayed */ // DefaultObfuscatorValueRegex is the default regexp used to obfuscate values DefaultObfuscatorValueRegex = `` /* 578-byte string literal not displayed */ // DefaultWAFTimeout is the default time limit past which a WAF run will timeout DefaultWAFTimeout = 2 * time.Millisecond // DefaultTraceRate is the default limit (trace/sec) past which ASM traces are sampled out DefaultTraceRate = 100 // up to 100 appsec traces/s )
Configuration constants and default values
Variables ¶
This section is empty.
Functions ¶
func IsEnabledByEnvironment ¶
IsEnabledByEnvironment returns true when appsec is enabled by the environment variable EnvEnabled being set to a truthy value, as well as whether the environment variable was set at all or not (so it is possible to distinguish between explicitly false, and false-by-default). If the EnvEnabled variable is set to a value that is not a valid boolean (according to strconv.ParseBool), it is considered false-y, and a detailed error is also returned.
func RASPEnabled ¶ added in v2.3.0
func RASPEnabled() bool
RASPEnabled returns true if RASP functionalities are enabled through the env, or if DD_APPSEC_RASP_ENABLED is not set
func RateLimitFromEnv ¶ added in v2.3.0
func RateLimitFromEnv() (rate int64)
RateLimitFromEnv reads and parses the trace rate limit set through the env If not set, it defaults to `DefaultTraceRate`
func RulesFromEnv ¶ added in v2.3.0
RulesFromEnv returns the security rules provided through the environment If the env var is not set, the default recommended rules are returned instead
func WAFTimeoutFromEnv ¶ added in v2.3.0
WAFTimeoutFromEnv reads and parses the WAF timeout value set through the env If not set, it defaults to `DefaultWAFTimeout`
Types ¶
type APISecConfig ¶ added in v2.3.0
type APISecConfig struct {
Sampler apisec.Sampler
Enabled bool
IsProxy bool
// Deprecated: use the new [APISecConfig.Sampler] instead.
SampleRate float64
// DownstreamRequestBodyAnalysisSampleRate is the sample rate for downstream request body analysis per incoming request.
DownstreamRequestBodyAnalysisSampleRate float64
// MaxDownstreamRequestBodyAnalysis is the maximum size in bytes of downstream request body to be analyzed.
MaxDownstreamRequestBodyAnalysis int
}
APISecConfig holds the configuration for API Security schemas reporting. It is used to enabled/disable the feature.
func NewAPISecConfig ¶ added in v2.3.0
func NewAPISecConfig(opts ...APISecOption) APISecConfig
NewAPISecConfig creates and returns a new API Security configuration by reading the env
type APISecOption ¶ added in v2.3.0
type APISecOption func(*APISecConfig)
func WithAPISecSampler ¶ added in v2.3.0
func WithAPISecSampler(sampler apisec.Sampler) APISecOption
WithAPISecSampler sets the sampler for the API Security configuration. This is useful for testing purposes.
func WithProxy ¶ added in v2.3.0
func WithProxy() APISecOption
WithProxy configures API Security for a proxy environment.
type AddressSet ¶
type AddressSet map[string]struct{}
AddressSet is a set of WAF addresses.
func NewAddressSet ¶
func NewAddressSet(addrs []string) AddressSet
func (AddressSet) AnyOf ¶
func (set AddressSet) AnyOf(anyOf ...string) bool
AnyOf returns true if any of the addresses in the set are in the given list.
type Config ¶
type Config struct {
*WAFManager
// WAFTimeout is the maximum WAF execution time
WAFTimeout time.Duration
// TraceRateLimit is the AppSec trace rate limit (traces per second).
TraceRateLimit int64
// APISec configuration
APISec APISecConfig
// RC is the remote configuration client used to receive product configuration updates. Nil if RC is disabled (default)
RC *remoteconfig.ClientConfig
// RASP determines whether RASP features are enabled or not.
RASP bool
// SupportedAddresses are the addresses that the AppSec listener will bind to.
SupportedAddresses AddressSet
// MetaStructAvailable is true if meta struct is supported by the trace agent.
MetaStructAvailable bool
BlockingUnavailable bool
// TracingAsTransport is true if APM is disabled and manually force keeping a trace is the only way for it to be sent.
TracingAsTransport bool
}
Config is the AppSec configuration.
type EnablementMode ¶
type EnablementMode int8
const ( // ForcedOff is the mode where AppSec is forced to be disabled, not allowing remote activation. ForcedOff EnablementMode = -1 // RCStandby is the mode where AppSec is in stand-by, waiting remote activation. RCStandby EnablementMode = 0 // ForcedOn is the mode where AppSec is forced to be enabled. ForcedOn EnablementMode = 1 )
type ObfuscatorConfig ¶ added in v2.3.0
ObfuscatorConfig wraps the key and value regexp to be passed to the WAF to perform obfuscation.
func NewObfuscatorConfig ¶ added in v2.3.0
func NewObfuscatorConfig() ObfuscatorConfig
NewObfuscatorConfig creates and returns a new WAF obfuscator configuration by reading the env
type StartConfig ¶
type StartConfig struct {
// RC is the remote config client configuration to be used.
RC *remoteconfig.ClientConfig
// IsEnabled is a function that determines whether AppSec is enabled or not. When unset, the
// default [IsEnabled] function is used.
EnablementMode func() (EnablementMode, telemetry.Origin, error)
// MetaStructAvailable is true if meta struct is supported by the trace agent.
MetaStructAvailable bool
APISecOptions []APISecOption
BlockingUnavailable bool
// ProxyEnvironment is true if the application is running in a proxy environment,
// such as within an Envoy External Processor.
ProxyEnvironment bool
}
func NewStartConfig ¶
func NewStartConfig(opts ...StartOption) *StartConfig
func (*StartConfig) NewConfig ¶
func (c *StartConfig) NewConfig() (*Config, error)
NewConfig returns a fresh appsec configuration read from the env
type StartOption ¶
type StartOption func(c *StartConfig)
StartOption is used to customize the AppSec configuration when invoked with appsec.Start()
func WithAPISecOptions ¶
func WithAPISecOptions(opts ...APISecOption) StartOption
func WithBlockingUnavailable ¶ added in v2.1.0
func WithBlockingUnavailable(unavailable bool) StartOption
func WithEnablementMode ¶
func WithEnablementMode(mode EnablementMode) StartOption
WithEnablementMode forces AppSec enablement, replacing the default initialization conditions implemented by IsEnabledByEnvironment.
func WithMetaStructAvailable ¶
func WithMetaStructAvailable(available bool) StartOption
func WithProxyEnvironment ¶ added in v2.1.0
func WithProxyEnvironment() StartOption
func WithRCConfig ¶
func WithRCConfig(cfg remoteconfig.ClientConfig) StartOption
WithRCConfig sets the AppSec remote config client configuration to the specified cfg
type WAFManager ¶ added in v2.1.0
type WAFManager struct {
// contains filtered or unexported fields
}
WAFManager holds a libddwaf.Builder and allows managing its configuration.
func NewWAFManager ¶ added in v2.1.0
func NewWAFManager(obfuscator ObfuscatorConfig) (*WAFManager, error)
NewWAFManager creates a new WAFManager with the provided config.ObfuscatorConfig and initial rules (if any).
func NewWAFManagerWithStaticRules ¶ added in v2.3.0
func NewWAFManagerWithStaticRules(obfuscator ObfuscatorConfig, staticRules []byte) (*WAFManager, error)
func (*WAFManager) AddOrUpdateConfig ¶ added in v2.1.0
func (m *WAFManager) AddOrUpdateConfig(path string, fragment any) (libddwaf.Diagnostics, error)
AddOrUpdateConfig adds or updates a configuration in the receiving WAFManager.
func (*WAFManager) Close ¶ added in v2.1.0
func (m *WAFManager) Close()
Close releases all resources associated with this WAFManager.
func (*WAFManager) ConfigPaths ¶ added in v2.1.0
func (m *WAFManager) ConfigPaths(filter string) []string
ConfigPaths returns the list of configuration paths currently loaded in the receiving WAFManager. This is typically used for testing purposes. An optional filter regular expression can be provided to limit what paths are returned.
func (*WAFManager) NewHandle ¶ added in v2.1.0
func (m *WAFManager) NewHandle() (*libddwaf.Handle, string)
NewHandle returns a new *libddwaf.Handle (which may be nil if no valid WAF could be built) and the version of the rules that were used to build it.
func (*WAFManager) RemoveConfig ¶ added in v2.1.0
func (m *WAFManager) RemoveConfig(path string)
RemoveConfig removes a configuration from the receiving WAFManager.
func (*WAFManager) RemoveDefaultConfig ¶ added in v2.1.0
func (m *WAFManager) RemoveDefaultConfig() bool
RemoveDefaultConfig removes the initial configuration from the receiving WAFManager. Returns true if the default config was actually removed; false otherwise (e.g, if it had previously been removed, or there was no default config to begin with).
func (*WAFManager) Reset ¶ added in v2.1.0
func (m *WAFManager) Reset() error
Reset resets the WAF manager to its initial state.
func (*WAFManager) RestoreDefaultConfig ¶ added in v2.1.0
func (m *WAFManager) RestoreDefaultConfig() error
RestoreDefaultConfig restores the initial configurations to the receiving WAFManager.