Endpoint Agent Deployment Guide

Deploying the DNS Armor™ Endpoint Agent on Windows, macOS, and Linux: requirements, API key setup, silent install, GPO and MDM mass deployment, and verification.

Complete Deployment and Configuration Guide for IT Professionals and Security Teams

1. Introduction#

This section outlines the deployment and configuration procedures for implementing the DNS Armor™ Endpoint Agent, part of the DNS Armor™ Protect (DNS Firewall) product family. The Endpoint Agent extends Protect's DNS protection to individual devices by securely routing DNS traffic through the Protect cloud, enforcing security policies, and ensuring consistent threat protection regardless of network location. It provides visibility, control, and protection for roaming and remote endpoints, maintaining the same security standards as on-premises environments.

1.1 Document Purpose#

This deployment guide provides step-by-step instructions for installing, configuring, and validating the DNS Armor™ Endpoint Agent. The guide covers:

• Complete installation and registration process
• Policy synchronization and enforcement behaviour from the Protect cloud platform
• Validation and monitoring procedures to ensure proper functionality and protection

1.2 Intended Audience#

This guide is designed for technical professionals responsible for deploying and managing DNS security on endpoint devices within their organization:

• Network Administrators – Managing DNS configurations and ensuring secure name resolution
• Security Engineers – Implementing and monitoring Protect security policies for endpoint protection
• IT Support Teams – Handling installation, troubleshooting, and maintenance of the endpoint agent
• System Administrators – Integrating the agent with directory services and endpoint management tools

ℹ️ Note: Readers should have a working knowledge of DNS concepts, endpoint configuration, network security principles, and familiarity with Windows or macOS administration.

2. Solution Overview#

DNS Armor™ Protect (DNS Firewall) provides comprehensive protection against DNS-based threats for both on-premise and remote users. The DNS Armor™ Endpoint Agent extends this protection to individual devices, ensuring secure DNS resolution even when users are outside the corporate network.

The agent acts as a lightweight client that enforces DNS security policies locally on the endpoint, forwarding DNS queries securely to the Protect cloud for inspection and policy enforcement. This approach provides consistent threat protection, visibility, and control across all user environments whether on internal networks, public Wi-Fi, or mobile connections.

2.1 Query Processing Flow#

• Client DNS queries are directed to Cloud platform
• Cloud platform applies security policies and threat intelligence
• Safe responses are returned to clients; malicious queries are blocked
• All actions are logged in the cloud portal

2.2 DNS Armor™ Endpoint Agent – Traffic Flow Overview#

When the DNS Armor™ Endpoint Agent is deployed on a user's device, it operates as a lightweight local DNS forwarder, enforcing DNS security policies to ensure consistent protection both inside and outside the corporate network.

It automatically detects VPN and split-tunnel configurations, to ensure accurate and secure DNS resolution for both internal and external domains.

2.2.1 Traffic Flow Description#

DNS Interception

The agent intercepts all DNS queries generated by the operating system or applications.

Split-Tunnel Awareness (VPN Detection)

When a VPN connection is active, the agent automatically detects split-tunnel configurations and classifies DNS queries accordingly:

• Internal domains defined within the VPN split-tunnel settings are forwarded through the VPN tunnel to the organization's Local Resolver.
• External or internet-bound domains (not covered by the split-tunnel routes) are securely forwarded to the Protect cloud security platform for inspection.

Policy Enforcement & Threat Detection

• For external queries, the Protect cloud applies real-time threat detection, domain categorization, and policy enforcement to block malicious or restricted domains.
• For internal queries, resolutions occur locally to ensure low latency and secure access to internal resources.

Threat Analysis & Logging

• Every query processed by the cloud is analyzed using AI-based threat intelligence to detect DNS tunneling, C2 communication, and other suspicious activity.
• All events are logged and visible in the DNS Armor™ management portal for monitoring and reporting.

Response Handling

• Allowed domains receive their valid IP addresses.
• Blocked or suspicious domains are redirected or denied per security policies.

Continuous Protection

• The agent ensures unified protection and consistent policy enforcement, regardless of the user's location whether connected to the corporate LAN, a public Wi-Fi, or a home network.
• It fully supports split DNS tunneling, VPN, and Zero Trust Network Access (ZTNA) integrations for seamless operation.

Business Continuity

The system ensures continuous DNS service availability:

• Automatic failover to local DNS infrastructure during cloud connectivity disruptions

3. Pre-Deployment Planning#

3.1 Pre-Implementation#

Before deploying the DNS Armor™ Endpoint Agent, ensure proper preparation to guarantee smooth installation and integration with your environment. The following section outlines key planning considerations for successful implementation.

3.1.1 Access and Credentials#

• DNS Armor™ portal access: https://dnsarmor.secure-domains.org
• Portal administrator credentials validated
• API code creation permissions verified (Administration → API Keys)

ℹ️ Note for self-service accounts: On self-service (Self-Signed) accounts, endpoint enrollment capacity comes from your plan's seats — one seat corresponds to one enrolled device, and Education & Library seats carry a device multiplier. See the Self-Service Guide for plan seats and subscription management.

3.1.2 Environmental Assessment#

• Confirm supported operating systems (Windows, macOS, Linux).
• Verify outbound DNS and HTTPS connectivity to the DNS Armor™ Protect (DNS Firewall) cloud.

3.2 System Requirements#

3.2.1 Supported Operating Systems#

DNS Armor™ Endpoint Agent supports multiple operating systems, including Windows, macOS, and Linux. Ensure the following system requirements are met before deployment.

Windows System Requirements

Supported Versions: Windows 10, 11 and Windows Server 2019, 2022

macOS System Requirements

Supported Versions: macOS 11 Big Sur and later

Linux System Requirements

Supported Versions: Ubuntu 20.04 LTS and later, Debian 11 and later

ℹ️ NOTE: For the latest supported versions and system requirements, refer to the DNS Armor™ portal download page.

3.3 Network Requirements#

3.3.1 Required Network Flows#

The following network flows must be permitted for proper endpoint agent operation. Ensure your firewall and network security policies allow outbound connectivity for the destinations listed below.

Priority Definitions

• Critical: Required for core agent functionality. Blocking these flows will prevent the agent from operating correctly.
• Conditional: Required only when specific features are enabled (e.g., VPN split-tunnel bypass).

⚠️ IMPORTANT: Network security appliances and firewalls must support Server Name Indication (SNI) inspection for TLS-based traffic filtering. Due to the dynamic nature of cloud service IP addresses, firewall rules that rely solely on IP-based filtering may be insufficient and could result in connectivity failures. Ensure your security infrastructure is configured to permit traffic based on SNI/FQDN rules for the TLS destinations listed above.

Before proceeding with installation, verify that all critical network flows are permitted and connectivity to the required destinations has been validated.

4. Installation and Configuration#

4.1 Portal Access#

Before beginning installation, verify access to the DNS Armor™ management portal:

• Navigate to: https://dnsarmor.secure-domains.org
• Log in with your administrative credentials
• Verify you have permissions to access the Administration section and, under DNS Firewall, the Security and Monitoring sections

ℹ️ NOTE: If you do not have portal access, contact your DNS Armor™ administrator or support@secure-domains.org to request credentials.

4.2 Endpoint Agent Download#

Download the appropriate Agent for your Environment:

1. Log in to DNS Armor™ portal: https://dnsarmor.secure-domains.org
2. Navigate to: Administration → Downloads and open the Endpoint Agent tab
3. Select the Agent matching your environment:
   • Windows: Download
   • macOS: Download
   • Linux (Ubuntu/Debian): Download
4. Click Download and save the file

ℹ️ NOTE: Mobile protection for iPhone & iPad and Android & Chromebook devices is delivered through the Apple App Store (iPhone & iPad, iOS 16.0 or later) and Google Play (Android & Chromebook, Android 7.0 or later); links are available on the same Endpoint Agent tab.

✅ BEST PRACTICE: Download the latest available version to ensure you have the most recent security updates and feature enhancements.

4.3 API Key Configuration#

The API code (API key) authenticates the Agent with the cloud portal and enables policy synchronization:

1. Log in to the DNS Armor™ portal: https://dnsarmor.secure-domains.org
2. Navigate to: Administration → API Keys (the API Codes page)
3. Click Create API Code

ℹ️ NOTE: Each tenant can hold up to 3 API codes for operational flexibility and key rotation.

1. Select the customer (or reseller) and the tenant, then click Create API Code
2. Copy the displayed API code immediately

⚠️ CRITICAL: The full API code is displayed only once — afterwards only its last 4 characters remain visible in the portal. Store it securely in your password management system. If lost, you must reset the code with the Reset action or create a new one; resetting immediately invalidates the old code on every device using it.

1. Create a new Notepad file and rename it "API-code"
2. Paste the generated API code into the Notepad file and save it

Ensure that both the Endpoint Agent installer and the "API-Code" Notepad file are located in the same folder before proceeding with the installation.

4.4 Install the Endpoint Agent#

Follow the steps below to install the DNS Armor™ Endpoint Agent on supported operating systems:

4.4.1 Locate Installation Files#

1. Ensure both the Endpoint Agent installer and the API-code Notepad file are in the same folder.
2. Double-click the DNS Armor™ Endpoint Agent setup file.
3. When prompted, allow the installer to run with administrator privileges.
4. Follow the on-screen instructions in the setup wizard.
5. The installer will automatically detect the API code from the API-code file for registration.
6. Once installation is completed, the agent will register with the DNS Armor™ cloud portal using the provided API code.

4.5 Mass Deployment#

The DNS Armor™ Endpoint Agent supports enterprise-scale deployment using various automated distribution methods, enabling IT administrators to deploy the agent across multiple endpoints efficiently.

4.5.1 Deployment Methods#

The agent can be deployed through multiple enterprise management platforms:

• Mobile Device Management (MDM) – Deploy via MDM solutions such as Microsoft Intune, Jamf, or Workspace ONE
• Group Policy Object (GPO) – Deploy through Active Directory Group Policy for Windows environments
• Configuration Management Tools – Use tools like SCCM, Ansible, Puppet, or Chef for automated deployment
• Scripted Deployment – Custom PowerShell or Bash scripts for flexible deployment scenarios

4.5.2 Silent Installation Command-Line Options#

The installer supports silent installation with the following command-line arguments:

API Key Configuration Methods

The API code can be provided using either of the following methods:

• API-code.txt file: Place a text file named API-code.txt containing the API code in the same folder as the installer
• /API command argument: Pass the API code directly as a command-line parameter using /API=<api-code>

Command-Line Arguments

• /S – Silent installation mode (no user interface)
• /API=<api-code> – Specify the API code for agent registration
• /PATH="<custom-path>" – (Optional) Set custom installation path. Default: C:\Program Files (x86)\Secure Domains\DNS Armor

Installation Examples

Basic silent installation with API code:

DNS-Armor-Setup.exe /S /API=<api-code>

Silent installation with custom path:

DNS-Armor-Setup.exe /S /API=<api-code> /PATH="C:\Custom\Install\Path"

ℹ️ NOTE: For mass deployment, ensure the API code is securely managed and distributed according to your organization's security policies.

4.6 Verification#

• Confirm that the agent appears with an Online (or Connected-Enabled) status in the portal under DNS Firewall → Monitoring → Endpoints
• Set the endpoint's Admin Status to Enabled using the Enable Admin Status action in the endpoint row's Actions menu

ℹ️ NOTE: If the tenant has a security policy with auto-enrollment enabled, newly registered endpoints are enabled and added to that policy automatically (see Section 5.1.2), so enabling Admin Status manually is not needed.

5. Policy Configuration#

5.1 Endpoint Agent Policy Configuration#

Security policies define how DNS Armor™ Protect (DNS Firewall) handles the DNS traffic of your endpoints. To configure policies for the Endpoint Agent:

5.1.1 Log in to the Cloud Portal#

URL: https://dnsarmor.secure-domains.org

5.1.2 Create Security Policies#

Navigate to: DNS Firewall → Security → Cloud Policies (page title: Security Policies) and click Create Policy. The creation wizard walks through four steps: Tenant Info, Basic Settings, Mapping, and Security Rules.

Configure the following:

Tenant Selection (Tenant Info step)

Tenant → Select the customer (or reseller) and the tenant.

Policy Name (Basic Settings step)

Policy Name → Specify a clear and descriptive name for the policy

Policy Status

Policy Status (Basic Settings step) → Set to Enabled to activate the policy.

Time-Based Activation (Optional)

Policies are enforced 24/7 by default. In the Basic Settings step, enable Time Based Activation to restrict enforcement to a schedule:

• Timezone: Choose your local timezone or UTC
• Date Range: (Optional) Define start/end dates
• Time Range: Define start/end times (e.g., 08:00-18:00)
• Active Days: Select specific weekdays

Select Endpoints (Mapping step)

Select Endpoints → Choose the endpoints on which you want to apply and enforce the security policy.

Optionally enable Auto-enroll new endpoints into this policy: any new endpoint registering with the tenant's API code is automatically enabled and added to this policy. Only one policy per tenant may have auto-enrollment turned on.

5.1.3 Configure Security Rules#

In the Security Rules step, select the protections the policy enforces:

Threats

Select the threat categories to block, for example:

• Malware Domains: Block known malware command & control servers
• Phishing Sites: Block credential harvesting and phishing domains
• Ransomware C2: Block ransomware communication channels
• Cryptomining: Block cryptojacking and unauthorized mining
• Botnets: Block botnet command & control infrastructure

ℹ️ NOTE: DNS Armor™ maintains over 10 million threat indicators updated continuously from global threat intelligence sources. External RPZ feeds (external RPZ sources managed under DNS Firewall → Security → Automated Feeds) can also be selected in the same step.

AI Threat Detection

• Enable Advanced AI Threat Detection to add AI-powered rules to the policy sequence: AI Tunneling Detection (DNS-tunneling data exfiltration), AI FastFlux Detection (fast-flux domains), and AI Infiltration Detection (infiltration attacks)
• AI-based analysis detects anomalous DNS query patterns and data exfiltration attempts
• Blocks unauthorized covert channels over DNS protocol
• On self-service plans this capability requires DNS Armor Protect Advanced

Web and App Filtering

Attach Web Filters and Apps to block access by website category or application and enforce acceptable use policies.

Typical categories include:

• Adult/Pornography
• Gambling
• Drugs/Illegal Substances
• Weapons
• Hate Speech
• Social Media (optional)
• Streaming Media (optional)
• Gaming (optional)
• Productivity/Business (allow list)

Override Settings

Policy Mode sets how matches are handled: Blocking (matches are actively blocked) or Logging (matches are logged only, not blocked — monitoring mode).

The Override Action replaces the per-rule action for every match in the policy:

• Default: Apply each rule's own configured action
• NXDOMAIN: Block by returning a domain-not-found response
• DROP: Silently drop the query
• PASS-THRU: Permit query to proceed
• Redirect: Redirect matched queries to a specified domain or IP (e.g., a block page)

Rule Priority Order: rules within the policy are applied top-to-bottom — drag rules to change priority; rules at the top have higher precedence.

Click Create Policy to finalize.

5.2 Local Rulesets (Optional)#

• Navigate to DNS Firewall → Security → Rulesets and click Create Local Ruleset.
• Create custom rulesets to act as Access Control Lists (ACLs).
• Use them to explicitly allow or block specific domains or IPs (per-rule actions include PASSTHRU, NXDOMAIN, DROP, and Redirect to a domain or IP).
• Rule types: Domain Match (wildcards such as *.example.com supported), IP Match (CIDR), and PTR (Reverse DNS).
• Example: Always allow or block a particular domain.
• Exclusive Allowlist mode blocks all DNS queries except those explicitly allowed in the ruleset.
• Attach rulesets to security policies in the Security Rules step for additional control.
• Verify the Rule Priority Order in the policy (drag rulesets to reorder) to ensure rules are applied as intended.

6. Monitoring and Validation#

To make sure your deployment is running smoothly, you can monitor the Endpoint Agent from the Cloud Portal.

6.1 Endpoint Monitoring#

Navigate to: DNS Firewall → Monitoring → Endpoints

The Endpoints page provides dashboard cards summarizing total registered endpoints, connection status breakdown, Admin Status, tenant distribution, and agent versions. The endpoint table lists each device with its tenant, public and private IP, MAC address, identity, type, connection status (Online, Offline, Connected-Enabled, Connected-Disabled, Disconnected, Requires Update), Admin Status (Enabled/Disabled), and last-seen time; connection status is derived from the endpoint's last-seen heartbeat. Endpoints can be enabled/disabled or deleted individually or in bulk. Search and filters apply across the full dataset, results can be exported to CSV, and an auto-refresh interval keeps the view current.

ℹ️ NOTE: An endpoint that is assigned to a security policy cannot be deleted; the portal reports that the endpoint is associated with a security policy. Remove the endpoint from the policy first (DNS Firewall → Security → Cloud Policies → edit the policy → Mapping step), then delete it.

END OF DOCUMENT

DNS Armor™ Endpoint Agent Deployment Guide

v2.1 · July 2026

© 2026 Secure Domains - All Rights Reserved

For technical support: support@secure-domains.org
Portal: https://dnsarmor.secure-domains.org
Documentation: https://www.secure-domains.org/documentation