2017/11/30 - AWS WAF - 7 new 4 updated api methods
Changes This release adds support for rule group and managed rule group. Rule group is a container of rules that customers can create, put rules in it and associate the rule group to a WebACL. All rules in a rule group will function identically as they would if each rule was individually associated to the WebACL. Managed rule group is a pre-configured rule group composed by our security partners and made available via the AWS Marketplace. Customers can subscribe to these managed rule groups, associate the managed rule group to their WebACL and start using them immediately to protect their resources.
Inserts or deletes ActivatedRule objects in a RuleGroup .
You can only insert REGULAR rules into a rule group.
You can have a maximum of ten rules per rule group.
To create and configure a RuleGroup , perform the following steps:
Create and update the Rules that you want to include in the RuleGroup . See CreateRule.
Use GetChangeToken to get the change token that you provide in the ChangeToken parameter of an UpdateRuleGroup request.
Submit an UpdateRuleGroup request to add Rules to the RuleGroup .
Create and update a WebACL that contains the RuleGroup . See CreateWebACL.
If you want to replace one Rule with another, you delete the existing one and add the new one.
For more information about how to use the AWS WAF API to allow or block HTTP requests, see the AWS WAF Developer Guide.
See also: AWS API Documentation
Request Syntax
client.update_rule_group(
RuleGroupId='string',
Updates=[
{
'Action': 'INSERT'|'DELETE',
'ActivatedRule': {
'Priority': 123,
'RuleId': 'string',
'Action': {
'Type': 'BLOCK'|'ALLOW'|'COUNT'
},
'OverrideAction': {
'Type': 'NONE'|'COUNT'
},
'Type': 'REGULAR'|'RATE_BASED'|'GROUP'
}
},
],
ChangeToken='string'
)
string
[REQUIRED]
The RuleGroupId of the RuleGroup that you want to update. RuleGroupId is returned by CreateRuleGroup and by ListRuleGroups.
list
[REQUIRED]
An array of RuleGroupUpdate objects that you want to insert into or delete from a RuleGroup.
You can only insert REGULAR rules into a rule group.
The Action data type within ActivatedRule is used only when submitting an UpdateWebACL request. ActivatedRule|Action is not applicable and therefore not available for UpdateRuleGroup .
(dict) --
Specifies an ActivatedRule and indicates whether you want to add it to a RuleGroup or delete it from a RuleGroup .
Action (string) -- [REQUIRED]
Specify INSERT to add an ActivatedRule to a RuleGroup . Use DELETE to remove an ActivatedRule from a RuleGroup .
ActivatedRule (dict) -- [REQUIRED]
The ActivatedRule object specifies a Rule that you want to insert or delete, the priority of the Rule in the WebACL , and the action that you want AWS WAF to take when a web request matches the Rule ( ALLOW , BLOCK , or COUNT ).
Priority (integer) -- [REQUIRED]
Specifies the order in which the Rules in a WebACL are evaluated. Rules with a lower value for Priority are evaluated before Rules with a higher value. The value must be a unique integer. If you add multiple Rules to a WebACL , the values don't need to be consecutive.
RuleId (string) -- [REQUIRED]
The RuleId for a Rule . You use RuleId to get more information about a Rule (see GetRule ), update a Rule (see UpdateRule ), insert a Rule into a WebACL or delete a one from a WebACL (see UpdateWebACL ), or delete a Rule from AWS WAF (see DeleteRule ).
RuleId is returned by CreateRule and by ListRules.
Action (dict) --
Specifies the action that CloudFront or AWS WAF takes when a web request matches the conditions in the Rule . Valid values for Action include the following:
ALLOW : CloudFront responds with the requested object.
BLOCK : CloudFront responds with an HTTP 403 (Forbidden) status code.
COUNT : AWS WAF increments a counter of requests that match the conditions in the rule and then continues to inspect the web request based on the remaining rules in the web ACL.
The Action data type within ActivatedRule is used only when submitting an UpdateWebACL request. ActivatedRule|Action is not applicable and therefore not available for UpdateRuleGroup .
Type (string) -- [REQUIRED]
Specifies how you want AWS WAF to respond to requests that match the settings in a Rule . Valid settings include the following:
ALLOW : AWS WAF allows requests
BLOCK : AWS WAF blocks requests
COUNT : AWS WAF increments a counter of the requests that match all of the conditions in the rule. AWS WAF then continues to inspect the web request based on the remaining rules in the web ACL. You can't specify COUNT for the default action for a WebACL .
OverrideAction (dict) --
Use the OverrideAction to test your RuleGroup .
Any rule in a RuleGroup can potentially block a request. If you set the OverrideAction to None , the RuleGroup will block a request if any individual rule in the RuleGroup matches the request and is configured to block that request. However if you first want to test the RuleGroup , set the OverrideAction to Count . The RuleGroup will then override any block action specified by individual rules contained within the group. Instead of blocking matching requests, those requests will be counted. You can view a record of counted requests using GetSampledRequests.
The OverrideAction data type within ActivatedRule is used only when submitting an UpdateRuleGroup request. ActivatedRule|OverrideAction is not applicable and therefore not available for UpdateWebACL .
Type (string) -- [REQUIRED]
COUNT overrides the action specified by the individual rule within a RuleGroup . If set to NONE , the rule's action will take place.
Type (string) --
The rule type, either REGULAR , as defined by Rule, RATE_BASED , as defined by RateBasedRule, or GROUP , as defined by RuleGroup. The default is REGULAR. Although this field is optional, be aware that if you try to add a RATE_BASED rule to a web ACL without setting the type, the UpdateWebACL request will fail because the request tries to add a REGULAR rule with the specified ID, which does not exist.
string
[REQUIRED]
The value returned by the most recent call to GetChangeToken.
dict
Response Syntax
{
'ChangeToken': 'string'
}
Response Structure
(dict) --
ChangeToken (string) --
The ChangeToken that you used to submit the UpdateRuleGroup request. You can also use this value to query the status of the request. For more information, see GetChangeTokenStatus.
Creates a RuleGroup . A rule group is a collection of predefined rules that you add to a web ACL. You use UpdateRuleGroup to add rules to the rule group.
Rule groups are subject to the following limits:
Three rule groups per account. You can request an increase to this limit by contacting customer support.
One rule group per web ACL.
Ten rules per rule group.
For more information about how to use the AWS WAF API to allow or block HTTP requests, see the AWS WAF Developer Guide.
See also: AWS API Documentation
Request Syntax
client.create_rule_group(
Name='string',
MetricName='string',
ChangeToken='string'
)
string
[REQUIRED]
A friendly name or description of the RuleGroup. You can't change Name after you create a RuleGroup .
string
[REQUIRED]
A friendly name or description for the metrics for this RuleGroup . The name can contain only alphanumeric characters (A-Z, a-z, 0-9); the name can't contain whitespace. You can't change the name of the metric after you create the RuleGroup .
string
[REQUIRED]
The value returned by the most recent call to GetChangeToken.
dict
Response Syntax
{
'RuleGroup': {
'RuleGroupId': 'string',
'Name': 'string',
'MetricName': 'string'
},
'ChangeToken': 'string'
}
Response Structure
(dict) --
RuleGroup (dict) --
An empty RuleGroup.
RuleGroupId (string) --
A unique identifier for a RuleGroup . You use RuleGroupId to get more information about a RuleGroup (see GetRuleGroup ), update a RuleGroup (see UpdateRuleGroup ), insert a RuleGroup into a WebACL or delete a one from a WebACL (see UpdateWebACL ), or delete a RuleGroup from AWS WAF (see DeleteRuleGroup ).
RuleGroupId is returned by CreateRuleGroup and by ListRuleGroups.
Name (string) --
The friendly name or description for the RuleGroup . You can't change the name of a RuleGroup after you create it.
MetricName (string) --
A friendly name or description for the metrics for this RuleGroup . The name can contain only alphanumeric characters (A-Z, a-z, 0-9); the name can't contain whitespace. You can't change the name of the metric after you create the RuleGroup .
ChangeToken (string) --
The ChangeToken that you used to submit the CreateRuleGroup request. You can also use this value to query the status of the request. For more information, see GetChangeTokenStatus.
Returns an array of RuleGroup objects that you are subscribed to.
See also: AWS API Documentation
Request Syntax
client.list_subscribed_rule_groups(
NextMarker='string',
Limit=123
)
string
If you specify a value for Limit and you have more ByteMatchSets subscribed rule groups than the value of Limit , AWS WAF returns a NextMarker value in the response that allows you to list another group of subscribed rule groups. For the second and subsequent ListSubscribedRuleGroupsRequest requests, specify the value of NextMarker from the previous response to get information about another batch of subscribed rule groups.
integer
Specifies the number of subscribed rule groups that you want AWS WAF to return for this request. If you have more objects than the number you specify for Limit , the response includes a NextMarker value that you can use to get another batch of objects.
dict
Response Syntax
{
'NextMarker': 'string',
'RuleGroups': [
{
'RuleGroupId': 'string',
'Name': 'string',
'MetricName': 'string'
},
]
}
Response Structure
(dict) --
NextMarker (string) --
If you have more objects than the number that you specified for Limit in the request, the response includes a NextMarker value. To list more objects, submit another ListSubscribedRuleGroups request, and specify the NextMarker value from the response in the NextMarker value in the next request.
RuleGroups (list) --
An array of RuleGroup objects.
(dict) --
A summary of the rule groups you are subscribed to.
RuleGroupId (string) --
A unique identifier for a RuleGroup .
Name (string) --
A friendly name or description of the RuleGroup . You can't change the name of a RuleGroup after you create it.
MetricName (string) --
A friendly name or description for the metrics for this RuleGroup . The name can contain only alphanumeric characters (A-Z, a-z, 0-9); the name can't contain whitespace. You can't change the name of the metric after you create the RuleGroup .
Returns an array of ActivatedRule objects.
See also: AWS API Documentation
Request Syntax
client.list_activated_rules_in_rule_group(
RuleGroupId='string',
NextMarker='string',
Limit=123
)
string
The RuleGroupId of the RuleGroup for which you want to get a list of ActivatedRule objects.
string
If you specify a value for Limit and you have more ActivatedRules than the value of Limit , AWS WAF returns a NextMarker value in the response that allows you to list another group of ActivatedRules . For the second and subsequent ListActivatedRulesInRuleGroup requests, specify the value of NextMarker from the previous response to get information about another batch of ActivatedRules .
integer
Specifies the number of ActivatedRules that you want AWS WAF to return for this request. If you have more ActivatedRules than the number that you specify for Limit , the response includes a NextMarker value that you can use to get another batch of ActivatedRules .
dict
Response Syntax
{
'NextMarker': 'string',
'ActivatedRules': [
{
'Priority': 123,
'RuleId': 'string',
'Action': {
'Type': 'BLOCK'|'ALLOW'|'COUNT'
},
'OverrideAction': {
'Type': 'NONE'|'COUNT'
},
'Type': 'REGULAR'|'RATE_BASED'|'GROUP'
},
]
}
Response Structure
(dict) --
NextMarker (string) --
If you have more ActivatedRules than the number that you specified for Limit in the request, the response includes a NextMarker value. To list more ActivatedRules , submit another ListActivatedRulesInRuleGroup request, and specify the NextMarker value from the response in the NextMarker value in the next request.
ActivatedRules (list) --
An array of ActivatedRules objects.
(dict) --
The ActivatedRule object in an UpdateWebACL request specifies a Rule that you want to insert or delete, the priority of the Rule in the WebACL , and the action that you want AWS WAF to take when a web request matches the Rule ( ALLOW , BLOCK , or COUNT ).
To specify whether to insert or delete a Rule , use the Action parameter in the WebACLUpdate data type.
Priority (integer) --
Specifies the order in which the Rules in a WebACL are evaluated. Rules with a lower value for Priority are evaluated before Rules with a higher value. The value must be a unique integer. If you add multiple Rules to a WebACL , the values don't need to be consecutive.
RuleId (string) --
The RuleId for a Rule . You use RuleId to get more information about a Rule (see GetRule ), update a Rule (see UpdateRule ), insert a Rule into a WebACL or delete a one from a WebACL (see UpdateWebACL ), or delete a Rule from AWS WAF (see DeleteRule ).
RuleId is returned by CreateRule and by ListRules.
Action (dict) --
Specifies the action that CloudFront or AWS WAF takes when a web request matches the conditions in the Rule . Valid values for Action include the following:
ALLOW : CloudFront responds with the requested object.
BLOCK : CloudFront responds with an HTTP 403 (Forbidden) status code.
COUNT : AWS WAF increments a counter of requests that match the conditions in the rule and then continues to inspect the web request based on the remaining rules in the web ACL.
The Action data type within ActivatedRule is used only when submitting an UpdateWebACL request. ActivatedRule|Action is not applicable and therefore not available for UpdateRuleGroup .
Type (string) --
Specifies how you want AWS WAF to respond to requests that match the settings in a Rule . Valid settings include the following:
ALLOW : AWS WAF allows requests
BLOCK : AWS WAF blocks requests
COUNT : AWS WAF increments a counter of the requests that match all of the conditions in the rule. AWS WAF then continues to inspect the web request based on the remaining rules in the web ACL. You can't specify COUNT for the default action for a WebACL .
OverrideAction (dict) --
Use the OverrideAction to test your RuleGroup .
Any rule in a RuleGroup can potentially block a request. If you set the OverrideAction to None , the RuleGroup will block a request if any individual rule in the RuleGroup matches the request and is configured to block that request. However if you first want to test the RuleGroup , set the OverrideAction to Count . The RuleGroup will then override any block action specified by individual rules contained within the group. Instead of blocking matching requests, those requests will be counted. You can view a record of counted requests using GetSampledRequests.
The OverrideAction data type within ActivatedRule is used only when submitting an UpdateRuleGroup request. ActivatedRule|OverrideAction is not applicable and therefore not available for UpdateWebACL .
Type (string) --
COUNT overrides the action specified by the individual rule within a RuleGroup . If set to NONE , the rule's action will take place.
Type (string) --
The rule type, either REGULAR , as defined by Rule, RATE_BASED , as defined by RateBasedRule, or GROUP , as defined by RuleGroup. The default is REGULAR. Although this field is optional, be aware that if you try to add a RATE_BASED rule to a web ACL without setting the type, the UpdateWebACL request will fail because the request tries to add a REGULAR rule with the specified ID, which does not exist.
Returns the RuleGroup that is specified by the RuleGroupId that you included in the GetRuleGroup request.
To view the rules in a rule group, use ListActivatedRulesInRuleGroup.
See also: AWS API Documentation
Request Syntax
client.get_rule_group(
RuleGroupId='string'
)
string
[REQUIRED]
The RuleGroupId of the RuleGroup that you want to get. RuleGroupId is returned by CreateRuleGroup and by ListRuleGroups.
dict
Response Syntax
{
'RuleGroup': {
'RuleGroupId': 'string',
'Name': 'string',
'MetricName': 'string'
}
}
Response Structure
(dict) --
RuleGroup (dict) --
Information about the RuleGroup that you specified in the GetRuleGroup request.
RuleGroupId (string) --
A unique identifier for a RuleGroup . You use RuleGroupId to get more information about a RuleGroup (see GetRuleGroup ), update a RuleGroup (see UpdateRuleGroup ), insert a RuleGroup into a WebACL or delete a one from a WebACL (see UpdateWebACL ), or delete a RuleGroup from AWS WAF (see DeleteRuleGroup ).
RuleGroupId is returned by CreateRuleGroup and by ListRuleGroups.
Name (string) --
The friendly name or description for the RuleGroup . You can't change the name of a RuleGroup after you create it.
MetricName (string) --
A friendly name or description for the metrics for this RuleGroup . The name can contain only alphanumeric characters (A-Z, a-z, 0-9); the name can't contain whitespace. You can't change the name of the metric after you create the RuleGroup .
Returns an array of RuleGroup objects.
See also: AWS API Documentation
Request Syntax
client.list_rule_groups(
NextMarker='string',
Limit=123
)
string
If you specify a value for Limit and you have more RuleGroups than the value of Limit , AWS WAF returns a NextMarker value in the response that allows you to list another group of RuleGroups . For the second and subsequent ListRuleGroups requests, specify the value of NextMarker from the previous response to get information about another batch of RuleGroups .
integer
Specifies the number of RuleGroups that you want AWS WAF to return for this request. If you have more RuleGroups than the number that you specify for Limit , the response includes a NextMarker value that you can use to get another batch of RuleGroups .
dict
Response Syntax
{
'NextMarker': 'string',
'RuleGroups': [
{
'RuleGroupId': 'string',
'Name': 'string'
},
]
}
Response Structure
(dict) --
NextMarker (string) --
If you have more RuleGroups than the number that you specified for Limit in the request, the response includes a NextMarker value. To list more RuleGroups , submit another ListRuleGroups request, and specify the NextMarker value from the response in the NextMarker value in the next request.
RuleGroups (list) --
An array of RuleGroup objects.
(dict) --
Contains the identifier and the friendly name or description of the RuleGroup .
RuleGroupId (string) --
A unique identifier for a RuleGroup . You use RuleGroupId to get more information about a RuleGroup (see GetRuleGroup ), update a RuleGroup (see UpdateRuleGroup ), insert a RuleGroup into a WebACL or delete one from a WebACL (see UpdateWebACL ), or delete a RuleGroup from AWS WAF (see DeleteRuleGroup ).
RuleGroupId is returned by CreateRuleGroup and by ListRuleGroups.
Name (string) --
A friendly name or description of the RuleGroup. You can't change the name of a RuleGroup after you create it.
Permanently deletes a RuleGroup. You can't delete a RuleGroup if it's still used in any WebACL objects or if it still includes any rules.
If you just want to remove a RuleGroup from a WebACL , use UpdateWebACL.
To permanently delete a RuleGroup from AWS WAF, perform the following steps:
Update the RuleGroup to remove rules, if any. For more information, see UpdateRuleGroup.
Use GetChangeToken to get the change token that you provide in the ChangeToken parameter of a DeleteRuleGroup request.
Submit a DeleteRuleGroup request.
See also: AWS API Documentation
Request Syntax
client.delete_rule_group(
RuleGroupId='string',
ChangeToken='string'
)
string
[REQUIRED]
The RuleGroupId of the RuleGroup that you want to delete. RuleGroupId is returned by CreateRuleGroup and by ListRuleGroups.
string
[REQUIRED]
The value returned by the most recent call to GetChangeToken.
dict
Response Syntax
{
'ChangeToken': 'string'
}
Response Structure
(dict) --
ChangeToken (string) --
The ChangeToken that you used to submit the DeleteRuleGroup request. You can also use this value to query the status of the request. For more information, see GetChangeTokenStatus.
{'WebACL': {'Rules': {'OverrideAction': {'Type': 'NONE | COUNT'},
'Type': {'GROUP'}}}}
Creates a WebACL , which contains the Rules that identify the CloudFront web requests that you want to allow, block, or count. AWS WAF evaluates Rules in order based on the value of Priority for each Rule .
You also specify a default action, either ALLOW or BLOCK . If a web request doesn't match any of the Rules in a WebACL , AWS WAF responds to the request with the default action.
To create and configure a WebACL , perform the following steps:
Create and update the ByteMatchSet objects and other predicates that you want to include in Rules . For more information, see CreateByteMatchSet, UpdateByteMatchSet, CreateIPSet, UpdateIPSet, CreateSqlInjectionMatchSet, and UpdateSqlInjectionMatchSet.
Create and update the Rules that you want to include in the WebACL . For more information, see CreateRule and UpdateRule.
Use GetChangeToken to get the change token that you provide in the ChangeToken parameter of a CreateWebACL request.
Submit a CreateWebACL request.
Use GetChangeToken to get the change token that you provide in the ChangeToken parameter of an UpdateWebACL request.
Submit an UpdateWebACL request to specify the Rules that you want to include in the WebACL , to specify the default action, and to associate the WebACL with a CloudFront distribution.
For more information about how to use the AWS WAF API, see the AWS WAF Developer Guide.
See also: AWS API Documentation
Request Syntax
client.create_web_acl(
Name='string',
MetricName='string',
DefaultAction={
'Type': 'BLOCK'|'ALLOW'|'COUNT'
},
ChangeToken='string'
)
string
[REQUIRED]
A friendly name or description of the WebACL. You can't change Name after you create the WebACL .
string
[REQUIRED]
A friendly name or description for the metrics for this WebACL . The name can contain only alphanumeric characters (A-Z, a-z, 0-9); the name can't contain whitespace. You can't change MetricName after you create the WebACL .
dict
[REQUIRED]
The action that you want AWS WAF to take when a request doesn't match the criteria specified in any of the Rule objects that are associated with the WebACL .
Type (string) -- [REQUIRED]
Specifies how you want AWS WAF to respond to requests that match the settings in a Rule . Valid settings include the following:
ALLOW : AWS WAF allows requests
BLOCK : AWS WAF blocks requests
COUNT : AWS WAF increments a counter of the requests that match all of the conditions in the rule. AWS WAF then continues to inspect the web request based on the remaining rules in the web ACL. You can't specify COUNT for the default action for a WebACL .
string
[REQUIRED]
The value returned by the most recent call to GetChangeToken.
dict
Response Syntax
{
'WebACL': {
'WebACLId': 'string',
'Name': 'string',
'MetricName': 'string',
'DefaultAction': {
'Type': 'BLOCK'|'ALLOW'|'COUNT'
},
'Rules': [
{
'Priority': 123,
'RuleId': 'string',
'Action': {
'Type': 'BLOCK'|'ALLOW'|'COUNT'
},
'OverrideAction': {
'Type': 'NONE'|'COUNT'
},
'Type': 'REGULAR'|'RATE_BASED'|'GROUP'
},
]
},
'ChangeToken': 'string'
}
Response Structure
(dict) --
WebACL (dict) --
The WebACL returned in the CreateWebACL response.
WebACLId (string) --
A unique identifier for a WebACL . You use WebACLId to get information about a WebACL (see GetWebACL ), update a WebACL (see UpdateWebACL ), and delete a WebACL from AWS WAF (see DeleteWebACL ).
WebACLId is returned by CreateWebACL and by ListWebACLs.
Name (string) --
A friendly name or description of the WebACL . You can't change the name of a WebACL after you create it.
MetricName (string) --
A friendly name or description for the metrics for this WebACL . The name can contain only alphanumeric characters (A-Z, a-z, 0-9); the name can't contain whitespace. You can't change MetricName after you create the WebACL .
DefaultAction (dict) --
The action to perform if none of the Rules contained in the WebACL match. The action is specified by the WafAction object.
Type (string) --
Specifies how you want AWS WAF to respond to requests that match the settings in a Rule . Valid settings include the following:
ALLOW : AWS WAF allows requests
BLOCK : AWS WAF blocks requests
COUNT : AWS WAF increments a counter of the requests that match all of the conditions in the rule. AWS WAF then continues to inspect the web request based on the remaining rules in the web ACL. You can't specify COUNT for the default action for a WebACL .
Rules (list) --
An array that contains the action for each Rule in a WebACL , the priority of the Rule , and the ID of the Rule .
(dict) --
The ActivatedRule object in an UpdateWebACL request specifies a Rule that you want to insert or delete, the priority of the Rule in the WebACL , and the action that you want AWS WAF to take when a web request matches the Rule ( ALLOW , BLOCK , or COUNT ).
To specify whether to insert or delete a Rule , use the Action parameter in the WebACLUpdate data type.
Priority (integer) --
Specifies the order in which the Rules in a WebACL are evaluated. Rules with a lower value for Priority are evaluated before Rules with a higher value. The value must be a unique integer. If you add multiple Rules to a WebACL , the values don't need to be consecutive.
RuleId (string) --
The RuleId for a Rule . You use RuleId to get more information about a Rule (see GetRule ), update a Rule (see UpdateRule ), insert a Rule into a WebACL or delete a one from a WebACL (see UpdateWebACL ), or delete a Rule from AWS WAF (see DeleteRule ).
RuleId is returned by CreateRule and by ListRules.
Action (dict) --
Specifies the action that CloudFront or AWS WAF takes when a web request matches the conditions in the Rule . Valid values for Action include the following:
ALLOW : CloudFront responds with the requested object.
BLOCK : CloudFront responds with an HTTP 403 (Forbidden) status code.
COUNT : AWS WAF increments a counter of requests that match the conditions in the rule and then continues to inspect the web request based on the remaining rules in the web ACL.
The Action data type within ActivatedRule is used only when submitting an UpdateWebACL request. ActivatedRule|Action is not applicable and therefore not available for UpdateRuleGroup .
Type (string) --
Specifies how you want AWS WAF to respond to requests that match the settings in a Rule . Valid settings include the following:
ALLOW : AWS WAF allows requests
BLOCK : AWS WAF blocks requests
COUNT : AWS WAF increments a counter of the requests that match all of the conditions in the rule. AWS WAF then continues to inspect the web request based on the remaining rules in the web ACL. You can't specify COUNT for the default action for a WebACL .
OverrideAction (dict) --
Use the OverrideAction to test your RuleGroup .
Any rule in a RuleGroup can potentially block a request. If you set the OverrideAction to None , the RuleGroup will block a request if any individual rule in the RuleGroup matches the request and is configured to block that request. However if you first want to test the RuleGroup , set the OverrideAction to Count . The RuleGroup will then override any block action specified by individual rules contained within the group. Instead of blocking matching requests, those requests will be counted. You can view a record of counted requests using GetSampledRequests.
The OverrideAction data type within ActivatedRule is used only when submitting an UpdateRuleGroup request. ActivatedRule|OverrideAction is not applicable and therefore not available for UpdateWebACL .
Type (string) --
COUNT overrides the action specified by the individual rule within a RuleGroup . If set to NONE , the rule's action will take place.
Type (string) --
The rule type, either REGULAR , as defined by Rule, RATE_BASED , as defined by RateBasedRule, or GROUP , as defined by RuleGroup. The default is REGULAR. Although this field is optional, be aware that if you try to add a RATE_BASED rule to a web ACL without setting the type, the UpdateWebACL request will fail because the request tries to add a REGULAR rule with the specified ID, which does not exist.
ChangeToken (string) --
The ChangeToken that you used to submit the CreateWebACL request. You can also use this value to query the status of the request. For more information, see GetChangeTokenStatus.
{'SampledRequests': {'RuleWithinRuleGroup': 'string'}}
Gets detailed information about a specified number of requests--a sample--that AWS WAF randomly selects from among the first 5,000 requests that your AWS 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.
GetSampledRequests returns 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, GetSampledRequests returns an updated time range. This new time range indicates the actual period during which AWS WAF selected the requests in the sample.
See also: AWS API Documentation
Request Syntax
client.get_sampled_requests(
WebAclId='string',
RuleId='string',
TimeWindow={
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1)
},
MaxItems=123
)
string
[REQUIRED]
The WebACLId of the WebACL for which you want GetSampledRequests to return a sample of requests.
string
[REQUIRED]
RuleId is one of three values:
The RuleId of the Rule or the RuleGroupId of the RuleGroup for which you want GetSampledRequests to return a sample of requests.
Default_Action , which causes GetSampledRequests to return a sample of the requests that didn't match any of the rules in the specified WebACL .
dict
[REQUIRED]
The start date and time and the end date and time of the range for which you want GetSampledRequests to return a sample of requests. Specify the date and time in the following format: "2016-09-27T14:50Z" . You can specify any time range in the previous three hours.
StartTime (datetime) -- [REQUIRED]
The beginning of the time range from which you want GetSampledRequests to return a sample of the requests that your AWS resource received. Specify the date and time in the following format: "2016-09-27T14:50Z" . You can specify any time range in the previous three hours.
EndTime (datetime) -- [REQUIRED]
The end of the time range from which you want GetSampledRequests to return a sample of the requests that your AWS resource received. Specify the date and time in the following format: "2016-09-27T14:50Z" . You can specify any time range in the previous three hours.
integer
[REQUIRED]
The number of requests that you want AWS WAF to return from among the first 5,000 requests that your AWS resource received during the time range. If your resource received fewer requests than the value of MaxItems , GetSampledRequests returns information about all of them.
dict
Response Syntax
{
'SampledRequests': [
{
'Request': {
'ClientIP': 'string',
'Country': 'string',
'URI': 'string',
'Method': 'string',
'HTTPVersion': 'string',
'Headers': [
{
'Name': 'string',
'Value': 'string'
},
]
},
'Weight': 123,
'Timestamp': datetime(2015, 1, 1),
'Action': 'string',
'RuleWithinRuleGroup': 'string'
},
],
'PopulationSize': 123,
'TimeWindow': {
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
SampledRequests (list) --
A complex type that contains detailed information about each of the requests in the sample.
(dict) --
The response from a GetSampledRequests request includes a SampledHTTPRequests complex type that appears as SampledRequests in the response syntax. SampledHTTPRequests contains one SampledHTTPRequest object for each web request that is returned by GetSampledRequests .
Request (dict) --
A complex type that contains detailed information about the request.
ClientIP (string) --
The IP address that the request originated from. If the WebACL 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 request
Country (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 part of a web request that identifies the resource, for example, /images/daily-ad.jpg .
Method (string) --
The HTTP method specified in the sampled web request. CloudFront supports the following methods: DELETE , GET , HEAD , OPTIONS , PATCH , POST , and PUT .
HTTPVersion (string) --
The HTTP version specified in the sampled web request, for example, HTTP/1.1 .
Headers (list) --
A complex type that contains two values for each header in the sampled web request: the name of the header and the value of the header.
(dict) --
The response from a GetSampledRequests request includes an HTTPHeader complex type that appears as Headers in the response syntax. HTTPHeader contains the names and values of all of the headers that appear in one of the web requests that were returned by GetSampledRequests .
Name (string) --
The name of one of the headers in the sampled web request.
Value (string) --
The value of one of the headers in the sampled web request.
Weight (integer) --
A value that indicates how one result in the response relates proportionally to other results in the response. A result that has a weight of 2 represents roughly twice as many CloudFront web requests as a result that has a weight of 1 .
Timestamp (datetime) --
The time at which AWS WAF received the request from your AWS resource, in Unix time format (in seconds).
Action (string) --
The action for the Rule that the request matched: ALLOW , BLOCK , or COUNT .
RuleWithinRuleGroup (string) --
This value is returned if the GetSampledRequests request specifies the ID of a RuleGroup rather than the ID of an individual rule. RuleWithinRuleGroup is the rule within the specified RuleGroup that matched the request listed in the response.
PopulationSize (integer) --
The total number of requests from which GetSampledRequests got a sample of MaxItems requests. If PopulationSize is less than MaxItems , the sample includes every request that your AWS resource received during the specified time range.
TimeWindow (dict) --
Usually, TimeWindow is the time range that you specified in the GetSampledRequests request. However, if your AWS resource received more than 5,000 requests during the time range that you specified in the request, GetSampledRequests returns the time range for the first 5,000 requests.
StartTime (datetime) --
The beginning of the time range from which you want GetSampledRequests to return a sample of the requests that your AWS resource received. Specify the date and time in the following format: "2016-09-27T14:50Z" . You can specify any time range in the previous three hours.
EndTime (datetime) --
The end of the time range from which you want GetSampledRequests to return a sample of the requests that your AWS resource received. Specify the date and time in the following format: "2016-09-27T14:50Z" . You can specify any time range in the previous three hours.
{'WebACL': {'Rules': {'OverrideAction': {'Type': 'NONE | COUNT'},
'Type': {'GROUP'}}}}
Returns the WebACL that is specified by WebACLId .
See also: AWS API Documentation
Request Syntax
client.get_web_acl(
WebACLId='string'
)
string
[REQUIRED]
The WebACLId of the WebACL that you want to get. WebACLId is returned by CreateWebACL and by ListWebACLs.
dict
Response Syntax
{
'WebACL': {
'WebACLId': 'string',
'Name': 'string',
'MetricName': 'string',
'DefaultAction': {
'Type': 'BLOCK'|'ALLOW'|'COUNT'
},
'Rules': [
{
'Priority': 123,
'RuleId': 'string',
'Action': {
'Type': 'BLOCK'|'ALLOW'|'COUNT'
},
'OverrideAction': {
'Type': 'NONE'|'COUNT'
},
'Type': 'REGULAR'|'RATE_BASED'|'GROUP'
},
]
}
}
Response Structure
(dict) --
WebACL (dict) --
Information about the WebACL that you specified in the GetWebACL request. For more information, see the following topics:
WebACL: Contains DefaultAction , MetricName , Name , an array of Rule objects, and WebACLId
DefaultAction (Data type is WafAction ): Contains Type
Rules : Contains an array of ActivatedRule objects, which contain Action , Priority , and RuleId
Action : Contains Type
WebACLId (string) --
A unique identifier for a WebACL . You use WebACLId to get information about a WebACL (see GetWebACL ), update a WebACL (see UpdateWebACL ), and delete a WebACL from AWS WAF (see DeleteWebACL ).
WebACLId is returned by CreateWebACL and by ListWebACLs.
Name (string) --
A friendly name or description of the WebACL . You can't change the name of a WebACL after you create it.
MetricName (string) --
A friendly name or description for the metrics for this WebACL . The name can contain only alphanumeric characters (A-Z, a-z, 0-9); the name can't contain whitespace. You can't change MetricName after you create the WebACL .
DefaultAction (dict) --
The action to perform if none of the Rules contained in the WebACL match. The action is specified by the WafAction object.
Type (string) --
Specifies how you want AWS WAF to respond to requests that match the settings in a Rule . Valid settings include the following:
ALLOW : AWS WAF allows requests
BLOCK : AWS WAF blocks requests
COUNT : AWS WAF increments a counter of the requests that match all of the conditions in the rule. AWS WAF then continues to inspect the web request based on the remaining rules in the web ACL. You can't specify COUNT for the default action for a WebACL .
Rules (list) --
An array that contains the action for each Rule in a WebACL , the priority of the Rule , and the ID of the Rule .
(dict) --
The ActivatedRule object in an UpdateWebACL request specifies a Rule that you want to insert or delete, the priority of the Rule in the WebACL , and the action that you want AWS WAF to take when a web request matches the Rule ( ALLOW , BLOCK , or COUNT ).
To specify whether to insert or delete a Rule , use the Action parameter in the WebACLUpdate data type.
Priority (integer) --
Specifies the order in which the Rules in a WebACL are evaluated. Rules with a lower value for Priority are evaluated before Rules with a higher value. The value must be a unique integer. If you add multiple Rules to a WebACL , the values don't need to be consecutive.
RuleId (string) --
The RuleId for a Rule . You use RuleId to get more information about a Rule (see GetRule ), update a Rule (see UpdateRule ), insert a Rule into a WebACL or delete a one from a WebACL (see UpdateWebACL ), or delete a Rule from AWS WAF (see DeleteRule ).
RuleId is returned by CreateRule and by ListRules.
Action (dict) --
Specifies the action that CloudFront or AWS WAF takes when a web request matches the conditions in the Rule . Valid values for Action include the following:
ALLOW : CloudFront responds with the requested object.
BLOCK : CloudFront responds with an HTTP 403 (Forbidden) status code.
COUNT : AWS WAF increments a counter of requests that match the conditions in the rule and then continues to inspect the web request based on the remaining rules in the web ACL.
The Action data type within ActivatedRule is used only when submitting an UpdateWebACL request. ActivatedRule|Action is not applicable and therefore not available for UpdateRuleGroup .
Type (string) --
Specifies how you want AWS WAF to respond to requests that match the settings in a Rule . Valid settings include the following:
ALLOW : AWS WAF allows requests
BLOCK : AWS WAF blocks requests
COUNT : AWS WAF increments a counter of the requests that match all of the conditions in the rule. AWS WAF then continues to inspect the web request based on the remaining rules in the web ACL. You can't specify COUNT for the default action for a WebACL .
OverrideAction (dict) --
Use the OverrideAction to test your RuleGroup .
Any rule in a RuleGroup can potentially block a request. If you set the OverrideAction to None , the RuleGroup will block a request if any individual rule in the RuleGroup matches the request and is configured to block that request. However if you first want to test the RuleGroup , set the OverrideAction to Count . The RuleGroup will then override any block action specified by individual rules contained within the group. Instead of blocking matching requests, those requests will be counted. You can view a record of counted requests using GetSampledRequests.
The OverrideAction data type within ActivatedRule is used only when submitting an UpdateRuleGroup request. ActivatedRule|OverrideAction is not applicable and therefore not available for UpdateWebACL .
Type (string) --
COUNT overrides the action specified by the individual rule within a RuleGroup . If set to NONE , the rule's action will take place.
Type (string) --
The rule type, either REGULAR , as defined by Rule, RATE_BASED , as defined by RateBasedRule, or GROUP , as defined by RuleGroup. The default is REGULAR. Although this field is optional, be aware that if you try to add a RATE_BASED rule to a web ACL without setting the type, the UpdateWebACL request will fail because the request tries to add a REGULAR rule with the specified ID, which does not exist.
{'Updates': {'ActivatedRule': {'OverrideAction': {'Type': 'NONE | COUNT'},
'Type': {'GROUP'}}}}
Inserts or deletes ActivatedRule objects in a WebACL . Each Rule identifies web requests that you want to allow, block, or count. When you update a WebACL , you specify the following values:
A default action for the WebACL , either ALLOW or BLOCK . AWS WAF performs the default action if a request doesn't match the criteria in any of the Rules in a WebACL .
The Rules that you want to add and/or delete. If you want to replace one Rule with another, you delete the existing Rule and add the new one.
For each Rule , whether you want AWS WAF to allow requests, block requests, or count requests that match the conditions in the Rule .
The order in which you want AWS WAF to evaluate the Rules in a WebACL . If you add more than one Rule to a WebACL , AWS WAF evaluates each request against the Rules in order based on the value of Priority . (The Rule that has the lowest value for Priority is evaluated first.) When a web request matches all of the predicates (such as ByteMatchSets and IPSets ) in a Rule , AWS WAF immediately takes the corresponding action, allow or block, and doesn't evaluate the request against the remaining Rules in the WebACL , if any.
To create and configure a WebACL , perform the following steps:
Create and update the predicates that you want to include in Rules . For more information, see CreateByteMatchSet, UpdateByteMatchSet, CreateIPSet, UpdateIPSet, CreateSqlInjectionMatchSet, and UpdateSqlInjectionMatchSet.
Create and update the Rules that you want to include in the WebACL . For more information, see CreateRule and UpdateRule.
Create a WebACL . See CreateWebACL.
Use GetChangeToken to get the change token that you provide in the ChangeToken parameter of an UpdateWebACL request.
Submit an UpdateWebACL request to specify the Rules that you want to include in the WebACL , to specify the default action, and to associate the WebACL with a CloudFront distribution.
Be aware that if you try to add a RATE_BASED rule to a web ACL without setting the rule type when first creating the rule, the UpdateWebACL request will fail because the request tries to add a REGULAR rule (the default rule type) with the specified ID, which does not exist.
For more information about how to use the AWS WAF API to allow or block HTTP requests, see the AWS WAF Developer Guide.
See also: AWS API Documentation
Request Syntax
client.update_web_acl(
WebACLId='string',
ChangeToken='string',
Updates=[
{
'Action': 'INSERT'|'DELETE',
'ActivatedRule': {
'Priority': 123,
'RuleId': 'string',
'Action': {
'Type': 'BLOCK'|'ALLOW'|'COUNT'
},
'OverrideAction': {
'Type': 'NONE'|'COUNT'
},
'Type': 'REGULAR'|'RATE_BASED'|'GROUP'
}
},
],
DefaultAction={
'Type': 'BLOCK'|'ALLOW'|'COUNT'
}
)
string
[REQUIRED]
The WebACLId of the WebACL that you want to update. WebACLId is returned by CreateWebACL and by ListWebACLs.
string
[REQUIRED]
The value returned by the most recent call to GetChangeToken.
list
An array of updates to make to the WebACL.
An array of WebACLUpdate objects that you want to insert into or delete from a WebACL. For more information, see the applicable data types:
WebACLUpdate: Contains Action and ActivatedRule
ActivatedRule: Contains Action , Priority , RuleId , and Type . The OverrideAction data type within ActivatedRule is used only when submitting an UpdateRuleGroup request. ActivatedRule|OverrideAction is not applicable and therefore not available for UpdateWebACL .
WafAction: Contains Type
(dict) --
Specifies whether to insert a Rule into or delete a Rule from a WebACL .
Action (string) -- [REQUIRED]
Specifies whether to insert a Rule into or delete a Rule from a WebACL .
ActivatedRule (dict) -- [REQUIRED]
The ActivatedRule object in an UpdateWebACL request specifies a Rule that you want to insert or delete, the priority of the Rule in the WebACL , and the action that you want AWS WAF to take when a web request matches the Rule ( ALLOW , BLOCK , or COUNT ).
Priority (integer) -- [REQUIRED]
Specifies the order in which the Rules in a WebACL are evaluated. Rules with a lower value for Priority are evaluated before Rules with a higher value. The value must be a unique integer. If you add multiple Rules to a WebACL , the values don't need to be consecutive.
RuleId (string) -- [REQUIRED]
The RuleId for a Rule . You use RuleId to get more information about a Rule (see GetRule ), update a Rule (see UpdateRule ), insert a Rule into a WebACL or delete a one from a WebACL (see UpdateWebACL ), or delete a Rule from AWS WAF (see DeleteRule ).
RuleId is returned by CreateRule and by ListRules.
Action (dict) --
Specifies the action that CloudFront or AWS WAF takes when a web request matches the conditions in the Rule . Valid values for Action include the following:
ALLOW : CloudFront responds with the requested object.
BLOCK : CloudFront responds with an HTTP 403 (Forbidden) status code.
COUNT : AWS WAF increments a counter of requests that match the conditions in the rule and then continues to inspect the web request based on the remaining rules in the web ACL.
The Action data type within ActivatedRule is used only when submitting an UpdateWebACL request. ActivatedRule|Action is not applicable and therefore not available for UpdateRuleGroup .
Type (string) -- [REQUIRED]
Specifies how you want AWS WAF to respond to requests that match the settings in a Rule . Valid settings include the following:
ALLOW : AWS WAF allows requests
BLOCK : AWS WAF blocks requests
COUNT : AWS WAF increments a counter of the requests that match all of the conditions in the rule. AWS WAF then continues to inspect the web request based on the remaining rules in the web ACL. You can't specify COUNT for the default action for a WebACL .
OverrideAction (dict) --
Use the OverrideAction to test your RuleGroup .
Any rule in a RuleGroup can potentially block a request. If you set the OverrideAction to None , the RuleGroup will block a request if any individual rule in the RuleGroup matches the request and is configured to block that request. However if you first want to test the RuleGroup , set the OverrideAction to Count . The RuleGroup will then override any block action specified by individual rules contained within the group. Instead of blocking matching requests, those requests will be counted. You can view a record of counted requests using GetSampledRequests.
The OverrideAction data type within ActivatedRule is used only when submitting an UpdateRuleGroup request. ActivatedRule|OverrideAction is not applicable and therefore not available for UpdateWebACL .
Type (string) -- [REQUIRED]
COUNT overrides the action specified by the individual rule within a RuleGroup . If set to NONE , the rule's action will take place.
Type (string) --
The rule type, either REGULAR , as defined by Rule, RATE_BASED , as defined by RateBasedRule, or GROUP , as defined by RuleGroup. The default is REGULAR. Although this field is optional, be aware that if you try to add a RATE_BASED rule to a web ACL without setting the type, the UpdateWebACL request will fail because the request tries to add a REGULAR rule with the specified ID, which does not exist.
dict
A default action for the web ACL, either ALLOW or BLOCK. AWS WAF performs the default action if a request doesn't match the criteria in any of the rules in a web ACL.
Type (string) -- [REQUIRED]
Specifies how you want AWS WAF to respond to requests that match the settings in a Rule . Valid settings include the following:
ALLOW : AWS WAF allows requests
BLOCK : AWS WAF blocks requests
COUNT : AWS WAF increments a counter of the requests that match all of the conditions in the rule. AWS WAF then continues to inspect the web request based on the remaining rules in the web ACL. You can't specify COUNT for the default action for a WebACL .
dict
Response Syntax
{
'ChangeToken': 'string'
}
Response Structure
(dict) --
ChangeToken (string) --
The ChangeToken that you used to submit the UpdateWebACL request. You can also use this value to query the status of the request. For more information, see GetChangeTokenStatus.