Amazon Route 53 Resolver

2026/11/19 - Amazon Route 53 Resolver - 1 new 12 updated api methods

Changes  Route 53 Resolver DNS Firewall adds the AutoAllowlist firewall rule type, which observes the domains your VPCs resolve and allows the ones you approve, and the ListFirewallRuleDomains API.

ListFirewallRuleDomains (new) Link ¶

Retrieves the domains of an AutoAllowlist firewall rule. Only the owner of the rule group can call this operation. Results are paginated. Use MaxResults and NextToken to retrieve additional domains.

Identify the rule by FirewallThreatProtectionId to get the domains that DNS Firewall observed in the VPCs that use the rule group, through a rule group association or through a Route 53 Profile that includes the rule group, including VPCs in other accounts. Each domain is returned with its DomainStatus and request counts. Use QueryOptions to filter and sort the results.

Identify the rule's managed domain list by FirewallDomainListId to get the domains that the rule currently allows. For any other domain list, use ListFirewallDomains.

See also: AWS API Documentation

Request Syntax

client.list_firewall_rule_domains(
    FirewallRuleGroupId='string',
    FirewallThreatProtectionId='string',
    FirewallDomainListId='string',
    QueryOptions={
        'DomainStatus': 'OBSERVED'|'ALLOWED'|'DENIED',
        'SortBy': 'TIME_ADDED'|'DAILY_TOTAL'|'TOTAL_REQUESTS',
        'SortOrder': 'ASC'|'DESC',
        'DomainNameFilter': 'string'
    },
    MaxResults=123,
    NextToken='string'
)
type FirewallRuleGroupId:

string

param FirewallRuleGroupId:

[REQUIRED]

The unique identifier of the firewall rule group that contains the rule.

type FirewallThreatProtectionId:

string

param FirewallThreatProtectionId:

The threat protection ID that identifies an AutoAllowlist rule. Provide this to list an AutoAllowlist rule's domains.

type FirewallDomainListId:

string

param FirewallDomainListId:

The ID of the AutoAllowlist rule's managed domain list. Provide this to list the domains that the rule currently allows.

type QueryOptions:

dict

param QueryOptions:

Optional filters and sort order for the returned domains. If you don't specify this, the operation returns the OBSERVED domains sorted by TIME_ADDED in descending order. See ListFirewallRuleDomainsQueryOptions.

  • DomainStatus (string) --

    Filters the returned domains by review status. Valid values:

    • OBSERVED - Domains that DNS Firewall saw in the VPCs' DNS traffic and that you haven't allowed or denied. After the look-back window, a domain is observed when any DNS Firewall rule blocks a query for it from a VPC that uses the rule group, including rules in other rule groups, or when you remove it from the managed domain list. Domains from the look-back period that keep being queried and aren't blocked move to ALLOWED within about a day after the rule is created.

    • ALLOWED - Domains that DNS Firewall allowed queries for, whether or not they're in the rule's managed domain list.

    • DENIED - Domains that were denied with the DENY operation. A denied domain that is still queried and not blocked can move to ALLOWED.

    If you don't specify a value, the operation returns OBSERVED domains.

  • SortBy (string) --

    The attribute to sort the returned domains by. Valid values:

    • TIME_ADDED - The AddedTime of the domain.

    • DAILY_TOTAL - The Last24HourRequests count.

    • TOTAL_REQUESTS - The TotalRequests count.

    If you don't specify a value, the operation sorts by TIME_ADDED.

  • SortOrder (string) --

    The sort direction: ASC for ascending or DESC for descending. If you don't specify a value, the operation sorts in descending order.

  • DomainNameFilter (string) --

    Returns only the domains whose name contains this substring.

type MaxResults:

integer

param MaxResults:

The maximum number of domains that you want to return in a single call. If more domains remain than can be returned, the response includes a NextToken value that you can use in a subsequent call to get the next batch. The default is 100.

type NextToken:

string

param NextToken:

For the first call to this operation, omit this value. If more domains remain than can be returned in a single call, the response includes a NextToken value. In your next call, specify that value to get the next batch of domains.

rtype:

dict

returns:

Response Syntax

{
    'Domains': [
        {
            'DomainName': 'string',
            'DomainStatus': 'OBSERVED'|'ALLOWED'|'DENIED'|'UNKNOWN',
            'Last24HourRequests': 123,
            'TotalRequests': 123,
            'AddedTime': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Domains (list) --

      The domains for the rule. See FirewallRuleDomain.

      • (dict) --

        A domain that DNS Firewall observed for an AutoAllowlist rule, with its review status and request volume. Counts are aggregated across all VPCs that use the rule group, through a rule group association or through a Route 53 Profile that includes the rule group, including VPCs in other accounts. The domain isn't attributed to the VPC or account in which it was observed.

        • DomainName (string) --

          The domain name.

        • DomainStatus (string) --

          The review status of the domain:

          • OBSERVED - DNS Firewall saw the domain in the VPCs' DNS traffic and you haven't allowed or denied it. The look-back window seeds the initial observed domains. After that, a domain becomes observed when any DNS Firewall rule blocks a query for it from a VPC that uses the rule group, including rules in other rule groups, or when you remove it from the managed domain list with REMOVE. To keep observing new domains, place a rule that blocks the domains you haven't approved after the AutoAllowlist rule. Domains from the look-back period that keep being queried and aren't blocked move to ALLOWED within about a day after the rule is created. Observed domains aren't evaluated for safety, so review them before you allow them.

          • ALLOWED - DNS Firewall allowed queries for the domain, whether or not the domain is in the rule's managed domain list. To get the domains in the managed domain list (the allowlist that the rule enforces), call ListFirewallRuleDomains with FirewallDomainListId.

          • DENIED - The domain was denied with the DENY operation of UpdateFirewallDomains, which also removes it from the managed domain list if it was there. A denied domain that is still queried and not blocked can move to ALLOWED.

        • Last24HourRequests (integer) --

          The number of DNS requests observed for this domain in the last 24 hours.

        • TotalRequests (integer) --

          The total number of DNS requests observed for this domain since it was first added, including the requests in the look-back window that seeded the rule.

        • AddedTime (string) --

          The date and time when the domain was first observed and added, in RFC 3339 format.

    • NextToken (string) --

      If more domains remain than were returned in this response, DNS Firewall provides a NextToken value that you can use in a subsequent call to get the next batch of domains.

BatchCreateFirewallRule (updated) Link ¶
Changes (request, response)
Request
{'CreateFirewallRuleEntries': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                                      'ImportFromFirewallDomainListId': 'string',
                                                                      'InitialDataTimeframeHours': 'integer'}}}}
Response
{'CreateErrors': {'FirewallRule': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                                          'ImportFromFirewallDomainListId': 'string',
                                                                          'InitialDataTimeframeHours': 'integer'}}}},
 'CreatedFirewallRules': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                                 'ImportFromFirewallDomainListId': 'string',
                                                                 'InitialDataTimeframeHours': 'integer'}}}}

Creates multiple DNS Firewall rules in the specified rule group.

See also: AWS API Documentation

Request Syntax

client.batch_create_firewall_rule(
    CreateFirewallRuleEntries=[
        {
            'CreatorRequestId': 'string',
            'FirewallRuleGroupId': 'string',
            'FirewallDomainListId': 'string',
            'Priority': 123,
            'Action': 'ALLOW'|'BLOCK'|'ALERT',
            'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
            'BlockOverrideDomain': 'string',
            'BlockOverrideDnsType': 'CNAME',
            'BlockOverrideTtl': 123,
            'Name': 'string',
            'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
            'Qtype': 'string',
            'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
            'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
            'FirewallRuleType': {
                'PartnerThreatProtection': {
                    'Partner': 'string'
                },
                'FirewallAdvancedContentCategory': {
                    'Category': 'string'
                },
                'FirewallAdvancedThreatCategory': {
                    'Category': 'string'
                },
                'DnsThreatProtection': {
                    'Value': 'string',
                    'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
                },
                'AutoAllowlist': {
                    'InitialDataTimeframeHours': 123,
                    'ImportFromFirewallDomainListId': 'string',
                    'AutoAllowlistFirewallDomainListId': 'string'
                }
            }
        },
    ]
)
type CreateFirewallRuleEntries:

list

param CreateFirewallRuleEntries:

[REQUIRED]

The list of firewall rules to create.

  • (dict) --

    The details for creating a single firewall rule in a batch operation.

    • CreatorRequestId (string) -- [REQUIRED]

      A unique string that identifies the request and that allows you to retry failed requests without the risk of running the operation twice. CreatorRequestId can be any unique string, for example, a date/time stamp.

    • FirewallRuleGroupId (string) -- [REQUIRED]

      The unique identifier of the firewall rule group where you want to create the rule.

    • FirewallDomainListId (string) --

      The ID of the domain list that you want to use in the rule. This setting is mutually exclusive with DnsThreatProtection and FirewallRuleType.

    • Priority (integer) -- [REQUIRED]

      The setting that determines the processing order of the rule in the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

    • Action (string) -- [REQUIRED]

      The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

      • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

      • ALERT - Permit the request and send metrics and logs to CloudWatch.

      • BLOCK - Disallow the request. This option requires additional details in the rule's BlockResponse.

    • BlockResponse (string) --

      The way that you want DNS Firewall to block the request, used with the rule action setting BLOCK.

      • NODATA - Respond indicating that the query was successful, but no response is available for it.

      • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

      • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

    • BlockOverrideDomain (string) --

      The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

    • BlockOverrideDnsType (string) --

      The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

    • BlockOverrideTtl (integer) --

      The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      This setting is required if the BlockResponse setting is OVERRIDE.

    • Name (string) -- [REQUIRED]

      A name that lets you identify the rule in the rule group.

    • FirewallDomainRedirectionAction (string) --

      How you want the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

      INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

      TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the redirection list to the domain list.

    • Qtype (string) --

      The DNS query type you want the rule to evaluate. Allowed values are:

      • A: Returns an IPv4 address.

      • AAAA: Returns an IPv6 address.

      • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

      • CNAME: Returns another domain name.

      • DS: Record that identifies the DNSSEC signing key of a delegated zone.

      • MX: Specifies mail servers.

      • NAPTR: Regular-expression-based rewriting of domain names.

      • NS: Authoritative name servers.

      • PTR: Maps an IP address to a domain name.

      • SOA: Start of authority record for the zone.

      • SPF: Lists the servers authorized to send emails from a domain.

      • SRV: Application specific values that identify servers.

      • TXT: Verifies email senders and application-specific values.

      • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

    • DnsThreatProtection (string) --

      The type of the DNS Firewall Advanced rule. This setting is mutually exclusive with FirewallDomainListId and FirewallRuleType. Valid values are:

      • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

      • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

      • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

    • ConfidenceThreshold (string) --

      The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

      • LOW: Provides the highest detection rate for threats, but also increases false positives.

      • MEDIUM: Provides a balance between detecting threats and false positives.

      • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

    • FirewallRuleType (dict) --

      The rule type configuration for the firewall rule. This is a tagged union — set exactly one of its members. This setting is mutually exclusive with the top-level FirewallDomainListId and DnsThreatProtection fields. Use one of:

      • FirewallAdvancedContentCategory — match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

      • FirewallAdvancedThreatCategory — match an Amazon Web Services-managed advanced threat category (for example, PHISHING).

      • DnsThreatProtection — match a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

      • PartnerThreatProtection — match a third-party threat feed delivered through Amazon Web Services Marketplace. The selected partner must be an active subscription on the calling account.

      • AutoAllowlist — automatically observe the domains that the VPCs associated with the rule group resolve, and allow the ones that you approve. See AutoAllowlistConfig.

      To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

      • PartnerThreatProtection (dict) --

        Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

        • Partner (string) -- [REQUIRED]

          The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

      • FirewallAdvancedContentCategory (dict) --

        Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

        • Category (string) -- [REQUIRED]

          The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

      • FirewallAdvancedThreatCategory (dict) --

        Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

        • Category (string) -- [REQUIRED]

          The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

      • DnsThreatProtection (dict) --

        Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

        • Value (string) -- [REQUIRED]

          The type of DNS threat protection. Valid values are:

          • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

          • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

          • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

        • ConfidenceThreshold (string) -- [REQUIRED]

          The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

          • LOW: Provides the highest detection rate for threats, but also increases false positives.

          • MEDIUM: Provides a balance between detecting threats and false positives.

          • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

      • AutoAllowlist (dict) --

        Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

        • InitialDataTimeframeHours (integer) -- [REQUIRED]

          The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

        • ImportFromFirewallDomainListId (string) --

          The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

        • AutoAllowlistFirewallDomainListId (string) --

          The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

rtype:

dict

returns:

Response Syntax

{
    'CreatedFirewallRules': [
        {
            'FirewallRuleGroupId': 'string',
            'FirewallDomainListId': 'string',
            'FirewallThreatProtectionId': 'string',
            'Name': 'string',
            'Priority': 123,
            'Action': 'ALLOW'|'BLOCK'|'ALERT',
            'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
            'BlockOverrideDomain': 'string',
            'BlockOverrideDnsType': 'CNAME',
            'BlockOverrideTtl': 123,
            'CreatorRequestId': 'string',
            'CreationTime': 'string',
            'ModificationTime': 'string',
            'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
            'Qtype': 'string',
            'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
            'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
            'FirewallRuleType': {
                'PartnerThreatProtection': {
                    'Partner': 'string'
                },
                'FirewallAdvancedContentCategory': {
                    'Category': 'string'
                },
                'FirewallAdvancedThreatCategory': {
                    'Category': 'string'
                },
                'DnsThreatProtection': {
                    'Value': 'string',
                    'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
                },
                'AutoAllowlist': {
                    'InitialDataTimeframeHours': 123,
                    'ImportFromFirewallDomainListId': 'string',
                    'AutoAllowlistFirewallDomainListId': 'string'
                }
            },
            'Status': 'string',
            'StatusMessage': 'string'
        },
    ],
    'CreateErrors': [
        {
            'FirewallRule': {
                'CreatorRequestId': 'string',
                'FirewallRuleGroupId': 'string',
                'FirewallDomainListId': 'string',
                'Priority': 123,
                'Action': 'ALLOW'|'BLOCK'|'ALERT',
                'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
                'BlockOverrideDomain': 'string',
                'BlockOverrideDnsType': 'CNAME',
                'BlockOverrideTtl': 123,
                'Name': 'string',
                'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
                'Qtype': 'string',
                'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
                'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
                'FirewallRuleType': {
                    'PartnerThreatProtection': {
                        'Partner': 'string'
                    },
                    'FirewallAdvancedContentCategory': {
                        'Category': 'string'
                    },
                    'FirewallAdvancedThreatCategory': {
                        'Category': 'string'
                    },
                    'DnsThreatProtection': {
                        'Value': 'string',
                        'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
                    },
                    'AutoAllowlist': {
                        'InitialDataTimeframeHours': 123,
                        'ImportFromFirewallDomainListId': 'string',
                        'AutoAllowlistFirewallDomainListId': 'string'
                    }
                }
            },
            'Code': 'string',
            'Message': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • CreatedFirewallRules (list) --

      The firewall rules that were successfully created by the request.

      • (dict) --

        A single firewall rule in a rule group.

        • FirewallRuleGroupId (string) --

          The unique identifier of the Firewall rule group of the rule.

        • FirewallDomainListId (string) --

          The ID of the domain list that's used in the rule.

        • FirewallThreatProtectionId (string) --

          ID of the DNS Firewall Advanced rule.

        • Name (string) --

          The name of the rule.

        • Priority (integer) --

          The priority of the rule in the rule group. This value must be unique within the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

        • Action (string) --

          The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

          • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

          • ALERT - Permit the request to go through but send an alert to the logs.

          • BLOCK - Disallow the request. If this is specified, additional handling details are provided in the rule's BlockResponse setting.

        • BlockResponse (string) --

          The way that you want DNS Firewall to block the request. Used for the rule action setting BLOCK.

          • NODATA - Respond indicating that the query was successful, but no response is available for it.

          • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

          • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

        • BlockOverrideDomain (string) --

          The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • BlockOverrideDnsType (string) --

          The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • BlockOverrideTtl (integer) --

          The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • CreatorRequestId (string) --

          A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of executing the operation twice. This can be any unique string, for example, a timestamp.

        • CreationTime (string) --

          The date and time that the rule was created, in Unix time format and Coordinated Universal Time (UTC).

        • ModificationTime (string) --

          The date and time that the rule was last modified, in Unix time format and Coordinated Universal Time (UTC).

        • FirewallDomainRedirectionAction (string) --

          How you want the the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

          INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

          TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the domain in the redirection list to the domain list.

        • Qtype (string) --

          The DNS query type you want the rule to evaluate. Allowed values are;

          • A: Returns an IPv4 address.

          • AAAA: Returns an Ipv6 address.

          • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

          • CNAME: Returns another domain name.

          • DS: Record that identifies the DNSSEC signing key of a delegated zone.

          • MX: Specifies mail servers.

          • NAPTR: Regular-expression-based rewriting of domain names.

          • NS: Authoritative name servers.

          • PTR: Maps an IP address to a domain name.

          • SOA: Start of authority record for the zone.

          • SPF: Lists the servers authorized to send emails from a domain.

          • SRV: Application specific values that identify servers.

          • TXT: Verifies email senders and application-specific values.

          • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

        • DnsThreatProtection (string) --

          The type of the DNS Firewall Advanced rule. Valid values are:

          • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

          • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

          • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

        • ConfidenceThreshold (string) --

          The confidence threshold for DNS Firewall Advanced. You must provide this value when you create a DNS Firewall Advanced rule. The confidence level values mean:

          • LOW: Provides the highest detection rate for threats, but also increases false positives.

          • MEDIUM: Provides a balance between detecting threats and false positives.

          • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

        • FirewallRuleType (dict) --

          The rule type configuration for the firewall rule. This is a tagged union — exactly one of its members will be populated. Possible members are:

          • FirewallAdvancedContentCategory — an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

          • FirewallAdvancedThreatCategory — an Amazon Web Services-managed advanced threat category (for example, PHISHING).

          • DnsThreatProtection — a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

          • PartnerThreatProtection — a third-party threat feed delivered through Amazon Web Services Marketplace.

          • AutoAllowlist — an AutoAllowlist rule, which allows the domains on its managed domain list. See AutoAllowlistConfig.

          To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

          • PartnerThreatProtection (dict) --

            Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

            • Partner (string) --

              The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

          • FirewallAdvancedContentCategory (dict) --

            Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

            • Category (string) --

              The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

          • FirewallAdvancedThreatCategory (dict) --

            Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

            • Category (string) --

              The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

          • DnsThreatProtection (dict) --

            Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

            • Value (string) --

              The type of DNS threat protection. Valid values are:

              • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

              • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

              • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

            • ConfidenceThreshold (string) --

              The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

              • LOW: Provides the highest detection rate for threats, but also increases false positives.

              • MEDIUM: Provides a balance between detecting threats and false positives.

              • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

          • AutoAllowlist (dict) --

            Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

            • InitialDataTimeframeHours (integer) --

              The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

            • ImportFromFirewallDomainListId (string) --

              The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

            • AutoAllowlistFirewallDomainListId (string) --

              The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

        • Status (string) --

          The lifecycle state of the firewall rule. Possible values:

          • CREATING — DNS Firewall is provisioning the rule. Rules created with the PartnerThreatProtection rule type begin in this state while DNS Firewall verifies the calling account's Amazon Web Services Marketplace entitlement. Rules created with the AutoAllowlist rule type begin in this state while DNS Firewall reads the look-back window of each VPC that uses the rule group.

          • COMPLETE — The rule is provisioned and enforcing matches.

          • CREATION_FAILED — Provisioning failed. StatusMessage contains a human-readable reason. A rule in this state is immutable: UpdateFirewallRule rejects the request, and the rule must be removed with DeleteFirewallRule.

          For rules that do not require asynchronous provisioning, this field may be absent.

        • StatusMessage (string) --

          An additional message about the rule's lifecycle state. Populated when Status is CREATION_FAILED to describe why provisioning failed.

    • CreateErrors (list) --

      A list of errors that occurred while creating the firewall rules.

      • (dict) --

        An error that occurred while creating a firewall rule in a batch operation.

        • FirewallRule (dict) --

          The firewall rule entry that caused the error.

          • CreatorRequestId (string) --

            A unique string that identifies the request and that allows you to retry failed requests without the risk of running the operation twice. CreatorRequestId can be any unique string, for example, a date/time stamp.

          • FirewallRuleGroupId (string) --

            The unique identifier of the firewall rule group where you want to create the rule.

          • FirewallDomainListId (string) --

            The ID of the domain list that you want to use in the rule. This setting is mutually exclusive with DnsThreatProtection and FirewallRuleType.

          • Priority (integer) --

            The setting that determines the processing order of the rule in the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

          • Action (string) --

            The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

            • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

            • ALERT - Permit the request and send metrics and logs to CloudWatch.

            • BLOCK - Disallow the request. This option requires additional details in the rule's BlockResponse.

          • BlockResponse (string) --

            The way that you want DNS Firewall to block the request, used with the rule action setting BLOCK.

            • NODATA - Respond indicating that the query was successful, but no response is available for it.

            • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

            • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

          • BlockOverrideDomain (string) --

            The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

          • BlockOverrideDnsType (string) --

            The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

          • BlockOverrideTtl (integer) --

            The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

            This setting is required if the BlockResponse setting is OVERRIDE.

          • Name (string) --

            A name that lets you identify the rule in the rule group.

          • FirewallDomainRedirectionAction (string) --

            How you want the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

            INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

            TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the redirection list to the domain list.

          • Qtype (string) --

            The DNS query type you want the rule to evaluate. Allowed values are:

            • A: Returns an IPv4 address.

            • AAAA: Returns an IPv6 address.

            • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

            • CNAME: Returns another domain name.

            • DS: Record that identifies the DNSSEC signing key of a delegated zone.

            • MX: Specifies mail servers.

            • NAPTR: Regular-expression-based rewriting of domain names.

            • NS: Authoritative name servers.

            • PTR: Maps an IP address to a domain name.

            • SOA: Start of authority record for the zone.

            • SPF: Lists the servers authorized to send emails from a domain.

            • SRV: Application specific values that identify servers.

            • TXT: Verifies email senders and application-specific values.

            • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

          • DnsThreatProtection (string) --

            The type of the DNS Firewall Advanced rule. This setting is mutually exclusive with FirewallDomainListId and FirewallRuleType. Valid values are:

            • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

            • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

            • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

          • ConfidenceThreshold (string) --

            The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

            • LOW: Provides the highest detection rate for threats, but also increases false positives.

            • MEDIUM: Provides a balance between detecting threats and false positives.

            • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

          • FirewallRuleType (dict) --

            The rule type configuration for the firewall rule. This is a tagged union — set exactly one of its members. This setting is mutually exclusive with the top-level FirewallDomainListId and DnsThreatProtection fields. Use one of:

            • FirewallAdvancedContentCategory — match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

            • FirewallAdvancedThreatCategory — match an Amazon Web Services-managed advanced threat category (for example, PHISHING).

            • DnsThreatProtection — match a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

            • PartnerThreatProtection — match a third-party threat feed delivered through Amazon Web Services Marketplace. The selected partner must be an active subscription on the calling account.

            • AutoAllowlist — automatically observe the domains that the VPCs associated with the rule group resolve, and allow the ones that you approve. See AutoAllowlistConfig.

            To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

            • PartnerThreatProtection (dict) --

              Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

              • Partner (string) --

                The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

            • FirewallAdvancedContentCategory (dict) --

              Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

              • Category (string) --

                The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

            • FirewallAdvancedThreatCategory (dict) --

              Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

              • Category (string) --

                The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

            • DnsThreatProtection (dict) --

              Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

              • Value (string) --

                The type of DNS threat protection. Valid values are:

                • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

                • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

                • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

              • ConfidenceThreshold (string) --

                The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

                • LOW: Provides the highest detection rate for threats, but also increases false positives.

                • MEDIUM: Provides a balance between detecting threats and false positives.

                • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

            • AutoAllowlist (dict) --

              Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

              • InitialDataTimeframeHours (integer) --

                The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

              • ImportFromFirewallDomainListId (string) --

                The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

              • AutoAllowlistFirewallDomainListId (string) --

                The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

        • Code (string) --

          The error code for the failure.

        • Message (string) --

          A message that provides details about the error.

BatchDeleteFirewallRule (updated) Link ¶
Changes (response)
{'DeletedFirewallRules': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                                 'ImportFromFirewallDomainListId': 'string',
                                                                 'InitialDataTimeframeHours': 'integer'}}}}

Deletes multiple DNS Firewall rules from the specified rule group.

See also: AWS API Documentation

Request Syntax

client.batch_delete_firewall_rule(
    DeleteFirewallRuleEntries=[
        {
            'FirewallRuleGroupId': 'string',
            'FirewallDomainListId': 'string',
            'FirewallThreatProtectionId': 'string',
            'Qtype': 'string'
        },
    ]
)
type DeleteFirewallRuleEntries:

list

param DeleteFirewallRuleEntries:

[REQUIRED]

The list of firewall rules to delete.

  • (dict) --

    The details for deleting a single firewall rule in a batch operation.

    • FirewallRuleGroupId (string) -- [REQUIRED]

      The unique identifier of the firewall rule group for the rule.

    • FirewallDomainListId (string) --

      The ID of the domain list that's used in the rule.

    • FirewallThreatProtectionId (string) --

      The ID of the DNS Firewall Advanced rule.

    • Qtype (string) --

      The DNS query type that the rule evaluates.

rtype:

dict

returns:

Response Syntax

{
    'DeletedFirewallRules': [
        {
            'FirewallRuleGroupId': 'string',
            'FirewallDomainListId': 'string',
            'FirewallThreatProtectionId': 'string',
            'Name': 'string',
            'Priority': 123,
            'Action': 'ALLOW'|'BLOCK'|'ALERT',
            'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
            'BlockOverrideDomain': 'string',
            'BlockOverrideDnsType': 'CNAME',
            'BlockOverrideTtl': 123,
            'CreatorRequestId': 'string',
            'CreationTime': 'string',
            'ModificationTime': 'string',
            'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
            'Qtype': 'string',
            'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
            'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
            'FirewallRuleType': {
                'PartnerThreatProtection': {
                    'Partner': 'string'
                },
                'FirewallAdvancedContentCategory': {
                    'Category': 'string'
                },
                'FirewallAdvancedThreatCategory': {
                    'Category': 'string'
                },
                'DnsThreatProtection': {
                    'Value': 'string',
                    'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
                },
                'AutoAllowlist': {
                    'InitialDataTimeframeHours': 123,
                    'ImportFromFirewallDomainListId': 'string',
                    'AutoAllowlistFirewallDomainListId': 'string'
                }
            },
            'Status': 'string',
            'StatusMessage': 'string'
        },
    ],
    'DeleteErrors': [
        {
            'FirewallRule': {
                'FirewallRuleGroupId': 'string',
                'FirewallDomainListId': 'string',
                'FirewallThreatProtectionId': 'string',
                'Qtype': 'string'
            },
            'Code': 'string',
            'Message': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • DeletedFirewallRules (list) --

      The firewall rules that were successfully deleted by the request.

      • (dict) --

        A single firewall rule in a rule group.

        • FirewallRuleGroupId (string) --

          The unique identifier of the Firewall rule group of the rule.

        • FirewallDomainListId (string) --

          The ID of the domain list that's used in the rule.

        • FirewallThreatProtectionId (string) --

          ID of the DNS Firewall Advanced rule.

        • Name (string) --

          The name of the rule.

        • Priority (integer) --

          The priority of the rule in the rule group. This value must be unique within the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

        • Action (string) --

          The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

          • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

          • ALERT - Permit the request to go through but send an alert to the logs.

          • BLOCK - Disallow the request. If this is specified, additional handling details are provided in the rule's BlockResponse setting.

        • BlockResponse (string) --

          The way that you want DNS Firewall to block the request. Used for the rule action setting BLOCK.

          • NODATA - Respond indicating that the query was successful, but no response is available for it.

          • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

          • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

        • BlockOverrideDomain (string) --

          The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • BlockOverrideDnsType (string) --

          The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • BlockOverrideTtl (integer) --

          The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • CreatorRequestId (string) --

          A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of executing the operation twice. This can be any unique string, for example, a timestamp.

        • CreationTime (string) --

          The date and time that the rule was created, in Unix time format and Coordinated Universal Time (UTC).

        • ModificationTime (string) --

          The date and time that the rule was last modified, in Unix time format and Coordinated Universal Time (UTC).

        • FirewallDomainRedirectionAction (string) --

          How you want the the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

          INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

          TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the domain in the redirection list to the domain list.

        • Qtype (string) --

          The DNS query type you want the rule to evaluate. Allowed values are;

          • A: Returns an IPv4 address.

          • AAAA: Returns an Ipv6 address.

          • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

          • CNAME: Returns another domain name.

          • DS: Record that identifies the DNSSEC signing key of a delegated zone.

          • MX: Specifies mail servers.

          • NAPTR: Regular-expression-based rewriting of domain names.

          • NS: Authoritative name servers.

          • PTR: Maps an IP address to a domain name.

          • SOA: Start of authority record for the zone.

          • SPF: Lists the servers authorized to send emails from a domain.

          • SRV: Application specific values that identify servers.

          • TXT: Verifies email senders and application-specific values.

          • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

        • DnsThreatProtection (string) --

          The type of the DNS Firewall Advanced rule. Valid values are:

          • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

          • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

          • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

        • ConfidenceThreshold (string) --

          The confidence threshold for DNS Firewall Advanced. You must provide this value when you create a DNS Firewall Advanced rule. The confidence level values mean:

          • LOW: Provides the highest detection rate for threats, but also increases false positives.

          • MEDIUM: Provides a balance between detecting threats and false positives.

          • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

        • FirewallRuleType (dict) --

          The rule type configuration for the firewall rule. This is a tagged union — exactly one of its members will be populated. Possible members are:

          • FirewallAdvancedContentCategory — an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

          • FirewallAdvancedThreatCategory — an Amazon Web Services-managed advanced threat category (for example, PHISHING).

          • DnsThreatProtection — a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

          • PartnerThreatProtection — a third-party threat feed delivered through Amazon Web Services Marketplace.

          • AutoAllowlist — an AutoAllowlist rule, which allows the domains on its managed domain list. See AutoAllowlistConfig.

          To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

          • PartnerThreatProtection (dict) --

            Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

            • Partner (string) --

              The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

          • FirewallAdvancedContentCategory (dict) --

            Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

            • Category (string) --

              The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

          • FirewallAdvancedThreatCategory (dict) --

            Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

            • Category (string) --

              The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

          • DnsThreatProtection (dict) --

            Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

            • Value (string) --

              The type of DNS threat protection. Valid values are:

              • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

              • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

              • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

            • ConfidenceThreshold (string) --

              The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

              • LOW: Provides the highest detection rate for threats, but also increases false positives.

              • MEDIUM: Provides a balance between detecting threats and false positives.

              • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

          • AutoAllowlist (dict) --

            Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

            • InitialDataTimeframeHours (integer) --

              The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

            • ImportFromFirewallDomainListId (string) --

              The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

            • AutoAllowlistFirewallDomainListId (string) --

              The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

        • Status (string) --

          The lifecycle state of the firewall rule. Possible values:

          • CREATING — DNS Firewall is provisioning the rule. Rules created with the PartnerThreatProtection rule type begin in this state while DNS Firewall verifies the calling account's Amazon Web Services Marketplace entitlement. Rules created with the AutoAllowlist rule type begin in this state while DNS Firewall reads the look-back window of each VPC that uses the rule group.

          • COMPLETE — The rule is provisioned and enforcing matches.

          • CREATION_FAILED — Provisioning failed. StatusMessage contains a human-readable reason. A rule in this state is immutable: UpdateFirewallRule rejects the request, and the rule must be removed with DeleteFirewallRule.

          For rules that do not require asynchronous provisioning, this field may be absent.

        • StatusMessage (string) --

          An additional message about the rule's lifecycle state. Populated when Status is CREATION_FAILED to describe why provisioning failed.

    • DeleteErrors (list) --

      A list of errors that occurred while deleting the firewall rules.

      • (dict) --

        An error that occurred while deleting a firewall rule in a batch operation.

        • FirewallRule (dict) --

          The firewall rule entry that caused the error.

          • FirewallRuleGroupId (string) --

            The unique identifier of the firewall rule group for the rule.

          • FirewallDomainListId (string) --

            The ID of the domain list that's used in the rule.

          • FirewallThreatProtectionId (string) --

            The ID of the DNS Firewall Advanced rule.

          • Qtype (string) --

            The DNS query type that the rule evaluates.

        • Code (string) --

          The error code for the failure.

        • Message (string) --

          A message that provides details about the error.

BatchUpdateFirewallRule (updated) Link ¶
Changes (request, response)
Request
{'UpdateFirewallRuleEntries': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                                      'ImportFromFirewallDomainListId': 'string',
                                                                      'InitialDataTimeframeHours': 'integer'}}}}
Response
{'UpdateErrors': {'FirewallRule': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                                          'ImportFromFirewallDomainListId': 'string',
                                                                          'InitialDataTimeframeHours': 'integer'}}}},
 'UpdatedFirewallRules': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                                 'ImportFromFirewallDomainListId': 'string',
                                                                 'InitialDataTimeframeHours': 'integer'}}}}

Updates multiple DNS Firewall rules in the specified rule group.

See also: AWS API Documentation

Request Syntax

client.batch_update_firewall_rule(
    UpdateFirewallRuleEntries=[
        {
            'FirewallRuleGroupId': 'string',
            'FirewallDomainListId': 'string',
            'FirewallThreatProtectionId': 'string',
            'Priority': 123,
            'Action': 'ALLOW'|'BLOCK'|'ALERT',
            'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
            'BlockOverrideDomain': 'string',
            'BlockOverrideDnsType': 'CNAME',
            'BlockOverrideTtl': 123,
            'Name': 'string',
            'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
            'Qtype': 'string',
            'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
            'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
            'FirewallRuleType': {
                'PartnerThreatProtection': {
                    'Partner': 'string'
                },
                'FirewallAdvancedContentCategory': {
                    'Category': 'string'
                },
                'FirewallAdvancedThreatCategory': {
                    'Category': 'string'
                },
                'DnsThreatProtection': {
                    'Value': 'string',
                    'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
                },
                'AutoAllowlist': {
                    'InitialDataTimeframeHours': 123,
                    'ImportFromFirewallDomainListId': 'string',
                    'AutoAllowlistFirewallDomainListId': 'string'
                }
            }
        },
    ]
)
type UpdateFirewallRuleEntries:

list

param UpdateFirewallRuleEntries:

[REQUIRED]

The list of firewall rules to update.

  • (dict) --

    The details for updating a single firewall rule in a batch operation.

    • FirewallRuleGroupId (string) -- [REQUIRED]

      The unique identifier of the firewall rule group for the rule.

    • FirewallDomainListId (string) --

      The ID of the domain list to use in the rule. This setting is mutually exclusive with DnsThreatProtection and FirewallRuleType.

    • FirewallThreatProtectionId (string) --

      The ID of the DNS Firewall Advanced rule.

    • Priority (integer) --

      The setting that determines the processing order of the rule in the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

    • Action (string) --

      The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

      • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

      • ALERT - Permit the request and send metrics and logs to CloudWatch.

      • BLOCK - Disallow the request. This option requires additional details in the rule's BlockResponse.

    • BlockResponse (string) --

      The way that you want DNS Firewall to block the request, used with the rule action setting BLOCK.

      • NODATA - Respond indicating that the query was successful, but no response is available for it.

      • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

      • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

    • BlockOverrideDomain (string) --

      The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

    • BlockOverrideDnsType (string) --

      The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

    • BlockOverrideTtl (integer) --

      The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      This setting is required if the BlockResponse setting is OVERRIDE.

    • Name (string) --

      The name of the rule.

    • FirewallDomainRedirectionAction (string) --

      How you want the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

      INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

      TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the redirection list to the domain list.

    • Qtype (string) --

      The DNS query type you want the rule to evaluate. Allowed values are:

      • A: Returns an IPv4 address.

      • AAAA: Returns an IPv6 address.

      • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

      • CNAME: Returns another domain name.

      • DS: Record that identifies the DNSSEC signing key of a delegated zone.

      • MX: Specifies mail servers.

      • NAPTR: Regular-expression-based rewriting of domain names.

      • NS: Authoritative name servers.

      • PTR: Maps an IP address to a domain name.

      • SOA: Start of authority record for the zone.

      • SPF: Lists the servers authorized to send emails from a domain.

      • SRV: Application specific values that identify servers.

      • TXT: Verifies email senders and application-specific values.

      • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

    • DnsThreatProtection (string) --

      The type of the DNS Firewall Advanced rule. This setting is mutually exclusive with FirewallDomainListId and FirewallRuleType. Valid values are:

      • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

      • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

      • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

    • ConfidenceThreshold (string) --

      The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

      • LOW: Provides the highest detection rate for threats, but also increases false positives.

      • MEDIUM: Provides a balance between detecting threats and false positives.

      • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

    • FirewallRuleType (dict) --

      The rule type configuration for the firewall rule. This is a tagged union — set exactly one of its members. This setting is mutually exclusive with the top-level FirewallDomainListId and DnsThreatProtection fields. Use one of:

      • FirewallAdvancedContentCategory — match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

      • FirewallAdvancedThreatCategory — match an Amazon Web Services-managed advanced threat category (for example, PHISHING).

      • DnsThreatProtection — match a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

      • PartnerThreatProtection — match a third-party threat feed delivered through Amazon Web Services Marketplace. The selected partner must be an active subscription on the calling account.

      To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

      You can't specify FirewallRuleType when you update an AutoAllowlist rule, even with its current values. InitialDataTimeframeHours and ImportFromFirewallDomainListId can't be changed. To change them, delete the rule and create a new one. Deleting an AutoAllowlist rule also deletes its managed domain list and the domains that you allowed.

      • PartnerThreatProtection (dict) --

        Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

        • Partner (string) -- [REQUIRED]

          The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

      • FirewallAdvancedContentCategory (dict) --

        Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

        • Category (string) -- [REQUIRED]

          The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

      • FirewallAdvancedThreatCategory (dict) --

        Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

        • Category (string) -- [REQUIRED]

          The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

      • DnsThreatProtection (dict) --

        Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

        • Value (string) -- [REQUIRED]

          The type of DNS threat protection. Valid values are:

          • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

          • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

          • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

        • ConfidenceThreshold (string) -- [REQUIRED]

          The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

          • LOW: Provides the highest detection rate for threats, but also increases false positives.

          • MEDIUM: Provides a balance between detecting threats and false positives.

          • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

      • AutoAllowlist (dict) --

        Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

        • InitialDataTimeframeHours (integer) -- [REQUIRED]

          The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

        • ImportFromFirewallDomainListId (string) --

          The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

        • AutoAllowlistFirewallDomainListId (string) --

          The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

rtype:

dict

returns:

Response Syntax

{
    'UpdatedFirewallRules': [
        {
            'FirewallRuleGroupId': 'string',
            'FirewallDomainListId': 'string',
            'FirewallThreatProtectionId': 'string',
            'Name': 'string',
            'Priority': 123,
            'Action': 'ALLOW'|'BLOCK'|'ALERT',
            'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
            'BlockOverrideDomain': 'string',
            'BlockOverrideDnsType': 'CNAME',
            'BlockOverrideTtl': 123,
            'CreatorRequestId': 'string',
            'CreationTime': 'string',
            'ModificationTime': 'string',
            'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
            'Qtype': 'string',
            'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
            'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
            'FirewallRuleType': {
                'PartnerThreatProtection': {
                    'Partner': 'string'
                },
                'FirewallAdvancedContentCategory': {
                    'Category': 'string'
                },
                'FirewallAdvancedThreatCategory': {
                    'Category': 'string'
                },
                'DnsThreatProtection': {
                    'Value': 'string',
                    'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
                },
                'AutoAllowlist': {
                    'InitialDataTimeframeHours': 123,
                    'ImportFromFirewallDomainListId': 'string',
                    'AutoAllowlistFirewallDomainListId': 'string'
                }
            },
            'Status': 'string',
            'StatusMessage': 'string'
        },
    ],
    'UpdateErrors': [
        {
            'FirewallRule': {
                'FirewallRuleGroupId': 'string',
                'FirewallDomainListId': 'string',
                'FirewallThreatProtectionId': 'string',
                'Priority': 123,
                'Action': 'ALLOW'|'BLOCK'|'ALERT',
                'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
                'BlockOverrideDomain': 'string',
                'BlockOverrideDnsType': 'CNAME',
                'BlockOverrideTtl': 123,
                'Name': 'string',
                'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
                'Qtype': 'string',
                'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
                'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
                'FirewallRuleType': {
                    'PartnerThreatProtection': {
                        'Partner': 'string'
                    },
                    'FirewallAdvancedContentCategory': {
                        'Category': 'string'
                    },
                    'FirewallAdvancedThreatCategory': {
                        'Category': 'string'
                    },
                    'DnsThreatProtection': {
                        'Value': 'string',
                        'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
                    },
                    'AutoAllowlist': {
                        'InitialDataTimeframeHours': 123,
                        'ImportFromFirewallDomainListId': 'string',
                        'AutoAllowlistFirewallDomainListId': 'string'
                    }
                }
            },
            'Code': 'string',
            'Message': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • UpdatedFirewallRules (list) --

      The firewall rules that were successfully updated by the request.

      • (dict) --

        A single firewall rule in a rule group.

        • FirewallRuleGroupId (string) --

          The unique identifier of the Firewall rule group of the rule.

        • FirewallDomainListId (string) --

          The ID of the domain list that's used in the rule.

        • FirewallThreatProtectionId (string) --

          ID of the DNS Firewall Advanced rule.

        • Name (string) --

          The name of the rule.

        • Priority (integer) --

          The priority of the rule in the rule group. This value must be unique within the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

        • Action (string) --

          The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

          • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

          • ALERT - Permit the request to go through but send an alert to the logs.

          • BLOCK - Disallow the request. If this is specified, additional handling details are provided in the rule's BlockResponse setting.

        • BlockResponse (string) --

          The way that you want DNS Firewall to block the request. Used for the rule action setting BLOCK.

          • NODATA - Respond indicating that the query was successful, but no response is available for it.

          • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

          • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

        • BlockOverrideDomain (string) --

          The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • BlockOverrideDnsType (string) --

          The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • BlockOverrideTtl (integer) --

          The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • CreatorRequestId (string) --

          A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of executing the operation twice. This can be any unique string, for example, a timestamp.

        • CreationTime (string) --

          The date and time that the rule was created, in Unix time format and Coordinated Universal Time (UTC).

        • ModificationTime (string) --

          The date and time that the rule was last modified, in Unix time format and Coordinated Universal Time (UTC).

        • FirewallDomainRedirectionAction (string) --

          How you want the the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

          INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

          TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the domain in the redirection list to the domain list.

        • Qtype (string) --

          The DNS query type you want the rule to evaluate. Allowed values are;

          • A: Returns an IPv4 address.

          • AAAA: Returns an Ipv6 address.

          • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

          • CNAME: Returns another domain name.

          • DS: Record that identifies the DNSSEC signing key of a delegated zone.

          • MX: Specifies mail servers.

          • NAPTR: Regular-expression-based rewriting of domain names.

          • NS: Authoritative name servers.

          • PTR: Maps an IP address to a domain name.

          • SOA: Start of authority record for the zone.

          • SPF: Lists the servers authorized to send emails from a domain.

          • SRV: Application specific values that identify servers.

          • TXT: Verifies email senders and application-specific values.

          • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

        • DnsThreatProtection (string) --

          The type of the DNS Firewall Advanced rule. Valid values are:

          • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

          • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

          • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

        • ConfidenceThreshold (string) --

          The confidence threshold for DNS Firewall Advanced. You must provide this value when you create a DNS Firewall Advanced rule. The confidence level values mean:

          • LOW: Provides the highest detection rate for threats, but also increases false positives.

          • MEDIUM: Provides a balance between detecting threats and false positives.

          • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

        • FirewallRuleType (dict) --

          The rule type configuration for the firewall rule. This is a tagged union — exactly one of its members will be populated. Possible members are:

          • FirewallAdvancedContentCategory — an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

          • FirewallAdvancedThreatCategory — an Amazon Web Services-managed advanced threat category (for example, PHISHING).

          • DnsThreatProtection — a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

          • PartnerThreatProtection — a third-party threat feed delivered through Amazon Web Services Marketplace.

          • AutoAllowlist — an AutoAllowlist rule, which allows the domains on its managed domain list. See AutoAllowlistConfig.

          To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

          • PartnerThreatProtection (dict) --

            Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

            • Partner (string) --

              The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

          • FirewallAdvancedContentCategory (dict) --

            Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

            • Category (string) --

              The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

          • FirewallAdvancedThreatCategory (dict) --

            Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

            • Category (string) --

              The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

          • DnsThreatProtection (dict) --

            Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

            • Value (string) --

              The type of DNS threat protection. Valid values are:

              • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

              • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

              • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

            • ConfidenceThreshold (string) --

              The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

              • LOW: Provides the highest detection rate for threats, but also increases false positives.

              • MEDIUM: Provides a balance between detecting threats and false positives.

              • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

          • AutoAllowlist (dict) --

            Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

            • InitialDataTimeframeHours (integer) --

              The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

            • ImportFromFirewallDomainListId (string) --

              The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

            • AutoAllowlistFirewallDomainListId (string) --

              The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

        • Status (string) --

          The lifecycle state of the firewall rule. Possible values:

          • CREATING — DNS Firewall is provisioning the rule. Rules created with the PartnerThreatProtection rule type begin in this state while DNS Firewall verifies the calling account's Amazon Web Services Marketplace entitlement. Rules created with the AutoAllowlist rule type begin in this state while DNS Firewall reads the look-back window of each VPC that uses the rule group.

          • COMPLETE — The rule is provisioned and enforcing matches.

          • CREATION_FAILED — Provisioning failed. StatusMessage contains a human-readable reason. A rule in this state is immutable: UpdateFirewallRule rejects the request, and the rule must be removed with DeleteFirewallRule.

          For rules that do not require asynchronous provisioning, this field may be absent.

        • StatusMessage (string) --

          An additional message about the rule's lifecycle state. Populated when Status is CREATION_FAILED to describe why provisioning failed.

    • UpdateErrors (list) --

      A list of errors that occurred while updating the firewall rules.

      • (dict) --

        An error that occurred while updating a firewall rule in a batch operation.

        • FirewallRule (dict) --

          The firewall rule entry that caused the error.

          • FirewallRuleGroupId (string) --

            The unique identifier of the firewall rule group for the rule.

          • FirewallDomainListId (string) --

            The ID of the domain list to use in the rule. This setting is mutually exclusive with DnsThreatProtection and FirewallRuleType.

          • FirewallThreatProtectionId (string) --

            The ID of the DNS Firewall Advanced rule.

          • Priority (integer) --

            The setting that determines the processing order of the rule in the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

          • Action (string) --

            The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

            • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

            • ALERT - Permit the request and send metrics and logs to CloudWatch.

            • BLOCK - Disallow the request. This option requires additional details in the rule's BlockResponse.

          • BlockResponse (string) --

            The way that you want DNS Firewall to block the request, used with the rule action setting BLOCK.

            • NODATA - Respond indicating that the query was successful, but no response is available for it.

            • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

            • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

          • BlockOverrideDomain (string) --

            The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

          • BlockOverrideDnsType (string) --

            The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

          • BlockOverrideTtl (integer) --

            The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

            This setting is required if the BlockResponse setting is OVERRIDE.

          • Name (string) --

            The name of the rule.

          • FirewallDomainRedirectionAction (string) --

            How you want the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

            INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

            TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the redirection list to the domain list.

          • Qtype (string) --

            The DNS query type you want the rule to evaluate. Allowed values are:

            • A: Returns an IPv4 address.

            • AAAA: Returns an IPv6 address.

            • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

            • CNAME: Returns another domain name.

            • DS: Record that identifies the DNSSEC signing key of a delegated zone.

            • MX: Specifies mail servers.

            • NAPTR: Regular-expression-based rewriting of domain names.

            • NS: Authoritative name servers.

            • PTR: Maps an IP address to a domain name.

            • SOA: Start of authority record for the zone.

            • SPF: Lists the servers authorized to send emails from a domain.

            • SRV: Application specific values that identify servers.

            • TXT: Verifies email senders and application-specific values.

            • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

          • DnsThreatProtection (string) --

            The type of the DNS Firewall Advanced rule. This setting is mutually exclusive with FirewallDomainListId and FirewallRuleType. Valid values are:

            • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

            • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

            • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

          • ConfidenceThreshold (string) --

            The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

            • LOW: Provides the highest detection rate for threats, but also increases false positives.

            • MEDIUM: Provides a balance between detecting threats and false positives.

            • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

          • FirewallRuleType (dict) --

            The rule type configuration for the firewall rule. This is a tagged union — set exactly one of its members. This setting is mutually exclusive with the top-level FirewallDomainListId and DnsThreatProtection fields. Use one of:

            • FirewallAdvancedContentCategory — match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

            • FirewallAdvancedThreatCategory — match an Amazon Web Services-managed advanced threat category (for example, PHISHING).

            • DnsThreatProtection — match a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

            • PartnerThreatProtection — match a third-party threat feed delivered through Amazon Web Services Marketplace. The selected partner must be an active subscription on the calling account.

            To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

            You can't specify FirewallRuleType when you update an AutoAllowlist rule, even with its current values. InitialDataTimeframeHours and ImportFromFirewallDomainListId can't be changed. To change them, delete the rule and create a new one. Deleting an AutoAllowlist rule also deletes its managed domain list and the domains that you allowed.

            • PartnerThreatProtection (dict) --

              Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

              • Partner (string) --

                The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

            • FirewallAdvancedContentCategory (dict) --

              Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

              • Category (string) --

                The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

            • FirewallAdvancedThreatCategory (dict) --

              Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

              • Category (string) --

                The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

            • DnsThreatProtection (dict) --

              Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

              • Value (string) --

                The type of DNS threat protection. Valid values are:

                • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

                • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

                • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

              • ConfidenceThreshold (string) --

                The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

                • LOW: Provides the highest detection rate for threats, but also increases false positives.

                • MEDIUM: Provides a balance between detecting threats and false positives.

                • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

            • AutoAllowlist (dict) --

              Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

              • InitialDataTimeframeHours (integer) --

                The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

              • ImportFromFirewallDomainListId (string) --

                The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

              • AutoAllowlistFirewallDomainListId (string) --

                The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

        • Code (string) --

          The error code for the failure.

        • Message (string) --

          A message that provides details about the error.

CreateFirewallDomainList (updated) Link ¶
Changes (response)
{'FirewallDomainList': {'ManagedListType': {'AUTOALLOWLIST'}}}

Creates an empty firewall domain list for use in DNS Firewall rules. You can populate the domains for the new list with a file, using ImportFirewallDomains, or with domain strings, using UpdateFirewallDomains.

See also: AWS API Documentation

Request Syntax

client.create_firewall_domain_list(
    CreatorRequestId='string',
    Name='string',
    Tags=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
)
type CreatorRequestId:

string

param CreatorRequestId:

[REQUIRED]

A unique string that identifies the request and that allows you to retry failed requests without the risk of running the operation twice. CreatorRequestId can be any unique string, for example, a date/time stamp.

This field is autopopulated if not provided.

type Name:

string

param Name:

[REQUIRED]

A name that lets you identify the domain list to manage and use it.

type Tags:

list

param Tags:

A list of the tag keys and values that you want to associate with the domain list.

  • (dict) --

    One tag that you want to add to the specified resource. A tag consists of a Key (a name for the tag) and a Value.

    • Key (string) -- [REQUIRED]

      The name for the tag. For example, if you want to associate Resolver resources with the account IDs of your customers for billing purposes, the value of Key might be account-id.

    • Value (string) -- [REQUIRED]

      The value for the tag. For example, if Key is account-id, then Value might be the ID of the customer account that you're creating the resource for.

rtype:

dict

returns:

Response Syntax

{
    'FirewallDomainList': {
        'Id': 'string',
        'Arn': 'string',
        'Name': 'string',
        'DomainCount': 123,
        'Status': 'COMPLETE'|'COMPLETE_IMPORT_FAILED'|'IMPORTING'|'DELETING'|'UPDATING',
        'StatusMessage': 'string',
        'ManagedOwnerName': 'string',
        'CreatorRequestId': 'string',
        'CreationTime': 'string',
        'ModificationTime': 'string',
        'Category': 'string',
        'ManagedListType': 'THREAT'|'CONTENT'|'AUTOALLOWLIST'
    }
}

Response Structure

  • (dict) --

    • FirewallDomainList (dict) --

      The domain list that you just created.

      • Id (string) --

        The ID of the domain list.

      • Arn (string) --

        The Amazon Resource Name (ARN) of the firewall domain list.

      • Name (string) --

        The name of the domain list.

      • DomainCount (integer) --

        The number of domain names that are specified in the domain list.

      • Status (string) --

        The status of the domain list.

      • StatusMessage (string) --

        Additional information about the status of the list, if available.

      • ManagedOwnerName (string) --

        The owner of the list, used only for lists that are not managed by you. For example, the managed domain list AWSManagedDomainsMalwareDomainList has the managed owner name Route 53 Resolver DNS Firewall.

      • CreatorRequestId (string) --

        A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of running the operation twice. This can be any unique string, for example, a timestamp.

      • CreationTime (string) --

        The date and time that the domain list was created, in Unix time format and Coordinated Universal Time (UTC).

      • ModificationTime (string) --

        The date and time that the domain list was last modified, in Unix time format and Coordinated Universal Time (UTC).

      • Category (string) --

        The category of the domain list.

      • ManagedListType (string) --

        The type of the managed domain list, for example THREAT.

CreateFirewallRule (updated) Link ¶
Changes (request, response)
Request
{'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                        'ImportFromFirewallDomainListId': 'string',
                                        'InitialDataTimeframeHours': 'integer'}}}
Response
{'FirewallRule': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                         'ImportFromFirewallDomainListId': 'string',
                                                         'InitialDataTimeframeHours': 'integer'}}}}

Creates a single DNS Firewall rule in the specified rule group. The rule can use any one of the following match sources, and the chosen source must be supplied through the matching request field — they are mutually exclusive:

  • FirewallDomainListId — match a customer-managed or Amazon Web Services-managed domain list.

  • DnsThreatProtection — match a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

  • FirewallRuleType — match one of the rule-type variants: FirewallAdvancedContentCategory, FirewallAdvancedThreatCategory, DnsThreatProtection, PartnerThreatProtection, or AutoAllowlist. ListFirewallRuleTypes returns the first four. The PartnerThreatProtection variant requires an active Amazon Web Services Marketplace subscription to the named partner product.

For rules that require asynchronous provisioning (the PartnerThreatProtection and AutoAllowlist rule types), the rule's Status begins at CREATING and transitions to COMPLETE once the rule is provisioned: for PartnerThreatProtection, when the marketplace entitlement is verified, and for AutoAllowlist, when DNS Firewall has read the look-back window of every VPC that uses the rule group, which can take hours for a rule group that many VPCs use. If provisioning fails, Status becomes CREATION_FAILED and StatusMessage contains a human-readable reason; the rule is then immutable and must be removed with DeleteFirewallRule.

See also: AWS API Documentation

Request Syntax

client.create_firewall_rule(
    CreatorRequestId='string',
    FirewallRuleGroupId='string',
    FirewallDomainListId='string',
    Priority=123,
    Action='ALLOW'|'BLOCK'|'ALERT',
    BlockResponse='NODATA'|'NXDOMAIN'|'OVERRIDE',
    BlockOverrideDomain='string',
    BlockOverrideDnsType='CNAME',
    BlockOverrideTtl=123,
    Name='string',
    FirewallDomainRedirectionAction='INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
    Qtype='string',
    DnsThreatProtection='DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
    ConfidenceThreshold='LOW'|'MEDIUM'|'HIGH',
    FirewallRuleType={
        'PartnerThreatProtection': {
            'Partner': 'string'
        },
        'FirewallAdvancedContentCategory': {
            'Category': 'string'
        },
        'FirewallAdvancedThreatCategory': {
            'Category': 'string'
        },
        'DnsThreatProtection': {
            'Value': 'string',
            'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
        },
        'AutoAllowlist': {
            'InitialDataTimeframeHours': 123,
            'ImportFromFirewallDomainListId': 'string',
            'AutoAllowlistFirewallDomainListId': 'string'
        }
    }
)
type CreatorRequestId:

string

param CreatorRequestId:

[REQUIRED]

A unique string that identifies the request and that allows you to retry failed requests without the risk of running the operation twice. CreatorRequestId can be any unique string, for example, a date/time stamp.

This field is autopopulated if not provided.

type FirewallRuleGroupId:

string

param FirewallRuleGroupId:

[REQUIRED]

The unique identifier of the firewall rule group where you want to create the rule.

type FirewallDomainListId:

string

param FirewallDomainListId:

The ID of the domain list that you want to use in the rule. Can't be used together with DnsThreatProtecton.

type Priority:

integer

param Priority:

[REQUIRED]

The setting that determines the processing order of the rule in the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

You must specify a unique priority for each rule in a rule group. To make it easier to insert rules later, leave space between the numbers, for example, use 100, 200, and so on. You can change the priority setting for the rules in a rule group at any time.

type Action:

string

param Action:

[REQUIRED]

The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

  • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

  • ALERT - Permit the request and send metrics and logs to Cloud Watch.

  • BLOCK - Disallow the request. This option requires additional details in the rule's BlockResponse.

type BlockResponse:

string

param BlockResponse:

The way that you want DNS Firewall to block the request, used with the rule action setting BLOCK.

  • NODATA - Respond indicating that the query was successful, but no response is available for it.

  • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

  • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

This setting is required if the rule action setting is BLOCK.

type BlockOverrideDomain:

string

param BlockOverrideDomain:

The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

This setting is required if the BlockResponse setting is OVERRIDE.

type BlockOverrideDnsType:

string

param BlockOverrideDnsType:

The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

This setting is required if the BlockResponse setting is OVERRIDE.

type BlockOverrideTtl:

integer

param BlockOverrideTtl:

The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

This setting is required if the BlockResponse setting is OVERRIDE.

type Name:

string

param Name:

[REQUIRED]

A name that lets you identify the rule in the rule group.

type FirewallDomainRedirectionAction:

string

param FirewallDomainRedirectionAction:

How you want the the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the domain in the redirection list to the domain list.

You can't set this value on an AutoAllowlist rule, which always inspects the redirection chain.

type Qtype:

string

param Qtype:

The DNS query type you want the rule to evaluate. Allowed values are;

  • A: Returns an IPv4 address.

  • AAAA: Returns an Ipv6 address.

  • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

  • CNAME: Returns another domain name.

  • DS: Record that identifies the DNSSEC signing key of a delegated zone.

  • MX: Specifies mail servers.

  • NAPTR: Regular-expression-based rewriting of domain names.

  • NS: Authoritative name servers.

  • PTR: Maps an IP address to a domain name.

  • SOA: Start of authority record for the zone.

  • SPF: Lists the servers authorized to send emails from a domain.

  • SRV: Application specific values that identify servers.

  • TXT: Verifies email senders and application-specific values.

  • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

You can't set Qtype on an AutoAllowlist rule, because the rule applies to all query types.

type DnsThreatProtection:

string

param DnsThreatProtection:

The type of the DNS Firewall Advanced rule. This setting is mutually exclusive with FirewallDomainListId and FirewallRuleType. Valid values are:

  • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

  • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

  • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

type ConfidenceThreshold:

string

param ConfidenceThreshold:

The confidence threshold for DNS Firewall Advanced. You must provide this value when you create a DNS Firewall Advanced rule. The confidence level values mean:

  • LOW: Provides the highest detection rate for threats, but also increases false positives.

  • MEDIUM: Provides a balance between detecting threats and false positives.

  • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

type FirewallRuleType:

dict

param FirewallRuleType:

The rule type configuration for the firewall rule. This is a tagged union — set exactly one of its members. This setting is mutually exclusive with the top-level FirewallDomainListId and DnsThreatProtection fields. Use one of:

  • FirewallAdvancedContentCategory — match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

  • FirewallAdvancedThreatCategory — match an Amazon Web Services-managed advanced threat category (for example, PHISHING).

  • DnsThreatProtection — match a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

  • PartnerThreatProtection — match a third-party threat feed delivered through Amazon Web Services Marketplace. The selected partner must be an active subscription on the calling account.

  • AutoAllowlist — automatically observe the domains that the VPCs associated with the rule group resolve, and allow the ones that you approve. See AutoAllowlistConfig.

To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

  • PartnerThreatProtection (dict) --

    Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

    • Partner (string) -- [REQUIRED]

      The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

  • FirewallAdvancedContentCategory (dict) --

    Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

    • Category (string) -- [REQUIRED]

      The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

  • FirewallAdvancedThreatCategory (dict) --

    Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

    • Category (string) -- [REQUIRED]

      The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

  • DnsThreatProtection (dict) --

    Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

    • Value (string) -- [REQUIRED]

      The type of DNS threat protection. Valid values are:

      • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

      • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

      • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

    • ConfidenceThreshold (string) -- [REQUIRED]

      The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

      • LOW: Provides the highest detection rate for threats, but also increases false positives.

      • MEDIUM: Provides a balance between detecting threats and false positives.

      • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

  • AutoAllowlist (dict) --

    Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

    • InitialDataTimeframeHours (integer) -- [REQUIRED]

      The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

    • ImportFromFirewallDomainListId (string) --

      The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

    • AutoAllowlistFirewallDomainListId (string) --

      The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

rtype:

dict

returns:

Response Syntax

{
    'FirewallRule': {
        'FirewallRuleGroupId': 'string',
        'FirewallDomainListId': 'string',
        'FirewallThreatProtectionId': 'string',
        'Name': 'string',
        'Priority': 123,
        'Action': 'ALLOW'|'BLOCK'|'ALERT',
        'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
        'BlockOverrideDomain': 'string',
        'BlockOverrideDnsType': 'CNAME',
        'BlockOverrideTtl': 123,
        'CreatorRequestId': 'string',
        'CreationTime': 'string',
        'ModificationTime': 'string',
        'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
        'Qtype': 'string',
        'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
        'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
        'FirewallRuleType': {
            'PartnerThreatProtection': {
                'Partner': 'string'
            },
            'FirewallAdvancedContentCategory': {
                'Category': 'string'
            },
            'FirewallAdvancedThreatCategory': {
                'Category': 'string'
            },
            'DnsThreatProtection': {
                'Value': 'string',
                'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
            },
            'AutoAllowlist': {
                'InitialDataTimeframeHours': 123,
                'ImportFromFirewallDomainListId': 'string',
                'AutoAllowlistFirewallDomainListId': 'string'
            }
        },
        'Status': 'string',
        'StatusMessage': 'string'
    }
}

Response Structure

  • (dict) --

    • FirewallRule (dict) --

      The firewall rule that you just created.

      • FirewallRuleGroupId (string) --

        The unique identifier of the Firewall rule group of the rule.

      • FirewallDomainListId (string) --

        The ID of the domain list that's used in the rule.

      • FirewallThreatProtectionId (string) --

        ID of the DNS Firewall Advanced rule.

      • Name (string) --

        The name of the rule.

      • Priority (integer) --

        The priority of the rule in the rule group. This value must be unique within the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

      • Action (string) --

        The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

        • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

        • ALERT - Permit the request to go through but send an alert to the logs.

        • BLOCK - Disallow the request. If this is specified, additional handling details are provided in the rule's BlockResponse setting.

      • BlockResponse (string) --

        The way that you want DNS Firewall to block the request. Used for the rule action setting BLOCK.

        • NODATA - Respond indicating that the query was successful, but no response is available for it.

        • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

        • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

      • BlockOverrideDomain (string) --

        The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      • BlockOverrideDnsType (string) --

        The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      • BlockOverrideTtl (integer) --

        The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      • CreatorRequestId (string) --

        A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of executing the operation twice. This can be any unique string, for example, a timestamp.

      • CreationTime (string) --

        The date and time that the rule was created, in Unix time format and Coordinated Universal Time (UTC).

      • ModificationTime (string) --

        The date and time that the rule was last modified, in Unix time format and Coordinated Universal Time (UTC).

      • FirewallDomainRedirectionAction (string) --

        How you want the the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

        INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

        TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the domain in the redirection list to the domain list.

      • Qtype (string) --

        The DNS query type you want the rule to evaluate. Allowed values are;

        • A: Returns an IPv4 address.

        • AAAA: Returns an Ipv6 address.

        • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

        • CNAME: Returns another domain name.

        • DS: Record that identifies the DNSSEC signing key of a delegated zone.

        • MX: Specifies mail servers.

        • NAPTR: Regular-expression-based rewriting of domain names.

        • NS: Authoritative name servers.

        • PTR: Maps an IP address to a domain name.

        • SOA: Start of authority record for the zone.

        • SPF: Lists the servers authorized to send emails from a domain.

        • SRV: Application specific values that identify servers.

        • TXT: Verifies email senders and application-specific values.

        • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

      • DnsThreatProtection (string) --

        The type of the DNS Firewall Advanced rule. Valid values are:

        • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

        • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

        • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

      • ConfidenceThreshold (string) --

        The confidence threshold for DNS Firewall Advanced. You must provide this value when you create a DNS Firewall Advanced rule. The confidence level values mean:

        • LOW: Provides the highest detection rate for threats, but also increases false positives.

        • MEDIUM: Provides a balance between detecting threats and false positives.

        • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

      • FirewallRuleType (dict) --

        The rule type configuration for the firewall rule. This is a tagged union — exactly one of its members will be populated. Possible members are:

        • FirewallAdvancedContentCategory — an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

        • FirewallAdvancedThreatCategory — an Amazon Web Services-managed advanced threat category (for example, PHISHING).

        • DnsThreatProtection — a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

        • PartnerThreatProtection — a third-party threat feed delivered through Amazon Web Services Marketplace.

        • AutoAllowlist — an AutoAllowlist rule, which allows the domains on its managed domain list. See AutoAllowlistConfig.

        To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

        • PartnerThreatProtection (dict) --

          Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

          • Partner (string) --

            The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

        • FirewallAdvancedContentCategory (dict) --

          Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

          • Category (string) --

            The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

        • FirewallAdvancedThreatCategory (dict) --

          Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

          • Category (string) --

            The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

        • DnsThreatProtection (dict) --

          Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

          • Value (string) --

            The type of DNS threat protection. Valid values are:

            • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

            • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

            • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

          • ConfidenceThreshold (string) --

            The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

            • LOW: Provides the highest detection rate for threats, but also increases false positives.

            • MEDIUM: Provides a balance between detecting threats and false positives.

            • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

        • AutoAllowlist (dict) --

          Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

          • InitialDataTimeframeHours (integer) --

            The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

          • ImportFromFirewallDomainListId (string) --

            The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

          • AutoAllowlistFirewallDomainListId (string) --

            The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

      • Status (string) --

        The lifecycle state of the firewall rule. Possible values:

        • CREATING — DNS Firewall is provisioning the rule. Rules created with the PartnerThreatProtection rule type begin in this state while DNS Firewall verifies the calling account's Amazon Web Services Marketplace entitlement. Rules created with the AutoAllowlist rule type begin in this state while DNS Firewall reads the look-back window of each VPC that uses the rule group.

        • COMPLETE — The rule is provisioned and enforcing matches.

        • CREATION_FAILED — Provisioning failed. StatusMessage contains a human-readable reason. A rule in this state is immutable: UpdateFirewallRule rejects the request, and the rule must be removed with DeleteFirewallRule.

        For rules that do not require asynchronous provisioning, this field may be absent.

      • StatusMessage (string) --

        An additional message about the rule's lifecycle state. Populated when Status is CREATION_FAILED to describe why provisioning failed.

DeleteFirewallDomainList (updated) Link ¶
Changes (response)
{'FirewallDomainList': {'ManagedListType': {'AUTOALLOWLIST'}}}

Deletes the specified domain list.

See also: AWS API Documentation

Request Syntax

client.delete_firewall_domain_list(
    FirewallDomainListId='string'
)
type FirewallDomainListId:

string

param FirewallDomainListId:

[REQUIRED]

The ID of the domain list that you want to delete.

rtype:

dict

returns:

Response Syntax

{
    'FirewallDomainList': {
        'Id': 'string',
        'Arn': 'string',
        'Name': 'string',
        'DomainCount': 123,
        'Status': 'COMPLETE'|'COMPLETE_IMPORT_FAILED'|'IMPORTING'|'DELETING'|'UPDATING',
        'StatusMessage': 'string',
        'ManagedOwnerName': 'string',
        'CreatorRequestId': 'string',
        'CreationTime': 'string',
        'ModificationTime': 'string',
        'Category': 'string',
        'ManagedListType': 'THREAT'|'CONTENT'|'AUTOALLOWLIST'
    }
}

Response Structure

  • (dict) --

    • FirewallDomainList (dict) --

      The domain list that you just deleted.

      • Id (string) --

        The ID of the domain list.

      • Arn (string) --

        The Amazon Resource Name (ARN) of the firewall domain list.

      • Name (string) --

        The name of the domain list.

      • DomainCount (integer) --

        The number of domain names that are specified in the domain list.

      • Status (string) --

        The status of the domain list.

      • StatusMessage (string) --

        Additional information about the status of the list, if available.

      • ManagedOwnerName (string) --

        The owner of the list, used only for lists that are not managed by you. For example, the managed domain list AWSManagedDomainsMalwareDomainList has the managed owner name Route 53 Resolver DNS Firewall.

      • CreatorRequestId (string) --

        A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of running the operation twice. This can be any unique string, for example, a timestamp.

      • CreationTime (string) --

        The date and time that the domain list was created, in Unix time format and Coordinated Universal Time (UTC).

      • ModificationTime (string) --

        The date and time that the domain list was last modified, in Unix time format and Coordinated Universal Time (UTC).

      • Category (string) --

        The category of the domain list.

      • ManagedListType (string) --

        The type of the managed domain list, for example THREAT.

DeleteFirewallRule (updated) Link ¶
Changes (response)
{'FirewallRule': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                         'ImportFromFirewallDomainListId': 'string',
                                                         'InitialDataTimeframeHours': 'integer'}}}}

Deletes the specified firewall rule. Identify the rule using either FirewallDomainListId (for domain-list and DNS Firewall Advanced rules) or FirewallThreatProtectionId (for partner-managed and DNS Firewall Advanced rules) — together with FirewallRuleGroupId.

DeleteFirewallRule is the only operation that succeeds against a rule whose Status is CREATION_FAILED.

See also: AWS API Documentation

Request Syntax

client.delete_firewall_rule(
    FirewallRuleGroupId='string',
    FirewallDomainListId='string',
    FirewallThreatProtectionId='string',
    Qtype='string'
)
type FirewallRuleGroupId:

string

param FirewallRuleGroupId:

[REQUIRED]

The unique identifier of the firewall rule group that you want to delete the rule from.

type FirewallDomainListId:

string

param FirewallDomainListId:

The ID of the domain list that's used in the rule.

type FirewallThreatProtectionId:

string

param FirewallThreatProtectionId:

The ID that is created for a DNS Firewall Advanced rule.

type Qtype:

string

param Qtype:

The DNS query type that the rule you are deleting evaluates. Allowed values are;

  • A: Returns an IPv4 address.

  • AAAA: Returns an Ipv6 address.

  • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

  • CNAME: Returns another domain name.

  • DS: Record that identifies the DNSSEC signing key of a delegated zone.

  • MX: Specifies mail servers.

  • NAPTR: Regular-expression-based rewriting of domain names.

  • NS: Authoritative name servers.

  • PTR: Maps an IP address to a domain name.

  • SOA: Start of authority record for the zone.

  • SPF: Lists the servers authorized to send emails from a domain.

  • SRV: Application specific values that identify servers.

  • TXT: Verifies email senders and application-specific values.

  • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

rtype:

dict

returns:

Response Syntax

{
    'FirewallRule': {
        'FirewallRuleGroupId': 'string',
        'FirewallDomainListId': 'string',
        'FirewallThreatProtectionId': 'string',
        'Name': 'string',
        'Priority': 123,
        'Action': 'ALLOW'|'BLOCK'|'ALERT',
        'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
        'BlockOverrideDomain': 'string',
        'BlockOverrideDnsType': 'CNAME',
        'BlockOverrideTtl': 123,
        'CreatorRequestId': 'string',
        'CreationTime': 'string',
        'ModificationTime': 'string',
        'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
        'Qtype': 'string',
        'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
        'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
        'FirewallRuleType': {
            'PartnerThreatProtection': {
                'Partner': 'string'
            },
            'FirewallAdvancedContentCategory': {
                'Category': 'string'
            },
            'FirewallAdvancedThreatCategory': {
                'Category': 'string'
            },
            'DnsThreatProtection': {
                'Value': 'string',
                'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
            },
            'AutoAllowlist': {
                'InitialDataTimeframeHours': 123,
                'ImportFromFirewallDomainListId': 'string',
                'AutoAllowlistFirewallDomainListId': 'string'
            }
        },
        'Status': 'string',
        'StatusMessage': 'string'
    }
}

Response Structure

  • (dict) --

    • FirewallRule (dict) --

      The specification for the firewall rule that you just deleted.

      • FirewallRuleGroupId (string) --

        The unique identifier of the Firewall rule group of the rule.

      • FirewallDomainListId (string) --

        The ID of the domain list that's used in the rule.

      • FirewallThreatProtectionId (string) --

        ID of the DNS Firewall Advanced rule.

      • Name (string) --

        The name of the rule.

      • Priority (integer) --

        The priority of the rule in the rule group. This value must be unique within the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

      • Action (string) --

        The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

        • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

        • ALERT - Permit the request to go through but send an alert to the logs.

        • BLOCK - Disallow the request. If this is specified, additional handling details are provided in the rule's BlockResponse setting.

      • BlockResponse (string) --

        The way that you want DNS Firewall to block the request. Used for the rule action setting BLOCK.

        • NODATA - Respond indicating that the query was successful, but no response is available for it.

        • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

        • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

      • BlockOverrideDomain (string) --

        The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      • BlockOverrideDnsType (string) --

        The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      • BlockOverrideTtl (integer) --

        The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      • CreatorRequestId (string) --

        A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of executing the operation twice. This can be any unique string, for example, a timestamp.

      • CreationTime (string) --

        The date and time that the rule was created, in Unix time format and Coordinated Universal Time (UTC).

      • ModificationTime (string) --

        The date and time that the rule was last modified, in Unix time format and Coordinated Universal Time (UTC).

      • FirewallDomainRedirectionAction (string) --

        How you want the the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

        INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

        TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the domain in the redirection list to the domain list.

      • Qtype (string) --

        The DNS query type you want the rule to evaluate. Allowed values are;

        • A: Returns an IPv4 address.

        • AAAA: Returns an Ipv6 address.

        • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

        • CNAME: Returns another domain name.

        • DS: Record that identifies the DNSSEC signing key of a delegated zone.

        • MX: Specifies mail servers.

        • NAPTR: Regular-expression-based rewriting of domain names.

        • NS: Authoritative name servers.

        • PTR: Maps an IP address to a domain name.

        • SOA: Start of authority record for the zone.

        • SPF: Lists the servers authorized to send emails from a domain.

        • SRV: Application specific values that identify servers.

        • TXT: Verifies email senders and application-specific values.

        • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

      • DnsThreatProtection (string) --

        The type of the DNS Firewall Advanced rule. Valid values are:

        • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

        • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

        • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

      • ConfidenceThreshold (string) --

        The confidence threshold for DNS Firewall Advanced. You must provide this value when you create a DNS Firewall Advanced rule. The confidence level values mean:

        • LOW: Provides the highest detection rate for threats, but also increases false positives.

        • MEDIUM: Provides a balance between detecting threats and false positives.

        • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

      • FirewallRuleType (dict) --

        The rule type configuration for the firewall rule. This is a tagged union — exactly one of its members will be populated. Possible members are:

        • FirewallAdvancedContentCategory — an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

        • FirewallAdvancedThreatCategory — an Amazon Web Services-managed advanced threat category (for example, PHISHING).

        • DnsThreatProtection — a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

        • PartnerThreatProtection — a third-party threat feed delivered through Amazon Web Services Marketplace.

        • AutoAllowlist — an AutoAllowlist rule, which allows the domains on its managed domain list. See AutoAllowlistConfig.

        To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

        • PartnerThreatProtection (dict) --

          Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

          • Partner (string) --

            The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

        • FirewallAdvancedContentCategory (dict) --

          Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

          • Category (string) --

            The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

        • FirewallAdvancedThreatCategory (dict) --

          Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

          • Category (string) --

            The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

        • DnsThreatProtection (dict) --

          Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

          • Value (string) --

            The type of DNS threat protection. Valid values are:

            • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

            • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

            • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

          • ConfidenceThreshold (string) --

            The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

            • LOW: Provides the highest detection rate for threats, but also increases false positives.

            • MEDIUM: Provides a balance between detecting threats and false positives.

            • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

        • AutoAllowlist (dict) --

          Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

          • InitialDataTimeframeHours (integer) --

            The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

          • ImportFromFirewallDomainListId (string) --

            The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

          • AutoAllowlistFirewallDomainListId (string) --

            The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

      • Status (string) --

        The lifecycle state of the firewall rule. Possible values:

        • CREATING — DNS Firewall is provisioning the rule. Rules created with the PartnerThreatProtection rule type begin in this state while DNS Firewall verifies the calling account's Amazon Web Services Marketplace entitlement. Rules created with the AutoAllowlist rule type begin in this state while DNS Firewall reads the look-back window of each VPC that uses the rule group.

        • COMPLETE — The rule is provisioned and enforcing matches.

        • CREATION_FAILED — Provisioning failed. StatusMessage contains a human-readable reason. A rule in this state is immutable: UpdateFirewallRule rejects the request, and the rule must be removed with DeleteFirewallRule.

        For rules that do not require asynchronous provisioning, this field may be absent.

      • StatusMessage (string) --

        An additional message about the rule's lifecycle state. Populated when Status is CREATION_FAILED to describe why provisioning failed.

GetFirewallDomainList (updated) Link ¶
Changes (response)
{'FirewallDomainList': {'ManagedListType': {'AUTOALLOWLIST'}},
 'FirewallRuleGroupId': 'string',
 'FirewallThreatProtectionId': 'string'}

Retrieves the specified firewall domain list.

See also: AWS API Documentation

Request Syntax

client.get_firewall_domain_list(
    FirewallDomainListId='string'
)
type FirewallDomainListId:

string

param FirewallDomainListId:

[REQUIRED]

The ID of the domain list.

rtype:

dict

returns:

Response Syntax

{
    'FirewallDomainList': {
        'Id': 'string',
        'Arn': 'string',
        'Name': 'string',
        'DomainCount': 123,
        'Status': 'COMPLETE'|'COMPLETE_IMPORT_FAILED'|'IMPORTING'|'DELETING'|'UPDATING',
        'StatusMessage': 'string',
        'ManagedOwnerName': 'string',
        'CreatorRequestId': 'string',
        'CreationTime': 'string',
        'ModificationTime': 'string',
        'Category': 'string',
        'ManagedListType': 'THREAT'|'CONTENT'|'AUTOALLOWLIST'
    },
    'FirewallRuleGroupId': 'string',
    'FirewallThreatProtectionId': 'string'
}

Response Structure

  • (dict) --

    • FirewallDomainList (dict) --

      The domain list that you requested.

      • Id (string) --

        The ID of the domain list.

      • Arn (string) --

        The Amazon Resource Name (ARN) of the firewall domain list.

      • Name (string) --

        The name of the domain list.

      • DomainCount (integer) --

        The number of domain names that are specified in the domain list.

      • Status (string) --

        The status of the domain list.

      • StatusMessage (string) --

        Additional information about the status of the list, if available.

      • ManagedOwnerName (string) --

        The owner of the list, used only for lists that are not managed by you. For example, the managed domain list AWSManagedDomainsMalwareDomainList has the managed owner name Route 53 Resolver DNS Firewall.

      • CreatorRequestId (string) --

        A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of running the operation twice. This can be any unique string, for example, a timestamp.

      • CreationTime (string) --

        The date and time that the domain list was created, in Unix time format and Coordinated Universal Time (UTC).

      • ModificationTime (string) --

        The date and time that the domain list was last modified, in Unix time format and Coordinated Universal Time (UTC).

      • Category (string) --

        The category of the domain list.

      • ManagedListType (string) --

        The type of the managed domain list, for example THREAT.

    • FirewallRuleGroupId (string) --

      For an AutoAllowlist domain list, the ID of the firewall rule group that contains the AutoAllowlist rule that owns this domain list. Present only when ManagedListType is AUTOALLOWLIST.

    • FirewallThreatProtectionId (string) --

      For an AutoAllowlist domain list, the threat protection ID of the auto-allowlist rule that owns this domain list. Provide it to ListFirewallRuleDomains to review the observed, allowed, and denied domains. Present only when ManagedListType is AUTOALLOWLIST.

ListFirewallDomainLists (updated) Link ¶
Changes (response)
{'FirewallDomainLists': {'FirewallRuleGroupId': 'string',
                         'FirewallThreatProtectionId': 'string',
                         'ManagedListType': {'AUTOALLOWLIST'},
                         'Status': 'COMPLETE | COMPLETE_IMPORT_FAILED | '
                                   'IMPORTING | DELETING | UPDATING'}}

Retrieves the firewall domain lists that you have defined. For each firewall domain list, you can retrieve the domains that are defined for a list by calling ListFirewallDomains.

A single call to this list operation might return only a partial list of the domain lists. For information, see MaxResults.

See also: AWS API Documentation

Request Syntax

client.list_firewall_domain_lists(
    MaxResults=123,
    NextToken='string'
)
type MaxResults:

integer

param MaxResults:

The maximum number of objects that you want Resolver to return for this request. If more objects are available, in the response, Resolver provides a NextToken value that you can use in a subsequent call to get the next batch of objects.

If you don't specify a value for MaxResults, Resolver returns up to 100 objects.

type NextToken:

string

param NextToken:

For the first call to this list request, omit this value.

When you request a list of objects, Resolver returns at most the number of objects specified in MaxResults. If more objects are available for retrieval, Resolver returns a NextToken value in the response. To retrieve the next batch of objects, use the token that was returned for the prior request in your next request.

rtype:

dict

returns:

Response Syntax

{
    'NextToken': 'string',
    'FirewallDomainLists': [
        {
            'Id': 'string',
            'Arn': 'string',
            'Name': 'string',
            'CreatorRequestId': 'string',
            'ManagedOwnerName': 'string',
            'ManagedListType': 'THREAT'|'CONTENT'|'AUTOALLOWLIST',
            'Category': 'string',
            'FirewallRuleGroupId': 'string',
            'FirewallThreatProtectionId': 'string',
            'Status': 'COMPLETE'|'COMPLETE_IMPORT_FAILED'|'IMPORTING'|'DELETING'|'UPDATING'
        },
    ]
}

Response Structure

  • (dict) --

    • NextToken (string) --

      If objects are still available for retrieval, Resolver returns this token in the response. To retrieve the next batch of objects, provide this token in your next request.

    • FirewallDomainLists (list) --

      A list of the domain lists that you have defined.

      This might be a partial list of the domain lists that you've defined. For information, see MaxResults.

      • (dict) --

        Minimal high-level information for a firewall domain list. The action ListFirewallDomainLists returns an array of these objects.

        To retrieve full information for a firewall domain list, call GetFirewallDomainList and ListFirewallDomains.

        • Id (string) --

          The ID of the domain list.

        • Arn (string) --

          The Amazon Resource Name (ARN) of the firewall domain list metadata.

        • Name (string) --

          The name of the domain list.

        • CreatorRequestId (string) --

          A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of running the operation twice. This can be any unique string, for example, a timestamp.

        • ManagedOwnerName (string) --

          The owner of the list, used only for lists that are not managed by you. For example, the managed domain list AWSManagedDomainsMalwareDomainList has the managed owner name Route 53 Resolver DNS Firewall.

        • ManagedListType (string) --

          The type of the managed domain list, for example THREAT.

        • Category (string) --

          The category of the domain list.

        • FirewallRuleGroupId (string) --

          For an AutoAllowlist domain list, the ID of the firewall rule group that contains the auto-allowlist rule that owns this domain list. Use it to navigate to the rule group and its VPC associations. Present only when ManagedListType is AUTOALLOWLIST.

        • FirewallThreatProtectionId (string) --

          For an AutoAllowlist domain list, the threat protection ID of the auto-allowlist rule that owns this domain list. Provide it to ListFirewallRuleDomains to review the observed, allowed, and denied domains. Present only when ManagedListType is AUTOALLOWLIST.

        • Status (string) --

          For an AutoAllowlist domain list, the status of the list: IMPORTING while domains are being copied from the source domain list specified at rule creation, COMPLETE_IMPORT_FAILED if that copy failed, UPDATING while a change made with UpdateFirewallDomains is being applied, COMPLETE otherwise, and DELETING while the owning rule is being deleted. The first change that you make after a failed copy replaces COMPLETE_IMPORT_FAILED with UPDATING and then COMPLETE. Present only when ManagedListType is AUTOALLOWLIST. Use GetFirewallDomainList for the status of other domain lists.

ListFirewallRules (updated) Link ¶
Changes (response)
{'FirewallRules': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                          'ImportFromFirewallDomainListId': 'string',
                                                          'InitialDataTimeframeHours': 'integer'}}}}

Retrieves the firewall rules that you have defined for the specified firewall rule group. DNS Firewall uses the rules in a rule group to filter DNS network traffic for a VPC.

A single call might return only a partial list of the rules. For information, see MaxResults.

For rules that require asynchronous provisioning, the response includes Status (see FirewallRule) and, on failure, StatusMessage with the reason.

See also: AWS API Documentation

Request Syntax

client.list_firewall_rules(
    FirewallRuleGroupId='string',
    Priority=123,
    Action='ALLOW'|'BLOCK'|'ALERT',
    MaxResults=123,
    NextToken='string'
)
type FirewallRuleGroupId:

string

param FirewallRuleGroupId:

[REQUIRED]

The unique identifier of the firewall rule group that you want to retrieve the rules for.

type Priority:

integer

param Priority:

Optional additional filter for the rules to retrieve.

The setting that determines the processing order of the rules in a rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

type Action:

string

param Action:

Optional additional filter for the rules to retrieve.

The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

  • ALLOW - Permit the request to go through. Not availabe for DNS Firewall Advanced rules.

  • ALERT - Permit the request to go through but send an alert to the logs.

  • BLOCK - Disallow the request. If this is specified, additional handling details are provided in the rule's BlockResponse setting.

type MaxResults:

integer

param MaxResults:

The maximum number of objects that you want Resolver to return for this request. If more objects are available, in the response, Resolver provides a NextToken value that you can use in a subsequent call to get the next batch of objects.

If you don't specify a value for MaxResults, Resolver returns up to 100 objects.

type NextToken:

string

param NextToken:

For the first call to this list request, omit this value.

When you request a list of objects, Resolver returns at most the number of objects specified in MaxResults. If more objects are available for retrieval, Resolver returns a NextToken value in the response. To retrieve the next batch of objects, use the token that was returned for the prior request in your next request.

rtype:

dict

returns:

Response Syntax

{
    'NextToken': 'string',
    'FirewallRules': [
        {
            'FirewallRuleGroupId': 'string',
            'FirewallDomainListId': 'string',
            'FirewallThreatProtectionId': 'string',
            'Name': 'string',
            'Priority': 123,
            'Action': 'ALLOW'|'BLOCK'|'ALERT',
            'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
            'BlockOverrideDomain': 'string',
            'BlockOverrideDnsType': 'CNAME',
            'BlockOverrideTtl': 123,
            'CreatorRequestId': 'string',
            'CreationTime': 'string',
            'ModificationTime': 'string',
            'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
            'Qtype': 'string',
            'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
            'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
            'FirewallRuleType': {
                'PartnerThreatProtection': {
                    'Partner': 'string'
                },
                'FirewallAdvancedContentCategory': {
                    'Category': 'string'
                },
                'FirewallAdvancedThreatCategory': {
                    'Category': 'string'
                },
                'DnsThreatProtection': {
                    'Value': 'string',
                    'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
                },
                'AutoAllowlist': {
                    'InitialDataTimeframeHours': 123,
                    'ImportFromFirewallDomainListId': 'string',
                    'AutoAllowlistFirewallDomainListId': 'string'
                }
            },
            'Status': 'string',
            'StatusMessage': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • NextToken (string) --

      If objects are still available for retrieval, Resolver returns this token in the response. To retrieve the next batch of objects, provide this token in your next request.

    • FirewallRules (list) --

      A list of the rules that you have defined.

      This might be a partial list of the firewall rules that you've defined. For information, see MaxResults.

      • (dict) --

        A single firewall rule in a rule group.

        • FirewallRuleGroupId (string) --

          The unique identifier of the Firewall rule group of the rule.

        • FirewallDomainListId (string) --

          The ID of the domain list that's used in the rule.

        • FirewallThreatProtectionId (string) --

          ID of the DNS Firewall Advanced rule.

        • Name (string) --

          The name of the rule.

        • Priority (integer) --

          The priority of the rule in the rule group. This value must be unique within the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

        • Action (string) --

          The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

          • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

          • ALERT - Permit the request to go through but send an alert to the logs.

          • BLOCK - Disallow the request. If this is specified, additional handling details are provided in the rule's BlockResponse setting.

        • BlockResponse (string) --

          The way that you want DNS Firewall to block the request. Used for the rule action setting BLOCK.

          • NODATA - Respond indicating that the query was successful, but no response is available for it.

          • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

          • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

        • BlockOverrideDomain (string) --

          The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • BlockOverrideDnsType (string) --

          The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • BlockOverrideTtl (integer) --

          The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

        • CreatorRequestId (string) --

          A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of executing the operation twice. This can be any unique string, for example, a timestamp.

        • CreationTime (string) --

          The date and time that the rule was created, in Unix time format and Coordinated Universal Time (UTC).

        • ModificationTime (string) --

          The date and time that the rule was last modified, in Unix time format and Coordinated Universal Time (UTC).

        • FirewallDomainRedirectionAction (string) --

          How you want the the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

          INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

          TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the domain in the redirection list to the domain list.

        • Qtype (string) --

          The DNS query type you want the rule to evaluate. Allowed values are;

          • A: Returns an IPv4 address.

          • AAAA: Returns an Ipv6 address.

          • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

          • CNAME: Returns another domain name.

          • DS: Record that identifies the DNSSEC signing key of a delegated zone.

          • MX: Specifies mail servers.

          • NAPTR: Regular-expression-based rewriting of domain names.

          • NS: Authoritative name servers.

          • PTR: Maps an IP address to a domain name.

          • SOA: Start of authority record for the zone.

          • SPF: Lists the servers authorized to send emails from a domain.

          • SRV: Application specific values that identify servers.

          • TXT: Verifies email senders and application-specific values.

          • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

        • DnsThreatProtection (string) --

          The type of the DNS Firewall Advanced rule. Valid values are:

          • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

          • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

          • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

        • ConfidenceThreshold (string) --

          The confidence threshold for DNS Firewall Advanced. You must provide this value when you create a DNS Firewall Advanced rule. The confidence level values mean:

          • LOW: Provides the highest detection rate for threats, but also increases false positives.

          • MEDIUM: Provides a balance between detecting threats and false positives.

          • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

        • FirewallRuleType (dict) --

          The rule type configuration for the firewall rule. This is a tagged union — exactly one of its members will be populated. Possible members are:

          • FirewallAdvancedContentCategory — an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

          • FirewallAdvancedThreatCategory — an Amazon Web Services-managed advanced threat category (for example, PHISHING).

          • DnsThreatProtection — a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

          • PartnerThreatProtection — a third-party threat feed delivered through Amazon Web Services Marketplace.

          • AutoAllowlist — an AutoAllowlist rule, which allows the domains on its managed domain list. See AutoAllowlistConfig.

          To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

          • PartnerThreatProtection (dict) --

            Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

            • Partner (string) --

              The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

          • FirewallAdvancedContentCategory (dict) --

            Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

            • Category (string) --

              The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

          • FirewallAdvancedThreatCategory (dict) --

            Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

            • Category (string) --

              The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

          • DnsThreatProtection (dict) --

            Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

            • Value (string) --

              The type of DNS threat protection. Valid values are:

              • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

              • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

              • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

            • ConfidenceThreshold (string) --

              The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

              • LOW: Provides the highest detection rate for threats, but also increases false positives.

              • MEDIUM: Provides a balance between detecting threats and false positives.

              • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

          • AutoAllowlist (dict) --

            Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

            • InitialDataTimeframeHours (integer) --

              The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

            • ImportFromFirewallDomainListId (string) --

              The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

            • AutoAllowlistFirewallDomainListId (string) --

              The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

        • Status (string) --

          The lifecycle state of the firewall rule. Possible values:

          • CREATING — DNS Firewall is provisioning the rule. Rules created with the PartnerThreatProtection rule type begin in this state while DNS Firewall verifies the calling account's Amazon Web Services Marketplace entitlement. Rules created with the AutoAllowlist rule type begin in this state while DNS Firewall reads the look-back window of each VPC that uses the rule group.

          • COMPLETE — The rule is provisioned and enforcing matches.

          • CREATION_FAILED — Provisioning failed. StatusMessage contains a human-readable reason. A rule in this state is immutable: UpdateFirewallRule rejects the request, and the rule must be removed with DeleteFirewallRule.

          For rules that do not require asynchronous provisioning, this field may be absent.

        • StatusMessage (string) --

          An additional message about the rule's lifecycle state. Populated when Status is CREATION_FAILED to describe why provisioning failed.

UpdateFirewallDomains (updated) Link ¶
Changes (request)
{'Operation': {'DENY'}}

Updates the firewall domain list from an array of domain specifications.

For an AutoAllowlist rule's managed domain list, use ADD to approve observed domains, REMOVE to stop allowing domains, unless a wildcard entry that's still on the list matches them, and DENY to dismiss observed domains. REPLACE and ImportFirewallDomains aren't supported for these lists.

DNS Firewall throttles UpdateFirewallDomains requests based on both the request rate and the total number of domains across your requests.

Best Practice for Updating Domain Lists

If you only need to modify a subset of domains, use the ADD or REMOVE operations instead of REPLACE. With REPLACE, you send the complete list you want to end up with, and throttling counts every domain in that request, including domains that aren't changing, which can use up your available throttling capacity.

See also: AWS API Documentation

Request Syntax

client.update_firewall_domains(
    FirewallDomainListId='string',
    Operation='ADD'|'REMOVE'|'REPLACE'|'DENY',
    Domains=[
        'string',
    ]
)
type FirewallDomainListId:

string

param FirewallDomainListId:

[REQUIRED]

The ID of the domain list whose domains you want to update.

type Operation:

string

param Operation:

[REQUIRED]

What you want DNS Firewall to do with the domains that you are providing:

  • ADD - Add the domains to the ones that are already in the domain list. For an AutoAllowlist rule's managed domain list, this also marks the observed domains as allowed.

  • REMOVE - Search the domain list for the domains and remove them from the list. For an AutoAllowlist rule's managed domain list, the rule no longer allows the removed domains, unless a wildcard entry that's still on the list matches them.

  • REPLACE - Update the domain list to exactly match the list that you are providing. Not supported for an AutoAllowlist rule's managed domain list.

  • DENY - For an AutoAllowlist rule's managed domain list only, mark the specified observed domains as denied so that they're no longer listed for review. If a domain is on the managed domain list, DENY also removes it from the list. Specify fully qualified domain names. Wildcards aren't accepted.

type Domains:

list

param Domains:

[REQUIRED]

A list of domains to use in the update operation.

Each domain specification in your domain list must satisfy the following requirements:

  • It can optionally start with * (asterisk).

  • With the exception of the optional starting asterisk, it must only contain the following characters: A-Z, a-z, 0-9, - (hyphen).

  • It must be from 1-255 characters in length.

  • (string) --

rtype:

dict

returns:

Response Syntax

{
    'Id': 'string',
    'Name': 'string',
    'Status': 'COMPLETE'|'COMPLETE_IMPORT_FAILED'|'IMPORTING'|'DELETING'|'UPDATING',
    'StatusMessage': 'string'
}

Response Structure

  • (dict) --

    • Id (string) --

      The ID of the firewall domain list that DNS Firewall just updated.

    • Name (string) --

      The name of the domain list.

    • Status (string) --

      Status of the UpdateFirewallDomains request.

    • StatusMessage (string) --

      Additional information about the status of the list, if available.

UpdateFirewallRule (updated) Link ¶
Changes (request, response)
Request
{'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                        'ImportFromFirewallDomainListId': 'string',
                                        'InitialDataTimeframeHours': 'integer'}}}
Response
{'FirewallRule': {'FirewallRuleType': {'AutoAllowlist': {'AutoAllowlistFirewallDomainListId': 'string',
                                                         'ImportFromFirewallDomainListId': 'string',
                                                         'InitialDataTimeframeHours': 'integer'}}}}

Updates the specified firewall rule. The rule's FirewallRuleType, FirewallDomainListId, and top-level DnsThreatProtection match source cannot be changed after creation. Rules whose Status is CREATING or CREATION_FAILED cannot be updated; remove a failed rule with DeleteFirewallRule.

See also: AWS API Documentation

Request Syntax

client.update_firewall_rule(
    FirewallRuleGroupId='string',
    FirewallDomainListId='string',
    FirewallThreatProtectionId='string',
    Priority=123,
    Action='ALLOW'|'BLOCK'|'ALERT',
    BlockResponse='NODATA'|'NXDOMAIN'|'OVERRIDE',
    BlockOverrideDomain='string',
    BlockOverrideDnsType='CNAME',
    BlockOverrideTtl=123,
    Name='string',
    FirewallDomainRedirectionAction='INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
    Qtype='string',
    DnsThreatProtection='DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
    ConfidenceThreshold='LOW'|'MEDIUM'|'HIGH',
    FirewallRuleType={
        'PartnerThreatProtection': {
            'Partner': 'string'
        },
        'FirewallAdvancedContentCategory': {
            'Category': 'string'
        },
        'FirewallAdvancedThreatCategory': {
            'Category': 'string'
        },
        'DnsThreatProtection': {
            'Value': 'string',
            'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
        },
        'AutoAllowlist': {
            'InitialDataTimeframeHours': 123,
            'ImportFromFirewallDomainListId': 'string',
            'AutoAllowlistFirewallDomainListId': 'string'
        }
    }
)
type FirewallRuleGroupId:

string

param FirewallRuleGroupId:

[REQUIRED]

The unique identifier of the firewall rule group for the rule.

type FirewallDomainListId:

string

param FirewallDomainListId:

The ID of the domain list to use in the rule.

type FirewallThreatProtectionId:

string

param FirewallThreatProtectionId:

The DNS Firewall Advanced rule ID.

type Priority:

integer

param Priority:

The setting that determines the processing order of the rule in the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

You must specify a unique priority for each rule in a rule group. To make it easier to insert rules later, leave space between the numbers, for example, use 100, 200, and so on. You can change the priority setting for the rules in a rule group at any time.

type Action:

string

param Action:

The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

  • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

  • ALERT - Permit the request to go through but send an alert to the logs.

  • BLOCK - Disallow the request. This option requires additional details in the rule's BlockResponse.

type BlockResponse:

string

param BlockResponse:

The way that you want DNS Firewall to block the request. Used for the rule action setting BLOCK.

  • NODATA - Respond indicating that the query was successful, but no response is available for it.

  • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

  • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

type BlockOverrideDomain:

string

param BlockOverrideDomain:

The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

type BlockOverrideDnsType:

string

param BlockOverrideDnsType:

The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

type BlockOverrideTtl:

integer

param BlockOverrideTtl:

The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

type Name:

string

param Name:

The name of the rule.

type FirewallDomainRedirectionAction:

string

param FirewallDomainRedirectionAction:

How you want the the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the domain in the redirection list to the domain list.

You can't set this value on an AutoAllowlist rule, which always inspects the redirection chain.

type Qtype:

string

param Qtype:

The DNS query type you want the rule to evaluate. Allowed values are;

  • A: Returns an IPv4 address.

  • AAAA: Returns an Ipv6 address.

  • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

  • CNAME: Returns another domain name.

  • DS: Record that identifies the DNSSEC signing key of a delegated zone.

  • MX: Specifies mail servers.

  • NAPTR: Regular-expression-based rewriting of domain names.

  • NS: Authoritative name servers.

  • PTR: Maps an IP address to a domain name.

  • SOA: Start of authority record for the zone.

  • SPF: Lists the servers authorized to send emails from a domain.

  • SRV: Application specific values that identify servers.

  • TXT: Verifies email senders and application-specific values.

  • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

You can't set Qtype on an AutoAllowlist rule, because the rule applies to all query types.

type DnsThreatProtection:

string

param DnsThreatProtection:

The type of the DNS Firewall Advanced rule. This setting is mutually exclusive with FirewallDomainListId and FirewallRuleType. Valid values are:

  • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

  • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

  • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

type ConfidenceThreshold:

string

param ConfidenceThreshold:

The confidence threshold for DNS Firewall Advanced. You must provide this value when you create a DNS Firewall Advanced rule. The confidence level values mean:

  • LOW: Provides the highest detection rate for threats, but also increases false positives.

  • MEDIUM: Provides a balance between detecting threats and false positives.

  • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

type FirewallRuleType:

dict

param FirewallRuleType:

The rule type configuration for the firewall rule. This is a tagged union — set exactly one of its members. This setting is mutually exclusive with the top-level FirewallDomainListId and DnsThreatProtection fields. Use one of:

  • FirewallAdvancedContentCategory — match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

  • FirewallAdvancedThreatCategory — match an Amazon Web Services-managed advanced threat category (for example, PHISHING).

  • DnsThreatProtection — match a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

  • PartnerThreatProtection — match a third-party threat feed delivered through Amazon Web Services Marketplace. The selected partner must be an active subscription on the calling account.

To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

You can't specify FirewallRuleType when you update an AutoAllowlist rule, even with its current values. InitialDataTimeframeHours and ImportFromFirewallDomainListId can't be changed. To change them, delete the rule and create a new one. Deleting an AutoAllowlist rule also deletes its managed domain list and the domains that you allowed.

  • PartnerThreatProtection (dict) --

    Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

    • Partner (string) -- [REQUIRED]

      The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

  • FirewallAdvancedContentCategory (dict) --

    Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

    • Category (string) -- [REQUIRED]

      The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

  • FirewallAdvancedThreatCategory (dict) --

    Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

    • Category (string) -- [REQUIRED]

      The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

  • DnsThreatProtection (dict) --

    Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

    • Value (string) -- [REQUIRED]

      The type of DNS threat protection. Valid values are:

      • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

      • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

      • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

    • ConfidenceThreshold (string) -- [REQUIRED]

      The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

      • LOW: Provides the highest detection rate for threats, but also increases false positives.

      • MEDIUM: Provides a balance between detecting threats and false positives.

      • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

  • AutoAllowlist (dict) --

    Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

    • InitialDataTimeframeHours (integer) -- [REQUIRED]

      The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

    • ImportFromFirewallDomainListId (string) --

      The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

    • AutoAllowlistFirewallDomainListId (string) --

      The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

rtype:

dict

returns:

Response Syntax

{
    'FirewallRule': {
        'FirewallRuleGroupId': 'string',
        'FirewallDomainListId': 'string',
        'FirewallThreatProtectionId': 'string',
        'Name': 'string',
        'Priority': 123,
        'Action': 'ALLOW'|'BLOCK'|'ALERT',
        'BlockResponse': 'NODATA'|'NXDOMAIN'|'OVERRIDE',
        'BlockOverrideDomain': 'string',
        'BlockOverrideDnsType': 'CNAME',
        'BlockOverrideTtl': 123,
        'CreatorRequestId': 'string',
        'CreationTime': 'string',
        'ModificationTime': 'string',
        'FirewallDomainRedirectionAction': 'INSPECT_REDIRECTION_DOMAIN'|'TRUST_REDIRECTION_DOMAIN',
        'Qtype': 'string',
        'DnsThreatProtection': 'DGA'|'DNS_TUNNELING'|'DICTIONARY_DGA',
        'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH',
        'FirewallRuleType': {
            'PartnerThreatProtection': {
                'Partner': 'string'
            },
            'FirewallAdvancedContentCategory': {
                'Category': 'string'
            },
            'FirewallAdvancedThreatCategory': {
                'Category': 'string'
            },
            'DnsThreatProtection': {
                'Value': 'string',
                'ConfidenceThreshold': 'LOW'|'MEDIUM'|'HIGH'
            },
            'AutoAllowlist': {
                'InitialDataTimeframeHours': 123,
                'ImportFromFirewallDomainListId': 'string',
                'AutoAllowlistFirewallDomainListId': 'string'
            }
        },
        'Status': 'string',
        'StatusMessage': 'string'
    }
}

Response Structure

  • (dict) --

    • FirewallRule (dict) --

      The firewall rule that you just updated.

      • FirewallRuleGroupId (string) --

        The unique identifier of the Firewall rule group of the rule.

      • FirewallDomainListId (string) --

        The ID of the domain list that's used in the rule.

      • FirewallThreatProtectionId (string) --

        ID of the DNS Firewall Advanced rule.

      • Name (string) --

        The name of the rule.

      • Priority (integer) --

        The priority of the rule in the rule group. This value must be unique within the rule group. DNS Firewall processes the rules in a rule group by order of priority, starting from the lowest setting.

      • Action (string) --

        The action that DNS Firewall should take on a DNS query when it matches one of the domains in the rule's domain list, or a threat in a DNS Firewall Advanced rule:

        • ALLOW - Permit the request to go through. Not available for DNS Firewall Advanced rules.

        • ALERT - Permit the request to go through but send an alert to the logs.

        • BLOCK - Disallow the request. If this is specified, additional handling details are provided in the rule's BlockResponse setting.

      • BlockResponse (string) --

        The way that you want DNS Firewall to block the request. Used for the rule action setting BLOCK.

        • NODATA - Respond indicating that the query was successful, but no response is available for it.

        • NXDOMAIN - Respond indicating that the domain name that's in the query doesn't exist.

        • OVERRIDE - Provide a custom override in the response. This option requires custom handling details in the rule's BlockOverride* settings.

      • BlockOverrideDomain (string) --

        The custom DNS record to send back in response to the query. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      • BlockOverrideDnsType (string) --

        The DNS record's type. This determines the format of the record value that you provided in BlockOverrideDomain. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      • BlockOverrideTtl (integer) --

        The recommended amount of time, in seconds, for the DNS resolver or web browser to cache the provided override record. Used for the rule action BLOCK with a BlockResponse setting of OVERRIDE.

      • CreatorRequestId (string) --

        A unique string defined by you to identify the request. This allows you to retry failed requests without the risk of executing the operation twice. This can be any unique string, for example, a timestamp.

      • CreationTime (string) --

        The date and time that the rule was created, in Unix time format and Coordinated Universal Time (UTC).

      • ModificationTime (string) --

        The date and time that the rule was last modified, in Unix time format and Coordinated Universal Time (UTC).

      • FirewallDomainRedirectionAction (string) --

        How you want the the rule to evaluate DNS redirection in the DNS redirection chain, such as CNAME or DNAME.

        INSPECT_REDIRECTION_DOMAIN: (Default) inspects all domains in the redirection chain. The individual domains in the redirection chain must be added to the domain list.

        TRUST_REDIRECTION_DOMAIN: Inspects only the first domain in the redirection chain. You don't need to add the subsequent domains in the domain in the redirection list to the domain list.

      • Qtype (string) --

        The DNS query type you want the rule to evaluate. Allowed values are;

        • A: Returns an IPv4 address.

        • AAAA: Returns an Ipv6 address.

        • CAA: Restricts CAs that can create SSL/TLS certifications for the domain.

        • CNAME: Returns another domain name.

        • DS: Record that identifies the DNSSEC signing key of a delegated zone.

        • MX: Specifies mail servers.

        • NAPTR: Regular-expression-based rewriting of domain names.

        • NS: Authoritative name servers.

        • PTR: Maps an IP address to a domain name.

        • SOA: Start of authority record for the zone.

        • SPF: Lists the servers authorized to send emails from a domain.

        • SRV: Application specific values that identify servers.

        • TXT: Verifies email senders and application-specific values.

        • A query type you define by using the DNS type ID, for example 28 for AAAA. The values must be defined as TYPENUMBER, where the NUMBER can be 1-65534, for example, TYPE28. For more information, see List of DNS record types.

      • DnsThreatProtection (string) --

        The type of the DNS Firewall Advanced rule. Valid values are:

        • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

        • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

        • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

      • ConfidenceThreshold (string) --

        The confidence threshold for DNS Firewall Advanced. You must provide this value when you create a DNS Firewall Advanced rule. The confidence level values mean:

        • LOW: Provides the highest detection rate for threats, but also increases false positives.

        • MEDIUM: Provides a balance between detecting threats and false positives.

        • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

      • FirewallRuleType (dict) --

        The rule type configuration for the firewall rule. This is a tagged union — exactly one of its members will be populated. Possible members are:

        • FirewallAdvancedContentCategory — an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH).

        • FirewallAdvancedThreatCategory — an Amazon Web Services-managed advanced threat category (for example, PHISHING).

        • DnsThreatProtection — a built-in DNS Firewall Advanced threat detector ( DGA, DNS_TUNNELING, or DICTIONARY_DGA).

        • PartnerThreatProtection — a third-party threat feed delivered through Amazon Web Services Marketplace.

        • AutoAllowlist — an AutoAllowlist rule, which allows the domains on its managed domain list. See AutoAllowlistConfig.

        To enumerate the values supported in your account, call ListFirewallRuleTypes. It doesn't return AutoAllowlist.

        • PartnerThreatProtection (dict) --

          Configures the rule to match a third-party threat feed delivered through Amazon Web Services Marketplace. The calling account must hold an active subscription to the partner product named in Partner; if the subscription is missing or revoked, the rule is created with Status CREATION_FAILED and cannot be modified — only deleted. See PartnerThreatProtectionConfig.

          • Partner (string) --

            The identifier of the partner threat-protection product, exactly as returned in the Value field of a FirewallRuleTypeDefinition with RuleType set to PartnerThreatProtection. The calling account must hold an active Amazon Web Services Marketplace subscription to this product.

        • FirewallAdvancedContentCategory (dict) --

          Configures the rule to match an Amazon Web Services-managed content category (for example, VIOLENCE_AND_HATE_SPEECH). See FirewallAdvancedContentCategoryConfig.

          • Category (string) --

            The content category identifier. To retrieve the list of available content categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedContentCategory.

        • FirewallAdvancedThreatCategory (dict) --

          Configures the rule to match an Amazon Web Services-managed advanced threat category (for example, PHISHING). See FirewallAdvancedThreatCategoryConfig.

          • Category (string) --

            The threat category identifier. To retrieve the list of available threat categories, call ListFirewallRuleTypes with RuleType set to FirewallAdvancedThreatCategory.

        • DnsThreatProtection (dict) --

          Configures the rule to match a built-in DNS Firewall Advanced threat detector — DGA, DNS_TUNNELING, or DICTIONARY_DGA. See DnsThreatProtectionRuleTypeConfig.

          • Value (string) --

            The type of DNS threat protection. Valid values are:

            • DGA: Domain generation algorithms detection. DGAs are used by attackers to generate a large number of domains to launch malware attacks.

            • DNS_TUNNELING: DNS tunneling detection. DNS tunneling is used by attackers to exfiltrate data from the client by using the DNS tunnel without making a network connection to the client.

            • DICTIONARY_DGA: Dictionary-based domain generation algorithms detection. Dictionary DGAs use wordlists to generate domains that appear more legitimate, making them harder to detect than traditional DGAs.

          • ConfidenceThreshold (string) --

            The confidence threshold for DNS Firewall Advanced. You must provide this value when you create or update a DNS Firewall Advanced rule. The confidence level values mean:

            • LOW: Provides the highest detection rate for threats, but also increases false positives.

            • MEDIUM: Provides a balance between detecting threats and false positives.

            • HIGH: Detects only the most well corroborated threats with a low rate of false positives.

        • AutoAllowlist (dict) --

          Configures the rule as an AutoAllowlist rule, which observes the DNS traffic of the VPCs that use the rule group, through a rule group association or a Route 53 Profile, so that you can review the domains and allow them. See AutoAllowlistConfig.

          • InitialDataTimeframeHours (integer) --

            The look-back window, in hours, of historical DNS traffic that DNS Firewall uses to seed the initial set of observed domains when you create the rule. Valid values are from 1 to 168 (7 days). You can't change this value after you create the rule.

          • ImportFromFirewallDomainListId (string) --

            The ID of a domain list whose domains DNS Firewall copies into the AutoAllowlist rule's managed domain list after you create the rule. You must own the source list, and it must be in COMPLETE status, in the same Region, and not a managed or AutoAllowlist list. DNS Firewall reads the source list while the copy runs, so don't change or delete it until the managed list's status is no longer IMPORTING. A change made to the source list during the copy can be reflected in the managed list, and deleting the source list fails the copy. The managed list then has status COMPLETE, or COMPLETE_IMPORT_FAILED if the copy failed. DNS Firewall uses this value only when you create the rule.

          • AutoAllowlistFirewallDomainListId (string) --

            The ID of the managed domain list that DNS Firewall creates and maintains for this AutoAllowlist rule. The list is named AutoAllowlist - followed by the rule name, cut to 64 characters, and is renamed when you rename the rule. DNS Firewall returns this value in responses. You can't set it.

      • Status (string) --

        The lifecycle state of the firewall rule. Possible values:

        • CREATING — DNS Firewall is provisioning the rule. Rules created with the PartnerThreatProtection rule type begin in this state while DNS Firewall verifies the calling account's Amazon Web Services Marketplace entitlement. Rules created with the AutoAllowlist rule type begin in this state while DNS Firewall reads the look-back window of each VPC that uses the rule group.

        • COMPLETE — The rule is provisioned and enforcing matches.

        • CREATION_FAILED — Provisioning failed. StatusMessage contains a human-readable reason. A rule in this state is immutable: UpdateFirewallRule rejects the request, and the rule must be removed with DeleteFirewallRule.

        For rules that do not require asynchronous provisioning, this field may be absent.

      • StatusMessage (string) --

        An additional message about the rule's lifecycle state. Populated when Status is CREATION_FAILED to describe why provisioning failed.