Shield examples using Amazon CLI - Amazon Command Line Interface
Actions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Shield examples using Amazon CLI

The following code examples show you how to perform actions and implement common scenarios by using the Amazon Command Line Interface with Shield.

Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios and cross-service examples.

Scenarios are code examples that show you how to accomplish a specific task by calling multiple functions within the same service.

Each example includes a link to GitHub, where you can find instructions on how to set up and run the code in context.

Topics

Actions

The following code example shows how to use associate-drt-log-bucket.

Amazon CLI

To authorize the DRT to access an Amazon S3 bucket

The following associate-drt-log-bucket example creates an association between the DRT and the specified S3 bucket. This permits the DRT to access the bucket on behalf of the account.:

aws shield associate-drt-log-bucket \
    --log-bucket flow-logs-for-website-lb

This command produces no output.

For more information, see Authorize the DDoS Response Team in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use associate-drt-role.

Amazon CLI

To authorize the DRT to mitigate potential attacks on your behalf

The following associate-drt-role example creates an association between the DRT and the specified role. The DRT can use the role to access and manage the account.

aws shield associate-drt-role \
    --role-arn arn:aws:iam::123456789012:role/service-role/DrtRole

This command produces no output.

For more information, see Authorize the DDoS Response Team in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use create-protection.

Amazon CLI

To enable Amazon Shield Advanced protection for a single Amazon resource

The following create-protection example enables Shield Advanced protection for the specified Amazon CloudFront distribution.

aws shield create-protection \
    --name "Protection for CloudFront distribution" \
    --resource-arn arn:aws:cloudfront::123456789012:distribution/E198WC25FXOWY8

Output:

{
    "ProtectionId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}

For more information, see Specify Your Resources to Protect in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use create-subscription.

Amazon CLI

To enable Amazon Shield Advanced protection for an account

The following create-subscription example enables Shield Advanced protection for the account.

aws shield create-subscription

This command produces no output.

For more information, see Getting Started with Amazon Shield Advanced in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use delete-protection.

Amazon CLI

To remove Amazon Shield Advanced protection from an Amazon resource

The following delete-protection example removes the specified Amazon Shield Advanced protection.

aws shield delete-protection \
    --protection-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

This command produces no output.

For more information, see Removing Amazon Shield Advanced from an Amazon Resource in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use describe-attack.

Amazon CLI

To retrieve a detailed description of an attack

The following describe-attack example displays details about the DDoS attack with the specified attack ID. You can obtain attack IDs by running the list-attacks command.

aws shield describe-attack --attack-id a1b2c3d4-5678-90ab-cdef-EXAMPLE22222

Output:

{
    "Attack": {
        "AttackId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
        "ResourceArn": "arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/testElb",
        "SubResources": [
            {
                "Type": "IP",
                "Id": "192.0.2.2",
                "AttackVectors": [
                    {
                        "VectorType": "SYN_FLOOD",
                        "VectorCounters": [
                            {
                                "Name": "SYN_FLOOD_BPS",
                                "Max": 982184.0,
                                "Average": 982184.0,
                                "Sum": 11786208.0,
                                "N": 12,
                                "Unit": "BPS"
                            }
                        ]
                    }
                ],
                "Counters": []
            },
            {
                "Type": "IP",
                "Id": "192.0.2.3",
                "AttackVectors": [
                    {
                        "VectorType": "SYN_FLOOD",
                        "VectorCounters": [
                            {
                                "Name": "SYN_FLOOD_BPS",
                                "Max": 982184.0,
                                "Average": 982184.0,
                                "Sum": 9821840.0,
                                "N": 10,
                                "Unit": "BPS"
                            }
                        ]
                    }
                ],
                "Counters": []
            },
            {
                "Type": "IP",
                "Id": "192.0.2.4",
                "AttackVectors": [
                    {
                        "VectorType": "SYN_FLOOD",
                        "VectorCounters": [
                            {
                                "Name": "SYN_FLOOD_BPS",
                                "Max": 982184.0,
                                "Average": 982184.0,
                                "Sum": 7857472.0,
                                "N": 8,
                                "Unit": "BPS"
                            }
                        ]
                    }
                ],
                "Counters": []
            },
            {
                "Type": "IP",
                "Id": "192.0.2.5",
                "AttackVectors": [
                    {
                        "VectorType": "SYN_FLOOD",
                        "VectorCounters": [
                            {
                                "Name": "SYN_FLOOD_BPS",
                                "Max": 982184.0,
                                "Average": 982184.0,
                                "Sum": 1964368.0,
                                "N": 2,
                                "Unit": "BPS"
                            }
                        ]
                    }
                ],
                "Counters": []
            },
            {
                "Type": "IP",
                "Id": "2001:DB8::bcde:4321:8765:0:0",
                "AttackVectors": [
                    {
                        "VectorType": "SYN_FLOOD",
                        "VectorCounters": [
                            {
                                "Name": "SYN_FLOOD_BPS",
                                "Max": 982184.0,
                                "Average": 982184.0,
                                "Sum": 1964368.0,
                                "N": 2,
                                "Unit": "BPS"
                            }
                        ]
                    }
                ],
                "Counters": []
            },
            {
                "Type": "IP",
                "Id": "192.0.2.6",
                "AttackVectors": [
                    {
                        "VectorType": "SYN_FLOOD",
                        "VectorCounters": [
                            {
                                "Name": "SYN_FLOOD_BPS",
                                "Max": 982184.0,
                                "Average": 982184.0,
                                "Sum": 1964368.0,
                                "N": 2,
                                "Unit": "BPS"
                            }
                        ]
                    }
                ],
                "Counters": []
            }
        ],
        "StartTime": 1576024927.457,
        "EndTime": 1576025647.457,
        "AttackCounters": [],
        "AttackProperties": [
            {
                "AttackLayer": "NETWORK",
                "AttackPropertyIdentifier": "SOURCE_IP_ADDRESS",
                "TopContributors": [
                    {
                        "Name": "198.51.100.5",
                        "Value": 2024475682
                    },
                    {
                        "Name": "198.51.100.8",
                        "Value": 1311380863
                    },
                    {
                        "Name": "203.0.113.4",
                        "Value": 900599855
                    },
                    {
                        "Name": "198.51.100.4",
                        "Value": 769417366
                    },
                    {
                        "Name": "203.1.113.13",
                        "Value": 757992847
                    }
                ],
                "Unit": "BYTES",
                "Total": 92773354841
            },
            {
                "AttackLayer": "NETWORK",
                "AttackPropertyIdentifier": "SOURCE_COUNTRY",
                "TopContributors": [
                    {
                        "Name": "United States",
                        "Value": 80938161764
                    },
                    {
                        "Name": "Brazil",
                        "Value": 9929864330
                    },
                    {
                        "Name": "Netherlands",
                        "Value": 1635009446
                    },
                    {
                        "Name": "Mexico",
                        "Value": 144832971
                    },
                    {
                        "Name": "Japan",
                        "Value": 45369000
                    }
                ],
                "Unit": "BYTES",
                "Total": 92773354841
            },
            {
                "AttackLayer": "NETWORK",
                "AttackPropertyIdentifier": "SOURCE_ASN",
                "TopContributors": [
                    {
                        "Name": "12345",
                        "Value": 74953625841
                    },
                    {
                        "Name": "12346",
                        "Value": 4440087595
                    },
                    {
                        "Name": "12347",
                        "Value": 1635009446
                    },
                    {
                        "Name": "12348",
                        "Value": 1221230000
                    },
                    {
                        "Name": "12349",
                        "Value": 1199425294
                    }
                ],
                "Unit": "BYTES",
                "Total": 92755479921
            }
        ],
        "Mitigations": []
    }
}

For more information, see Reviewing DDoS Incidents in the Amazon Shield Advanced Developer Guide.

  • For API details, see DescribeAttack in Amazon CLI Command Reference.

The following code example shows how to use describe-drt-access.

Amazon CLI

To retrieve a description of the authorizations the DRT has to mitigate attacks on your behalf

The following describe-drt-access example retrieves the role and S3 bucket authorizations that the DRT has, which allow it to respond to potential attacks on your behalf.

aws shield describe-drt-access

Output:

{
    "RoleArn": "arn:aws:iam::123456789012:role/service-role/DrtRole",
    "LogBucketList": [
        "flow-logs-for-website-lb"
    ]
}

For more information, see Authorize the DDoS Response Team in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use describe-emergency-contact-settings.

Amazon CLI

To retrieve emergency e-mail addresses that you have on file with the DRT

The following describe-emergency-contact-settings example retrieves the e-mail addresses that are on file with the DRT for the account. These are the addresses the DRT should contact when it's responding to a suspected attack.

aws shield describe-emergency-contact-settings

Output:

{
    "EmergencyContactList": [
        {
            "EmailAddress": "ops@example.com"
        },
        {
            "EmailAddress": "ddos-notifications@example.com"
       }
    ]
}

For more information, see How Amazon Shield Works<https://docs.aws.amazon.com/waf/latest/developerguide/ddos-overview.html> in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use describe-protection.

Amazon CLI

To retrieve the details for an Amazon Shield Advanced protection

The following describe-protection example displays details about the Shield Advanced protection with the specified ID. You can obtain protection IDs by running the list-protections command.

aws shield describe-protection \
    --protection-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

Output:

{
    "Protection": {
        "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "Name": "1.2.3.4",
        "ResourceArn": "arn:aws:ec2:us-west-2:123456789012:eip-allocation/eipalloc-0ac1537af40742a6d"
    }
}

For more information, see Specify Your Resources to Protect in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use describe-subscription.

Amazon CLI

To retrieve the details of the Amazon Shield Advanced protection for the account

The following describe-subscription example displays details about the Shield Advanced protection provided for the account.:

aws shield describe-subscription

Output:

{
    "Subscription": {
        "StartTime": 1534368978.0,
        "EndTime": 1597613778.0,
        "TimeCommitmentInSeconds": 63244800,
        "AutoRenew": "ENABLED",
        "Limits": [
            {
                "Type": "GLOBAL_ACCELERATOR",
                "Max": 1000
            },
            {
                "Type": "ROUTE53_HOSTED_ZONE",
                "Max": 1000
            },
            {
                "Type": "CF_DISTRIBUTION",
                "Max": 1000
            },
            {
                "Type": "ELB_LOAD_BALANCER",
                "Max": 1000
            },
            {
                "Type": "EC2_ELASTIC_IP_ALLOCATION",
                "Max": 1000
            }
        ]
    }
}

For more information, see How Amazon Shield Works in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use disassociate-drt-log-bucket.

Amazon CLI

To remove the authorization for DRT to access an Amazon S3 bucket on your behalf

The following disassociate-drt-log-bucket example removes the association between the DRT and the specified S3 bucket. After this command completes, the DRT can no longer access the bucket on behalf of the account.

aws shield disassociate-drt-log-bucket \
    --log-bucket flow-logs-for-website-lb

This command produces no output.

For more information, see Authorize the DDoS Response Team in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use disassociate-drt-role.

Amazon CLI

To remove the authorization for DRT to mitigate potential attacks on your behalf

The following disassociate-drt-role example removes the association between the DRT and the account. After this call, the DRT can no longer access or manage your account.

aws shield disassociate-drt-role

This command produces no output.

For more information, see Authorize the DDoS Response Team in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use get-subscription-state.

Amazon CLI

To retrieve the current state of the account's Amazon Shield Advanced subscription

The following get-subscription-state example retrieves the state of the Shield Advanced protection for the account.

aws shield get-subscription-state

Output:

{
    "SubscriptionState": "ACTIVE"
}

For more information, see How Amazon Shield Works in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use list-attacks.

Amazon CLI

To retrieve attack summaries from Amazon Shield Advanced

The following list-attacks example retrieves summaries of attacks for the specified Amazon CloudFront distribution during the specified time period. The response includes attack IDs that you can provide to the describe-attack command for detailed information on an attack.

aws shield list-attacks \
    --resource-arns arn:aws:cloudfront::12345678910:distribution/E1PXMP22ZVFAOR \
    --start-time FromInclusive=1529280000,ToExclusive=1529300000

Output:

{
    "AttackSummaries": [
        {
            "AttackId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
            "ResourceArn": "arn:aws:cloudfront::123456789012:distribution/E1PXMP22ZVFAOR",
            "StartTime": 1529280000.0,
            "EndTime": 1529449200.0,
            "AttackVectors": [
                {
                    "VectorType": "SYN_FLOOD"
                }
            ]
        }
    ]
}

For more information, see Reviewing DDoS Incidents in the Amazon Shield Advanced Developer Guide.

  • For API details, see ListAttacks in Amazon CLI Command Reference.

The following code example shows how to use list-protections.

Amazon CLI

To retrieve protection summaries from Amazon Shield Advanced

The following list-protections example retrieves summaries of the protections that are enabled for the account.

aws shield list-protections

Output:

{
    "Protections": [
        {
            "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
            "Name": "Protection for CloudFront distribution",
            "ResourceArn": "arn:aws:cloudfront::123456789012:distribution/E198WC25FXOWY8"
        }
    ]
}

For more information, see Specify Your Resources to Protect in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use update-emergency-contact-settings.

Amazon CLI

To define the emergency e-mail addresses that are on file with the DRT

The following update-emergency-contact-settings example defines two e-mail addresses that the DRT should contact when it's responding to a suspected attack.

aws shield update-emergency-contact-settings \
        --emergency-contact-list EmailAddress=ops@example.com EmailAddress=ddos-notifications@example.com

This command produces no output.

For more information, see How Amazon Shield Works in the Amazon Shield Advanced Developer Guide.

The following code example shows how to use update-subscription.

Amazon CLI

To modify the account's Amazon Shield Advanced subscription

The following update-subscription example enables auto-renewal of the Amazon Shield Advanced subscription for the account.

aws shield update-subscription \
    --auto-renew ENABLED

This command produces no output.

For more information, see How Amazon Shield Works in the Amazon Shield Advanced Developer Guide.