This document describes the integration process for ThreatSTOP DNS Defense on an AWS Route 53 Resolver DNS Firewall


This document describes how to integrate ThreatSTOP’s DNS Defense service on an AWS Route 53 Resolver. This integration runs entirely in ThreatSTOP’s Cloud, updating DNS Lists in the Route 53 Resolver DNS Firewall and optionally retrieving its log files for reporting.

The integration supports block and allow rules. It can only be configured to only monitor DNS requests, and not block. The Route 53 Resolver DNS Firewall does not support blocking based on IP addresses in the DNS responses.

Log upload/Reporting is an optional feature. They are enabled for trial accounts. After your ThreatSTOP trial expires, the feature must be activated by your ThreatSTOP Sales representative to remain active.


This integration works with AWS’s Route 53 Resolver DNS Firewall.

  • The Route 53 Rule Group can not be shared with other AWS accounts.
  • The integration is not available for the ap-east-1 AWS zone.

To enable logging and reporting features, an AWS S3 bucket is also required.

Mappings with ThreatSTOP RPZ

ThreatSTOP DNS policies support the RPZ feature set. Because the Route 53 Resolver DNS Firewall doesn’t filter based on IP addresses in the DNS responses, the policy sent to the firewall will filter out IP address records. NSIP and NSDNAME records are also removed.

If your policy contains an Allow section (targets or User-defined List), they will be mapped to the Alert action. The Alert action will allow the DNS query but logs it.

RPZ actions are are mapped to the DNS Firewall rules as follows:

RPZ Action Route 53 Resolver DNS Firewall Action
NXDOMAIN (CNAME .) Block or Alert
NODATA (CNAME .*) Block or Alert
CNAME fqdn Walled Garden (fqdn) or Alert
Passthru (rpz-passthru.) Alert
DROP (rpz-drop.) Not supported (records will be removed from the policy)
A ip address Not supported (records will be removed from the policy)

Current Version

Current Version Released
1.00 October 2021

Data Flow Diagram

Install Methods

The Policy updates and Log file retrieval run in the ThreatSTOP cloud. No agent is required in your system. The installation requires:

  • an active ThreatSTOP account
  • a Route 53 resolver DNS Firewall
  • an S3 bucket for logging (optional)
  • a ThreatSTOP DNS Firewall device configured with an AWS access key with permissions to access the resolver and S3 bucket

Installation considerations

  • Domains can start with a wildcard (*
  • Block lists and Allow lists are both supported.
  • Filtering based on IP addresses in resource records is not supported. If your ThreatSTOP policy contains IP targets, the records will be removed before applying the policy.
  • The DNS Firewall will be applied to DNS queries from the VPCs associated with the DNS Firewall.
  • You can setup integrations with multiple DNS Firewall rule groups by creating multiple devices in the ThreatSTOP Portal.

Maximum Policy Size

  • At the time this document was written, AWS Route 53 Resolver DNS Firewall has a default quota of 100,000 domains in a region, across all DNS Fireweall rule groups in the region.
  • The default policy will have fewer than 100,000 records. A typical custom policy will vary from 300,000 to 1,000,000 domains.
  • If your policy exceeds this setting, it will be truncated.
  • You can submit a request to AWS to increase the limits for your instance by contacting AWS support (Domains per Account quota at After approval, you can update the Max Policy Size setting to match your custom AWS setting.
  • The quota increase must be requested for each region where you want to deploy a ThreatSTOP policy larger than 100,000 domains.


  • The ThreatSTOP Cloud will connect your AWS account to update the DNS Firewall policy and retrieve its logs.
  • Route 53 permissions: use either
    • Route53ResolverFullAccess, if you want to use default AWS permissions. This grants access to VPC settings that is not required for the integration.
    • or these specific permissions. They can also be applied to the ARN of the Rule Group.
    "Version": "2012-10-17",
    "Statement": [
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "route53domains:*",
            "Resource": "*"
    "Version": "2012-10-17",
    "Statement": [
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "route53resolver:*",
            "Resource": "*"
  • Service: S3: use either
    • AmazonS3ReadOnlyAccess
    • or these specific permissions. They can also be applied to the ARN of the S3 bucket.
    "Version": "2012-10-17",
    "Statement": [
            "Effect": "Allow",
            "Action": [
            "Resource": "*"
  • Access keys can be associated with a policy that restricts access based on the source IP. If you do so, please allow these subnets:


Step 1 - AWS Configuration

Route 53 resolver

To use the DNS Firewall, you will need to create a Route 53 resolver endpoint, a DNS Firewall rule group and associate the rule group with one or more VPCs. The endpoint configuration will depend on your AWS topology. In this example, we will use an Outbound Endpoint to protect EC2 instances.

  • Open the AWS Console and select the region where you will add your DNS Firewall.
  • Browse to the Route 53 service.
  • In the left menu, select Rule Groups under DNS Firewall.
  • Click the Create Rule Group button
  • Set a name and description, click Next
  • Step through the creation process without adding rules or setting priorities. Rules will be populated by the integration.
  • Tags are optional.
  • Complete the creation of the rule group. Make a note of its ID at the top of the Rule Group details page.


The DNS Firewall instance can write logs to an S3 bucket or to a Kinesis Data stream. The integration is currently able to read logs from an S3 bucket. This is an optional but recommended step, required only if you want to use ThreatSTOP’s reporting features.

  • In the same region as the DNS Firewall, browse to the S3 service.
  • You can either create a new bucket or use an existing one
  • You can optionally create a directory in the bucket for the DNS Firewall to store the logs.
  • Make note of the S3 ARN and directory path.

Query Logging

This step will configure the DNS Firewall to log to the S3 bucket. It is only required when you want to use the reporting features or in monitor-only mode.

  • In the AWS Console, go the the Route 53 service for the region being configured
  • In the left menu, select Query Logging under Resolver.
  • In the Query Logging list page, select Configure Query Logging.
  • Pick a name.
  • Select S3 bucket as the destination.
  • Enter the S3 ARN and Path or use Browse S3 to find the bucket and directory created in the previous step.
  • Select the VPC(s) for which DNS traffic will be logged. The typical configuration would associate the same VPC(s) as the DNS Firewall Rule Group.


To allow ThreatSTOP’s Cloud to update the policy and retrieve the DNS Firewall logs, you will need to provide an AWS Access Key. We recommend setting a key for a user whose policy limits access to the required services and objects.

  • Open the AWS Console and browse to the IAM service
  • Create a policy with the access documented in the Permissions section above.
    • The DNS Firewall permissions are required for Policy management.
    • The S3 permissions are only required if you are using the reporting features.
    • Optionally, configure the policy to restrict access to ThreatSTOP’s subnets.
  • Create a new user (Users > Add User)
    • Set the credential type to Access Key - Programatic Access
    • Attach the policy created above
    • After completing the user creation process, make note of the AWS key ID and secret to configure the integration in the next step.

Step 2 - Portal device configuration

During this step, you will create a device entry on the Admin Portal. You will select a device type (AWS > WAFv2) and enter the configuration settings.

To create a DNS Firewall device entry:

  • Log into the Admin Portal with your ThreatSTOP account
  • Browse to the Device page and click Add Device
  • Select the device manufacturer and model:
    • Type: DNS Defense
    • Manufacturer: AWS
    • Model: Route 53 Resolver
    • Integration type: Cloud
  • Nickname: this is a mnemonic name used to identify the device. It can be set to any string (A-Z, 0-9, - and _). If you create multiple device entries, each entry must have a unique nickname. The Nickname will be used to identify the firewall and in the Reporting user interface.

  • Policy: select a pre-defined policy or a customized policy. It must be a DNS Defense Policy. See this note for compatibility with ThreatSTOP targets.

  • Note: An optional field to store a note of your choice about the device - location, identifiers, model…

  • AWS Region: the name of the region where the Route 53 Resolver DNS Firewall is located.

  • Rule Group ID: the ID of the DNS Firewall rule group that the policy will be applied to.

  • AWS Access key ID: the ID for the Access Key to access the AWS services.

  • AWS Access key secret: the secret associated with the key.

  • Maximum Policy Size: the default maximum size of a DNS Firewall list in the Route 53 Resolver is 100,000 domains. If AWS has granted a higher quota to your account, you can increase the setting to max your quotas.

  • Monitor only: set to Yes to set the policy to monitor DNS requests, i.e. log DNS requests that would normally blocked by the policy. The default behavior (No) will block DNS requests for domain names found in your policy.

  • Log Upload: Set to Enabled to enable log collection and reporting for the resolver. This feature is optional and requires a subscription after your trial expires.

Upon saving the form, a device entry will be created in ThreatSTOP’s cloud. The policy will be generated (if new) and sync’ed to the DNS Firewall. Please allow up to 30 minutes for the initial setup to complete.

Step 3 - Testing the setup

Block mode

  • Create an EC2 instance in a VPC associated with the Route 53 Resolver and Firewall.
  • Attempt to resolve using dig or nslookup. The lookup should not return an IP address.
  • If an IP address is returned, check the contents of the DNS Firewall’s domain list in the AWS Console.
    • If the domain list is not populated, the integration has not successfully run. Check the permissions associated with the AWS access key.
    • If the domain list is populated, check the VPC associations.

Monitor-only mode

Query Logging must be enabled to see the actions taken by the DNS Firewall in monitor-only mode.

  • Create an EC2 instance in a VPC associated with the Route 53 Resolver and Firewall.
  • Attempt to resolve using dig or nslookup. The lookup should succeed and return an IP address.
  • After a couple of minutes, retrieve the log files written in your S3 bucket and you should find the test lookup.

Integration Status

  • Typically, the policy is updated every 2 hours.

In the ThreatSTOP Portal, the Devices List page shows the state of the device - whether it is available to load policies or not, as well as the time of the last policy update and the time the most recent log file was retrieved from S3.

Custom policies

AWS Route 53 Resolver doesn’t filter based on IP addresses. When creating a custom policy, only Domain targets will be installed in the AWS DNS Firewall. If you add IP targets to your policy, the integration will remove them before proceeding. This will also cause the policy size displayed in the Portal to be larger than its actual size.

Logging and Reporting

If the log upload feature is available and enabled, the ThreatSTOP cloud will retrieve new logs from S3 every 15 minutes. The logs can be analyzed in the DNS Defense Reports 15 minutes after they’ve been uploaded.

  • You can check that logs are created for the test DNS queries. It takes a few minutes for log files to be available in S3.
  • If logs are not shown in the ThreatSTOP Portal within 30 minutes, check the permissions on the Access Key and verify that Log Upload is enabled in the device configuration in the ThreatSTOP Portal.

Uninstalling ThreatSTOP

  • To uninstall the ThreatSTOP integration:
    • Delete the device entry on the ThreatSTOP Admin Portal.
    • Remove the VPC assocation in the AWS Console.
    • Delete the rule group.

You can also suspend the filtering by keeping the integration configured but removing the association of the Rule Group with your VPC(s).

Version Changelog

Version Release Date Notes
1.00 October 2021 Initial release