Skip to content

AwsShieldBuilder

Bases: AbstractAWSResourceBuilder['AwsShieldBuilder', AwsShieldConfig]

AWS CDK builder for AWS Shield Advanced DDoS protection configuration.

Orchestrates the deployment of AWS Shield Advanced protection for critical infrastructure components including CloudFront distributions and Route53 hosted zones. Provides enterprise-grade DDoS mitigation with automatic response capabilities, 24/7 DDoS Response Team support, and cost protection against attack-related scaling charges.

The builder creates: - CloudFront distribution Shield Advanced protection with automatic response - Route53 hosted zone Shield Advanced protection for DNS infrastructure - Application layer automatic response configuration for threat mitigation - Proper resource tagging for Shield protection management - Integration with existing CloudFront and Route53 resources

Source code in mare_aws_common_lib/builders/aws_shield_builder.py 
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
class AwsShieldBuilder(AbstractAWSResourceBuilder["AwsShieldBuilder", AwsShieldConfig]):
    """AWS CDK builder for AWS Shield Advanced DDoS protection configuration.

    Orchestrates the deployment of AWS Shield Advanced protection for critical
    infrastructure components including CloudFront distributions and Route53 hosted
    zones. Provides enterprise-grade DDoS mitigation with automatic response
    capabilities, 24/7 DDoS Response Team support, and cost protection against
    attack-related scaling charges.

    The builder creates:
    - CloudFront distribution Shield Advanced protection with automatic response
    - Route53 hosted zone Shield Advanced protection for DNS infrastructure
    - Application layer automatic response configuration for threat mitigation
    - Proper resource tagging for Shield protection management
    - Integration with existing CloudFront and Route53 resources
    """

    _resource_type : AWSResourceType = AWSResourceType.SHIELD
    _requires_builder_config: bool = False

    def reset(self) -> None:
        """Reset builder state and clear configuration data.

        Initializes the builder for a new build cycle by clearing all
        configuration data and resetting CloudFront distribution and
        Route53 references to default values.
        """
        super().reset()
        self._cloudfront_distribution: cloudfront.Distribution = None
        self._route53_config: Dict[str, Any] = {}

    def set_cloudfront_distribution(self, cloudfront_dist: cloudfront.Distribution) -> 'AwsShieldBuilder': 
        """Set the CloudFront distribution for Shield Advanced protection.

        Configures the CloudFront distribution that will receive AWS Shield Advanced
        DDoS protection, enabling enhanced threat detection and automatic mitigation
        capabilities for global content delivery infrastructure.

        Args:
            cloudfront_dist: CloudFront distribution CDK construct requiring protection

        Returns:
            Builder instance for method chaining
        """
        self._cloudfront_distribution = cloudfront_dist
        return self

    def set_route53_config(self, config: Dict[str, Any]) -> 'AwsShieldBuilder': 
        """Configure Route53 hosted zone for Shield Advanced protection.

        Sets the Route53 hosted zone configuration that will receive AWS Shield
        Advanced DDoS protection, securing DNS infrastructure against volumetric
        and application layer attacks targeting domain resolution services.

        Args:
            config: Route53 configuration containing hosted_zone_id and domain_name

        Returns:
            Builder instance for method chaining
        """
        self._route53_config = config
        return self

    def build(self, scope : Construct) -> None:
        """Build AWS Shield Advanced protection for CloudFront and Route53 resources.

        Creates Shield Advanced protection configurations for both CloudFront
        distribution and Route53 hosted zone with automatic response capabilities
        enabled. Establishes comprehensive DDoS protection coverage for web
        application infrastructure with real-time threat mitigation.

        The CloudFront protection includes application layer automatic response
        that can automatically block detected DDoS attacks, while Route53
        protection secures DNS resolution against volumetric attacks.

        Args:
            scope: CDK construct scope for resource creation

        Raises:
            ValidationError: If configuration validation fails
            ValueError: If required configurations are missing
        """
        super().build()

        shield_cloudfront = shield.CfnProtection(
            scope,
            self._get_cfn_logical_id("cloudfront"),
            name=self._get_name_for_resource(f"cloudfront-shield-protection-{self._application_helper.get_target_env()}", 
                                                max_length=AWSResourceNameLength.SHIELD.value),
            resource_arn=self._config.typed.cloudfront_distribution.distribution_arn,
            application_layer_automatic_response_configuration={
                "status": "ENABLED",  # Enables automatic mitigation
                "action": {
                    "block": {}  # Blocks detected DDoS attacks automatically
                }
            }
        )
        self._tag_resource(shield_cloudfront)

        hosted_zone: route53.HostedZone = self._get_route53_hosted_zone(scope)
        shield_route53 = shield.CfnProtection(
            scope,
            self._get_cfn_logical_id("route53"),
            name=self._get_name_for_resource(f"route53-shield-protection-{self._application_helper.get_target_env()}", 
                                                max_length=AWSResourceNameLength.SHIELD.value),
            resource_arn=hosted_zone.hosted_zone_arn
        )
        self._tag_resource(shield_route53)

    def _get_route53_hosted_zone(self, scope : Construct) -> route53.HostedZone :
        """Retrieve Route53 hosted zone reference for Shield protection.

        Creates a reference to the existing Route53 hosted zone that will
        receive AWS Shield Advanced protection, enabling DNS infrastructure
        security against DDoS attacks and DNS-based threats.

        Args:
            scope: CDK construct scope for resource reference

        Returns:
            Route53 hosted zone reference for Shield protection enrollment
        """
        return route53.HostedZone.from_hosted_zone_attributes(
            scope, 
            "HostedZone-Shield-Builder",
            hosted_zone_id = self._config.route53.hosted_zone_id,
            zone_name = self._config.route53.domain_name
        )

    def _set_config(self) -> None:
        """Validate and set the AWS Shield configuration from builder inputs.

        Combines the CloudFront distribution and Route53 configuration to create
        a validated AwsShieldConfig instance, ensuring all required resources
        and validation rules are satisfied for Shield Advanced deployment.

        Raises:
            ValidationError: If the combined configuration fails validation
        """
        try:
            self._config = AwsShieldConfig(**{
                "route53": self._route53_config,
                "cloudfront_distribution": self._cloudfront_distribution
            })
        except ValidationError as e:
            self._log_validation_error(e, AwsShieldConfig)
            raise

    def _control_consistency(self) -> None:
        """Validate builder state and configuration consistency.

        Performs pre-build validation to ensure all required configurations
        are present and the builder state is consistent for successful AWS
        Shield Advanced protection deployment. Validates both CloudFront
        distribution and Route53 hosted zone availability.

        Raises:
            ValueError: If Route53 configuration or CloudFront distribution is missing
            ValidationError: If configuration validation fails
        """
        super()._control_consistency()

        if not self._route53_config:
            raise ValueError("Route 53 configuration must be set before building")

        if not self._cloudfront_distribution:
            raise ValueError("Cloudfront distribution must be set before building.")

        self._set_config()

Attributes

_requires_builder_config = False class-attribute instance-attribute

_resource_type = AWSResourceType.SHIELD class-attribute instance-attribute

Functions

_control_consistency()

Validate builder state and configuration consistency.

Performs pre-build validation to ensure all required configurations are present and the builder state is consistent for successful AWS Shield Advanced protection deployment. Validates both CloudFront distribution and Route53 hosted zone availability.

Raises:

Type Description
ValueError

If Route53 configuration or CloudFront distribution is missing
ValidationError

If configuration validation fails
Source code in mare_aws_common_lib/builders/aws_shield_builder.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
def _control_consistency(self) -> None:
    """Validate builder state and configuration consistency.

    Performs pre-build validation to ensure all required configurations
    are present and the builder state is consistent for successful AWS
    Shield Advanced protection deployment. Validates both CloudFront
    distribution and Route53 hosted zone availability.

    Raises:
        ValueError: If Route53 configuration or CloudFront distribution is missing
        ValidationError: If configuration validation fails
    """
    super()._control_consistency()

    if not self._route53_config:
        raise ValueError("Route 53 configuration must be set before building")

    if not self._cloudfront_distribution:
        raise ValueError("Cloudfront distribution must be set before building.")

    self._set_config()

_get_route53_hosted_zone(scope)

Retrieve Route53 hosted zone reference for Shield protection.

Creates a reference to the existing Route53 hosted zone that will receive AWS Shield Advanced protection, enabling DNS infrastructure security against DDoS attacks and DNS-based threats.

Parameters:

Name Type Description Default
scope Construct

CDK construct scope for resource reference

 required

Returns:

Type Description
HostedZone

Route53 hosted zone reference for Shield protection enrollment
Source code in mare_aws_common_lib/builders/aws_shield_builder.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
def _get_route53_hosted_zone(self, scope : Construct) -> route53.HostedZone :
    """Retrieve Route53 hosted zone reference for Shield protection.

    Creates a reference to the existing Route53 hosted zone that will
    receive AWS Shield Advanced protection, enabling DNS infrastructure
    security against DDoS attacks and DNS-based threats.

    Args:
        scope: CDK construct scope for resource reference

    Returns:
        Route53 hosted zone reference for Shield protection enrollment
    """
    return route53.HostedZone.from_hosted_zone_attributes(
        scope, 
        "HostedZone-Shield-Builder",
        hosted_zone_id = self._config.route53.hosted_zone_id,
        zone_name = self._config.route53.domain_name
    )

_set_config()

Validate and set the AWS Shield configuration from builder inputs.

Combines the CloudFront distribution and Route53 configuration to create a validated AwsShieldConfig instance, ensuring all required resources and validation rules are satisfied for Shield Advanced deployment.

Raises:

Type Description
ValidationError

If the combined configuration fails validation
Source code in mare_aws_common_lib/builders/aws_shield_builder.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
def _set_config(self) -> None:
    """Validate and set the AWS Shield configuration from builder inputs.

    Combines the CloudFront distribution and Route53 configuration to create
    a validated AwsShieldConfig instance, ensuring all required resources
    and validation rules are satisfied for Shield Advanced deployment.

    Raises:
        ValidationError: If the combined configuration fails validation
    """
    try:
        self._config = AwsShieldConfig(**{
            "route53": self._route53_config,
            "cloudfront_distribution": self._cloudfront_distribution
        })
    except ValidationError as e:
        self._log_validation_error(e, AwsShieldConfig)
        raise

build(scope)

Build AWS Shield Advanced protection for CloudFront and Route53 resources.

Creates Shield Advanced protection configurations for both CloudFront distribution and Route53 hosted zone with automatic response capabilities enabled. Establishes comprehensive DDoS protection coverage for web application infrastructure with real-time threat mitigation.

The CloudFront protection includes application layer automatic response that can automatically block detected DDoS attacks, while Route53 protection secures DNS resolution against volumetric attacks.

Parameters:

Name Type Description Default
scope Construct

CDK construct scope for resource creation

 required

Raises:

Type Description
ValidationError

If configuration validation fails
ValueError

If required configurations are missing
Source code in mare_aws_common_lib/builders/aws_shield_builder.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def build(self, scope : Construct) -> None:
    """Build AWS Shield Advanced protection for CloudFront and Route53 resources.

    Creates Shield Advanced protection configurations for both CloudFront
    distribution and Route53 hosted zone with automatic response capabilities
    enabled. Establishes comprehensive DDoS protection coverage for web
    application infrastructure with real-time threat mitigation.

    The CloudFront protection includes application layer automatic response
    that can automatically block detected DDoS attacks, while Route53
    protection secures DNS resolution against volumetric attacks.

    Args:
        scope: CDK construct scope for resource creation

    Raises:
        ValidationError: If configuration validation fails
        ValueError: If required configurations are missing
    """
    super().build()

    shield_cloudfront = shield.CfnProtection(
        scope,
        self._get_cfn_logical_id("cloudfront"),
        name=self._get_name_for_resource(f"cloudfront-shield-protection-{self._application_helper.get_target_env()}", 
                                            max_length=AWSResourceNameLength.SHIELD.value),
        resource_arn=self._config.typed.cloudfront_distribution.distribution_arn,
        application_layer_automatic_response_configuration={
            "status": "ENABLED",  # Enables automatic mitigation
            "action": {
                "block": {}  # Blocks detected DDoS attacks automatically
            }
        }
    )
    self._tag_resource(shield_cloudfront)

    hosted_zone: route53.HostedZone = self._get_route53_hosted_zone(scope)
    shield_route53 = shield.CfnProtection(
        scope,
        self._get_cfn_logical_id("route53"),
        name=self._get_name_for_resource(f"route53-shield-protection-{self._application_helper.get_target_env()}", 
                                            max_length=AWSResourceNameLength.SHIELD.value),
        resource_arn=hosted_zone.hosted_zone_arn
    )
    self._tag_resource(shield_route53)

reset()

Reset builder state and clear configuration data.

Initializes the builder for a new build cycle by clearing all configuration data and resetting CloudFront distribution and Route53 references to default values.

Source code in mare_aws_common_lib/builders/aws_shield_builder.py 
33
34
35
36
37
38
39
40
41
42
def reset(self) -> None:
    """Reset builder state and clear configuration data.

    Initializes the builder for a new build cycle by clearing all
    configuration data and resetting CloudFront distribution and
    Route53 references to default values.
    """
    super().reset()
    self._cloudfront_distribution: cloudfront.Distribution = None
    self._route53_config: Dict[str, Any] = {}

set_cloudfront_distribution(cloudfront_dist)

Set the CloudFront distribution for Shield Advanced protection.

Configures the CloudFront distribution that will receive AWS Shield Advanced DDoS protection, enabling enhanced threat detection and automatic mitigation capabilities for global content delivery infrastructure.

Parameters:

Name Type Description Default
cloudfront_dist Distribution

CloudFront distribution CDK construct requiring protection

 required

Returns:

Type Description
AwsShieldBuilder

Builder instance for method chaining
Source code in mare_aws_common_lib/builders/aws_shield_builder.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def set_cloudfront_distribution(self, cloudfront_dist: cloudfront.Distribution) -> 'AwsShieldBuilder': 
    """Set the CloudFront distribution for Shield Advanced protection.

    Configures the CloudFront distribution that will receive AWS Shield Advanced
    DDoS protection, enabling enhanced threat detection and automatic mitigation
    capabilities for global content delivery infrastructure.

    Args:
        cloudfront_dist: CloudFront distribution CDK construct requiring protection

    Returns:
        Builder instance for method chaining
    """
    self._cloudfront_distribution = cloudfront_dist
    return self

set_route53_config(config)

Configure Route53 hosted zone for Shield Advanced protection.

Sets the Route53 hosted zone configuration that will receive AWS Shield Advanced DDoS protection, securing DNS infrastructure against volumetric and application layer attacks targeting domain resolution services.

Parameters:

Name Type Description Default
config Dict[str, Any]

Route53 configuration containing hosted_zone_id and domain_name

 required

Returns:

Type Description
AwsShieldBuilder

Builder instance for method chaining
Source code in mare_aws_common_lib/builders/aws_shield_builder.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def set_route53_config(self, config: Dict[str, Any]) -> 'AwsShieldBuilder': 
    """Configure Route53 hosted zone for Shield Advanced protection.

    Sets the Route53 hosted zone configuration that will receive AWS Shield
    Advanced DDoS protection, securing DNS infrastructure against volumetric
    and application layer attacks targeting domain resolution services.

    Args:
        config: Route53 configuration containing hosted_zone_id and domain_name

    Returns:
        Builder instance for method chaining
    """
    self._route53_config = config
    return self