Class CfnRuleGroup.RateBasedStatementProperty
A rate-based rule counts incoming requests and rate limits requests when they are coming at too fast a rate.
Inheritance
Implements
Namespace: Amazon.CDK.AWS.WAFv2
Assembly: Amazon.CDK.Lib.dll
Syntax (csharp)
public class RateBasedStatementProperty : Object, CfnRuleGroup.IRateBasedStatementProperty
Syntax (vb)
Public Class RateBasedStatementProperty
Inherits Object
Implements CfnRuleGroup.IRateBasedStatementProperty
Remarks
The rule categorizes requests according to your aggregation criteria, collects them into aggregation instances, and counts and rate limits the requests for each instance.
If you change any of these settings in a rule that's currently in use, the change resets the rule's rate limiting counts. This can pause the rule's rate limiting activities for up to a minute.
You can specify individual aggregation keys, like IP address or HTTP method. You can also specify aggregation key combinations, like IP address and HTTP method, or HTTP method, query argument, and cookie.
Each unique set of values for the aggregation keys that you specify is a separate aggregation instance, with the value from each key contributing to the aggregation instance definition.
For example, assume the rule evaluates web requests with the following IP address and HTTP method values:
The rule would create different aggregation instances according to your aggregation criteria, for example:
For any n-tuple of aggregation keys, each unique combination of values for the keys defines a separate aggregation instance, which AWS WAF counts and rate-limits individually.
You can optionally nest another statement inside the rate-based statement, to narrow the scope of the rule so that it only counts and rate limits requests that match the nested statement. You can use this nested scope-down statement in conjunction with your aggregation key specifications or you can just count and rate limit all requests that match the scope-down statement, without additional aggregation. When you choose to just manage all requests that match a scope-down statement, the aggregation instance is singular for the rule.
You cannot nest a RateBasedStatement
inside another statement, for example inside a NotStatement
or OrStatement
. You can define a RateBasedStatement
inside a web ACL and inside a rule group.
For additional information about the options, see Rate limiting web requests using rate-based rules in the AWS WAF Developer Guide .
If you only aggregate on the individual IP address or forwarded IP address, you can retrieve the list of IP addresses that AWS WAF is currently rate limiting for a rule through the API call GetRateBasedStatementManagedKeys
. This option is not available for other aggregation configurations.
AWS WAF tracks and manages web requests separately for each instance of a rate-based rule that you use. For example, if you provide the same rate-based rule settings in two web ACLs, each of the two rule statements represents a separate instance of the rate-based rule and gets its own tracking and management by AWS WAF . If you define a rate-based rule inside a rule group, and then use that rule group in multiple places, each use creates a separate instance of the rate-based rule that gets its own tracking and management by AWS WAF .
ExampleMetadata: fixture=_generated
Examples
// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
using Amazon.CDK.AWS.WAFv2;
var all;
var allQueryArguments;
var forwardedIp;
var httpMethod;
var ip;
var method;
var queryString;
RateBasedStatementProperty rateBasedStatementProperty_;
var singleHeader;
var singleQueryArgument;
StatementProperty statementProperty_;
var uriPath;
var rateBasedStatementProperty = new RateBasedStatementProperty {
AggregateKeyType = "aggregateKeyType",
Limit = 123,
// the properties below are optional
CustomKeys = new [] { new RateBasedStatementCustomKeyProperty {
Cookie = new RateLimitCookieProperty {
Name = "name",
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} }
},
ForwardedIp = forwardedIp,
Header = new RateLimitHeaderProperty {
Name = "name",
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} }
},
HttpMethod = httpMethod,
Ip = ip,
LabelNamespace = new RateLimitLabelNamespaceProperty {
Namespace = "namespace"
},
QueryArgument = new RateLimitQueryArgumentProperty {
Name = "name",
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} }
},
QueryString = new RateLimitQueryStringProperty {
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} }
},
UriPath = new RateLimitUriPathProperty {
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} }
}
} },
EvaluationWindowSec = 123,
ForwardedIpConfig = new ForwardedIPConfigurationProperty {
FallbackBehavior = "fallbackBehavior",
HeaderName = "headerName"
},
ScopeDownStatement = new StatementProperty {
AndStatement = new AndStatementProperty {
Statements = new [] { statementProperty_ }
},
ByteMatchStatement = new ByteMatchStatementProperty {
FieldToMatch = new FieldToMatchProperty {
AllQueryArguments = allQueryArguments,
Body = new BodyProperty {
OversizeHandling = "oversizeHandling"
},
Cookies = new CookiesProperty {
MatchPattern = new CookieMatchPatternProperty {
All = all,
ExcludedCookies = new [] { "excludedCookies" },
IncludedCookies = new [] { "includedCookies" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Headers = new HeadersProperty {
MatchPattern = new HeaderMatchPatternProperty {
All = all,
ExcludedHeaders = new [] { "excludedHeaders" },
IncludedHeaders = new [] { "includedHeaders" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Ja3Fingerprint = new JA3FingerprintProperty {
FallbackBehavior = "fallbackBehavior"
},
JsonBody = new JsonBodyProperty {
MatchPattern = new JsonMatchPatternProperty {
All = all,
IncludedPaths = new [] { "includedPaths" }
},
MatchScope = "matchScope",
// the properties below are optional
InvalidFallbackBehavior = "invalidFallbackBehavior",
OversizeHandling = "oversizeHandling"
},
Method = method,
QueryString = queryString,
SingleHeader = singleHeader,
SingleQueryArgument = singleQueryArgument,
UriPath = uriPath
},
PositionalConstraint = "positionalConstraint",
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} },
// the properties below are optional
SearchString = "searchString",
SearchStringBase64 = "searchStringBase64"
},
GeoMatchStatement = new GeoMatchStatementProperty {
CountryCodes = new [] { "countryCodes" },
ForwardedIpConfig = new ForwardedIPConfigurationProperty {
FallbackBehavior = "fallbackBehavior",
HeaderName = "headerName"
}
},
IpSetReferenceStatement = new Dictionary<string, object> {
{ "arn", "arn" },
// the properties below are optional
{ "ipSetForwardedIpConfig", new Dictionary<string, string> {
{ "fallbackBehavior", "fallbackBehavior" },
{ "headerName", "headerName" },
{ "position", "position" }
} }
},
LabelMatchStatement = new LabelMatchStatementProperty {
Key = "key",
Scope = "scope"
},
NotStatement = new NotStatementProperty {
Statement = statementProperty_
},
OrStatement = new OrStatementProperty {
Statements = new [] { statementProperty_ }
},
RateBasedStatement = rateBasedStatementProperty_,
RegexMatchStatement = new RegexMatchStatementProperty {
FieldToMatch = new FieldToMatchProperty {
AllQueryArguments = allQueryArguments,
Body = new BodyProperty {
OversizeHandling = "oversizeHandling"
},
Cookies = new CookiesProperty {
MatchPattern = new CookieMatchPatternProperty {
All = all,
ExcludedCookies = new [] { "excludedCookies" },
IncludedCookies = new [] { "includedCookies" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Headers = new HeadersProperty {
MatchPattern = new HeaderMatchPatternProperty {
All = all,
ExcludedHeaders = new [] { "excludedHeaders" },
IncludedHeaders = new [] { "includedHeaders" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Ja3Fingerprint = new JA3FingerprintProperty {
FallbackBehavior = "fallbackBehavior"
},
JsonBody = new JsonBodyProperty {
MatchPattern = new JsonMatchPatternProperty {
All = all,
IncludedPaths = new [] { "includedPaths" }
},
MatchScope = "matchScope",
// the properties below are optional
InvalidFallbackBehavior = "invalidFallbackBehavior",
OversizeHandling = "oversizeHandling"
},
Method = method,
QueryString = queryString,
SingleHeader = singleHeader,
SingleQueryArgument = singleQueryArgument,
UriPath = uriPath
},
RegexString = "regexString",
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} }
},
RegexPatternSetReferenceStatement = new RegexPatternSetReferenceStatementProperty {
Arn = "arn",
FieldToMatch = new FieldToMatchProperty {
AllQueryArguments = allQueryArguments,
Body = new BodyProperty {
OversizeHandling = "oversizeHandling"
},
Cookies = new CookiesProperty {
MatchPattern = new CookieMatchPatternProperty {
All = all,
ExcludedCookies = new [] { "excludedCookies" },
IncludedCookies = new [] { "includedCookies" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Headers = new HeadersProperty {
MatchPattern = new HeaderMatchPatternProperty {
All = all,
ExcludedHeaders = new [] { "excludedHeaders" },
IncludedHeaders = new [] { "includedHeaders" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Ja3Fingerprint = new JA3FingerprintProperty {
FallbackBehavior = "fallbackBehavior"
},
JsonBody = new JsonBodyProperty {
MatchPattern = new JsonMatchPatternProperty {
All = all,
IncludedPaths = new [] { "includedPaths" }
},
MatchScope = "matchScope",
// the properties below are optional
InvalidFallbackBehavior = "invalidFallbackBehavior",
OversizeHandling = "oversizeHandling"
},
Method = method,
QueryString = queryString,
SingleHeader = singleHeader,
SingleQueryArgument = singleQueryArgument,
UriPath = uriPath
},
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} }
},
SizeConstraintStatement = new SizeConstraintStatementProperty {
ComparisonOperator = "comparisonOperator",
FieldToMatch = new FieldToMatchProperty {
AllQueryArguments = allQueryArguments,
Body = new BodyProperty {
OversizeHandling = "oversizeHandling"
},
Cookies = new CookiesProperty {
MatchPattern = new CookieMatchPatternProperty {
All = all,
ExcludedCookies = new [] { "excludedCookies" },
IncludedCookies = new [] { "includedCookies" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Headers = new HeadersProperty {
MatchPattern = new HeaderMatchPatternProperty {
All = all,
ExcludedHeaders = new [] { "excludedHeaders" },
IncludedHeaders = new [] { "includedHeaders" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Ja3Fingerprint = new JA3FingerprintProperty {
FallbackBehavior = "fallbackBehavior"
},
JsonBody = new JsonBodyProperty {
MatchPattern = new JsonMatchPatternProperty {
All = all,
IncludedPaths = new [] { "includedPaths" }
},
MatchScope = "matchScope",
// the properties below are optional
InvalidFallbackBehavior = "invalidFallbackBehavior",
OversizeHandling = "oversizeHandling"
},
Method = method,
QueryString = queryString,
SingleHeader = singleHeader,
SingleQueryArgument = singleQueryArgument,
UriPath = uriPath
},
Size = 123,
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} }
},
SqliMatchStatement = new SqliMatchStatementProperty {
FieldToMatch = new FieldToMatchProperty {
AllQueryArguments = allQueryArguments,
Body = new BodyProperty {
OversizeHandling = "oversizeHandling"
},
Cookies = new CookiesProperty {
MatchPattern = new CookieMatchPatternProperty {
All = all,
ExcludedCookies = new [] { "excludedCookies" },
IncludedCookies = new [] { "includedCookies" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Headers = new HeadersProperty {
MatchPattern = new HeaderMatchPatternProperty {
All = all,
ExcludedHeaders = new [] { "excludedHeaders" },
IncludedHeaders = new [] { "includedHeaders" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Ja3Fingerprint = new JA3FingerprintProperty {
FallbackBehavior = "fallbackBehavior"
},
JsonBody = new JsonBodyProperty {
MatchPattern = new JsonMatchPatternProperty {
All = all,
IncludedPaths = new [] { "includedPaths" }
},
MatchScope = "matchScope",
// the properties below are optional
InvalidFallbackBehavior = "invalidFallbackBehavior",
OversizeHandling = "oversizeHandling"
},
Method = method,
QueryString = queryString,
SingleHeader = singleHeader,
SingleQueryArgument = singleQueryArgument,
UriPath = uriPath
},
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} },
// the properties below are optional
SensitivityLevel = "sensitivityLevel"
},
XssMatchStatement = new XssMatchStatementProperty {
FieldToMatch = new FieldToMatchProperty {
AllQueryArguments = allQueryArguments,
Body = new BodyProperty {
OversizeHandling = "oversizeHandling"
},
Cookies = new CookiesProperty {
MatchPattern = new CookieMatchPatternProperty {
All = all,
ExcludedCookies = new [] { "excludedCookies" },
IncludedCookies = new [] { "includedCookies" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Headers = new HeadersProperty {
MatchPattern = new HeaderMatchPatternProperty {
All = all,
ExcludedHeaders = new [] { "excludedHeaders" },
IncludedHeaders = new [] { "includedHeaders" }
},
MatchScope = "matchScope",
OversizeHandling = "oversizeHandling"
},
Ja3Fingerprint = new JA3FingerprintProperty {
FallbackBehavior = "fallbackBehavior"
},
JsonBody = new JsonBodyProperty {
MatchPattern = new JsonMatchPatternProperty {
All = all,
IncludedPaths = new [] { "includedPaths" }
},
MatchScope = "matchScope",
// the properties below are optional
InvalidFallbackBehavior = "invalidFallbackBehavior",
OversizeHandling = "oversizeHandling"
},
Method = method,
QueryString = queryString,
SingleHeader = singleHeader,
SingleQueryArgument = singleQueryArgument,
UriPath = uriPath
},
TextTransformations = new [] { new TextTransformationProperty {
Priority = 123,
Type = "type"
} }
}
}
};
Synopsis
Constructors
RateBasedStatementProperty() |
Properties
AggregateKeyType | Setting that indicates how to aggregate the request counts. |
CustomKeys | Specifies the aggregate keys to use in a rate-base rule. |
EvaluationWindowSec | The amount of time, in seconds, that AWS WAF should include in its request counts, looking back from the current time. |
ForwardedIpConfig | The configuration for inspecting IP addresses in an HTTP header that you specify, instead of using the IP address that's reported by the web request origin. |
Limit | The limit on requests per 5-minute period for a single aggregation instance for the rate-based rule. |
ScopeDownStatement | An optional nested statement that narrows the scope of the web requests that are evaluated and managed by the rate-based statement. |
Constructors
RateBasedStatementProperty()
public RateBasedStatementProperty()
Properties
AggregateKeyType
Setting that indicates how to aggregate the request counts.
public string AggregateKeyType { get; set; }
Property Value
System.String
Remarks
Web requests that are missing any of the components specified in the aggregation keys are omitted from the rate-based rule evaluation and handling.
With this option, you must configure the ScopeDownStatement
property.
With this option, you must specify the aggregate keys in the CustomKeys
property.
To aggregate on only the IP address or only the forwarded IP address, don't use custom keys. Instead, set the aggregate key type to IP
or FORWARDED_IP
.
With this option, you must specify the header to use in the ForwardedIPConfig
property.
To aggregate on a combination of the forwarded IP address with other aggregate keys, use CUSTOM_KEYS
.
To aggregate on a combination of the IP address with other aggregate keys, use CUSTOM_KEYS
.
CustomKeys
Specifies the aggregate keys to use in a rate-base rule.
public object CustomKeys { get; set; }
Property Value
System.Object
Remarks
EvaluationWindowSec
The amount of time, in seconds, that AWS WAF should include in its request counts, looking back from the current time.
public Nullable<double> EvaluationWindowSec { get; set; }
Property Value
System.Nullable<System.Double>
Remarks
For example, for a setting of 120, when AWS WAF checks the rate, it counts the requests for the 2 minutes immediately preceding the current time. Valid settings are 60, 120, 300, and 600.
This setting doesn't determine how often AWS WAF checks the rate, but how far back it looks each time it checks. AWS WAF checks the rate about every 10 seconds.
Default: 300
(5 minutes)
ForwardedIpConfig
The configuration for inspecting IP addresses in an HTTP header that you specify, instead of using the IP address that's reported by the web request origin.
public object ForwardedIpConfig { get; set; }
Property Value
System.Object
Remarks
Commonly, this is the X-Forwarded-For (XFF) header, but you can specify any header name.
If the specified header isn't present in the request, AWS WAF doesn't apply the rule to the web request at all.
This is required if you specify a forwarded IP in the rule's aggregate key settings.
Limit
The limit on requests per 5-minute period for a single aggregation instance for the rate-based rule.
public double Limit { get; set; }
Property Value
System.Double
Remarks
If the rate-based statement includes a ScopeDownStatement
, this limit is applied only to the requests that match the statement.
Examples:
ScopeDownStatement
An optional nested statement that narrows the scope of the web requests that are evaluated and managed by the rate-based statement.
public object ScopeDownStatement { get; set; }
Property Value
System.Object
Remarks
When you use a scope-down statement, the rate-based rule only tracks and rate limits requests that match the scope-down statement. You can use any nestable Statement
in the scope-down statement, and you can nest statements at any level, the same as you can for a rule statement.