2020/11/13 - AWS Shield - 7 new 1 updated api methods
Changes This release adds APIs for two new features: 1) Allow customers to bundle resources into protection groups and treat as a single unit. 2) Provide per-account event summaries to all AWS customers.
Provides information about the number and type of attacks AWS Shield has detected in the last year for all resources that belong to your account, regardless of whether you've defined Shield protections for them. This operation is available to Shield customers as well as to Shield Advanced customers.
The operation returns data for the time range of midnight UTC, one year ago, to midnight UTC, today. For example, if the current time is 2020-10-26 15:39:32 PDT , equal to 2020-10-26 22:39:32 UTC , then the time range for the attack data returned is from 2019-10-26 00:00:00 UTC to 2020-10-26 00:00:00 UTC .
The time range indicates the period covered by the attack statistics data items.
See also: AWS API Documentation
Request Syntax
client.describe_attack_statistics()
dict
Response Syntax
{
'TimeRange': {
'FromInclusive': datetime(2015, 1, 1),
'ToExclusive': datetime(2015, 1, 1)
},
'DataItems': [
{
'AttackVolume': {
'BitsPerSecond': {
'Max': 123.0
},
'PacketsPerSecond': {
'Max': 123.0
},
'RequestsPerSecond': {
'Max': 123.0
}
},
'AttackCount': 123
},
]
}
Response Structure
(dict) --
TimeRange (dict) --
The time range.
DataItems (list) --
The data that describes the attacks detected during the time period.
(dict) --
A single attack statistics data record. This is returned by DescribeAttackStatistics along with a time range indicating the time period that the attack statistics apply to.
AttackVolume (dict) --
Information about the volume of attacks during the time period. If the accompanying AttackCount is zero, this setting might be empty.
BitsPerSecond (dict) --
A statistics object that uses bits per second as the unit. This is included for network level attacks.
Max (float) --
The maximum attack volume observed for the given unit.
PacketsPerSecond (dict) --
A statistics object that uses packets per second as the unit. This is included for network level attacks.
Max (float) --
The maximum attack volume observed for the given unit.
RequestsPerSecond (dict) --
A statistics object that uses requests per second as the unit. This is included for application level attacks, and is only available for accounts that are subscribed to Shield Advanced.
Max (float) --
The maximum attack volume observed for the given unit.
AttackCount (integer) --
The number of attacks detected during the time period. This is always present, but might be zero.
Retrieves the ProtectionGroup objects for the account.
See also: AWS API Documentation
Request Syntax
client.list_protection_groups(
NextToken='string',
MaxResults=123
)
string
The next token value from a previous call to ListProtectionGroups . Pass null if this is the first call.
integer
The maximum number of ProtectionGroup objects to return. If you leave this blank, Shield Advanced returns the first 20 results.
This is a maximum value. Shield Advanced might return the results in smaller batches. That is, the number of objects returned could be less than MaxResults , even if there are still more objects yet to return. If there are more objects to return, Shield Advanced returns a value in NextToken that you can use in your next request, to get the next batch of objects.
dict
Response Syntax
{
'ProtectionGroups': [
{
'ProtectionGroupId': 'string',
'Aggregation': 'SUM'|'MEAN'|'MAX',
'Pattern': 'ALL'|'ARBITRARY'|'BY_RESOURCE_TYPE',
'ResourceType': 'CLOUDFRONT_DISTRIBUTION'|'ROUTE_53_HOSTED_ZONE'|'ELASTIC_IP_ALLOCATION'|'CLASSIC_LOAD_BALANCER'|'APPLICATION_LOAD_BALANCER'|'GLOBAL_ACCELERATOR',
'Members': [
'string',
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
ProtectionGroups (list) --
(dict) --
A grouping of protected resources that you and AWS Shield Advanced can monitor as a collective. This resource grouping improves the accuracy of detection and reduces false positives.
ProtectionGroupId (string) --
The name of the protection group. You use this to identify the protection group in lists and to manage the protection group, for example to update, delete, or describe it.
Aggregation (string) --
Defines how AWS Shield combines resource data for the group in order to detect, mitigate, and report events.
Sum - Use the total traffic across the group. This is a good choice for most cases. Examples include Elastic IP addresses for EC2 instances that scale manually or automatically.
Mean - Use the average of the traffic across the group. This is a good choice for resources that share traffic uniformly. Examples include accelerators and load balancers.
Max - Use the highest traffic from each resource. This is useful for resources that don't share traffic and for resources that share that traffic in a non-uniform way. Examples include CloudFront distributions and origin resources for CloudFront distributions.
Pattern (string) --
The criteria to use to choose the protected resources for inclusion in the group. You can include all resources that have protections, provide a list of resource Amazon Resource Names (ARNs), or include all resources of a specified resource type.
ResourceType (string) --
The resource type to include in the protection group. All protected resources of this type are included in the protection group. You must set this when you set Pattern to BY_RESOURCE_TYPE and you must not set it for any other Pattern setting.
Members (list) --
The Amazon Resource Names (ARNs) of the resources to include in the protection group. You must set this when you set Pattern to ARBITRARY and you must not set it for any other Pattern setting.
(string) --
NextToken (string) --
If you specify a value for MaxResults and you have more protection groups than the value of MaxResults, AWS Shield Advanced returns this token that you can use in your next request, to get the next batch of objects.
Returns the specification for the specified protection group.
See also: AWS API Documentation
Request Syntax
client.describe_protection_group(
ProtectionGroupId='string'
)
string
[REQUIRED]
The name of the protection group. You use this to identify the protection group in lists and to manage the protection group, for example to update, delete, or describe it.
dict
Response Syntax
{
'ProtectionGroup': {
'ProtectionGroupId': 'string',
'Aggregation': 'SUM'|'MEAN'|'MAX',
'Pattern': 'ALL'|'ARBITRARY'|'BY_RESOURCE_TYPE',
'ResourceType': 'CLOUDFRONT_DISTRIBUTION'|'ROUTE_53_HOSTED_ZONE'|'ELASTIC_IP_ALLOCATION'|'CLASSIC_LOAD_BALANCER'|'APPLICATION_LOAD_BALANCER'|'GLOBAL_ACCELERATOR',
'Members': [
'string',
]
}
}
Response Structure
(dict) --
ProtectionGroup (dict) --
A grouping of protected resources that you and AWS Shield Advanced can monitor as a collective. This resource grouping improves the accuracy of detection and reduces false positives.
ProtectionGroupId (string) --
The name of the protection group. You use this to identify the protection group in lists and to manage the protection group, for example to update, delete, or describe it.
Aggregation (string) --
Defines how AWS Shield combines resource data for the group in order to detect, mitigate, and report events.
Sum - Use the total traffic across the group. This is a good choice for most cases. Examples include Elastic IP addresses for EC2 instances that scale manually or automatically.
Mean - Use the average of the traffic across the group. This is a good choice for resources that share traffic uniformly. Examples include accelerators and load balancers.
Max - Use the highest traffic from each resource. This is useful for resources that don't share traffic and for resources that share that traffic in a non-uniform way. Examples include CloudFront distributions and origin resources for CloudFront distributions.
Pattern (string) --
The criteria to use to choose the protected resources for inclusion in the group. You can include all resources that have protections, provide a list of resource Amazon Resource Names (ARNs), or include all resources of a specified resource type.
ResourceType (string) --
The resource type to include in the protection group. All protected resources of this type are included in the protection group. You must set this when you set Pattern to BY_RESOURCE_TYPE and you must not set it for any other Pattern setting.
Members (list) --
The Amazon Resource Names (ARNs) of the resources to include in the protection group. You must set this when you set Pattern to ARBITRARY and you must not set it for any other Pattern setting.
(string) --
Updates an existing protection group. A protection group is a grouping of protected resources so they can be handled as a collective. This resource grouping improves the accuracy of detection and reduces false positives.
See also: AWS API Documentation
Request Syntax
client.update_protection_group(
ProtectionGroupId='string',
Aggregation='SUM'|'MEAN'|'MAX',
Pattern='ALL'|'ARBITRARY'|'BY_RESOURCE_TYPE',
ResourceType='CLOUDFRONT_DISTRIBUTION'|'ROUTE_53_HOSTED_ZONE'|'ELASTIC_IP_ALLOCATION'|'CLASSIC_LOAD_BALANCER'|'APPLICATION_LOAD_BALANCER'|'GLOBAL_ACCELERATOR',
Members=[
'string',
]
)
string
[REQUIRED]
The name of the protection group. You use this to identify the protection group in lists and to manage the protection group, for example to update, delete, or describe it.
string
[REQUIRED]
Defines how AWS Shield combines resource data for the group in order to detect, mitigate, and report events.
Sum - Use the total traffic across the group. This is a good choice for most cases. Examples include Elastic IP addresses for EC2 instances that scale manually or automatically.
Mean - Use the average of the traffic across the group. This is a good choice for resources that share traffic uniformly. Examples include accelerators and load balancers.
Max - Use the highest traffic from each resource. This is useful for resources that don't share traffic and for resources that share that traffic in a non-uniform way. Examples include CloudFront distributions and origin resources for CloudFront distributions.
string
[REQUIRED]
The criteria to use to choose the protected resources for inclusion in the group. You can include all resources that have protections, provide a list of resource Amazon Resource Names (ARNs), or include all resources of a specified resource type.
string
The resource type to include in the protection group. All protected resources of this type are included in the protection group. You must set this when you set Pattern to BY_RESOURCE_TYPE and you must not set it for any other Pattern setting.
list
The Amazon Resource Names (ARNs) of the resources to include in the protection group. You must set this when you set Pattern to ARBITRARY and you must not set it for any other Pattern setting.
(string) --
dict
Response Syntax
{}
Response Structure
(dict) --
Removes the specified protection group.
See also: AWS API Documentation
Request Syntax
client.delete_protection_group(
ProtectionGroupId='string'
)
string
[REQUIRED]
The name of the protection group. You use this to identify the protection group in lists and to manage the protection group, for example to update, delete, or describe it.
dict
Response Syntax
{}
Response Structure
(dict) --
Retrieves the resources that are included in the protection group.
See also: AWS API Documentation
Request Syntax
client.list_resources_in_protection_group(
ProtectionGroupId='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The name of the protection group. You use this to identify the protection group in lists and to manage the protection group, for example to update, delete, or describe it.
string
The next token value from a previous call to ListResourcesInProtectionGroup . Pass null if this is the first call.
integer
The maximum number of resource ARN objects to return. If you leave this blank, Shield Advanced returns the first 20 results.
This is a maximum value. Shield Advanced might return the results in smaller batches. That is, the number of objects returned could be less than MaxResults , even if there are still more objects yet to return. If there are more objects to return, Shield Advanced returns a value in NextToken that you can use in your next request, to get the next batch of objects.
dict
Response Syntax
{
'ResourceArns': [
'string',
],
'NextToken': 'string'
}
Response Structure
(dict) --
ResourceArns (list) --
The Amazon Resource Names (ARNs) of the resources that are included in the protection group.
(string) --
NextToken (string) --
If you specify a value for MaxResults and you have more resources in the protection group than the value of MaxResults, AWS Shield Advanced returns this token that you can use in your next request, to get the next batch of objects.
Creates a grouping of protected resources so they can be handled as a collective. This resource grouping improves the accuracy of detection and reduces false positives.
See also: AWS API Documentation
Request Syntax
client.create_protection_group(
ProtectionGroupId='string',
Aggregation='SUM'|'MEAN'|'MAX',
Pattern='ALL'|'ARBITRARY'|'BY_RESOURCE_TYPE',
ResourceType='CLOUDFRONT_DISTRIBUTION'|'ROUTE_53_HOSTED_ZONE'|'ELASTIC_IP_ALLOCATION'|'CLASSIC_LOAD_BALANCER'|'APPLICATION_LOAD_BALANCER'|'GLOBAL_ACCELERATOR',
Members=[
'string',
]
)
string
[REQUIRED]
The name of the protection group. You use this to identify the protection group in lists and to manage the protection group, for example to update, delete, or describe it.
string
[REQUIRED]
Defines how AWS Shield combines resource data for the group in order to detect, mitigate, and report events.
Sum - Use the total traffic across the group. This is a good choice for most cases. Examples include Elastic IP addresses for EC2 instances that scale manually or automatically.
Mean - Use the average of the traffic across the group. This is a good choice for resources that share traffic uniformly. Examples include accelerators and load balancers.
Max - Use the highest traffic from each resource. This is useful for resources that don't share traffic and for resources that share that traffic in a non-uniform way. Examples include CloudFront distributions and origin resources for CloudFront distributions.
string
[REQUIRED]
The criteria to use to choose the protected resources for inclusion in the group. You can include all resources that have protections, provide a list of resource Amazon Resource Names (ARNs), or include all resources of a specified resource type.
string
The resource type to include in the protection group. All protected resources of this type are included in the protection group. Newly protected resources of this type are automatically added to the group. You must set this when you set Pattern to BY_RESOURCE_TYPE and you must not set it for any other Pattern setting.
list
The Amazon Resource Names (ARNs) of the resources to include in the protection group. You must set this when you set Pattern to ARBITRARY and you must not set it for any other Pattern setting.
(string) --
dict
Response Syntax
{}
Response Structure
(dict) --
{'Subscription': {'SubscriptionLimits': {'ProtectionGroupLimits': {'MaxProtectionGroups': 'long',
'PatternTypeLimits': {'ArbitraryPatternLimits': {'MaxMembers': 'long'}}},
'ProtectionLimits': {'ProtectedResourceTypeLimits': [{'Max': 'long',
'Type': 'string'}]}}}}
Provides details about the AWS Shield Advanced subscription for an account.
See also: AWS API Documentation
Request Syntax
client.describe_subscription()
dict
Response Syntax
{
'Subscription': {
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'TimeCommitmentInSeconds': 123,
'AutoRenew': 'ENABLED'|'DISABLED',
'Limits': [
{
'Type': 'string',
'Max': 123
},
],
'ProactiveEngagementStatus': 'ENABLED'|'DISABLED'|'PENDING',
'SubscriptionLimits': {
'ProtectionLimits': {
'ProtectedResourceTypeLimits': [
{
'Type': 'string',
'Max': 123
},
]
},
'ProtectionGroupLimits': {
'MaxProtectionGroups': 123,
'PatternTypeLimits': {
'ArbitraryPatternLimits': {
'MaxMembers': 123
}
}
}
}
}
}
Response Structure
(dict) --
Subscription (dict) --
The AWS Shield Advanced subscription details for an account.
StartTime (datetime) --
The start time of the subscription, in Unix time in seconds. For more information see timestamp .
EndTime (datetime) --
The date and time your subscription will end.
TimeCommitmentInSeconds (integer) --
The length, in seconds, of the AWS Shield Advanced subscription for the account.
AutoRenew (string) --
If ENABLED , the subscription will be automatically renewed at the end of the existing subscription period.
When you initally create a subscription, AutoRenew is set to ENABLED . You can change this by submitting an UpdateSubscription request. If the UpdateSubscription request does not included a value for AutoRenew , the existing value for AutoRenew remains unchanged.
Limits (list) --
Specifies how many protections of a given type you can create.
(dict) --
Specifies how many protections of a given type you can create.
Type (string) --
The type of protection.
Max (integer) --
The maximum number of protections that can be created for the specified Type .
ProactiveEngagementStatus (string) --
If ENABLED , the DDoS Response Team (DRT) will use email and phone to notify contacts about escalations to the DRT and to initiate proactive customer support.
If PENDING , you have requested proactive engagement and the request is pending. The status changes to ENABLED when your request is fully processed.
If DISABLED , the DRT will not proactively notify contacts about escalations or to initiate proactive customer support.
SubscriptionLimits (dict) --
Limits settings for your subscription.
ProtectionLimits (dict) --
Limits settings on protections for your subscription.
ProtectedResourceTypeLimits (list) --
The maximum number of resource types that you can specify in a protection.
(dict) --
Specifies how many protections of a given type you can create.
Type (string) --
The type of protection.
Max (integer) --
The maximum number of protections that can be created for the specified Type .
ProtectionGroupLimits (dict) --
Limits settings on protection groups for your subscription.
MaxProtectionGroups (integer) --
The maximum number of protection groups that you can have at one time.
PatternTypeLimits (dict) --
Limits settings by pattern type in the protection groups for your subscription.
ArbitraryPatternLimits (dict) --
Limits settings on protection groups with arbitrary pattern type.
MaxMembers (integer) --
The maximum number of resources you can specify for a single arbitrary pattern in a protection group.