Skip to main content

​
Overview

The DNS Filter integration enables ThreatAware to collect DNS security and filtering data from your DNS Filter environment, providing visibility into DNS security posture and web filtering policies.
Connection Method: API Setup Time: 10 minutes Access Required: DNS Filter Administrator account

​
Data collected

The DNS Filter integration provides:
  • DNS filtering policy data
  • Blocked DNS queries and threats
  • DNS security events
  • Web filtering logs
  • Threat intelligence data

​
Use cases

DNS Security Monitoring

Monitor DNS-based threats and blocked malicious domains

Filtering Policy Validation

Verify DNS filtering policies are enforced across devices

Threat Detection

Detect DNS-based threats and suspicious domain access attempts

Compliance Reporting

Generate reports showing DNS security coverage and incidents

​
Setup instructions

1

Access DNSFilter Dashboard

Log in to the DNSFilter Dashboard using an account with administrator privileges.
2

Navigate to API Settings

In the DNSFilter console:
  • Click on Settings in the main menu
  • Select API Access from the settings options
  • This section displays your API keys and allows you to manage API access
3

Generate API Key

In the API Access section:
  • Click Generate API Key
  • A new API key will be created for you
  • Configure the API key with the required permissions:
    • Typically Read-only access for monitoring is sufficient
    • Select only the necessary permissions for ThreatAware
  • Copy the generated API Key for use in ThreatAware
Only grant the minimum permissions necessary for ThreatAware to function
4

Configure in ThreatAware

Complete the integration setup in ThreatAware:
  • Open ThreatAware and navigate to Settings > Integrations
  • Search for and select DNSFilter
  • Enter the required credential:
    • API Key: The key generated in step 3
  • Click Connect to establish the integration
5

Verify Connection

After connecting:
  • Check that the Integration Status shows as Active
  • Verify that DNS filtering data begins appearing in ThreatAware within 5-10 minutes
  • Check the last sync timestamp

​
Required credentials

Field Name: DNSFilter API Key Type: Password (encrypted) Description: The API key generated in DNSFilter for ThreatAware integrationThis key provides access to DNS filtering and security data from DNSFilter.
Store this credential securely in your organisation’s password manager

​
Verification and testing

After setup, verify the integration is working correctly:
  1. Check Integration Status
    • Navigate to Settings > Integrations in ThreatAware
    • Confirm DNSFilter shows Active status
    • Check the last sync timestamp
  2. Verify Data Collection
    • Wait 5-10 minutes for the initial data poll
    • Check for DNS filtering and security data in ThreatAware
    • Verify the data matches what you see in DNSFilter
  3. Test Queries
    • Create a test query to filter DNS security events
    • Verify the filtering policy data matches your expectations

​
Troubleshooting

Symptoms: Integration status shows authentication failureSolutions:
  • Verify the API Key is correct and was copied without extra spaces
  • Ensure the API key has not been revoked in DNSFilter
  • Check that your DNSFilter account still has administrator privileges
  • Confirm the API key has the necessary permissions
  • Generate a new API key if needed
Symptoms: Connection succeeds but no DNS filtering data appearsSolutions:
  • Verify the API key has read permissions to DNS filtering data
  • Check the DNSFilter API Documentation for required permissions
  • Ensure the API key grants access to all required data types
  • Review the permissions assigned to the API key in DNSFilter
  • Recreate the API key with appropriate permissions if needed
Symptoms: Integration fails to connect or times outSolutions:
  • Verify the DNSFilter dashboard is accessible and online
  • Check firewall rules allow outbound HTTPS (443) to DNSFilter
  • Test the DNSFilter URL in a browser to ensure connectivity
  • Verify your internet connection is stable
  • Try connecting again after waiting a few minutes
Symptoms: Integration shows active but no DNS filtering data appearsSolutions:
  • Verify there is DNS filtering data in DNSFilter to collect
  • Check that DNS filtering is actively processing traffic
  • Confirm the API key has visibility to DNS events and logs
  • Ensure devices are using DNSFilter for DNS resolution
  • Wait up to 30 minutes for initial data sync to complete
  • Review ThreatAware integration logs for errors
Symptoms: Integration works initially but stops syncing dataSolutions:
  • Check DNSFilter for API rate limits
  • Verify the API key is not hitting usage limits
  • Wait for rate limits to reset before retrying
  • Contact DNSFilter support about increasing rate limits if needed
  • Optimize query patterns if possible to reduce API calls

​
Additional resources

DNSFilter API Documentation

Official DNSFilter API documentation for detailed API information

ThreatAware Support

Contact ThreatAware support for integration assistance

​
Best practices

API Key Management
  • Create a dedicated API key specifically for ThreatAware
  • Document the API key location in your organisation’s credential manager
  • Rotate API keys annually or per your security policy
  • Monitor for authentication failures in ThreatAware regularly
Security Considerations
  • Grant only read-only permissions (never write access)
  • Store API keys securely in your password manager
  • Regularly review API key usage in DNSFilter audit logs
  • Follow your organisation’s principle of least privilege
  • Revoke old API keys when they are no longer needed