> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threataware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DNS Filter

> Connect ThreatAware to DNS Filter for DNS security and filtering data

## 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.

<Info>
  **Connection Method**: API
  **Setup Time**: 10 minutes
  **Access Required**: DNS Filter Administrator account
</Info>

## 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

<CardGroup cols={2}>
  <Card title="DNS Security Monitoring" icon="shield">
    Monitor DNS-based threats and blocked malicious domains
  </Card>

  <Card title="Filtering Policy Validation" icon="filter">
    Verify DNS filtering policies are enforced across devices
  </Card>

  <Card title="Threat Detection" icon="triangle-exclamation">
    Detect DNS-based threats and suspicious domain access attempts
  </Card>

  <Card title="Compliance Reporting" icon="clipboard-check">
    Generate reports showing DNS security coverage and incidents
  </Card>
</CardGroup>

## Setup instructions

<Steps>
  <Step title="Access DNSFilter Dashboard">
    Log in to the [DNSFilter Dashboard](https://app.dnsfilter.com) using an account with administrator privileges.
  </Step>

  <Step title="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
  </Step>

  <Step title="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

    <Info>
      Only grant the minimum permissions necessary for ThreatAware to function
    </Info>
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>
</Steps>

## Required credentials

<AccordionGroup>
  <Accordion title="API Key" icon="lock">
    **Field Name**: DNSFilter API Key
    **Type**: Password (encrypted)
    **Description**: The API key generated in DNSFilter for ThreatAware integration

    This key provides access to DNS filtering and security data from DNSFilter.

    <Tip>
      Store this credential securely in your organisation's password manager
    </Tip>
  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="Invalid API Key Error" icon="triangle-exclamation">
    **Symptoms**: Integration status shows authentication failure

    **Solutions**:

    * 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
  </Accordion>

  <Accordion title="Permission Issues" icon="ban">
    **Symptoms**: Connection succeeds but no DNS filtering data appears

    **Solutions**:

    * Verify the API key has read permissions to DNS filtering data
    * Check the [DNSFilter API Documentation](https://docs.dnsfilter.com) 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
  </Accordion>

  <Accordion title="Connection Timeout" icon="clock">
    **Symptoms**: Integration fails to connect or times out

    **Solutions**:

    * 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
  </Accordion>

  <Accordion title="No Data After 10 Minutes" icon="database">
    **Symptoms**: Integration shows active but no DNS filtering data appears

    **Solutions**:

    * 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
  </Accordion>

  <Accordion title="API Rate Limiting" icon="tachometer-alt">
    **Symptoms**: Integration works initially but stops syncing data

    **Solutions**:

    * 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
  </Accordion>
</AccordionGroup>

## Additional resources

<CardGroup cols={2}>
  <Card title="DNSFilter API Documentation" icon="book" href="https://docs.dnsfilter.com">
    Official DNSFilter API documentation for detailed API information
  </Card>

  <Card title="ThreatAware Support" icon="life-ring" href="mailto:help@threataware.com">
    Contact ThreatAware support for integration assistance
  </Card>
</CardGroup>

## Best practices

<Tip>
  **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
</Tip>

<Tip>
  **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
</Tip>