SDK for PHP 3.x

Client: Aws\Shield\ShieldClient
Service ID: shield
Version: 2016-06-02

This page describes the parameters and results for the operations of the AWS Shield (2016-06-02), and shows how to use the Aws\Shield\ShieldClient object to call the described operations. This documentation is specific to the 2016-06-02 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

AssociateDRTLogBucket ( array $params = [] )
Authorizes the Shield Response Team (SRT) to access the specified Amazon S3 bucket containing log data such as Application Load Balancer access logs, CloudFront logs, or logs from third party sources.
AssociateDRTRole ( array $params = [] )
Authorizes the Shield Response Team (SRT) using the specified role, to access your Amazon Web Services account to assist with DDoS attack mitigation during potential attacks.
AssociateHealthCheck ( array $params = [] )
Adds health-based detection to the Shield Advanced protection for a resource.
AssociateProactiveEngagementDetails ( array $params = [] )
Initializes proactive engagement and sets the list of contacts for the Shield Response Team (SRT) to use.
CreateProtection ( array $params = [] )
Enables Shield Advanced for a specific Amazon Web Services resource.
CreateProtectionGroup ( array $params = [] )
Creates a grouping of protected resources so they can be handled as a collective.
CreateSubscription ( array $params = [] )
Activates Shield Advanced for an account.
DeleteProtection ( array $params = [] )
Deletes an Shield Advanced Protection.
DeleteProtectionGroup ( array $params = [] )
Removes the specified protection group.
DeleteSubscription ( array $params = [] )
Removes Shield Advanced from an account.
DescribeAttack ( array $params = [] )
Describes the details of a DDoS attack.
DescribeAttackStatistics ( array $params = [] )
Provides information about the number and type of attacks 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.
DescribeDRTAccess ( array $params = [] )
Returns the current role and list of Amazon S3 log buckets used by the Shield Response Team (SRT) to access your Amazon Web Services account while assisting with attack mitigation.
DescribeEmergencyContactSettings ( array $params = [] )
A list of email addresses and phone numbers that the Shield Response Team (SRT) can use to contact you if you have proactive engagement enabled, for escalations to the SRT and to initiate proactive customer support.
DescribeProtection ( array $params = [] )
Lists the details of a Protection object.
DescribeProtectionGroup ( array $params = [] )
Returns the specification for the specified protection group.
DescribeSubscription ( array $params = [] )
Provides details about the Shield Advanced subscription for an account.
DisableApplicationLayerAutomaticResponse ( array $params = [] )
Disable the Shield Advanced automatic application layer DDoS mitigation feature for the protected resource.
DisableProactiveEngagement ( array $params = [] )
Removes authorization from the Shield Response Team (SRT) to notify contacts about escalations to the SRT and to initiate proactive customer support.
DisassociateDRTLogBucket ( array $params = [] )
Removes the Shield Response Team's (SRT) access to the specified Amazon S3 bucket containing the logs that you shared previously.
DisassociateDRTRole ( array $params = [] )
Removes the Shield Response Team's (SRT) access to your Amazon Web Services account.
DisassociateHealthCheck ( array $params = [] )
Removes health-based detection from the Shield Advanced protection for a resource.
EnableApplicationLayerAutomaticResponse ( array $params = [] )
Enable the Shield Advanced automatic application layer DDoS mitigation for the protected resource.
EnableProactiveEngagement ( array $params = [] )
Authorizes the Shield Response Team (SRT) to use email and phone to notify contacts about escalations to the SRT and to initiate proactive customer support.
GetSubscriptionState ( array $params = [] )
Returns the SubscriptionState, either Active or Inactive.
ListAttacks ( array $params = [] )
Returns all ongoing DDoS attacks or all DDoS attacks during a specified time period.
ListProtectionGroups ( array $params = [] )
Retrieves ProtectionGroup objects for the account.
ListProtections ( array $params = [] )
Retrieves Protection objects for the account.
ListResourcesInProtectionGroup ( array $params = [] )
Retrieves the resources that are included in the protection group.
ListTagsForResource ( array $params = [] )
Gets information about Amazon Web Services tags for a specified Amazon Resource Name (ARN) in Shield.
TagResource ( array $params = [] )
Adds or updates tags for a resource in Shield.
UntagResource ( array $params = [] )
Removes tags from a resource in Shield.
UpdateApplicationLayerAutomaticResponse ( array $params = [] )
Updates an existing Shield Advanced automatic application layer DDoS mitigation configuration for the specified resource.
UpdateEmergencyContactSettings ( array $params = [] )
Updates the details of the list of email addresses and phone numbers that the Shield Response Team (SRT) can use to contact you if you have proactive engagement enabled, for escalations to the SRT and to initiate proactive customer support.
UpdateProtectionGroup ( array $params = [] )
Updates an existing protection group.
UpdateSubscription ( array $params = [] )
Updates the details of an existing subscription.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

ListAttacks
ListProtectionGroups
ListProtections
ListResourcesInProtectionGroup

Operations

AssociateDRTLogBucket

$result = $client->associateDRTLogBucket([/* ... */]);
$promise = $client->associateDRTLogBucketAsync([/* ... */]);

Authorizes the Shield Response Team (SRT) to access the specified Amazon S3 bucket containing log data such as Application Load Balancer access logs, CloudFront logs, or logs from third party sources. You can associate up to 10 Amazon S3 buckets with your subscription.

To use the services of the SRT and make an AssociateDRTLogBucket request, you must be subscribed to the Business Support plan or the Enterprise Support plan.

Parameter Syntax

$result = $client->associateDRTLogBucket([
    'LogBucket' => '<string>', // REQUIRED
]);

Parameter Details

Members
LogBucket
Required: Yes
Type: string

The Amazon S3 bucket that contains the logs that you want to share.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

NoAssociatedRoleException:

The ARN of the role that you specified does not exist.

LimitsExceededException:

Exception that indicates that the operation would exceed a limit.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

AccessDeniedForDependencyException:

In order to grant the necessary access to the Shield Response Team (SRT) the user submitting the request must have the iam:PassRole permission. This error indicates the user did not have the appropriate permissions. For more information, see Granting a User Permissions to Pass a Role to an Amazon Web Services Service.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

AssociateDRTRole

$result = $client->associateDRTRole([/* ... */]);
$promise = $client->associateDRTRoleAsync([/* ... */]);

Authorizes the Shield Response Team (SRT) using the specified role, to access your Amazon Web Services account to assist with DDoS attack mitigation during potential attacks. This enables the SRT to inspect your WAF configuration and create or update WAF rules and web ACLs.

You can associate only one RoleArn with your subscription. If you submit an AssociateDRTRole request for an account that already has an associated role, the new RoleArn will replace the existing RoleArn.

Prior to making the AssociateDRTRole request, you must attach the AWSShieldDRTAccessPolicy managed policy to the role that you'll specify in the request. You can access this policy in the IAM console at AWSShieldDRTAccessPolicy. For more information see Adding and removing IAM identity permissions. The role must also trust the service principal drt.shield.amazonaws.com. For more information, see IAM JSON policy elements: Principal.

The SRT will have access only to your WAF and Shield resources. By submitting this request, you authorize the SRT to inspect your WAF and Shield configuration and create and update WAF rules and web ACLs on your behalf. The SRT takes these actions only if explicitly authorized by you.

You must have the iam:PassRole permission to make an AssociateDRTRole request. For more information, see Granting a user permissions to pass a role to an Amazon Web Services service.

To use the services of the SRT and make an AssociateDRTRole request, you must be subscribed to the Business Support plan or the Enterprise Support plan.

Parameter Syntax

$result = $client->associateDRTRole([
    'RoleArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
RoleArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the role the SRT will use to access your Amazon Web Services account.

Prior to making the AssociateDRTRole request, you must attach the AWSShieldDRTAccessPolicy managed policy to this role. For more information see Attaching and Detaching IAM Policies.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

AccessDeniedForDependencyException:

In order to grant the necessary access to the Shield Response Team (SRT) the user submitting the request must have the iam:PassRole permission. This error indicates the user did not have the appropriate permissions. For more information, see Granting a User Permissions to Pass a Role to an Amazon Web Services Service.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

AssociateHealthCheck

$result = $client->associateHealthCheck([/* ... */]);
$promise = $client->associateHealthCheckAsync([/* ... */]);

Adds health-based detection to the Shield Advanced protection for a resource. Shield Advanced health-based detection uses the health of your Amazon Web Services resource to improve responsiveness and accuracy in attack detection and response.

You define the health check in Route 53 and then associate it with your Shield Advanced protection. For more information, see Shield Advanced Health-Based Detection in the WAF Developer Guide.

Parameter Syntax

$result = $client->associateHealthCheck([
    'HealthCheckArn' => '<string>', // REQUIRED
    'ProtectionId' => '<string>', // REQUIRED
]);

Parameter Details

Members
HealthCheckArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the health check to associate with the protection.

ProtectionId
Required: Yes
Type: string

The unique identifier (ID) for the Protection object to add the health check association to.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

LimitsExceededException:

Exception that indicates that the operation would exceed a limit.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

InvalidResourceException:

Exception that indicates that the resource is invalid. You might not have access to the resource, or the resource might not exist.

AssociateProactiveEngagementDetails

$result = $client->associateProactiveEngagementDetails([/* ... */]);
$promise = $client->associateProactiveEngagementDetailsAsync([/* ... */]);

Initializes proactive engagement and sets the list of contacts for the Shield Response Team (SRT) to use. You must provide at least one phone number in the emergency contact list.

After you have initialized proactive engagement using this call, to disable or enable proactive engagement, use the calls DisableProactiveEngagement and EnableProactiveEngagement.

This call defines the list of email addresses and phone numbers that the SRT can use to contact you for escalations to the SRT and to initiate proactive customer support.

The contacts that you provide in the request replace any contacts that were already defined. If you already have contacts defined and want to use them, retrieve the list using DescribeEmergencyContactSettings and then provide it to this call.

Parameter Syntax

$result = $client->associateProactiveEngagementDetails([
    'EmergencyContactList' => [ // REQUIRED
        [
            'ContactNotes' => '<string>',
            'EmailAddress' => '<string>', // REQUIRED
            'PhoneNumber' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Members
EmergencyContactList
Required: Yes
Type: Array of EmergencyContact structures

A list of email addresses and phone numbers that the Shield Response Team (SRT) can use to contact you for escalations to the SRT and to initiate proactive customer support.

To enable proactive engagement, the contact list must include at least one phone number.

The contacts that you provide here replace any contacts that were already defined. If you already have contacts defined and want to use them, retrieve the list using DescribeEmergencyContactSettings and then provide it here.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

CreateProtection

$result = $client->createProtection([/* ... */]);
$promise = $client->createProtectionAsync([/* ... */]);

Enables Shield Advanced for a specific Amazon Web Services resource. The resource can be an Amazon CloudFront distribution, Amazon Route 53 hosted zone, Global Accelerator standard accelerator, Elastic IP Address, Application Load Balancer, or a Classic Load Balancer. You can protect Amazon EC2 instances and Network Load Balancers by association with protected Amazon EC2 Elastic IP addresses.

You can add protection to only a single resource with each CreateProtection request. You can add protection to multiple resources at once through the Shield Advanced console at https://console.aws.amazon.com/wafv2/shieldv2#/. For more information see Getting Started with Shield Advanced and Adding Shield Advanced protection to Amazon Web Services resources.

Parameter Syntax

$result = $client->createProtection([
    'Name' => '<string>', // REQUIRED
    'ResourceArn' => '<string>', // REQUIRED
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Members
Name
Required: Yes
Type: string

Friendly name for the Protection you are creating.

ResourceArn
Required: Yes
Type: string

The ARN (Amazon Resource Name) of the resource to be protected.

The ARN should be in one of the following formats:

  • For an Application Load Balancer: arn:aws:elasticloadbalancing:region:account-id:loadbalancer/app/load-balancer-name/load-balancer-id

  • For an Elastic Load Balancer (Classic Load Balancer): arn:aws:elasticloadbalancing:region:account-id:loadbalancer/load-balancer-name

  • For an Amazon CloudFront distribution: arn:aws:cloudfront::account-id:distribution/distribution-id

  • For an Global Accelerator standard accelerator: arn:aws:globalaccelerator::account-id:accelerator/accelerator-id

  • For Amazon Route 53: arn:aws:route53:::hostedzone/hosted-zone-id

  • For an Elastic IP address: arn:aws:ec2:region:account-id:eip-allocation/allocation-id

Tags
Type: Array of Tag structures

One or more tag key-value pairs for the Protection object that is created.

Result Syntax

[
    'ProtectionId' => '<string>',
]

Result Details

Members
ProtectionId
Type: string

The unique identifier (ID) for the Protection object that is created.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidResourceException:

Exception that indicates that the resource is invalid. You might not have access to the resource, or the resource might not exist.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

LimitsExceededException:

Exception that indicates that the operation would exceed a limit.

ResourceAlreadyExistsException:

Exception indicating the specified resource already exists. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

CreateProtectionGroup

$result = $client->createProtectionGroup([/* ... */]);
$promise = $client->createProtectionGroupAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->createProtectionGroup([
    'Aggregation' => 'SUM|MEAN|MAX', // REQUIRED
    'Members' => ['<string>', ...],
    'Pattern' => 'ALL|ARBITRARY|BY_RESOURCE_TYPE', // REQUIRED
    'ProtectionGroupId' => '<string>', // REQUIRED
    'ResourceType' => 'CLOUDFRONT_DISTRIBUTION|ROUTE_53_HOSTED_ZONE|ELASTIC_IP_ALLOCATION|CLASSIC_LOAD_BALANCER|APPLICATION_LOAD_BALANCER|GLOBAL_ACCELERATOR',
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Members
Aggregation
Required: Yes
Type: string

Defines how 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 Amazon CloudFront and origin resources for CloudFront distributions.

Members
Type: Array of strings

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.

Pattern
Required: Yes
Type: 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.

ProtectionGroupId
Required: Yes
Type: 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.

ResourceType
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.

Tags
Type: Array of Tag structures

One or more tag key-value pairs for the protection group.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceAlreadyExistsException:

Exception indicating the specified resource already exists. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

LimitsExceededException:

Exception that indicates that the operation would exceed a limit.

CreateSubscription

$result = $client->createSubscription([/* ... */]);
$promise = $client->createSubscriptionAsync([/* ... */]);

Activates Shield Advanced for an account.

For accounts that are members of an Organizations organization, Shield Advanced subscriptions are billed against the organization's payer account, regardless of whether the payer account itself is subscribed.

When you initially create a subscription, your subscription is set to be automatically renewed at the end of the existing subscription period. You can change this by submitting an UpdateSubscription request.

Parameter Syntax

$result = $client->createSubscription([
]);

Parameter Details

Members

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceAlreadyExistsException:

Exception indicating the specified resource already exists. If available, this exception includes details in additional properties.

DeleteProtection

$result = $client->deleteProtection([/* ... */]);
$promise = $client->deleteProtectionAsync([/* ... */]);

Deletes an Shield Advanced Protection.

Parameter Syntax

$result = $client->deleteProtection([
    'ProtectionId' => '<string>', // REQUIRED
]);

Parameter Details

Members
ProtectionId
Required: Yes
Type: string

The unique identifier (ID) for the Protection object to be deleted.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

DeleteProtectionGroup

$result = $client->deleteProtectionGroup([/* ... */]);
$promise = $client->deleteProtectionGroupAsync([/* ... */]);

Removes the specified protection group.

Parameter Syntax

$result = $client->deleteProtectionGroup([
    'ProtectionGroupId' => '<string>', // REQUIRED
]);

Parameter Details

Members
ProtectionGroupId
Required: Yes
Type: 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.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

DeleteSubscription

$result = $client->deleteSubscription([/* ... */]);
$promise = $client->deleteSubscriptionAsync([/* ... */]);

Removes Shield Advanced from an account. Shield Advanced requires a 1-year subscription commitment. You cannot delete a subscription prior to the completion of that commitment.

Parameter Syntax

$result = $client->deleteSubscription([
]);

Parameter Details

Members

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

LockedSubscriptionException:

You are trying to update a subscription that has not yet completed the 1-year commitment. You can change the AutoRenew parameter during the last 30 days of your subscription. This exception indicates that you are attempting to change AutoRenew prior to that period.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

DescribeAttack

$result = $client->describeAttack([/* ... */]);
$promise = $client->describeAttackAsync([/* ... */]);

Describes the details of a DDoS attack.

Parameter Syntax

$result = $client->describeAttack([
    'AttackId' => '<string>', // REQUIRED
]);

Parameter Details

Members
AttackId
Required: Yes
Type: string

The unique identifier (ID) for the attack.

Result Syntax

[
    'Attack' => [
        'AttackCounters' => [
            [
                'Average' => <float>,
                'Max' => <float>,
                'N' => <integer>,
                'Name' => '<string>',
                'Sum' => <float>,
                'Unit' => '<string>',
            ],
            // ...
        ],
        'AttackId' => '<string>',
        'AttackProperties' => [
            [
                'AttackLayer' => 'NETWORK|APPLICATION',
                'AttackPropertyIdentifier' => 'DESTINATION_URL|REFERRER|SOURCE_ASN|SOURCE_COUNTRY|SOURCE_IP_ADDRESS|SOURCE_USER_AGENT|WORDPRESS_PINGBACK_REFLECTOR|WORDPRESS_PINGBACK_SOURCE',
                'TopContributors' => [
                    [
                        'Name' => '<string>',
                        'Value' => <integer>,
                    ],
                    // ...
                ],
                'Total' => <integer>,
                'Unit' => 'BITS|BYTES|PACKETS|REQUESTS',
            ],
            // ...
        ],
        'EndTime' => <DateTime>,
        'Mitigations' => [
            [
                'MitigationName' => '<string>',
            ],
            // ...
        ],
        'ResourceArn' => '<string>',
        'StartTime' => <DateTime>,
        'SubResources' => [
            [
                'AttackVectors' => [
                    [
                        'VectorCounters' => [
                            [
                                'Average' => <float>,
                                'Max' => <float>,
                                'N' => <integer>,
                                'Name' => '<string>',
                                'Sum' => <float>,
                                'Unit' => '<string>',
                            ],
                            // ...
                        ],
                        'VectorType' => '<string>',
                    ],
                    // ...
                ],
                'Counters' => [
                    [
                        'Average' => <float>,
                        'Max' => <float>,
                        'N' => <integer>,
                        'Name' => '<string>',
                        'Sum' => <float>,
                        'Unit' => '<string>',
                    ],
                    // ...
                ],
                'Id' => '<string>',
                'Type' => 'IP|URL',
            ],
            // ...
        ],
    ],
]

Result Details

Members
Attack
Type: AttackDetail structure

The attack that you requested.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

AccessDeniedException:

Exception that indicates the specified AttackId does not exist, or the requester does not have the appropriate permissions to access the AttackId.

DescribeAttackStatistics

$result = $client->describeAttackStatistics([/* ... */]);
$promise = $client->describeAttackStatisticsAsync([/* ... */]);

Provides information about the number and type of attacks 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.

Parameter Syntax

$result = $client->describeAttackStatistics([
]);

Parameter Details

Members

Result Syntax

[
    'DataItems' => [
        [
            'AttackCount' => <integer>,
            'AttackVolume' => [
                'BitsPerSecond' => [
                    'Max' => <float>,
                ],
                'PacketsPerSecond' => [
                    'Max' => <float>,
                ],
                'RequestsPerSecond' => [
                    'Max' => <float>,
                ],
            ],
        ],
        // ...
    ],
    'TimeRange' => [
        'FromInclusive' => <DateTime>,
        'ToExclusive' => <DateTime>,
    ],
]

Result Details

Members
DataItems
Required: Yes
Type: Array of AttackStatisticsDataItem structures

The data that describes the attacks detected during the time period.

TimeRange
Required: Yes
Type: TimeRange structure

The time range of the attack.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

DescribeDRTAccess

$result = $client->describeDRTAccess([/* ... */]);
$promise = $client->describeDRTAccessAsync([/* ... */]);

Returns the current role and list of Amazon S3 log buckets used by the Shield Response Team (SRT) to access your Amazon Web Services account while assisting with attack mitigation.

Parameter Syntax

$result = $client->describeDRTAccess([
]);

Parameter Details

Members

Result Syntax

[
    'LogBucketList' => ['<string>', ...],
    'RoleArn' => '<string>',
]

Result Details

Members
LogBucketList
Type: Array of strings

The list of Amazon S3 buckets accessed by the SRT.

RoleArn
Type: string

The Amazon Resource Name (ARN) of the role the SRT used to access your Amazon Web Services account.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

DescribeEmergencyContactSettings

$result = $client->describeEmergencyContactSettings([/* ... */]);
$promise = $client->describeEmergencyContactSettingsAsync([/* ... */]);

A list of email addresses and phone numbers that the Shield Response Team (SRT) can use to contact you if you have proactive engagement enabled, for escalations to the SRT and to initiate proactive customer support.

Parameter Syntax

$result = $client->describeEmergencyContactSettings([
]);

Parameter Details

Members

Result Syntax

[
    'EmergencyContactList' => [
        [
            'ContactNotes' => '<string>',
            'EmailAddress' => '<string>',
            'PhoneNumber' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
EmergencyContactList
Type: Array of EmergencyContact structures

A list of email addresses and phone numbers that the Shield Response Team (SRT) can use to contact you if you have proactive engagement enabled, for escalations to the SRT and to initiate proactive customer support.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

DescribeProtection

$result = $client->describeProtection([/* ... */]);
$promise = $client->describeProtectionAsync([/* ... */]);

Lists the details of a Protection object.

Parameter Syntax

$result = $client->describeProtection([
    'ProtectionId' => '<string>',
    'ResourceArn' => '<string>',
]);

Parameter Details

Members
ProtectionId
Type: string

The unique identifier (ID) for the Protection object to describe. You must provide either the ResourceArn of the protected resource or the ProtectionID of the protection, but not both.

ResourceArn
Type: string

The ARN (Amazon Resource Name) of the protected Amazon Web Services resource. You must provide either the ResourceArn of the protected resource or the ProtectionID of the protection, but not both.

Result Syntax

[
    'Protection' => [
        'ApplicationLayerAutomaticResponseConfiguration' => [
            'Action' => [
                'Block' => [
                ],
                'Count' => [
                ],
            ],
            'Status' => 'ENABLED|DISABLED',
        ],
        'HealthCheckIds' => ['<string>', ...],
        'Id' => '<string>',
        'Name' => '<string>',
        'ProtectionArn' => '<string>',
        'ResourceArn' => '<string>',
    ],
]

Result Details

Members
Protection
Type: Protection structure

The Protection that you requested.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

DescribeProtectionGroup

$result = $client->describeProtectionGroup([/* ... */]);
$promise = $client->describeProtectionGroupAsync([/* ... */]);

Returns the specification for the specified protection group.

Parameter Syntax

$result = $client->describeProtectionGroup([
    'ProtectionGroupId' => '<string>', // REQUIRED
]);

Parameter Details

Members
ProtectionGroupId
Required: Yes
Type: 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.

Result Syntax

[
    'ProtectionGroup' => [
        'Aggregation' => 'SUM|MEAN|MAX',
        'Members' => ['<string>', ...],
        'Pattern' => 'ALL|ARBITRARY|BY_RESOURCE_TYPE',
        'ProtectionGroupArn' => '<string>',
        'ProtectionGroupId' => '<string>',
        'ResourceType' => 'CLOUDFRONT_DISTRIBUTION|ROUTE_53_HOSTED_ZONE|ELASTIC_IP_ALLOCATION|CLASSIC_LOAD_BALANCER|APPLICATION_LOAD_BALANCER|GLOBAL_ACCELERATOR',
    ],
]

Result Details

Members
ProtectionGroup
Required: Yes
Type: ProtectionGroup structure

A grouping of protected resources that you and Shield Advanced can monitor as a collective. This resource grouping improves the accuracy of detection and reduces false positives.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

DescribeSubscription

$result = $client->describeSubscription([/* ... */]);
$promise = $client->describeSubscriptionAsync([/* ... */]);

Provides details about the Shield Advanced subscription for an account.

Parameter Syntax

$result = $client->describeSubscription([
]);

Parameter Details

Members

Result Syntax

[
    'Subscription' => [
        'AutoRenew' => 'ENABLED|DISABLED',
        'EndTime' => <DateTime>,
        'Limits' => [
            [
                'Max' => <integer>,
                'Type' => '<string>',
            ],
            // ...
        ],
        'ProactiveEngagementStatus' => 'ENABLED|DISABLED|PENDING',
        'StartTime' => <DateTime>,
        'SubscriptionArn' => '<string>',
        'SubscriptionLimits' => [
            'ProtectionGroupLimits' => [
                'MaxProtectionGroups' => <integer>,
                'PatternTypeLimits' => [
                    'ArbitraryPatternLimits' => [
                        'MaxMembers' => <integer>,
                    ],
                ],
            ],
            'ProtectionLimits' => [
                'ProtectedResourceTypeLimits' => [
                    [
                        'Max' => <integer>,
                        'Type' => '<string>',
                    ],
                    // ...
                ],
            ],
        ],
        'TimeCommitmentInSeconds' => <integer>,
    ],
]

Result Details

Members
Subscription
Type: Subscription structure

The Shield Advanced subscription details for an account.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

DisableApplicationLayerAutomaticResponse

$result = $client->disableApplicationLayerAutomaticResponse([/* ... */]);
$promise = $client->disableApplicationLayerAutomaticResponseAsync([/* ... */]);

Disable the Shield Advanced automatic application layer DDoS mitigation feature for the protected resource. This stops Shield Advanced from creating, verifying, and applying WAF rules for attacks that it detects for the resource.

Parameter Syntax

$result = $client->disableApplicationLayerAutomaticResponse([
    'ResourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
ResourceArn
Required: Yes
Type: string

The ARN (Amazon Resource Name) of the protected resource.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

DisableProactiveEngagement

$result = $client->disableProactiveEngagement([/* ... */]);
$promise = $client->disableProactiveEngagementAsync([/* ... */]);

Removes authorization from the Shield Response Team (SRT) to notify contacts about escalations to the SRT and to initiate proactive customer support.

Parameter Syntax

$result = $client->disableProactiveEngagement([
]);

Parameter Details

Members

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

DisassociateDRTLogBucket

$result = $client->disassociateDRTLogBucket([/* ... */]);
$promise = $client->disassociateDRTLogBucketAsync([/* ... */]);

Removes the Shield Response Team's (SRT) access to the specified Amazon S3 bucket containing the logs that you shared previously.

Parameter Syntax

$result = $client->disassociateDRTLogBucket([
    'LogBucket' => '<string>', // REQUIRED
]);

Parameter Details

Members
LogBucket
Required: Yes
Type: string

The Amazon S3 bucket that contains the logs that you want to share.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

NoAssociatedRoleException:

The ARN of the role that you specified does not exist.

AccessDeniedForDependencyException:

In order to grant the necessary access to the Shield Response Team (SRT) the user submitting the request must have the iam:PassRole permission. This error indicates the user did not have the appropriate permissions. For more information, see Granting a User Permissions to Pass a Role to an Amazon Web Services Service.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

DisassociateDRTRole

$result = $client->disassociateDRTRole([/* ... */]);
$promise = $client->disassociateDRTRoleAsync([/* ... */]);

Removes the Shield Response Team's (SRT) access to your Amazon Web Services account.

Parameter Syntax

$result = $client->disassociateDRTRole([
]);

Parameter Details

Members

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

DisassociateHealthCheck

$result = $client->disassociateHealthCheck([/* ... */]);
$promise = $client->disassociateHealthCheckAsync([/* ... */]);

Removes health-based detection from the Shield Advanced protection for a resource. Shield Advanced health-based detection uses the health of your Amazon Web Services resource to improve responsiveness and accuracy in attack detection and response.

You define the health check in Route 53 and then associate or disassociate it with your Shield Advanced protection. For more information, see Shield Advanced Health-Based Detection in the WAF Developer Guide.

Parameter Syntax

$result = $client->disassociateHealthCheck([
    'HealthCheckArn' => '<string>', // REQUIRED
    'ProtectionId' => '<string>', // REQUIRED
]);

Parameter Details

Members
HealthCheckArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the health check that is associated with the protection.

ProtectionId
Required: Yes
Type: string

The unique identifier (ID) for the Protection object to remove the health check association from.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

InvalidResourceException:

Exception that indicates that the resource is invalid. You might not have access to the resource, or the resource might not exist.

EnableApplicationLayerAutomaticResponse

$result = $client->enableApplicationLayerAutomaticResponse([/* ... */]);
$promise = $client->enableApplicationLayerAutomaticResponseAsync([/* ... */]);

Enable the Shield Advanced automatic application layer DDoS mitigation for the protected resource.

This feature is available for Amazon CloudFront distributions and Application Load Balancers only.

This causes Shield Advanced to create, verify, and apply WAF rules for DDoS attacks that it detects for the resource. Shield Advanced applies the rules in a Shield rule group inside the web ACL that you've associated with the resource. For information about how automatic mitigation works and the requirements for using it, see Shield Advanced automatic application layer DDoS mitigation.

Don't use this action to make changes to automatic mitigation settings when it's already enabled for a resource. Instead, use UpdateApplicationLayerAutomaticResponse.

To use this feature, you must associate a web ACL with the protected resource. The web ACL must be created using the latest version of WAF (v2). You can associate the web ACL through the Shield Advanced console at https://console.aws.amazon.com/wafv2/shieldv2#/. For more information, see Getting Started with Shield Advanced. You can also associate the web ACL to the resource through the WAF console or the WAF API, but you must manage Shield Advanced automatic mitigation through Shield Advanced. For information about WAF, see WAF Developer Guide.

Parameter Syntax

$result = $client->enableApplicationLayerAutomaticResponse([
    'Action' => [ // REQUIRED
        'Block' => [
        ],
        'Count' => [
        ],
    ],
    'ResourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
Action
Required: Yes
Type: ResponseAction structure

Specifies the action setting that Shield Advanced should use in the WAF rules that it creates on behalf of the protected resource in response to DDoS attacks. You specify this as part of the configuration for the automatic application layer DDoS mitigation feature, when you enable or update automatic mitigation. Shield Advanced creates the WAF rules in a Shield Advanced-managed rule group, inside the web ACL that you have associated with the resource.

ResourceArn
Required: Yes
Type: string

The ARN (Amazon Resource Name) of the protected resource.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

LimitsExceededException:

Exception that indicates that the operation would exceed a limit.

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

EnableProactiveEngagement

$result = $client->enableProactiveEngagement([/* ... */]);
$promise = $client->enableProactiveEngagementAsync([/* ... */]);

Authorizes the Shield Response Team (SRT) to use email and phone to notify contacts about escalations to the SRT and to initiate proactive customer support.

Parameter Syntax

$result = $client->enableProactiveEngagement([
]);

Parameter Details

Members

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

GetSubscriptionState

$result = $client->getSubscriptionState([/* ... */]);
$promise = $client->getSubscriptionStateAsync([/* ... */]);

Returns the SubscriptionState, either Active or Inactive.

Parameter Syntax

$result = $client->getSubscriptionState([
]);

Parameter Details

Members

Result Syntax

[
    'SubscriptionState' => 'ACTIVE|INACTIVE',
]

Result Details

Members
SubscriptionState
Required: Yes
Type: string

The status of the subscription.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ListAttacks

$result = $client->listAttacks([/* ... */]);
$promise = $client->listAttacksAsync([/* ... */]);

Returns all ongoing DDoS attacks or all DDoS attacks during a specified time period.

Parameter Syntax

$result = $client->listAttacks([
    'EndTime' => [
        'FromInclusive' => <integer || string || DateTime>,
        'ToExclusive' => <integer || string || DateTime>,
    ],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'ResourceArns' => ['<string>', ...],
    'StartTime' => [
        'FromInclusive' => <integer || string || DateTime>,
        'ToExclusive' => <integer || string || DateTime>,
    ],
]);

Parameter Details

Members
EndTime
Type: TimeRange structure

The end of the time period for the attacks. This is a timestamp type. The request syntax listing for this call indicates a number type, but you can provide the time in any valid timestamp format setting.

MaxResults
Type: int

The greatest number of objects that you want Shield Advanced to return to the list request. Shield Advanced might return fewer objects than you indicate in this setting, even if more objects are available. If there are more objects remaining, Shield Advanced will always also return a NextToken value in the response.

The default setting is 20.

NextToken
Type: string

When you request a list of objects from Shield Advanced, if the response does not include all of the remaining available objects, Shield Advanced includes a NextToken value in the response. You can retrieve the next batch of objects by requesting the list again and providing the token that was returned by the prior call in your request.

You can indicate the maximum number of objects that you want Shield Advanced to return for a single call with the MaxResults setting. Shield Advanced will not return more than MaxResults objects, but may return fewer, even if more objects are still available.

Whenever more objects remain that Shield Advanced has not yet returned to you, the response will include a NextToken value.

On your first call to a list operation, leave this setting empty.

ResourceArns
Type: Array of strings

The ARNs (Amazon Resource Names) of the resources that were attacked. If you leave this blank, all applicable resources for this account will be included.

StartTime
Type: TimeRange structure

The start of the time period for the attacks. This is a timestamp type. The request syntax listing for this call indicates a number type, but you can provide the time in any valid timestamp format setting.

Result Syntax

[
    'AttackSummaries' => [
        [
            'AttackId' => '<string>',
            'AttackVectors' => [
                [
                    'VectorType' => '<string>',
                ],
                // ...
            ],
            'EndTime' => <DateTime>,
            'ResourceArn' => '<string>',
            'StartTime' => <DateTime>,
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members
AttackSummaries
Type: Array of AttackSummary structures

The attack information for the specified time range.

NextToken
Type: string

When you request a list of objects from Shield Advanced, if the response does not include all of the remaining available objects, Shield Advanced includes a NextToken value in the response. You can retrieve the next batch of objects by requesting the list again and providing the token that was returned by the prior call in your request.

You can indicate the maximum number of objects that you want Shield Advanced to return for a single call with the MaxResults setting. Shield Advanced will not return more than MaxResults objects, but may return fewer, even if more objects are still available.

Whenever more objects remain that Shield Advanced has not yet returned to you, the response will include a NextToken value.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

ListProtectionGroups

$result = $client->listProtectionGroups([/* ... */]);
$promise = $client->listProtectionGroupsAsync([/* ... */]);

Retrieves ProtectionGroup objects for the account. You can retrieve all protection groups or you can provide filtering criteria and retrieve just the subset of protection groups that match the criteria.

Parameter Syntax

$result = $client->listProtectionGroups([
    'InclusionFilters' => [
        'Aggregations' => ['<string>', ...],
        'Patterns' => ['<string>', ...],
        'ProtectionGroupIds' => ['<string>', ...],
        'ResourceTypes' => ['<string>', ...],
    ],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
InclusionFilters

Narrows the set of protection groups that the call retrieves. You can retrieve a single protection group by its name and you can retrieve all protection groups that are configured with specific pattern or aggregation settings. You can provide up to one criteria per filter type. Shield Advanced returns the protection groups that exactly match all of the search criteria that you provide.

MaxResults
Type: int

The greatest number of objects that you want Shield Advanced to return to the list request. Shield Advanced might return fewer objects than you indicate in this setting, even if more objects are available. If there are more objects remaining, Shield Advanced will always also return a NextToken value in the response.

The default setting is 20.

NextToken
Type: string

When you request a list of objects from Shield Advanced, if the response does not include all of the remaining available objects, Shield Advanced includes a NextToken value in the response. You can retrieve the next batch of objects by requesting the list again and providing the token that was returned by the prior call in your request.

You can indicate the maximum number of objects that you want Shield Advanced to return for a single call with the MaxResults setting. Shield Advanced will not return more than MaxResults objects, but may return fewer, even if more objects are still available.

Whenever more objects remain that Shield Advanced has not yet returned to you, the response will include a NextToken value.

On your first call to a list operation, leave this setting empty.

Result Syntax

[
    'NextToken' => '<string>',
    'ProtectionGroups' => [
        [
            'Aggregation' => 'SUM|MEAN|MAX',
            'Members' => ['<string>', ...],
            'Pattern' => 'ALL|ARBITRARY|BY_RESOURCE_TYPE',
            'ProtectionGroupArn' => '<string>',
            'ProtectionGroupId' => '<string>',
            'ResourceType' => 'CLOUDFRONT_DISTRIBUTION|ROUTE_53_HOSTED_ZONE|ELASTIC_IP_ALLOCATION|CLASSIC_LOAD_BALANCER|APPLICATION_LOAD_BALANCER|GLOBAL_ACCELERATOR',
        ],
        // ...
    ],
]

Result Details

Members
NextToken
Type: string

When you request a list of objects from Shield Advanced, if the response does not include all of the remaining available objects, Shield Advanced includes a NextToken value in the response. You can retrieve the next batch of objects by requesting the list again and providing the token that was returned by the prior call in your request.

You can indicate the maximum number of objects that you want Shield Advanced to return for a single call with the MaxResults setting. Shield Advanced will not return more than MaxResults objects, but may return fewer, even if more objects are still available.

Whenever more objects remain that Shield Advanced has not yet returned to you, the response will include a NextToken value.

ProtectionGroups
Required: Yes
Type: Array of ProtectionGroup structures

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

InvalidPaginationTokenException:

Exception that indicates that the NextToken specified in the request is invalid. Submit the request using the NextToken value that was returned in the prior response.

ListProtections

$result = $client->listProtections([/* ... */]);
$promise = $client->listProtectionsAsync([/* ... */]);

Retrieves Protection objects for the account. You can retrieve all protections or you can provide filtering criteria and retrieve just the subset of protections that match the criteria.

Parameter Syntax

$result = $client->listProtections([
    'InclusionFilters' => [
        'ProtectionNames' => ['<string>', ...],
        'ResourceArns' => ['<string>', ...],
        'ResourceTypes' => ['<string>', ...],
    ],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
InclusionFilters
Type: InclusionProtectionFilters structure

Narrows the set of protections that the call retrieves. You can retrieve a single protection by providing its name or the ARN (Amazon Resource Name) of its protected resource. You can also retrieve all protections for a specific resource type. You can provide up to one criteria per filter type. Shield Advanced returns protections that exactly match all of the filter criteria that you provide.

MaxResults
Type: int

The greatest number of objects that you want Shield Advanced to return to the list request. Shield Advanced might return fewer objects than you indicate in this setting, even if more objects are available. If there are more objects remaining, Shield Advanced will always also return a NextToken value in the response.

The default setting is 20.

NextToken
Type: string

When you request a list of objects from Shield Advanced, if the response does not include all of the remaining available objects, Shield Advanced includes a NextToken value in the response. You can retrieve the next batch of objects by requesting the list again and providing the token that was returned by the prior call in your request.

You can indicate the maximum number of objects that you want Shield Advanced to return for a single call with the MaxResults setting. Shield Advanced will not return more than MaxResults objects, but may return fewer, even if more objects are still available.

Whenever more objects remain that Shield Advanced has not yet returned to you, the response will include a NextToken value.

On your first call to a list operation, leave this setting empty.

Result Syntax

[
    'NextToken' => '<string>',
    'Protections' => [
        [
            'ApplicationLayerAutomaticResponseConfiguration' => [
                'Action' => [
                    'Block' => [
                    ],
                    'Count' => [
                    ],
                ],
                'Status' => 'ENABLED|DISABLED',
            ],
            'HealthCheckIds' => ['<string>', ...],
            'Id' => '<string>',
            'Name' => '<string>',
            'ProtectionArn' => '<string>',
            'ResourceArn' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
NextToken
Type: string

When you request a list of objects from Shield Advanced, if the response does not include all of the remaining available objects, Shield Advanced includes a NextToken value in the response. You can retrieve the next batch of objects by requesting the list again and providing the token that was returned by the prior call in your request.

You can indicate the maximum number of objects that you want Shield Advanced to return for a single call with the MaxResults setting. Shield Advanced will not return more than MaxResults objects, but may return fewer, even if more objects are still available.

Whenever more objects remain that Shield Advanced has not yet returned to you, the response will include a NextToken value.

Protections
Type: Array of Protection structures

The array of enabled Protection objects.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

InvalidPaginationTokenException:

Exception that indicates that the NextToken specified in the request is invalid. Submit the request using the NextToken value that was returned in the prior response.

ListResourcesInProtectionGroup

$result = $client->listResourcesInProtectionGroup([/* ... */]);
$promise = $client->listResourcesInProtectionGroupAsync([/* ... */]);

Retrieves the resources that are included in the protection group.

Parameter Syntax

$result = $client->listResourcesInProtectionGroup([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'ProtectionGroupId' => '<string>', // REQUIRED
]);

Parameter Details

Members
MaxResults
Type: int

The greatest number of objects that you want Shield Advanced to return to the list request. Shield Advanced might return fewer objects than you indicate in this setting, even if more objects are available. If there are more objects remaining, Shield Advanced will always also return a NextToken value in the response.

The default setting is 20.

NextToken
Type: string

When you request a list of objects from Shield Advanced, if the response does not include all of the remaining available objects, Shield Advanced includes a NextToken value in the response. You can retrieve the next batch of objects by requesting the list again and providing the token that was returned by the prior call in your request.

You can indicate the maximum number of objects that you want Shield Advanced to return for a single call with the MaxResults setting. Shield Advanced will not return more than MaxResults objects, but may return fewer, even if more objects are still available.

Whenever more objects remain that Shield Advanced has not yet returned to you, the response will include a NextToken value.

On your first call to a list operation, leave this setting empty.

ProtectionGroupId
Required: Yes
Type: 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.

Result Syntax

[
    'NextToken' => '<string>',
    'ResourceArns' => ['<string>', ...],
]

Result Details

Members
NextToken
Type: string

When you request a list of objects from Shield Advanced, if the response does not include all of the remaining available objects, Shield Advanced includes a NextToken value in the response. You can retrieve the next batch of objects by requesting the list again and providing the token that was returned by the prior call in your request.

You can indicate the maximum number of objects that you want Shield Advanced to return for a single call with the MaxResults setting. Shield Advanced will not return more than MaxResults objects, but may return fewer, even if more objects are still available.

Whenever more objects remain that Shield Advanced has not yet returned to you, the response will include a NextToken value.

ResourceArns
Required: Yes
Type: Array of strings

The Amazon Resource Names (ARNs) of the resources that are included in the protection group.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

InvalidPaginationTokenException:

Exception that indicates that the NextToken specified in the request is invalid. Submit the request using the NextToken value that was returned in the prior response.

ListTagsForResource

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

Gets information about Amazon Web Services tags for a specified Amazon Resource Name (ARN) in Shield.

Parameter Syntax

$result = $client->listTagsForResource([
    'ResourceARN' => '<string>', // REQUIRED
]);

Parameter Details

Members
ResourceARN
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the resource to get tags for.

Result Syntax

[
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
Tags
Type: Array of Tag structures

A list of tag key and value pairs associated with the specified resource.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidResourceException:

Exception that indicates that the resource is invalid. You might not have access to the resource, or the resource might not exist.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

TagResource

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Adds or updates tags for a resource in Shield.

Parameter Syntax

$result = $client->tagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'Tags' => [ // REQUIRED
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Members
ResourceARN
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the resource that you want to add or update tags for.

Tags
Required: Yes
Type: Array of Tag structures

The tags that you want to modify or add to the resource.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidResourceException:

Exception that indicates that the resource is invalid. You might not have access to the resource, or the resource might not exist.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

UntagResource

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Removes tags from a resource in Shield.

Parameter Syntax

$result = $client->untagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'TagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
ResourceARN
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the resource that you want to remove tags from.

TagKeys
Required: Yes
Type: Array of strings

The tag key for each tag that you want to remove from the resource.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidResourceException:

Exception that indicates that the resource is invalid. You might not have access to the resource, or the resource might not exist.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

UpdateApplicationLayerAutomaticResponse

$result = $client->updateApplicationLayerAutomaticResponse([/* ... */]);
$promise = $client->updateApplicationLayerAutomaticResponseAsync([/* ... */]);

Updates an existing Shield Advanced automatic application layer DDoS mitigation configuration for the specified resource.

Parameter Syntax

$result = $client->updateApplicationLayerAutomaticResponse([
    'Action' => [ // REQUIRED
        'Block' => [
        ],
        'Count' => [
        ],
    ],
    'ResourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
Action
Required: Yes
Type: ResponseAction structure

Specifies the action setting that Shield Advanced should use in the WAF rules that it creates on behalf of the protected resource in response to DDoS attacks. You specify this as part of the configuration for the automatic application layer DDoS mitigation feature, when you enable or update automatic mitigation. Shield Advanced creates the WAF rules in a Shield Advanced-managed rule group, inside the web ACL that you have associated with the resource.

ResourceArn
Required: Yes
Type: string

The ARN (Amazon Resource Name) of the resource.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

InvalidOperationException:

Exception that indicates that the operation would not cause any change to occur.

UpdateEmergencyContactSettings

$result = $client->updateEmergencyContactSettings([/* ... */]);
$promise = $client->updateEmergencyContactSettingsAsync([/* ... */]);

Updates the details of the list of email addresses and phone numbers that the Shield Response Team (SRT) can use to contact you if you have proactive engagement enabled, for escalations to the SRT and to initiate proactive customer support.

Parameter Syntax

$result = $client->updateEmergencyContactSettings([
    'EmergencyContactList' => [
        [
            'ContactNotes' => '<string>',
            'EmailAddress' => '<string>', // REQUIRED
            'PhoneNumber' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Members
EmergencyContactList
Type: Array of EmergencyContact structures

A list of email addresses and phone numbers that the Shield Response Team (SRT) can use to contact you if you have proactive engagement enabled, for escalations to the SRT and to initiate proactive customer support.

If you have proactive engagement enabled, the contact list must include at least one phone number.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

UpdateProtectionGroup

$result = $client->updateProtectionGroup([/* ... */]);
$promise = $client->updateProtectionGroupAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->updateProtectionGroup([
    'Aggregation' => 'SUM|MEAN|MAX', // REQUIRED
    'Members' => ['<string>', ...],
    'Pattern' => 'ALL|ARBITRARY|BY_RESOURCE_TYPE', // REQUIRED
    'ProtectionGroupId' => '<string>', // REQUIRED
    'ResourceType' => 'CLOUDFRONT_DISTRIBUTION|ROUTE_53_HOSTED_ZONE|ELASTIC_IP_ALLOCATION|CLASSIC_LOAD_BALANCER|APPLICATION_LOAD_BALANCER|GLOBAL_ACCELERATOR',
]);

Parameter Details

Members
Aggregation
Required: Yes
Type: string

Defines how 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 Amazon CloudFront distributions and origin resources for CloudFront distributions.

Members
Type: Array of strings

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.

Pattern
Required: Yes
Type: 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.

ProtectionGroupId
Required: Yes
Type: 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.

ResourceType
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.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

UpdateSubscription

$result = $client->updateSubscription([/* ... */]);
$promise = $client->updateSubscriptionAsync([/* ... */]);

Updates the details of an existing subscription. Only enter values for parameters you want to change. Empty parameters are not updated.

For accounts that are members of an Organizations organization, Shield Advanced subscriptions are billed against the organization's payer account, regardless of whether the payer account itself is subscribed.

Parameter Syntax

$result = $client->updateSubscription([
    'AutoRenew' => 'ENABLED|DISABLED',
]);

Parameter Details

Members
AutoRenew
Type: string

When you initally create a subscription, AutoRenew is set to ENABLED. If ENABLED, the subscription will be automatically renewed at the end of the existing subscription period. 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.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalErrorException:

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

LockedSubscriptionException:

You are trying to update a subscription that has not yet completed the 1-year commitment. You can change the AutoRenew parameter during the last 30 days of your subscription. This exception indicates that you are attempting to change AutoRenew prior to that period.

ResourceNotFoundException:

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

InvalidParameterException:

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

OptimisticLockException:

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

Shapes

AccessDeniedException

Description

Exception that indicates the specified AttackId does not exist, or the requester does not have the appropriate permissions to access the AttackId.

Members
message
Type: string

AccessDeniedForDependencyException

Description

In order to grant the necessary access to the Shield Response Team (SRT) the user submitting the request must have the iam:PassRole permission. This error indicates the user did not have the appropriate permissions. For more information, see Granting a User Permissions to Pass a Role to an Amazon Web Services Service.

Members
message
Type: string

ApplicationLayerAutomaticResponseConfiguration

Description

The automatic application layer DDoS mitigation settings for a Protection. This configuration determines whether Shield Advanced automatically manages rules in the web ACL in order to respond to application layer events that Shield Advanced determines to be DDoS attacks.

Members
Action
Required: Yes
Type: ResponseAction structure

Specifies the action setting that Shield Advanced should use in the WAF rules that it creates on behalf of the protected resource in response to DDoS attacks. You specify this as part of the configuration for the automatic application layer DDoS mitigation feature, when you enable or update automatic mitigation. Shield Advanced creates the WAF rules in a Shield Advanced-managed rule group, inside the web ACL that you have associated with the resource.

Status
Required: Yes
Type: string

Indicates whether automatic application layer DDoS mitigation is enabled for the protection.

AttackDetail

Description

The details of a DDoS attack.

Members
AttackCounters
Type: Array of SummarizedCounter structures

List of counters that describe the attack for the specified time period.

AttackId
Type: string

The unique identifier (ID) of the attack.

AttackProperties
Type: Array of AttackProperty structures

The array of objects that provide details of the Shield event.

For infrastructure layer events (L3 and L4 events), you can view metrics for top contributors in Amazon CloudWatch metrics. For more information, see Shield metrics and alarms in the WAF Developer Guide.

EndTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time the attack ended, in Unix time in seconds.

Mitigations
Type: Array of Mitigation structures

List of mitigation actions taken for the attack.

ResourceArn
Type: string

The ARN (Amazon Resource Name) of the resource that was attacked.

StartTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time the attack started, in Unix time in seconds.

SubResources
Type: Array of SubResourceSummary structures

If applicable, additional detail about the resource being attacked, for example, IP address or URL.

AttackProperty

Description

Details of a Shield event. This is provided as part of an AttackDetail.

Members
AttackLayer
Type: string

The type of Shield event that was observed. NETWORK indicates layer 3 and layer 4 events and APPLICATION indicates layer 7 events.

For infrastructure layer events (L3 and L4 events), you can view metrics for top contributors in Amazon CloudWatch metrics. For more information, see Shield metrics and alarms in the WAF Developer Guide.

AttackPropertyIdentifier
Type: string

Defines the Shield event property information that is provided. The WORDPRESS_PINGBACK_REFLECTOR and WORDPRESS_PINGBACK_SOURCE values are valid only for WordPress reflective pingback events.

TopContributors
Type: Array of Contributor structures

Contributor objects for the top five contributors to a Shield event. A contributor is a source of traffic that Shield Advanced identifies as responsible for some or all of an event.

Total
Type: long (int|float)

The total contributions made to this Shield event by all contributors.

Unit
Type: string

The unit used for the Contributor Value property.

AttackStatisticsDataItem

Description

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.

Members
AttackCount
Required: Yes
Type: long (int|float)

The number of attacks detected during the time period. This is always present, but might be zero.

AttackVolume
Type: AttackVolume structure

Information about the volume of attacks during the time period. If the accompanying AttackCount is zero, this setting might be empty.

AttackSummary

Description

Summarizes all DDoS attacks for a specified time period.

Members
AttackId
Type: string

The unique identifier (ID) of the attack.

AttackVectors
Type: Array of AttackVectorDescription structures

The list of attacks for a specified time period.

EndTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

The end time of the attack, in Unix time in seconds.

ResourceArn
Type: string

The ARN (Amazon Resource Name) of the resource that was attacked.

StartTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

The start time of the attack, in Unix time in seconds.

AttackVectorDescription

Description

Describes the attack.

Members
VectorType
Required: Yes
Type: string

The attack type. Valid values:

  • UDP_TRAFFIC

  • UDP_FRAGMENT

  • GENERIC_UDP_REFLECTION

  • DNS_REFLECTION

  • NTP_REFLECTION

  • CHARGEN_REFLECTION

  • SSDP_REFLECTION

  • PORT_MAPPER

  • RIP_REFLECTION

  • SNMP_REFLECTION

  • MSSQL_REFLECTION

  • NET_BIOS_REFLECTION

  • SYN_FLOOD

  • ACK_FLOOD

  • REQUEST_FLOOD

  • HTTP_REFLECTION

  • UDS_REFLECTION

  • MEMCACHED_REFLECTION

AttackVolume

Description

Information about the volume of attacks during the time period, included in an AttackStatisticsDataItem. If the accompanying AttackCount in the statistics object is zero, this setting might be empty.

Members
BitsPerSecond
Type: AttackVolumeStatistics structure

A statistics object that uses bits per second as the unit. This is included for network level attacks.

PacketsPerSecond
Type: AttackVolumeStatistics structure

A statistics object that uses packets per second as the unit. This is included for network level attacks.

RequestsPerSecond
Type: AttackVolumeStatistics structure

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.

AttackVolumeStatistics

Description

Statistics objects for the various data types in AttackVolume.

Members
Max
Required: Yes
Type: double

The maximum attack volume observed for the given unit.

BlockAction

Description

Specifies that Shield Advanced should configure its WAF rules with the WAF Block action.

This is only used in the context of the ResponseAction setting.

JSON specification: "Block": {}

Members

Contributor

Description

A contributor to the attack and their contribution.

Members
Name
Type: string

The name of the contributor. The type of name that you'll find here depends on the AttackPropertyIdentifier setting in the AttackProperty where this contributor is defined. For example, if the AttackPropertyIdentifier is SOURCE_COUNTRY, the Name could be United States.

Value
Type: long (int|float)

The contribution of this contributor expressed in Protection units. For example 10,000.

CountAction

Description

Specifies that Shield Advanced should configure its WAF rules with the WAF Count action.

This is only used in the context of the ResponseAction setting.

JSON specification: "Count": {}

Members

EmergencyContact

Description

Contact information that the SRT can use to contact you if you have proactive engagement enabled, for escalations to the SRT and to initiate proactive customer support.

Members
ContactNotes
Type: string

Additional notes regarding the contact.

EmailAddress
Required: Yes
Type: string

The email address for the contact.

PhoneNumber
Type: string

The phone number for the contact.

InclusionProtectionFilters

Description

Narrows the set of protections that the call retrieves. You can retrieve a single protection by providing its name or the ARN (Amazon Resource Name) of its protected resource. You can also retrieve all protections for a specific resource type. You can provide up to one criteria per filter type. Shield Advanced returns protections that exactly match all of the filter criteria that you provide.

Members
ProtectionNames
Type: Array of strings

The name of the protection that you want to retrieve.

ResourceArns
Type: Array of strings

The ARN (Amazon Resource Name) of the resource whose protection you want to retrieve.

ResourceTypes
Type: Array of strings

The type of protected resource whose protections you want to retrieve.

InclusionProtectionGroupFilters

Description

Narrows the set of protection groups that the call retrieves. You can retrieve a single protection group by its name and you can retrieve all protection groups that are configured with a specific pattern, aggregation, or resource type. You can provide up to one criteria per filter type. Shield Advanced returns the protection groups that exactly match all of the search criteria that you provide.

Members
Aggregations
Type: Array of strings

The aggregation setting of the protection groups that you want to retrieve.

Patterns
Type: Array of strings

The pattern specification of the protection groups that you want to retrieve.

ProtectionGroupIds
Type: Array of strings

The ID of the protection group that you want to retrieve.

ResourceTypes
Type: Array of strings

The resource type configuration of the protection groups that you want to retrieve. In the protection group configuration, you specify the resource type when you set the group's Pattern to BY_RESOURCE_TYPE.

InternalErrorException

Description

Exception that indicates that a problem occurred with the service infrastructure. You can retry the request.

Members
message
Type: string

InvalidOperationException

Description

Exception that indicates that the operation would not cause any change to occur.

Members
message
Type: string

InvalidPaginationTokenException

Description

Exception that indicates that the NextToken specified in the request is invalid. Submit the request using the NextToken value that was returned in the prior response.

Members
message
Type: string

InvalidParameterException

Description

Exception that indicates that the parameters passed to the API are invalid. If available, this exception includes details in additional properties.

Members
fields
Type: Array of ValidationExceptionField structures

Fields that caused the exception.

message
Type: string
reason
Type: string

Additional information about the exception.

InvalidResourceException

Description

Exception that indicates that the resource is invalid. You might not have access to the resource, or the resource might not exist.

Members
message
Type: string

Limit

Description

Specifies how many protections of a given type you can create.

Members
Max
Type: long (int|float)

The maximum number of protections that can be created for the specified Type.

Type
Type: string

The type of protection.

LimitsExceededException

Description

Exception that indicates that the operation would exceed a limit.

Members
Limit
Type: long (int|float)

The threshold that would be exceeded.

Type
Type: string

The type of limit that would be exceeded.

message
Type: string

LockedSubscriptionException

Description

You are trying to update a subscription that has not yet completed the 1-year commitment. You can change the AutoRenew parameter during the last 30 days of your subscription. This exception indicates that you are attempting to change AutoRenew prior to that period.

Members
message
Type: string

Mitigation

Description

The mitigation applied to a DDoS attack.

Members
MitigationName
Type: string

The name of the mitigation taken for this attack.

NoAssociatedRoleException

Description

The ARN of the role that you specified does not exist.

Members
message
Type: string

OptimisticLockException

Description

Exception that indicates that the resource state has been modified by another client. Retrieve the resource and then retry your request.

Members
message
Type: string

Protection

Description

An object that represents a resource that is under DDoS protection.

Members
ApplicationLayerAutomaticResponseConfiguration

The automatic application layer DDoS mitigation settings for the protection. This configuration determines whether Shield Advanced automatically manages rules in the web ACL in order to respond to application layer events that Shield Advanced determines to be DDoS attacks.

HealthCheckIds
Type: Array of strings

The unique identifier (ID) for the Route 53 health check that's associated with the protection.

Id
Type: string

The unique identifier (ID) of the protection.

Name
Type: string

The name of the protection. For example, My CloudFront distributions.

ProtectionArn
Type: string

The ARN (Amazon Resource Name) of the protection.

ResourceArn
Type: string

The ARN (Amazon Resource Name) of the Amazon Web Services resource that is protected.

ProtectionGroup

Description

A grouping of protected resources that you and Shield Advanced can monitor as a collective. This resource grouping improves the accuracy of detection and reduces false positives.

Members
Aggregation
Required: Yes
Type: string

Defines how 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 Amazon CloudFront distributions and origin resources for CloudFront distributions.

Members
Required: Yes
Type: Array of strings

The ARNs (Amazon Resource Names) 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.

Pattern
Required: Yes
Type: 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 ARNs (Amazon Resource Names), or include all resources of a specified resource type.

ProtectionGroupArn
Type: string

The ARN (Amazon Resource Name) of the protection group.

ProtectionGroupId
Required: Yes
Type: 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.

ResourceType
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.

ProtectionGroupArbitraryPatternLimits

Description

Limits settings on protection groups with arbitrary pattern type.

Members
MaxMembers
Required: Yes
Type: long (int|float)

The maximum number of resources you can specify for a single arbitrary pattern in a protection group.

ProtectionGroupLimits

Description

Limits settings on protection groups for your subscription.

Members
MaxProtectionGroups
Required: Yes
Type: long (int|float)

The maximum number of protection groups that you can have at one time.

PatternTypeLimits
Required: Yes
Type: ProtectionGroupPatternTypeLimits structure

Limits settings by pattern type in the protection groups for your subscription.

ProtectionGroupPatternTypeLimits

Description

Limits settings by pattern type in the protection groups for your subscription.

Members
ArbitraryPatternLimits
Required: Yes
Type: ProtectionGroupArbitraryPatternLimits structure

Limits settings on protection groups with arbitrary pattern type.

ProtectionLimits

Description

Limits settings on protections for your subscription.

Members
ProtectedResourceTypeLimits
Required: Yes
Type: Array of Limit structures

The maximum number of resource types that you can specify in a protection.

ResourceAlreadyExistsException

Description

Exception indicating the specified resource already exists. If available, this exception includes details in additional properties.

Members
message
Type: string
resourceType
Type: string

The type of resource that already exists.

ResourceNotFoundException

Description

Exception indicating the specified resource does not exist. If available, this exception includes details in additional properties.

Members
message
Type: string
resourceType
Type: string

Type of resource.

ResponseAction

Description

Specifies the action setting that Shield Advanced should use in the WAF rules that it creates on behalf of the protected resource in response to DDoS attacks. You specify this as part of the configuration for the automatic application layer DDoS mitigation feature, when you enable or update automatic mitigation. Shield Advanced creates the WAF rules in a Shield Advanced-managed rule group, inside the web ACL that you have associated with the resource.

Members
Block
Type: BlockAction structure

Specifies that Shield Advanced should configure its WAF rules with the WAF Block action.

You must specify exactly one action, either Block or Count.

Count
Type: CountAction structure

Specifies that Shield Advanced should configure its WAF rules with the WAF Count action.

You must specify exactly one action, either Block or Count.

SubResourceSummary

Description

The attack information for the specified SubResource.

Members
AttackVectors
Type: Array of SummarizedAttackVector structures

The list of attack types and associated counters.

Counters
Type: Array of SummarizedCounter structures

The counters that describe the details of the attack.

Id
Type: string

The unique identifier (ID) of the SubResource.

Type
Type: string

The SubResource type.

Subscription

Description

Information about the Shield Advanced subscription for an account.

Members
AutoRenew
Type: 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.

EndTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time your subscription will end.

Limits
Type: Array of Limit structures

Specifies how many protections of a given type you can create.

ProactiveEngagementStatus
Type: string

If ENABLED, the Shield Response Team (SRT) will use email and phone to notify contacts about escalations to the SRT 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 SRT will not proactively notify contacts about escalations or to initiate proactive customer support.

StartTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

The start time of the subscription, in Unix time in seconds.

SubscriptionArn
Type: string

The ARN (Amazon Resource Name) of the subscription.

SubscriptionLimits
Required: Yes
Type: SubscriptionLimits structure

Limits settings for your subscription.

TimeCommitmentInSeconds
Type: long (int|float)

The length, in seconds, of the Shield Advanced subscription for the account.

SubscriptionLimits

Description

Limits settings for your subscription.

Members
ProtectionGroupLimits
Required: Yes
Type: ProtectionGroupLimits structure

Limits settings on protection groups for your subscription.

ProtectionLimits
Required: Yes
Type: ProtectionLimits structure

Limits settings on protections for your subscription.

SummarizedAttackVector

Description

A summary of information about the attack.

Members
VectorCounters
Type: Array of SummarizedCounter structures

The list of counters that describe the details of the attack.

VectorType
Required: Yes
Type: string

The attack type, for example, SNMP reflection or SYN flood.

SummarizedCounter

Description

The counter that describes a DDoS attack.

Members
Average
Type: double

The average value of the counter for a specified time period.

Max
Type: double

The maximum value of the counter for a specified time period.

N
Type: int

The number of counters for a specified time period.

Name
Type: string

The counter name.

Sum
Type: double

The total of counter values for a specified time period.

Unit
Type: string

The unit of the counters.

Tag

Description

A tag associated with an Amazon Web Services resource. Tags are key:value pairs that you can use to categorize and manage your resources, for purposes like billing or other management. Typically, the tag key represents a category, such as "environment", and the tag value represents a specific value within that category, such as "test," "development," or "production". Or you might set the tag key to "customer" and the value to the customer name or ID. You can specify one or more tags to add to each Amazon Web Services resource, up to 50 tags for a resource.

Members
Key
Type: string

Part of the key:value pair that defines a tag. You can use a tag key to describe a category of information, such as "customer." Tag keys are case-sensitive.

Value
Type: string

Part of the key:value pair that defines a tag. You can use a tag value to describe a specific value within a category, such as "companyA" or "companyB." Tag values are case-sensitive.

TimeRange

Description

The time range.

Members
FromInclusive
Type: timestamp (string|DateTime or anything parsable by strtotime)

The start time, in Unix time in seconds.

ToExclusive
Type: timestamp (string|DateTime or anything parsable by strtotime)

The end time, in Unix time in seconds.

ValidationExceptionField

Description

Provides information about a particular parameter passed inside a request that resulted in an exception.

Members
message
Required: Yes
Type: string

The message describing why the parameter failed validation.

name
Required: Yes
Type: string

The name of the parameter that failed validation.