get-sampled-requests¶
Description¶
Gets detailed information about a specified number of requests–a sample–that WAF randomly selects from among the first 5,000 requests that your Amazon Web Services resource received during a time range that you choose. You can specify a sample size of up to 500 requests, and you can specify any time range in the previous three hours.
GetSampledRequestsreturns a time range, which is usually the time range that you specified. However, if your resource (such as a CloudFront distribution) received 5,000 requests before the specified time range elapsed,GetSampledRequestsreturns an updated time range. This new time range indicates the actual period during which WAF selected the requests in the sample.
See also: AWS API Documentation
See ‘aws help’ for descriptions of global parameters.
Synopsis¶
get-sampled-requests
--web-acl-arn <value>
--rule-metric-name <value>
--scope <value>
--time-window <value>
--max-items <value>
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
Options¶
--web-acl-arn (string)
The Amazon resource name (ARN) of the
WebACLfor which you want a sample of requests.
--rule-metric-name (string)
The metric name assigned to the
RuleorRuleGroupfor which you want a sample of requests.
--scope (string)
Specifies whether this is for an Amazon CloudFront distribution or for a regional application. A regional application can be an Application Load Balancer (ALB), an Amazon API Gateway REST API, an AppSync GraphQL API, or an Amazon Cognito user pool.
To work with CloudFront, you must also specify the Region US East (N. Virginia) as follows:
CLI - Specify the Region when you use the CloudFront scope:
--scope=CLOUDFRONT --region=us-east-1.API and SDKs - For all calls, use the Region endpoint us-east-1.
Possible values:
CLOUDFRONT
REGIONAL
--time-window (structure)
The start date and time and the end date and time of the range for which you want
GetSampledRequeststo return a sample of requests. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator,Z. For example,"2016-09-27T14:50Z". You can specify any time range in the previous three hours. If you specify a start time that’s earlier than three hours ago, WAF sets it to three hours ago.StartTime -> (timestamp)
The beginning of the time range from which you want
GetSampledRequeststo return a sample of the requests that your Amazon Web Services resource received. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator,Z. For example,"2016-09-27T14:50Z". You can specify any time range in the previous three hours.EndTime -> (timestamp)
The end of the time range from which you want
GetSampledRequeststo return a sample of the requests that your Amazon Web Services resource received. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator,Z. For example,"2016-09-27T14:50Z". You can specify any time range in the previous three hours.
Shorthand Syntax:
StartTime=timestamp,EndTime=timestamp
JSON Syntax:
{
"StartTime": timestamp,
"EndTime": timestamp
}
--max-items (long)
The number of requests that you want WAF to return from among the first 5,000 requests that your Amazon Web Services resource received during the time range. If your resource received fewer requests than the value of
MaxItems,GetSampledRequestsreturns information about all of them.
--cli-input-json | --cli-input-yaml (string)
Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.
--generate-cli-skeleton (string)
Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.
See ‘aws help’ for descriptions of global parameters.
Examples¶
Note
To use the following examples, you must have the AWS CLI installed and configured. See the Getting started guide in the AWS CLI User Guide for more information.
Unless otherwise stated, all examples have unix-like quotation rules. These examples will need to be adapted to your terminal’s quoting rules. See Using quotation marks with strings in the AWS CLI User Guide .
To retrieve a sample of web requests for a web ACL
The following get-sampled-requests retrieves the sampled web requests for the specified web ACL, rule metric, and time frame.
aws wafv2 get-sampled-requests \
--web-acl-arn arn:aws:wafv2:us-west-2:123456789012:regional/webacl/test-cli/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--rule-metric-name AWS-AWSManagedRulesSQLiRuleSet \
--scope=REGIONAL \
--time-window StartTime=2020-02-12T20:00Z,EndTime=2020-02-12T21:10Z \
--max-items 100
Output:
{
"TimeWindow": {
"EndTime": 1581541800.0,
"StartTime": 1581537600.0
},
"SampledRequests": [
{
"Action": "BLOCK",
"Timestamp": 1581541799.564,
"RuleNameWithinRuleGroup": "AWS#AWSManagedRulesSQLiRuleSet#SQLi_BODY",
"Request": {
"Country": "US",
"URI": "/",
"Headers": [
{
"Name": "Host",
"Value": "alb-test-1EXAMPLE1.us-east-1.elb.amazonaws.com"
},
{
"Name": "Content-Length",
"Value": "7456"
},
{
"Name": "User-Agent",
"Value": "curl/7.53.1"
},
{
"Name": "Accept",
"Value": "/"
},
{
"Name": "Content-Type",
"Value": "application/x-www-form-urlencoded"
}
],
"ClientIP": "198.51.100.08",
"Method": "POST",
"HTTPVersion": "HTTP/1.1"
},
"Weight": 1
},
{
"Action": "BLOCK",
"Timestamp": 1581541799.988,
"RuleNameWithinRuleGroup": "AWS#AWSManagedRulesSQLiRuleSet#SQLi_BODY",
"Request": {
"Country": "US",
"URI": "/",
"Headers": [
{
"Name": "Host",
"Value": "alb-test-1EXAMPLE1.us-east-1.elb.amazonaws.com"
},
{
"Name": "Content-Length",
"Value": "7456"
},
{
"Name": "User-Agent",
"Value": "curl/7.53.1"
},
{
"Name": "Accept",
"Value": "/"
},
{
"Name": "Content-Type",
"Value": "application/x-www-form-urlencoded"
}
],
"ClientIP": "198.51.100.08",
"Method": "POST",
"HTTPVersion": "HTTP/1.1"
},
"Weight": 3
},
{
"Action": "BLOCK",
"Timestamp": 1581541799.846,
"RuleNameWithinRuleGroup": "AWS#AWSManagedRulesSQLiRuleSet#SQLi_BODY",
"Request": {
"Country": "US",
"URI": "/",
"Headers": [
{
"Name": "Host",
"Value": "alb-test-1EXAMPLE1.us-east-1.elb.amazonaws.com"
},
{
"Name": "Content-Length",
"Value": "7456"
},
{
"Name": "User-Agent",
"Value": "curl/7.53.1"
},
{
"Name": "Accept",
"Value": "/"
},
{
"Name": "Content-Type",
"Value": "application/x-www-form-urlencoded"
}
],
"ClientIP": "198.51.100.08",
"Method": "POST",
"HTTPVersion": "HTTP/1.1"
},
"Weight": 1
},
{
"Action": "BLOCK",
"Timestamp": 1581541799.4,
"RuleNameWithinRuleGroup": "AWS#AWSManagedRulesSQLiRuleSet#SQLi_BODY",
"Request": {
"Country": "US",
"URI": "/",
"Headers": [
{
"Name": "Host",
"Value": "alb-test-1EXAMPLE1.us-east-1.elb.amazonaws.com"
},
{
"Name": "Content-Length",
"Value": "7456"
},
{
"Name": "User-Agent",
"Value": "curl/7.53.1"
},
{
"Name": "Accept",
"Value": "/"
},
{
"Name": "Content-Type",
"Value": "application/x-www-form-urlencoded"
}
],
"ClientIP": "198.51.100.08",
"Method": "POST",
"HTTPVersion": "HTTP/1.1"
},
"Weight": 1
}
],
"PopulationSize": 4
}
For more information, see Viewing a Sample of Web Requests in the AWS WAF, AWS Firewall Manager, and AWS Shield Advanced Developer Guide.
Output¶
SampledRequests -> (list)
A complex type that contains detailed information about each of the requests in the sample.
(structure)
Represents a single sampled web request. The response from GetSampledRequests includes a
SampledHTTPRequestscomplex type that appears asSampledRequestsin the response syntax.SampledHTTPRequestscontains an array ofSampledHTTPRequestobjects.Request -> (structure)
A complex type that contains detailed information about the request.
ClientIP -> (string)
The IP address that the request originated from. If the web ACL is associated with a CloudFront distribution, this is the value of one of the following fields in CloudFront access logs:
c-ip, if the viewer did not use an HTTP proxy or a load balancer to send the request
x-forwarded-for, if the viewer did use an HTTP proxy or a load balancer to send the requestCountry -> (string)
The two-letter country code for the country that the request originated from. For a current list of country codes, see the Wikipedia entry ISO 3166-1 alpha-2 .
URI -> (string)
The URI path of the request, which identifies the resource, for example,
/images/daily-ad.jpg.Method -> (string)
The HTTP method specified in the sampled web request.
HTTPVersion -> (string)
The HTTP version specified in the sampled web request, for example,
HTTP/1.1.Headers -> (list)
A complex type that contains the name and value for each header in the sampled web request.
(structure)
Part of the response from GetSampledRequests . This is a complex type that appears as
Headersin the response syntax.HTTPHeadercontains the names and values of all of the headers that appear in one of the web requests.Name -> (string)
The name of the HTTP header.
Value -> (string)
The value of the HTTP header.
Weight -> (long)
A value that indicates how one result in the response relates proportionally to other results in the response. For example, a result that has a weight of
2represents roughly twice as many web requests as a result that has a weight of1.Timestamp -> (timestamp)
The time at which WAF received the request from your Amazon Web Services resource, in Unix time format (in seconds).
Action -> (string)
The action for the
Rulethat the request matched:Allow,Block, orCount.RuleNameWithinRuleGroup -> (string)
The name of the
Rulethat the request matched. For managed rule groups, the format for this name is<vendor name>#<managed rule group name>#<rule name>. For your own rule groups, the format for this name is<rule group name>#<rule name>. If the rule is not in a rule group, this field is absent.RequestHeadersInserted -> (list)
Custom request headers inserted by WAF into the request, according to the custom request configuration for the matching rule action.
(structure)
Part of the response from GetSampledRequests . This is a complex type that appears as
Headersin the response syntax.HTTPHeadercontains the names and values of all of the headers that appear in one of the web requests.Name -> (string)
The name of the HTTP header.
Value -> (string)
The value of the HTTP header.
ResponseCodeSent -> (integer)
The response code that was sent for the request.
Labels -> (list)
Labels applied to the web request by matching rules. WAF applies fully qualified labels to matching web requests. A fully qualified label is the concatenation of a label namespace and a rule label. The rule’s rule group or web ACL defines the label namespace.
For example,
awswaf:111122223333:myRuleGroup:testRules:testNS1:testNS2:labelNameAorawswaf:managed:aws:managed-rule-set:header:encoding:utf8.(structure)
A single label container. This is used as an element of a label array in multiple contexts, for example, in
RuleLabelsinside a Rule and inLabelsinside a SampledHTTPRequest .Name -> (string)
The label string.
CaptchaResponse -> (structure)
The
CAPTCHAresponse for the request.ResponseCode -> (integer)
The HTTP response code indicating the status of the
CAPTCHAtoken in the web request. If the token is missing, invalid, or expired, this code is405 Method Not Allowed.SolveTimestamp -> (long)
The time that the
CAPTCHApuzzle was solved for the supplied token.FailureReason -> (string)
The reason for failure, populated when the evaluation of the token fails.
PopulationSize -> (long)
The total number of requests from which
GetSampledRequestsgot a sample ofMaxItemsrequests. IfPopulationSizeis less thanMaxItems, the sample includes every request that your Amazon Web Services resource received during the specified time range.
TimeWindow -> (structure)
Usually,
TimeWindowis the time range that you specified in theGetSampledRequestsrequest. However, if your Amazon Web Services resource received more than 5,000 requests during the time range that you specified in the request,GetSampledRequestsreturns the time range for the first 5,000 requests. Times are in Coordinated Universal Time (UTC) format.StartTime -> (timestamp)
The beginning of the time range from which you want
GetSampledRequeststo return a sample of the requests that your Amazon Web Services resource received. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator,Z. For example,"2016-09-27T14:50Z". You can specify any time range in the previous three hours.EndTime -> (timestamp)
The end of the time range from which you want
GetSampledRequeststo return a sample of the requests that your Amazon Web Services resource received. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator,Z. For example,"2016-09-27T14:50Z". You can specify any time range in the previous three hours.