Breadcrumbs

Troubleshooting Guide

Internet Connectivity Issues

This portion of the guide helps identify whether connectivity issues are caused by basic network problems, DNS resolution failures, or configuration/policies. It applies to both agent-based and resolver-based deployments of EnforceDNS, although certain sections are specific to each.

Client-Side Configurations (Baseline Checks)

Before troubleshooting internet or DNS issues, confirm that the endpoint’s basic configuration is healthy. These checks do not determine how it is deployed — they simply verify that, regardless of deployment mode, the system is using the expected DNS settings and can communicate over required ports.

These baseline checks confirm:

  • If the EnforceDNS Agent is running (when used in your environment).

  • That DNS settings are correctly configured (127.0.0.1 or corporate/EnforceDNS resolvers).

  • That outbound DNS traffic (UDP/TCP 53) is not blocked by local firewalls.

Seeing 127.0.0.1 as the DNS server is only expected if the EnforceDNS Agent is used. In resolver-based deployments, DNS may point directly to EnforceDNS resolvers or corporate DNS.

Why this matters: If these checks fail, later DNS resolution tests will not give meaningful results until configuration issues are corrected.

Step 1: Check if EnforceDNS Agent is Installed/Running (If Used)

Windows (Command Prompt or PowerShell):

sc query "HYAS Protect"

  • STATE: RUNNING → Agent is installed and active.

  • The specified service does not exist → No agent installed (DNS may still be configured to EnforceDNS via network settings).

macOS (Terminal):

launchctl list | grep application.com.hyas

  • Output shows process ID if installed and running.

  • No output means agent not installed.

Step 2: Verify DNS Configuration

Windows (Command Prompt or PowerShell):

ipconfig /all

Check DNS Servers:

  • If 127.0.0.1 → Agent in use.

  • If other addresses (corporate DNS or EnforceDNS resolvers), then EnforceDNS may still be active via network configuration.

macOS (Terminal):

scutil --dns | grep 'nameserver'

  • 127.0.0.1 → Agent in use.

  • Other IPs → Network-level DNS configuration.

If DNS servers show neither 127.0.0.1 nor EnforceDNS resolvers, check for misconfiguration or VPN overrides.

Step 3: Check Firewall Configuration

EnforceDNS requires outbound UDP and TCP port 53 to:

  • 127.0.0.1 (loopback)

  • EnforceDNS upstream resolvers

Blocking either loopback (127.0.0.1) or EnforceDNS resolvers will cause DNS lookups to time out.



Verify Basic Network Connectivity

Before testing DNS, confirm that the device can reach the internet at a basic level. This test bypasses DNS and isolates general connectivity issues such as Wi‑Fi problems, firewall blocks, or routing failures.

Step 1: Ping Test

Open the command line tool and run:

ping 8.8.8.8

This uses Google’s public IP to bypass DNS and confirm raw internet reachability.

  • Windows: Stops after 4 replies.

  • macOS: Press Control + C to stop.

  • Successful replies: Internet is reachable (proceed to DNS tests).

  • Timeouts: General network issue (not DNS-related).

Verify DNS Resolution via EnforceDNS

Step 1: Run DNS Lookup

Run:

nslookup google.com

  • Valid IP returned: DNS functional.

  • NXDOMAIN: May indicate intentional block (policy).

  • Timeout/Server not found: Connectivity or DNS misconfiguration.

Note: If using the agent, Server: 127.0.0.1 is expected. Without the agent, DNS may point to threatER resolvers or corporate DNS servers.

Step 2: Compare with Public DNS (Bypass EnforceDNS)

If DNS resolution fails, you can test whether the issue is specific to EnforceDNS by querying a public resolver (e.g., Google DNS at 8.8.8.8):

nslookup google.com 8.8.8.8

  1. Check the Results

    • If public DNS resolves but EnforceDNS does not:
      EnforceDNS is likely blocking the domain per policy or there’s an issue with the agent’s upstream configuration.

    • If neither EnforceDNS nor public DNS resolves:
      The domain itself may be offline or misconfigured.

If you see timeouts, confirm firewall allows outbound UDP/TCP 53 as described in baseline checks.

NXDOMAIN vs Timeout

  • NXDOMAIN: Intentional block by EnforceDNS.

  • Timeout: Connectivity issue, misconfiguration, or firewall blocking UDP/TCP 53.

Advanced Device Troubleshooting

If DNS tests fail, perform these additional checks:

Toggle EnforceDNS Agent

Temporarily disable or stop the agent.

  • If internet works without agent → Likely EnforceDNS configuration/policy issue

  • If internet still fails → Issue unrelated to EnforceDNS

Test from Another Device

Run ping and nslookup from another device on the same network:

  • Works → Issue is local

  • Fails → Network-wide problem

Clear DNS Cache

Sometimes cached failures can cause persistent errors. To clear the cache, perform the following:

Windows:

ipconfig /flushdns

macOS:

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

VPN Troubleshooting

When a VPN is active, DNS behavior can change significantly. Many VPN clients modify system DNS settings, block traffic to the loopback interface (127.0.0.1), or tunnel all DNS queries through their own resolvers. Because the EnforceDNS Agent relies on 127.0.0.1 for DNS proxying, this can prevent EnforceDNS from functioning as expected.

Common VPN-related issues include:

  • EnforcdDNS being bypassed (DNS no longer goes through 127.0.0.1).

  • DNS queries timing out when VPN is connected.

  • Policy blocks not applying while on VPN.

  • Internet connectivity working without VPN but failing when VPN is active.

Follow the steps below to diagnose and resolve these issues.

Step 1: Check VPN Status

  1. Confirm whether the user is connected to a corporate or third-party VPN.

  2. Temporarily disconnect the VPN and re-run the ping and nslookup tests:

    • If DNS works without VPN but fails with VPN → VPN configuration likely overrides EnforceDNS.

    • If DNS fails both with and without VPN → Issue is unrelated to VPN.

Step 2: Verify DNS Settings While VPN is Active

Windows:

ipconfig /all

macOS:

scutil --dns | grep 'nameserver'

  1. Check if DNS is set to 127.0.0.1:

    1. If not 127.0.0.1 → VPN is forcing DNS through its own resolvers (EnforceDNS bypassed).

    2. If 127.0.0.1 but DNS queries fail → VPN may be blocking loopback traffic or outbound DNS.

Step 3: Determine Split vs Full Tunnel VPN

  1. Full Tunnel VPN: Routes all traffic (including DNS) through VPN → EnforceDNS may not function unless explicitly allowed.

  2. Split Tunnel VPN: Routes only corporate subnets through VPN → EnforceDNS can still operate normally.

Note: If your organization enforces full tunnel, ensure EnforceDNS is deployed on the VPN DNS path or exceptions are configured.

Step 4: Check Firewall or Policy Conflicts

  1. Some VPN clients enforce strict firewall rules that block outbound DNS or loopback traffic.

  2. Ensure UDP/TCP port 53 is allowed to 127.0.0.1 and EnforceDNS upstream resolvers.

Step 5: Test Resolution Using Public DNS (Bypass EnforceDNS)

While connected to VPN, test a public DNS resolver directly:

nslookup google.com 8.8.8.8

  1. If public DNS resolves but EnforceDNS does not: VPN is likely interfering with EnforceDNS’s DNS proxy.

  2. If neither resolves: Connectivity issue may be broader (check VPN connection health).

Step 6: Collect Logs for Escalation

  1. Navigate to EnforceDNS Portal> Organization Settings> EnforceDNS Agent> Manage

  2. Select the device you wish to obtain troubleshooting logs for and select Actions> Run Diagnostics.

  3. The results will be delivered to the Troubleshoot tab under Device Logs Received in approximately 10 minutes.

Important Note:

EnforceDNS requires DNS traffic to use 127.0.0.1. VPNs that override or block this will prevent proper operation.

Split-Horizon DNS Troubleshooting

These scenarios primarily affect internal corporate resources. You can skip this section if troubleshooting public websites.

Split-Horizon DNS (also known as internal/external DNS) is when different DNS answers are returned for the same domain depending on whether the query is made from inside or outside the corporate network. This is common for internal applications (e.g., app.company.com) that resolve to private IP addresses on corporate networks but resolve differently, or not at all, on the public internet.

When EnforceDNS is deployed, DNS traffic is proxied through the local loopback (127.0.0.1) and forwarded to EnforceDNS resolvers. This can cause issues with split-horizon configurations if EnforceDNS is not aware of your internal DNS zones, resulting in failed or incorrect resolution for internal domains.

Common Split-Horizon Symptoms

  • Internal corporate domains fail to resolve (NXDOMAIN) when using EnforceDNS.

  • Internal domains resolve to public IPs instead of internal ones, breaking access to internal services.

  • Internal applications only work when bypassing EnforceDNS or switching networks (e.g., connecting to VPN).

Step 1: Identify the Problem Domains

  1. Determine if the issue occurs only for internal corporate domains (e.g., intranet.company.com) or for public domains as well.

  2. If only internal domains fail → Split-horizon DNS misalignment is likely.

Step 2: Compare DNS Resolution Inside and Outside EnforceDNS

Run the following tests:

Default (EnforceDNS active):

nslookup intranet.company.com

Public DNS (bypass EnforceDNS):

nslookup intranet.company.com 8.8.8.8

Expected Results:

  • Internal domains should resolve to internal/private IP addresses when on corporate network or VPN.

  • If EnforceDNS returns NXDOMAIN or wrong IP while public DNS gives a different result, split-horizon misalignment is confirmed.

Step 3: Test With and Without VPN

  1. Connect to the corporate VPN and re-run the same nslookup tests.

  2. If the domain resolves correctly only when VPN is active:
    Internal DNS zones are only accessible via VPN and may not be configured in EnforceDNS.

  3. If the domain fails both on and off VPN:
    Likely not a split-horizon issue — check general DNS troubleshooting steps.

Step 4: Verify Internal Zone Configuration

  1. Check whether your organization has provided EnforceDNS with internal DNS zone information.

  2. Internal zones may need to be configured or excluded within EnforceDNS policies to avoid public resolution attempts.

Step 5: Temporary Workarounds

  • Temporarily bypass EnforceDNS for internal domains by manually adding internal DNS server IPs to system settings (testing only, not a permanent solution).

  • Confirm if resolution works correctly through corporate DNS directly.

Step 6: Collect Logs for Escalation

  1. Navigate to EnforceDNS Portal> Organization Settings> EnforceDNS Agent> Manage

  2. Select the device you wish to obtain troubleshooting logs for and select Actions> Run Diagnostics.

  3. Results will be delivered to the Troubleshoot tab under Device Logs Received in approximately 10 minutes.

Important Notes

  • EnforceDNS does not automatically detect internal zones. These must be manually configured or exempted by your IT team.

  • Split-horizon DNS problems frequently overlap with VPN troubleshooting. Check if VPN connection resolves the issue.

  • NXDOMAIN responses for internal domains usually indicate EnforceDNS forwarded the query to public DNS rather than an internal server.

Local Domain Troubleshooting

Local-only domains rely on internal name resolution (mDNS/NetBIOS) and are unrelated to public DNS. This section applies only to internal/local resources.

Local domains are custom DNS suffixes or hostnames that exist only within a local network (e.g., printer.local, nas.lan, or dev.company.local). These domains typically resolve through local DNS servers or mDNS/NetBIOS broadcasts, not public DNS. When EnforceDNS is deployed, all DNS queries are proxied through the local loopback (127.0.0.1) and forwarded to EnforceDNS resolvers.

Because EnforceDNS resolvers do not have knowledge of these local-only domains, they may return NXDOMAIN (non-existent domain) or fail to resolve, causing access problems for local resources.

Common Local Domain Symptoms

  • Devices like printers, file shares, or NAS servers become unreachable by hostname after EnforceDNS is installed.

  • Local development domains (*.local, *.lan) fail to resolve or return NXDOMAIN.

  • Internal-only services are accessible by IP address but not by hostname.

Step 1: Identify if the Domain is Local

  1. Determine if the failing domain is local-only:

    1. Check if it ends with .local, .lan, or another internal suffix.

    2. Check if it resolves to a private IP range (e.g., 192.168.x.x, 10.x.x.x, 172.16.x.x).

  2. If the domain does not exist publicly and only resolves internally → local domain issue is likely.

Step 2: Test DNS Resolution with EnforceDNS

Run the following command:

nslookup printer.local

Expected Result:

  • If EnforceDNS is unaware of the local domain, you may see:

** server can't find printer.local: NXDOMAIN


Step 3: Compare with Local DNS or IP

Try resolving using the device’s IP directly to confirm the service is reachable (this is an example IP only):

ping 192.168.1.50

If the IP works but hostname does not, the issue is strictly DNS-related, likely local domain resolution.

Step 4: Check DNS Configuration

Local domains typically require resolution via internal/local DNS servers or mDNS:

  1. Confirm whether your organization has configured search domains or conditional forwarding for local zones in EnforceDNS.

  2. If not configured, EnforceDNS will forward these queries to public DNS and fail.

Step 5: Workarounds for Testing

  1. Temporarily bypass EnforceDNS for local domains:

    1. Add local DNS server IPs manually to system DNS configuration (testing only).

  2. Alternatively, add the hostname and IP to the local hosts file (not recommended for permanent fix).

Step 6: Collect Logs for Escalation

  1. Navigate to EnforceDNS Portal> Organization Settings> Protect Agent> Manage

  2. Select the device you wish to obtain troubleshooting logs for and select Actions> Run Diagnostics.

  3. Results will be delivered to the Troubleshoot tab under Device Logs Received in approximately 10 minutes.

Important Notes

  • EnforceDNS resolvers do not handle .local or private DNS zones automatically; these must be configured or exempted by IT.

  • mDNS (multicast DNS) and NetBIOS-based name resolution are not forwarded by EnforceDNS and may require local network configuration.

  • This issue is distinct from split-horizon DNS: local domains are not public at all, while split-horizon domains are public but resolve differently internally.

Generate Troubleshooting Logs

If problems persist, generate logs for EnforceDNS support:

  1. Navigate to EnforceDNS Portal> Organization Settings> EnforceDNS Agent> Manage

  2. Select the device you wish to obtain troubleshooting logs for and select Actions> Run Diagnostics.

  3. Results will be delivered to the Troubleshoot tab under Device Logs Received in approximately 10 minutes.

Step 1: Determine if the Issue is General or DNS-Specific

First, verify whether the connectivity problem affects all websites or only specific ones.

  1. Open the Command Line Tool:

    1. Windows: Press Windows + R, type cmd, and press Enter.
      (Alternatively, search for "Command Prompt" in the Start menu.)

    2. macOS: Press Command + Space, type Terminal, and press Enter.

  2. Run the Ping Command:

    1. In the window that opens, type:

      1. ping 8.8.8.8

    2. On Windows, it will automatically stop after 4 replies.

    3. On macOS, it will keep running until you stop it with Control + C.

  3. Check the Results:

    1. If you see replies like this, you have basic internet connectivity:

      1. Windows:

        1. Reply from 8.8.8.8: bytes=32 time=14ms TTL=117

      2. macOS:

        1. 64 bytes from 8.8.8.8: icmp_seq=0 ttl=117 time=14.1 ms

    2. If you see timeouts, your device may be offline or blocked from reaching the internet:

      1. Windows:

        1. Request timed out.

      2. macOS:

        1. Request timeout for icmp_seq 0
Step 2: Test DNS Resolution with EnforceDNS

If the ping test succeeds, test whether DNS resolution via EnforceDNS is working. The EnforceDNS Agent uses a local DNS proxy (127.0.0.1) to forward queries to EnforceDNS resolvers.

  1. Open the Command Line Tool:

    1. Windows: Press Windows + R, type cmd, and press Enter.
      (Alternatively, search for “Command Prompt” in the Start menu.)

    2. macOS: Press Command + Space, type Terminal, and press Enter.

  2. Run the Nslookup Command:

    1. In the window that opens, type:

      1. nslookup google.com

    2. On Windows or macOS, this queries your configured DNS server (should be EnforceDNS if properly configured).

  3. Check the Results:

    1. If you see a valid IP address, DNS resolution is working:

      1. Example (Windows/macOS):

        1. Server:  127.0.0.1
Address: 127.0.0.1#53

Non-authoritative answer:
Name:    google.com
Address: 142.250.72.14

      2. Note: Seeing 127.0.0.1 as the server is expected with the EnforceDNS Agent, because it proxies DNS through the local loopback address.

      3. Important: EnforceDNS resolvers do not respond to ICMP (ping) requests. Use nslookup or dig to test DNS resolution — do not attempt to ping the actual resolvers directly.

    2. If you see an NXDOMAIN or non-existent domain message, it may indicate blocking:

      1. EnforceDNS may return NXDOMAIN (no such domain) if the site is blocked by policy.

        1. Example:

          1. ** server can't find examplemalware.com: NXDOMAIN

    3. If you see “Timed out” or “Server not found,” DNS is not responding:

      1. Could be misconfiguration or inability to reach EnforceDNS resolvers.

        1. Example:

          1. DNS request timed out.
timeout was 2 seconds.

            1. This indicates the EnforceDNS Agent cannot reach upstream DNS servers or is misconfigured. Check network connectivity or restart the agent.

Step 3: Confirm DNS Settings

Verify that your system is correctly pointing to the EnforceDNS Agent (loopback):

Windows:

ipconfig /all

  • Look for 127.0.0.1 under DNS Servers.

macOS:

scutil --dns | grep 'nameserver'

  • Confirm the DNS server shows 127.0.0.1.

Step 4: Additional Troubleshooting

If DNS still fails after the above steps, perform deeper troubleshooting:

  1. Enable/Disable the Agent

    1. Temporarily disable EnforceDNS (or stop the service) and re-test connectivity.

    2. If internet works without the agent: The issue is likely within EnforceDNS configuration or policy.

    3. If internet still fails without the agent: Problem is unrelated to EnforceDNS (check network/firewall).

  2. Test from Outside the Device

    1. From another device on the same network, perform the same ping and DNS tests.

    2. If other devices work: Issue is local to the original machine.

    3. If other devices fail too: Check upstream network/firewall settings.

  3. Firewall and Outbound DNS

    1. Ensure your firewall allows outbound DNS queries (UDP/TCP port 53) to EnforceDNS resolvers.

    2. Blocking outbound DNS will cause timeouts during nslookup.

  4. Collect Logs for Escalation

    1. Navigate to the EnforceDNS Portal> Organization Settings> EnforceDNS Agent> Manage.

    2. Select the device you wish to obtain troubleshooting logs for and select Actions> Run Diagnostics.

    3. Diagnostics will populate in the Troubleshoot tab under Device Logs Received in approximately 10 minutes.

EnforceDNS Agent Troubleshooting

For issues related to specific agents, please refer to the corresponding Agent Troubleshooting Guide below.

macOS

Windows