Local Resolver Guide

Deploying the DNS Armor™ Local Resolver appliance: ESXi, Hyper-V and KVM install, proxy and local modes, Active Directory, high availability, SIEM logging, and monitoring.

Comprehensive Deployment Guide — DNS Armor™ Protect (DNS Firewall)

1. Introduction#

This document provides comprehensive deployment procedures for implementing DNS Armor™ Protect (DNS Firewall) Local Resolver functionality within your DNS security infrastructure. The Local Resolver component serves as an intelligent intermediary that manages DNS query routing, applies security policies, enforces threat protection, and optimizes resolution performance while maintaining seamless integration with your existing network infrastructure.

1.1 Document Purpose#

This deployment guide provides step-by-step instructions for installing, configuring, and validating the Protect Local Resolver in both DNS Forward Proxy (DFP) and Local Resolver operating modes. The guide covers:

• Complete installation procedures from VM deployment to production cutover
• Detailed policy configuration for both operating modes
• Active Directory integration for identity-based logging
• High availability deployment architecture
• Comprehensive validation and troubleshooting procedures

1.2 Intended Audience#

This guide is designed for technical professionals responsible for DNS security infrastructure:

• Network Administrators - Responsible for DNS infrastructure and routing
• Security Engineers - Managing DNS security policies and threat protection
• IT Infrastructure Teams - Deploying and maintaining virtualized systems
• System Administrators - Overseeing Active Directory and logging infrastructure

Prerequisites: Readers should have working knowledge of DNS concepts, virtualization platforms, network security principles, and basic Linux command-line operations.

1.3 Document Conventions#

Throughout this document, the following conventions are used:

⚠️ CRITICAL Actions that could cause service disruption if not performed correctly

⚡ IMPORTANT Key information that affects security or functionality

ℹ️ NOTE Additional context or helpful information

✅ BEST PRACTICE Recommended approach based on field experience

💡 TIP Optimization suggestions or shortcuts

2. Solution Overview#

DNS Armor™ Protect (DNS Firewall) provides flexible deployment options to protect corporate networks and roaming users from DNS-based threats through comprehensive inspection, filtering, and threat intelligence. The Local Resolver brings Protect on-premises and supports two distinct deployment models, each optimized for specific organizational requirements.

2.1 Core Services#

2.1.1 DNS Proxy Service#

The DNS Proxy service provides secure DNS query forwarding with the following capabilities:

• Secure Transport: Forwards DNS communications using DNS over HTTPS (DoH) protocol, ensuring encrypted transmission of queries to the Protect cloud infrastructure
• Threat Protection: Applies comprehensive threat intelligence and security filtering to all DNS traffic
• Internal Domain Support: Maintains full compatibility with internal domain resolution through configurable bypass lists
• High Performance: Optimized query handling supporting up to 300,000 queries per second (QPS) with appropriate hardware

2.1.2 Local DNS Firewall#

The Local DNS Firewall enables on-premises security enforcement with these features:

• Local Inspection: Performs DNS security filtering and AI-based threat detection locally without forwarding traffic to the cloud
• Compliance Support: Ensures data sovereignty and supports environments with strict compliance requirements
• Bidirectional Synchronization: Maintains two-way exchange of DNS logs and security intelligence with cloud infrastructure for centralized visibility
• Statistical Analysis: Provides aggregated analytics across both cloud and on-premises deployments

2.1.3 Active Directory Connector#

The Active Directory Connector enriches DNS logs with identity information:

• User Attribution: Retrieves username and domain information from Active Directory for comprehensive audit trails
• Enhanced Visibility: Maps IP addresses to specific users for identity-based reporting and investigation
• Real-time Integration: Processes Windows Security Event logs (Event ID 4624) in real-time
• Syslog Transport: Receives authentication events via secure syslog over TLS on TCP port 6514

ℹ️ NOTE AD Connector functionality is available in both Local Resolver and DNS Forward Proxy modes.

2.1.4 Cloud Logs Connector#

The Cloud Logs Connector facilitates external log integration:

• Log Retrieval: Retrieves DNS query and firewall logs from the Protect platform
• Three Log Streams: Ships DNS firewall (RPZ) events, DNS query logs, and portal audit logs as three distinct syslog streams
• CEF over Syslog: Every record is a standards-compliant ArcSight CEF message carried in an RFC 3164 syslog envelope on facility local4, identified as Secure Domains | Logs Connector | 1.0.0
• SIEM Support: CEF is ingested natively by ArcSight, Microsoft Sentinel, and Elastic; ready-made onboarding templates for Splunk and QRadar are provided in Appendix D
• Compliance Logging: Ensures audit log retention for regulatory compliance requirements

2.2 Operating Modes#

The Protect Local Resolver supports two distinct operating modes, each designed for specific deployment scenarios and organizational requirements.

2.2.1 Local Resolver Proxy Mode#

Operational Model

In Local Resolver Proxy mode, the Local Resolver VM acts as a forwarding agent that transmits DNS queries to the Protect cloud platform for inspection and policy enforcement.

Key Characteristics

• Cloud-Based Policy Enforcement: All security policies are configured, managed, and enforced in the cloud portal
• Centralized Management: Policy updates are immediately effective without local configuration changes
• Scalability: Leverages cloud infrastructure for inspection capacity
• Reduced Local Resources: Lower memory requirements compared to Local Mode

Query Processing Flow

1. Client DNS queries are directed to Local Resolver VM (via DHCP or static configuration)
2. Internal domains (bypass list) are forwarded directly to local DNS servers
3. External queries are encrypted via DoH and sent to the Protect cloud
4. Cloud platform applies security policies and threat intelligence
5. Safe responses are returned to clients; malicious queries are blocked
6. All actions are logged in the cloud portal

Ideal Use Cases

• Organizations prioritizing centralized policy management
• Environments with reliable internet connectivity
• Deployments requiring minimal local resource allocation
• Multi-site deployments with consistent policy enforcement

2.2.2 Local Resolver Mode#

Operational Model

In Local Resolver mode, the VM performs all DNS inspection, filtering, and policy enforcement locally on-premises, with optional cloud synchronization for visibility and management.

Key Characteristics

• Local Policy Enforcement: Security policies are pushed from the cloud but executed locally on the VM
• Data Sovereignty: All DNS queries and logs are processed and stored on local VM disk
• Reduced Cloud Dependency: Maintains operation during internet connectivity disruptions
• Higher Resource Requirements: Requires additional memory for local threat intelligence databases

Query Processing Flow

1. Client DNS queries are directed to Local Resolver VM
2. Internal domains (bypass list) are forwarded directly to local DNS servers
3. External queries are inspected locally using on-premises threat intelligence
4. Local firewall engine applies security policies and blocks threats
5. Clean queries are forwarded to configured DNS forwarders
6. Logs are optionally synchronized to cloud for centralized reporting

Ideal Use Cases

• Organizations with compliance requirements for data sovereignty
• Environments requiring continued DNS security during internet outages
• Deployments in regions with high latency to cloud services
• Organizations preferring local control of security enforcement

2.3 Traffic Flow Architecture#

2.3.1 Proxy Mode Traffic Flow#

Phase 1: Cloud Connectivity Validation

The Local Resolver VM performs continuous health checks with the Protect cloud infrastructure:

• Scheduled connectivity verification ensures service availability
• Regular configuration synchronization maintains consistent security posture
• Automatic service failover based on connectivity status

Phase 2: DNS Query Routing

Client endpoints are configured to use the Local Resolver as their primary DNS server:

• DHCP Option 6: Dynamic IP environments receive DNS server configuration automatically
• Group Policy Objects (GPO): Static DNS configuration deployed via Active Directory
• Manual Configuration: Individual workstations configured with Local Resolver IP address

Phase 3: Query Classification and Processing

The Local Resolver classifies queries based on destination:

• Internal Domains: Queries matching bypass domain list are forwarded directly to authorized corporate DNS servers without inspection
• External Domains: Internet-destined queries are encrypted using DoH protocol and transmitted to Protect cloud services

Phase 4: Cloud Security Processing

The Protect cloud platform performs comprehensive security analysis:

• Real-time threat intelligence lookup across 10+ million indicators
• Category-based filtering (malware, phishing, inappropriate content)
• AI-powered DNS tunneling detection
• Policy enforcement based on organizational security requirements

Phase 5: Business Continuity

The system ensures continuous DNS service availability:

• Automatic failover to local DNS infrastructure during cloud connectivity disruptions
• High availability configuration through multiple Local Resolver deployments
• Graceful degradation maintains core DNS functionality

2.3.2 Local Mode Traffic Flow#

Phase 1: Endpoint Configuration

Client devices are configured via standard DNS server assignment methods:

• DHCP Option 6 designates Local Resolver as primary DNS server
• Secondary DNS server configured for failover (additional Local Resolver or corporate DNS)
• Centralized DNS traffic management through local infrastructure

Phase 2: Query Classification

The Local Resolver categorizes incoming DNS queries:

• Local DNS Queries: Requests for internal domains routed directly to designated bypass DNS servers without inspection
• External DNS Queries: Internet-bound queries subjected to local security filtering

Phase 3: Local Security Processing

On-premises DNS firewall performs comprehensive inspection:

• AI-based threat detection analyzes query patterns for anomalies
• Real-time policy enforcement without cloud dependency
• Local threat intelligence database provides malware and phishing protection
• Category-based filtering applied according to configured policies

Phase 4: DNS Resolution

Following security inspection, queries are resolved:

• Clean queries forwarded to configured DNS forwarders (ISP resolvers, public DNS providers, or upstream corporate DNS)
• Blocked queries return NXDOMAIN or configured block page IP
• All actions logged locally with optional cloud synchronization

Phase 5: Log Synchronization

DNS and security logs are managed according to configuration:

• Local storage on VM disk for immediate access
• Optional cloud upload for centralized reporting and analytics
• External syslog export for SIEM integration

3. Pre-Deployment Planning#

3.1 Pre-Implementation Checklist#

Complete the following checklist before beginning deployment to ensure a smooth implementation:

Access and Credentials#

• DNS Armor™ Protect (DNS Firewall) portal access confirmed: https://dnsarmor.secure-domains.org
• Portal administrator credentials validated
• API key generation permissions verified (Administration → API Keys)

Network Infrastructure#

• Target IP address for Local Resolver VM identified
• Network subnet and gateway information documented
• DNS forwarder IP addresses identified (ISP or public DNS)
• Internal DNS server IP addresses documented
• Firewall rules approved for required connectivity (see Section 3.3.2)

Domain and Policy Planning#

• Internal domain list compiled (domains to bypass inspection)
• Private network ranges/subnets documented
• External/public IP addresses identified (for DFP mode)
• DNS security policies defined (block categories, threat feeds)
• Policy enforcement schedule determined (24/7 or time-based)

Virtualization Platform#

• Hypervisor platform confirmed (VMware/Hyper-V/KVM)
• VM resource allocation approved (CPU, Memory, Disk per sizing table)
• Datastore/storage with 250GB available space identified
• Virtual network/VLAN configuration prepared

Active Directory Integration (if applicable)#

• Domain Controllers identified for log forwarding
• Log forwarding tool selected (NXLog recommended)
• Firewall rules approved for DC-to-Resolver syslog (TCP 6514)
• Event log permissions verified

High Availability Planning (if applicable)#

• Number of Local Resolver VMs determined (minimum 2 recommended)
• Load balancer evaluated (optional, DNS client failover sufficient)
• Failover testing plan documented

Integration and Logging#

• External syslog/SIEM server identified (if required)
• Syslog connectivity and port confirmed
• Log retention requirements documented
• NTP server identified for time synchronization

Change Management#

• Change control ticket approved
• Implementation maintenance window scheduled
• Rollback plan documented
• Stakeholder communication completed
• Pilot user group identified for initial testing

✅ BEST PRACTICE Schedule deployment during a maintenance window to allow adequate time for testing and validation before production cutover.

3.2 System Requirements#

3.2.1 Supported Hypervisors#

The Protect Local Resolver VM is compatible with the following virtualization platforms:

• VMware ESXi: Version 6.5 or higher
• Microsoft Hyper-V: Windows Server 2016 or higher with Hyper-V role enabled
• KVM/QEMU: Version 2.0 or higher
• Other: Any hypervisor supporting standard OVA/VMDK formats

3.2.2 Resource Requirements - Local Mode#

Local Resolver mode requires higher memory allocation to maintain local threat intelligence databases and perform on-premises inspection.

Terminology

• QPS: Queries Per Second - the number of DNS queries the system can process
• CHR: Cache Hit Rate - percentage of queries answered from cache (95% is typical)

Sizing Guideline

💡 TIP Quick Calculation: Approximately every 5 IP addresses will generate 1 QPS on average. For example, a network with 500 IPs typically generates ~100 QPS baseline load.

⚡ IMPORTANT Resource requirements assume 95% cache hit rate. Environments with lower cache hit rates may require additional resources.

3.2.3 Resource Requirements - Proxy Mode#

DNS Forward Proxy mode has lower memory requirements since security inspection occurs in the cloud.

✅ BEST PRACTICE Start with 8 vCPU configuration for typical deployments. Scale up or down based on actual usage patterns observed during pilot phase.

Disk Space Allocation

• Operating System: ~20 GB
• Log Storage: 180-200 GB (retention period depends on query volume)
• Threat Intelligence: ~5GB (Local Mode only)
• System Overhead: 10 GB reserved

3.3 Network Requirements#

Each Local Resolver VM requires two network interfaces:

• eth0 — Management: web UI (HTTPS 443) and SSH (TCP 22) access, and communication with hosts in the eth0 subnet
• eth1 — DNS and Internet: listens for client DNS queries and carries all internet-bound traffic (Protect Cloud, threat feeds, DNS forwarders); the default gateway is configured on eth1

ℹ️ NOTE All internet-bound communication happens on eth1. Traffic to hosts in the same subnet as eth0 uses eth0; all other traffic uses eth1.

3.3.1 Required Connectivity#

The Local Resolver VM requires network connectivity to various systems depending on enabled features:

Mandatory Connectivity

• Management API (HTTPS 443 to api.secure-domains.org and api-dev.secure-domains.org) - for management, policy synchronization and health checks
• Protect Cloud assigned IPs (HTTPS 443) - for DoH query forwarding (Proxy Mode only)
• Threat feed distribution (HTTPS 443 to 2ffa7d66f51860e0ce53f4154c49c787.r2.cloudflarestorage.com) - for threat-intelligence feed and update downloads
• Internal DNS servers (DNS 53) - for bypass domain resolution
• DNS clients (DNS 53) - for receiving queries from endpoints

Optional Connectivity

• Domain Controllers (Syslog/TLS 6514) - for Active Directory integration
• External syslog/SIEM servers (varies) - for log forwarding
• NTP servers (NTP 123) - for time synchronization
• Internet DNS servers (DNS 53, any destination) - Local Mode with recursion
• DNS Forwarders (DNS 53) - Local Mode with custom forwarders (ISP or public DNS servers)

3.3.2 Firewall Rules#

Configure the following firewall rules to permit required traffic flows. All rules should be documented in your firewall change request. Where the Local Resolver VM is the source or destination, the interface that carries the flow is shown in brackets (see Section 3.3). The Mode column shows whether a rule applies to Proxy Mode, Local Mode, or both.

* Protect Cloud IP addresses are assigned to your organization upon account creation.
† eth0 when the other host is in the same subnet as eth0; eth1 otherwise.

⚠️ CRITICAL Failure to permit the AD Event Logs rule (Domain Controllers → Local Resolver VM eth1, TCP 6514) will prevent Active Directory integration. Ensure this rule is in place before attempting AD configuration.

3.4 Information Gathering Worksheet#

Complete the following worksheet during planning phase. This information will be required during deployment.

VM Network Configuration#

Local Resolver Hostname: ___________________________
eth0 (Management) IP Address: ___________________________
eth0 Subnet Mask: ___________________________
eth1 (DNS & Internet) IP Address: ___________________________
eth1 Subnet Mask: ___________________________
Default Gateway (eth1): ___________________________
Primary DNS (for VM itself): ___________________________
Secondary DNS (for VM itself): ___________________________

DNS Infrastructure#

Internal DNS Server 1: ___________________________
Internal DNS Server 2: ___________________________
DNS Forwarder 1: ___________________________
DNS Forwarder 2: ___________________________

Bypass Domains (Internal)#

Domain 1: ___________________________
Domain 2: ___________________________
Domain 3: ___________________________
(Add additional as needed)

Private Network Subnets#

Subnet 1: ___________________________ (e.g., 192.168.1.0/24)
Subnet 2: ___________________________ (e.g., 10.0.0.0/16)
Subnet 3: ___________________________

External/Public IP Addresses (DFP Mode)#

Public IP 1: ___________________________ (NAT address)
Public IP 2: ___________________________

Active Directory Integration#

Domain Controller 1: ___________________________
Domain Controller 2: ___________________________
AD Domain Name: ___________________________

External Logging (Optional)#

SIEM/Syslog Server: ___________________________
Syslog Port: ___________________________
Syslog Protocol: UDP / TCP / TLS
Syslog Facility (default local4): ___________________________
SIEM Platform (for Appendix D templates): ArcSight / Sentinel / Splunk / QRadar / Elastic / Other

High Availability (Optional)#

Secondary Local Resolver IP: ___________________________
Tertiary Local Resolver IP: ___________________________
Load Balancer VIP (if used): ___________________________

Section 4: Installation & Configuration

4. Installation and Configuration#

4.1 Pre-Installation Preparation#

4.1.1 Portal Access#

Before beginning VM deployment, verify access to the DNS Armor™ Protect (DNS Firewall) management portal:

1. Navigate to: https://dnsarmor.secure-domains.org
2. Log in with your administrative credentials
3. Verify you have permissions to access Administration and DNS Firewall sections (Setup, Security, Monitoring)

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

4.1.2 Environment Assessment#

Review your completed Information Gathering Worksheet (Section 3.4) and verify all required information is available:

• Network configuration details (IP, subnet, gateway)
• DNS server addresses (internal and forwarders)
• Internal domain bypass list
• Subnet ranges for policy application
• Firewall rule approval documentation

4.1.3 VM Image Download#

Download the appropriate VM image for your hypervisor platform:

1. Log in to the Protect portal: https://dnsarmor.secure-domains.org
2. Navigate to: Administration → Downloads and open the Local Resolver tab
3. Select the VM model matching your environment:
   • VMware ESXi: Download OVA format (VMware OVA — for VMware ESXi & VirtualBox)
   • Microsoft Hyper-V: Download VHD/VHDX format (Microsoft VHD — for Hyper-V & Azure)
   • KVM/QEMU: Download QCOW2 format (OpenStack QCOW2 — for KVM & OpenStack)
4. Click Download and save the file to a location accessible from your hypervisor management console
5. Verify the downloaded file integrity using the provided checksum (if available)

ℹ️ NOTE The same tab offers the Local Resolver MIB file (SNMP monitoring definitions) for import into network management systems such as PRTG, Nagios, Zabbix, or SolarWinds.

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

4.2 Virtual Machine Deployment#

4.2.1 VM Creation#

Deploy the Protect Local Resolver VM according to your hypervisor platform:

VMware ESXi

1. Open vSphere Client or vCenter
2. Right-click on destination host/cluster and select Deploy OVF Template
3. Select the downloaded OVA file
4. Provide a name for the VM (e.g., "DNS-Armor-Resolver-01")
5. Select the destination datastore (ensure 250 GB available space)
6. Select the appropriate network/VLAN for the VM
7. Assign CPU and memory resources per sizing table (Section 3.2)
8. Review settings and click Finish to deploy

Microsoft Hyper-V

1. Open Hyper-V Manager
2. Click New → Virtual Machine
3. Specify name and location for VM files
4. Select Generation 2 (UEFI) or Generation 1 (BIOS) based on image
5. Assign memory per sizing table (enable Dynamic Memory if desired)
6. Configure networking (connect to appropriate virtual switch)
7. Select Use an existing virtual hard disk and browse to downloaded VHD/VHDX
8. Assign CPU count per sizing table
9. Complete wizard and verify settings

KVM/QEMU

1. Copy QCOW2 image to appropriate storage location
2. Create new VM using virt-manager or command line:

virt-install \
  --name dns-armor-resolver-01 \
  --memory 32768 \
  --vcpus 4 \
  --disk /path/to/dns-armor.qcow2 \
  --network bridge=br0 \
  --graphics vnc \
  --os-type linux \
  --import

Adjust memory and CPU values per sizing table

⚡ IMPORTANT Do not start the VM until you have verified network configuration and confirmed the VM is connected to the correct VLAN.

4.2.2 Initial Boot and Login#

Power on the newly deployed VM and access the console:

1. Start the VM through your hypervisor management interface
2. Wait for the boot process to complete (typically 2-3 minutes)
3. The login prompt will appear on the console

Default Credentials

• Username: admin
• Password: secure-domains

⚠️ CRITICAL You must change the default password immediately after initial login. Failure to do so represents a significant security vulnerability.

ℹ️ NOTE Initial login occurs via the VM console. Web interface access will be configured in subsequent steps.

4.2.3 Network Configuration#

Configure the network settings for the Local Resolver VM. The VM has two interfaces: eth0 (Management) and eth1 (DNS and Internet); see Section 3.3.

Option 1: DHCP Configuration (Not Recommended for Production)

If your environment uses DHCP and you want the VM to obtain an IP address automatically:

• The VM will attempt DHCP on both interfaces (eth0 and eth1) on boot
• Verify the addresses assigned to eth0 and eth1 using: ip addr show
• Proceed to Section 4.2.4

✅ BEST PRACTICE Use static IP configuration for production DNS servers to ensure consistent endpoint configuration.

Option 2: Static IP Configuration (Recommended)

To manually configure networking:

1. From the VM console, execute the networking configuration script:

sudo ./set_networking

2. The script runs as a guided wizard: it configures eth0 (Management) first, then eth1 (DNS and Internet), then the DNS servers the VM itself uses:

[Step 1 of 3] eth0 - Management interface
Enter eth0 IP Address: [Management IP, e.g., 192.168.100.10]
Enter eth0 Subnet Mask: [e.g., 255.255.255.0]

[Step 2 of 3] eth1 - DNS and Internet interface
Enter eth1 IP Address: [DNS listening IP that clients will use, e.g., 10.10.20.10]
Enter eth1 Subnet Mask: [e.g., 255.255.255.0]
Enter eth1 Default Gateway: [e.g., 10.10.20.1]

[Step 3 of 3] DNS servers for the VM itself
Enter Primary DNS: [e.g., 10.10.20.1]
Enter Secondary DNS (optional): [press Enter to skip]

3. Review the configuration summary for both interfaces
4. Confirm to apply settings
5. Wait for network service to restart (10-15 seconds)
6. Verify both interfaces and network connectivity (internet-bound traffic leaves through eth1):

ip addr show eth0
ip addr show eth1
ping 8.8.8.8
ping dnsarmor.secure-domains.org

⚡ IMPORTANT The DNS servers configured here are used BY the Local Resolver VM itself for management connectivity. They are NOT the DNS forwarders used for client queries.

ℹ️ NOTE No default gateway is set on eth0: it only reaches hosts in its own subnet (administrator workstations, and any Domain Controllers, internal DNS, NTP or SIEM servers in that subnet). All other traffic, including all internet-bound traffic, uses eth1 (see Section 3.3).

4.2.4 Web Interface Access#

The Local Resolver VM provides a web-based management interface for configuration and monitoring:

1. From an administrator workstation, open a web browser
2. Navigate to the eth0 (Management) address: https://[LOCAL_RESOLVER_ETH0_IP] (e.g., https://192.168.100.10)
3. Accept the self-signed certificate warning (you may add this to trusted certificates)
4. The DNS Armor™ Local Resolver login page will appear

Login Credentials

• Username: admin
• Password: secure-domains (unless already changed in console)

5. Click Login to access the dashboard

ℹ️ NOTE The web interface uses HTTPS on port 443. Ensure firewall rules permit access from administrator workstations to the eth0 (management) interface.

Dashboard Overview

Upon successful login, the Dashboard tab displays:

• System Resources: Real-time CPU, memory, and disk utilization graphs
• Service Status: Status of core services (DNS Proxy, Firewall, AD Connector)
• Quick Statistics: Current query rate, cache hit rate, blocked queries

ℹ️ NOTE The System Configuration section will only display complete information after portal setup is completed in Section 4.2.5.

4.2.5 System Setup Configuration#

The System Setup section establishes the connection between the Local Resolver VM and the Protect cloud management portal.

4.2.5.1 API Key Configuration

The API key authenticates the Local Resolver with the cloud portal and enables policy synchronization:

1. In the Local Resolver web interface, navigate to: System Setup tab
2. Locate the API Key field (currently empty)

3. Open a new browser tab and log in to the Protect portal: https://dnsarmor.secure-domains.org
4. Navigate to: Administration → API Keys (the page itself is titled API Codes)
5. Click Create API Code
6. Select the customer (or reseller) and tenant this Local Resolver belongs to and confirm
7. Copy the displayed API code immediately using the copy-to-clipboard button

⚠️ 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, use Reset API Code on the API Codes page to generate a replacement (this immediately invalidates the current code).

8. Return to the Local Resolver web interface
9. Paste the API code into the API Key field
10. The key will be masked for security after saving

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

4.2.5.2 Unique Identifier Configuration

The Unique Identifier is a customer-defined label that associates this Local Resolver with policies in the cloud portal:

1. In the Unique Identifier field, enter a meaningful identifier
   • Example: "SITE-NYC-RESOLVER-01"
   • Example: "HQ-DNS-PRIMARY"
2. Use letters, numbers, hyphens, and underscores only (no spaces)
3. This identifier must match exactly when creating policies in the portal

⚡ IMPORTANT The Unique Identifier is case-sensitive and must be entered identically in the cloud portal policy configuration.

4. Click Save to commit the API Key and Unique Identifier
5. The system will validate connectivity to the cloud portal
6. A success message confirms successful registration
7. The Dashboard will now display synchronized configuration details

✅ BEST PRACTICE Use a consistent naming convention for Unique Identifiers across your organization (e.g., SITE-LOCATION-FUNCTION-INSTANCE).

4.2.6 Log Processing Configuration#

Configure log processing and synchronization settings:

Navigate to: System Setup → Log Processing & Sync section

Log Synchronization Options

Option 1: Send All Historical Logs (Default)

• Sends all DNS and firewall logs from the beginning of Local Resolver operation
• Use this option for new deployments to ensure complete log visibility
• Initial sync may take time depending on query volume

Option 2: Custom Start Date

• Begin log processing from a specific date/time
• Useful for phased deployments or when historical data is not required
• Select date using the date picker control

External Syslog Configuration (Optional)

To forward logs to an external syslog server or SIEM:

1. Enable Send Logs to External Syslog Server
2. Enter the following details:
   • Syslog Server IP/Hostname: Destination syslog server
   • Port: Typically 514 (UDP), 1514 (TCP), or 6514 (TLS)
   • Protocol: Select UDP, TCP, or TLS based on server requirements
   • Format: Select syslog framing — RFC 3164 (default) or RFC 5424 (keeps the year and millisecond precision in the timestamp)
3. Click Test Connection to verify connectivity
4. Click Save to apply configuration

What the Resolver Sends

Every forwarded record is a standards-compliant ArcSight CEF message carried in a syslog envelope:

<166>Aug  5 00:14:07 secure-domains-local-resolver dns-rpz: CEF:0|Secure Domains|Logs Connector|1.0.0|1001|DNS RPZ|7|rt=… dhost=… src=… cs4Label=TenantName cs4=…

• Facility: local4 by default, so the default PRI is <166> (facility local4 = 20 × 8 + severity info = 6). Point any collector-side facility filter at local4.
• Syslog severity: deliberately fixed at info for every record. Per-event severity lives in the CEF header's 7th field (7 for RPZ, 2 for query, 5 for audit) — that is where every SIEM reads it. If the syslog severity also varied, a collector filtering on local4.info would silently drop the high-severity RPZ records, which are exactly the events you most want.
• Source identity: the CEF header carries Secure Domains | Logs Connector | 1.0.0. SIEMs key parser and log-source selection on this vendor + product pair — it is a stable contract and will not change.

Log Streams

Three independent streams are shipped, distinguished by the syslog TAG and the CEF SignatureID:

The complete field-by-field schema, byte-exact sample records, parsing rules, and ready-made onboarding templates for ArcSight, Microsoft Sentinel, Splunk, QRadar, and Elastic are provided in Appendix D: SIEM Integration Pack.

⚡ IMPORTANT Prefer TCP, TLS, or RELP transport. RPZ records run ~650 bytes and can exceed the 1024-byte practical limit for RFC 3164 over UDP; truncation is silent, and a truncated CEF record fails to parse at all.

✅ BEST PRACTICE Use syslog over TLS (port 6514) when transmitting logs across untrusted networks to ensure log confidentiality and integrity.

4.2.7 Network Settings#

Review and configure network settings for the Local Resolver:

Navigate to: Network tab

IP Address Configuration

• Displays the currently configured IP addresses of the Local Resolver's eth0 and eth1 interfaces
• To modify, use the console-based set_networking script (Section 4.2.3)

DNS Forwarders

DNS forwarders are the upstream DNS servers that will receive queries after security inspection:

• Local Mode: Queries are forwarded here after local inspection
• Proxy Mode: This setting is typically not used (queries go to cloud)

Common DNS Forwarder Options

• ISP DNS Servers: Use your internet service provider's resolvers
• Public DNS: Google (8.8.8.8, 8.8.4.4), Cloudflare (1.1.1.1), Quad9 (9.9.9.9)
• Corporate DNS: Upstream internal DNS servers
• Protect Cloud Resolvers: For an additional layer of cloud-based protection

1. Enter Primary DNS Forwarder IP address
2. Enter Secondary DNS Forwarder IP address (recommended)
3. Click Save to apply configuration

⚡ IMPORTANT DNS forwarders must be reachable from the Local Resolver VM. Verify firewall rules permit outbound DNS (port 53) to these servers.

4.2.8 Time Synchronization (NTP)#

Accurate time synchronization is critical for log correlation, certificate validation, and troubleshooting:

Navigate to: NTP tab

Importance of NTP Configuration

• Log Timestamps: Ensures accurate chronological ordering of events
• Certificate Validation: SSL/TLS certificates are time-sensitive
• Policy Scheduling: Time-based policies require accurate system time
• Forensic Analysis: Correlate events across multiple systems
• Cloud Synchronization: Prevents sync issues due to time drift

Recommended NTP Servers

Public NTP Servers

• time.google.com - Google Public NTP
• pool.ntp.org - NTP Pool Project
• time.nist.gov - US NIST Time Service
• time.windows.com - Microsoft Time Service

Internal NTP Servers

• Your Domain Controllers (if configured as time sources)
• Dedicated internal NTP appliances
• Network device NTP services

Configuration Steps

1. Click Add NTP Server
2. Enter NTP server hostname or IP address
3. Repeat to add additional servers (3-4 recommended for redundancy)
4. Click Save Changes
5. Verify synchronization status shows "Synced" after 1-2 minutes

✅ BEST PRACTICE Configure at least 3 NTP servers for redundancy. Mix internal and external sources to ensure continued synchronization during internet outages.

4.2.9 Password Management#

Change the default administrative password to secure the Local Resolver:

Navigate to: Password tab

⚠️ CRITICAL Changing the default password is mandatory for production deployment. Default credentials are publicly documented and represent a critical security vulnerability.

Password Requirements

• Minimum 12 characters (16+ recommended)
• Include uppercase and lowercase letters
• Include numbers
• Include special characters
• Do not reuse passwords from other systems
• Do not use common dictionary words

Change Password Procedure

1. Enter current password: secure-domains (if not yet changed)
2. Enter new password meeting complexity requirements
3. Confirm new password by entering it again
4. Click Change Password
5. You will be logged out automatically
6. Log back in with the new credentials to verify

✅ BEST PRACTICE Store the new password in your organization's password management system (e.g., HashiCorp Vault, LastPass Enterprise, 1Password). Do not store passwords in plain text documentation.

💡 TIP Consider implementing password rotation every 90 days and ensure multiple administrators have access through your password management system.

4.3 Policy Configuration - Local Resolver Mode#

Local Resolver mode performs DNS security inspection and policy enforcement locally on the VM. Policies are configured in the cloud portal and synchronized to the Local Resolver for local execution.

4.3.1 Private Network Creation#

Private networks define internal IP subnets where DNS security policies will be applied. This enables subnet-level policy control.

1. Log in to the Protect portal: https://dnsarmor.secure-domains.org
2. Navigate to: DNS Firewall → Setup → Networks and select the Private Networks tab
3. Click Create Network

4. Configure the private network:
   • Customer / Tenant: Select the customer (or reseller) and tenant this network belongs to (multi-tenant environments)
   • Network Description: Descriptive name (e.g., "Corporate-LAN", "Guest-WiFi")
   • Network Address(es): IP subnet(s) in CIDR notation, entered one per line or comma-separated; IPv4 and IPv6 are both supported and may be mixed in a single submission (e.g., 192.168.1.0/24, 10.0.0.0/16, 2001:db8::/32)

5. Click Create Private Network to save
6. Repeat for additional network segments requiring different policies

Use Case Examples

• Corporate-Workstations (192.168.10.0/24): Standard user security policies
• Guest-Network (192.168.99.0/24): Restrictive policies, limited access
• IT-Department (192.168.20.0/24): Relaxed policies for technical staff
• Lab-Environment (10.50.0.0/16): Custom policies for development/testing

ℹ️ NOTE External networks are not used in Local Resolver mode. External networks define public IP addresses and are only relevant for DNS Forward Proxy mode.

⚡ IMPORTANT Networks that are in use cannot be deleted. The portal refuses to delete a private network that is attached to a security policy or referenced by a Local Resolver network feed mapping, and shows a clear error naming the policies or resolvers that use it. Remove those references first, then delete the network.

4.3.2 Local Resolver Policy Creation#

Create the primary Local Resolver policy that defines operational parameters:

1. Navigate to: DNS Firewall → Setup → Local Resolvers
2. Click Create Local Resolver

Step 1: Operating Mode Selection

1. In the Resolver Mode section, select Local Resolver

ℹ️ NOTE Local Resolver mode enforces policies locally on the VM. Configuration is managed in the cloud portal but execution occurs on-premises.

Step 2: Policy Details

1. Configure basic policy settings:

• Customer / Tenant: Select the customer and tenant this configuration applies to
• Unique Identifier: Enter the EXACT identifier configured on the Local Resolver VM (Section 4.2.5.2)
  • This identifier links the policy to the specific VM
  • Must match exactly (case-sensitive)
  • Example: "SITE-NYC-RESOLVER-01"

⚠️ CRITICAL If the Unique Identifier does not match exactly, the policy will not be pushed to the Local Resolver and security enforcement will not function.

2. Click Next to proceed through the remaining wizard steps (Network & Security, Feed Management, Advanced Settings)

4.3.3 Bypass Domain Configuration#

Bypass domains are internal domains that should be resolved directly by local DNS servers without security inspection:

Bypass Domains

1. In the Bypass Domains section, add internal domains:
   • Domain Format: Enter fully qualified domain names or parent domains
   • Examples:
     • corp.local - All hosts within corp.local domain
     • internal.company.com - All hosts within internal.company.com domain
     • dc01.corp.local - Specific domain controller
     • lab.local - Test/development environment
2. Enter each internal domain on its own line (one domain per line)
3. Review the bypass list for completeness

💡 TIP Bypass domains can be defined inline for this resolver (Define Inline) or linked to a shared bypass configuration (Link to Bypass Config) managed centrally under DNS Firewall → Setup → Bypass Domains. Use a shared configuration when multiple resolvers need the same internal domain list.

Bypass DNS Servers

1. Configure DNS servers that will resolve bypass domains:
   • Server 1: Primary internal DNS server (e.g., Domain Controller)
   • Server 2: Secondary internal DNS server (recommended)
   • Examples:
     • 192.168.1.10 - Primary Domain Controller
     • 192.168.1.11 - Secondary Domain Controller

⚡ IMPORTANT Bypass DNS servers must be reachable from the Local Resolver VM. These are typically your Domain Controllers or internal DNS infrastructure.

Syslog Configuration (Optional)

1. If forwarding logs to external SIEM/syslog server:
   • Syslog Server: IP address or hostname of log collector
   • Syslog Port: Standard ports (514 UDP, 1514 TCP, 6514 TLS)
   • Protocol: Select UDP, TCP, or TLS (prefer TCP/TLS — RPZ records can exceed the 1024-byte RFC 3164 UDP limit)
   • Format: RFC 3164 (default) or RFC 5424 (keeps year and millisecond precision)

ℹ️ NOTE Records are shipped as ArcSight CEF on facility local4 across three streams (DNS RPZ 1001, DNS Query 1002, Audit 1003). See Section 4.2.6 for the format overview and Appendix D for the field reference and SIEM onboarding templates.

✅ BEST PRACTICE Use syslog over TLS (port 6514) to protect log confidentiality during transmission.

4.3.4 DNS Forwarder Configuration#

DNS forwarders are the upstream servers where clean DNS queries are sent after local security inspection:

1. In the DNS Forwarders (Local Mode) section, click Add Forwarder and enter the IP address of each upstream DNS server (at least two recommended for redundancy)

ℹ️ NOTE Alternatively, enable Enable DNS Recursion to let the resolver perform full recursive resolution itself; when DNS Recursion is disabled, at least one DNS forwarder is required. DNSSEC validation of upstream answers can be turned on with Enable DNSSEC Validation.

Common Forwarder Options

• ISP DNS: Your internet service provider's resolvers
• Public DNS: 8.8.8.8 (Google), 1.1.1.1 (Cloudflare), 9.9.9.9 (Quad9)
• Corporate Upstream: Existing corporate DNS infrastructure
• Protect Cloud: For an additional cloud-based protection layer

2. Click Next to proceed to feed management

4.3.5 Network Feed Mappings and Inspection Rules#

Network Feed Mappings define which security policies apply to which network segments:

Create Network Feed Mapping

1. In the Network Feed Mappings section, click Add Network Mapping
2. Select Private Network:
   • Select the private network (subnet) where this mapping applies
   • Multiple mappings can be created for different subnets
   • Toggle Network Enabled / Network Disabled and (optionally) Use ECS per mapping
3. Enforcement Mode: Choose how matches are handled for this network:
   • Blocking: Matches are actively blocked
   • Logging: Matches are logged only, not blocked (monitoring mode)
4. Override Action: Default (each rule/ruleset applies its own action) or Redirect to a specified Redirect Domain / IP (block page). Per-rule actions come from attached Local Rulesets: NXDOMAIN (Block), DROP, PASSTHRU (Allow), REDIRECT
5. Assign protection feeds to the mapping (each attached feed appears in the Feed Priority Order list for this network, where it can be dragged to reorder it):

Threat Feeds

The Threats feed category protects against, among others:

• 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 Protect maintains over 10 million threat indicators updated continuously from global threat intelligence sources.

DNS Tunneling Protection

• Enable Advanced AI Threat Detection for this Network to identify data exfiltration attempts
• AI-based analysis detects DNS tunneling, fast-flux domains, and infiltration attacks — enabling it automatically applies the AI Tunneling Detection, AI FastFlux Detection, and AI Infiltration Detection feeds
• Blocks unauthorized covert channels over DNS protocol

Web Filters (URL Category Filtering)

• Assign Web Filters to block access by website category (e.g., Adult Content, Gambling, Malware)
• Enforce acceptable use policies
• Categories include:
  • Adult/Pornography
  • Gambling
  • Drugs/Illegal Substances
  • Weapons
  • Hate Speech
  • Social Media (optional)
  • Streaming Media (optional)
  • Gaming (optional)
  • Productivity/Business (allow list)

Additional feed types available per mapping: Apps (application blocking), Geo Filtering, External RPZ feeds (managed under DNS Firewall → Security → Automated Feeds), Local Rulesets, and Exclusive Allowlist (blocks every query except domains explicitly allowed in the selected ruleset).

6. Schedule Settings (Optional):

Define when enforcement is active:

• Always active: 24/7 enforcement (default)
• Time-based activation: Restrict enforcement to specific weekdays and time ranges (e.g., 08:00-18:00, Mon-Fri). Use the Quick Presets — Business Hours (Mon-Fri, 09:00-17:00 UTC), Weekdays (Mon-Fri, all day), Weekends (Sat-Sun, all day) — or choose custom Active Days and an Active Time Range (UTC), with an optional Date Range

Example Schedules

• Block social media during business hours (Mon-Fri 09:00-17:00 UTC)
• Relaxed policies during weekends
• Enhanced monitoring during off-hours

Custom Domain Overrides (Optional)

Override category classifications for specific domains using rulesets:

• Allow rules (Local Ruleset, action PASSTHRU): Allow a domain despite a category block
  • Example: Allow linkedin.com even if social media blocked
• Block rules (Local Ruleset, action NXDOMAIN / DROP / REDIRECT): Block a domain despite a category allow
  • Example: Block specific gambling site not in feeds
• Exclusive Allowlist: Block all DNS queries except those explicitly allowed in the selected ruleset

See Section 4.3.7 for creating rulesets.

Feed Priority Order

⚡ IMPORTANT Feeds attached to a network are evaluated in order. Use drag-and-drop (or the Move to top / Move to bottom buttons) in the Feed Priority Order for this Network list to reorder them:

• More specific feeds/rulesets should be higher
• Broad feeds should be lower
• Allow (PASSTHRU) rulesets should precede block rulesets
• Use ruleset allow rules for specific exceptions rather than disabling entire feeds
• Keep broad category filtering in place and manage exceptions per domain
• When an Exclusive Allowlist is active, other feeds and the override action for that mapping are disabled — everything not explicitly allowed is blocked

Click Next to proceed to additional services

4.3.6 Active Directory Connector and Cloud Logs#

Configure optional services for enhanced visibility in the Advanced Settings step:

Active Directory Connector

Enable Active Directory integration to enrich logs with user identity information:

1. Check Enable Active Directory Connector
2. This enables the Local Resolver to receive Windows authentication logs
3. Configuration details are covered in Section 5 (Active Directory Integration)

Benefits of AD Integration

• Map IP addresses to usernames in DNS logs
• Identify which users accessed blocked or suspicious domains
• Support identity-based policy enforcement (future)
• Enhance forensic investigation capabilities

Cloud Logs Upload

Enable log synchronization to the Protect cloud portal:

1. Check Enable Cloud Logs Upload (available in Local Resolver mode only)
2. Configures automatic upload of DNS and firewall logs to cloud
3. Enables centralized reporting across multiple Local Resolvers
4. Provides access to cloud-based analytics and dashboards

Benefits of Cloud Log Upload

• Centralized visibility across all Local Resolver deployments
• Cloud-based reporting and analytics
• Long-term log retention in cloud storage
• Cross-site threat correlation
• Backup copy of logs for disaster recovery

💡 TIP Enable both AD Connector and Cloud Logs Upload for maximum visibility and forensic capability.

3. Click Create Local Resolver to finalize the configuration
4. The policy will be automatically pushed to the Local Resolver VM within 60 seconds
5. Verify policy synchronization in the VM web interface (Dashboard → System Configuration)

4.3.7 Local Rulesets (Optional)#

Local Rulesets provide Access Control List (ACL) functionality for granular domain and IP control:

Navigate to: DNS Firewall → Security → Rulesets

Use Cases for Rulesets

• Allow list: Always allow specific domains/IPs regardless of category
• Block list: Always block specific domains/IPs regardless of policy
• Custom Control: Organization-specific domain management
• Compliance: Enforce regulatory requirements for specific domains

Create Ruleset

1. Click Create Local Ruleset
2. Select the customer (or reseller) and tenant, then provide a descriptive Name (no spaces; e.g., "Corporate-Allowlist", "Executive-Bypass")

3. Add Rules:
   • Rule Type: Domain Match Rule (wildcards such as *.example.com supported), IP Match Rule (CIDR), or PTR (Reverse DNS) Rule
   • Domain: Enter domain name or wildcard pattern (for IP rules, the IP subnet(s) or address(es); multiple values comma-separated)
     • Example: example.com
     • Example: *.partner-company.com
   • Action: Select Allow or Block — PASSTHRU (Allow), NXDOMAIN (Block), DROP, or REDIRECT (to a domain/IP)
4. Click Add Rule for each entry
5. Review the rules for completeness
6. Optionally enable Exclusive Allowlist Mode — all DNS traffic is blocked except the domains/IPs explicitly allowed in this ruleset (all rules are forced to PASSTHRU (Allow), and you set the Default Block Action for everything else)
7. Click Create Ruleset

Attach Ruleset to Resolver Configuration

1. Navigate to: DNS Firewall → Setup → Local Resolvers
2. Edit the previously created Local Resolver
3. In the Network Feed Mappings section, attach the ruleset (feed type Local Rulesets, or Exclusive Allowlist) and position it in the Feed Priority Order
4. Save changes

⚡ IMPORTANT Rulesets are evaluated according to the feed priority order. Allow (PASSTHRU) entries positioned ahead of block feeds will override category/threat blocks.

✅ BEST PRACTICE Document the business justification for each allow entry for audit purposes.

ℹ️ NOTE A ruleset that is attached to a Local Resolver or security policy cannot be deleted — the portal blocks the deletion and lists the resolvers or policies using it. Detach it first.

4.4 Policy Configuration - DNS Forward Proxy Mode#

DNS Forward Proxy mode forwards DNS queries to the Protect cloud platform for inspection and policy enforcement. All security processing occurs in the cloud.

4.4.1 Network Creation (Private and External)#

DNS Forward Proxy mode requires both Private and External network definitions:

Create Private Networks

Private networks define internal client subnets (similar to Local Mode):

1. Navigate to: DNS Firewall → Setup → Networks and select the Private Networks tab
2. Click Create Network

Configure network details:

• Customer / Tenant: Select the customer (or reseller) and tenant this network belongs to
• Network Description: Descriptive name (e.g., "Office-Network")
• Network Address(es): Internal subnet(s) in CIDR notation (e.g., 192.168.1.0/24), one per line or comma-separated; IPv4 and IPv6 may be mixed

Click Create Private Network

Create External Networks

External networks define the public/NAT IP addresses from which the cloud receives DNS queries:

1. Navigate to: DNS Firewall → Setup → Networks and select the External Networks tab
2. Click Create Network

3. Configure network details:
   • Customer / Tenant: Select the customer (or reseller) and tenant this network belongs to
   • Network Description: Source location or site identifier (e.g., "Office-Public-IP")
   • Network Address(es): Public IP address or CIDR range, one per line or comma-separated
     • Example: 203.0.113.45 (single public IP)
     • Example: 203.0.113.0/24 (IP range)

Click Create External Network

ℹ️ NOTE External networks identify queries by source IP. If your organization has multiple sites with different public IPs, create separate external networks for each.

⚡ IMPORTANT An external network that is attached to a security policy cannot be deleted — the portal blocks the deletion with a clear error naming the policies that use it. If the network is activated for RPZ, de-activate it first. Detach it from those policies, then delete it.

4.4.2 Forward Proxy Policy Creation#

Create the DNS Forward Proxy policy:

1. Navigate to: DNS Firewall → Setup → Local Resolvers
2. Click Create Local Resolver

Step 1: Operating Mode Selection

1. In the Resolver Mode section, select DNS Forward Proxy

ℹ️ NOTE In DNS Forward Proxy mode, the Local Resolver VM acts as a forwarding agent. All inspection and policy enforcement occurs in the Protect cloud.

Step 2: Policy Details

1. Configure policy settings:

• Customer / Tenant: Select the appropriate customer and tenant
• Unique Identifier: Enter EXACT identifier from Local Resolver VM
  • Must match value configured in Section 4.2.5.2
  • Case-sensitive

Click Next

4.4.3 Bypass and Syslog Configuration#

Bypass Domains

Configure internal domains to bypass cloud inspection:

1. Add internal domains in Bypass Domains section:
   • Format: domain.local, internal.corp.com
   • These domains are resolved by Bypass DNS Servers
2. Bypass DNS Servers: Enter internal DNS server IP addresses
   • Typically Domain Controllers

Syslog Configuration (Optional)

1. Configure external syslog forwarding if required:
   • Syslog Server: External log collector IP/hostname
   • Port: Syslog port (514, 1514, 6514)
   • Protocol: UDP, TCP, or TLS (prefer TCP/TLS — RPZ records can exceed the 1024-byte RFC 3164 UDP limit)
2. Click Next

ℹ️ NOTE Records are shipped as ArcSight CEF on facility local4 across three streams (DNS RPZ 1001, DNS Query 1002, Audit 1003). See Section 4.2.6 for the format overview and Appendix D for the field reference and SIEM onboarding templates.

Network Feed Mappings (Not Used in Proxy Mode)

Network Feed Mappings are only applicable in Local Resolver mode. In DNS Forward Proxy mode, this section is bypassed:

ℹ️ NOTE Inspection rules for DNS Forward Proxy mode are configured separately in Cloud Security Policies (Section 4.4.4).

Click Next to proceed.

Active Directory Connector Configuration

Configure AD integration (optional):

1. Check Enable Active Directory Connector if user identity mapping is required
2. AD Connector configuration is detailed in Section 5
3. Click Create to finalize the Forward Proxy policy

4.4.4 Cloud Security Policies#

In DNS Forward Proxy mode, security policies are created separately under the Security section:

Navigate to: DNS Firewall → Security → Cloud Policies (the page is titled Security Policies) and click Create Policy. The wizard has four steps: Tenant Info → Basic Settings → Mapping → Security Rules.

Step 1: Tenant Selection

• Customer / Tenant: Select the appropriate customer (or reseller) and tenant

Step 2: Policy Status and Scheduling

1. Configure policy activation:
   • Policy Name: A clear, descriptive name
   • Status: Set the policy to active to enable enforcement
   • Time-Based Activation: Define when the policy is active
     • Leave disabled for 24/7 enforcement (default)
     • Or enable it, set the Timezone, and restrict enforcement to specific Active Days, a Date Range, and a Time Range

Step 3: Network Attachment

1. Attach External Network: Select the public IP (source of queries)
2. Attach Private Network: Select the internal subnet

ℹ️ NOTE Both External and Private networks must be attached. External network identifies the source, Private network provides context about client segment.

Step 4: Enforcement Actions

1. Configure security enforcement:

Threat Feeds

• Enable feeds based on threat landscape:
  • Malware Domains
  • Phishing Sites
  • Ransomware C2
  • Cryptomining
  • Botnets
• Over 10 million threat indicators continuously updated. External RPZ feeds (from DNS Firewall → Security → Automated Feeds) can also be attached

DNS Tunneling Protection

• Enable AI Tunneling Detection — enabling Advanced AI Threat Detection auto-applies it together with AI FastFlux Detection and AI Infiltration Detection
• AI-powered analysis identifies DNS tunneling, fast-flux domains, and infiltration attacks
• Blocks covert communication channels over DNS

Web Filters (URL Category Filtering)

• Assign Web Filters to block website categories (Adult, Gambling, etc.); Apps and Geo Filter rules are also available
• Policy Mode — Blocking: Matches are actively blocked
• Policy Mode — Logging: Matches are logged only, not blocked (monitoring mode)

Custom Domain Overrides

• Local Ruleset: Allow or block specific domains regardless of category verdicts
• Exclusive Allowlist: Block all DNS queries except those explicitly allowed in the selected ruleset
• Override Action: Optionally redirect blocked queries to a custom domain/IP (Redirect) instead of the default block response; Default keeps each rule's own action (NXDOMAIN (Block), DROP, PASSTHRU (Allow), or REDIRECT from attached Local Rulesets)

2. Click Create Policy to finalize

⚡ IMPORTANT Set the policy mode to Blocking for active enforcement; use Logging (shown as Monitoring in the policy list) to validate a new policy against live traffic before you switch blocking on.

⚡ IMPORTANT Rules within a policy are processed top-to-bottom. Drag entries in the Rule Priority Order to reorder them (highest priority first).

Local Rulesets (Optional)

Rulesets in DNS Forward Proxy mode function identically to Local Mode (Section 4.3.7):

1. Navigate to: DNS Firewall → Security → Rulesets and click Create Local Ruleset
2. Create rulesets for allow (PASSTHRU) / block (NXDOMAIN, DROP, REDIRECT) control, or an Exclusive Allowlist
3. Attach rulesets to security policies in the Security Rules step (Step 4) and order them in the Rule Priority Order

✅ BEST PRACTICE Use rulesets sparingly. Excessive allow entries can undermine security effectiveness.

Section 5: Active Directory Integration

5. Active Directory Integration#

5.1 Overview and Benefits#

The Active Directory Connector enriches DNS and firewall logs with user identity information by correlating IP addresses with authenticated usernames. This provides critical visibility for security investigations, policy enforcement, and compliance reporting.

Key Benefits#

• User Attribution: Identify which users accessed specific domains
• Forensic Investigation: Trace security incidents to individual user accounts
• Policy Compliance: Demonstrate user-level policy enforcement for audits
• Incident Response: Rapidly identify affected users during security events
• Behavioral Analysis: Detect anomalous user behavior patterns

Supported in Both Modes#

✅ Active Directory Connector functionality is available in both Local Resolver and DNS Forward Proxy modes.

5.2 Architecture and Requirements#

Data Flow#

Domain Controllers → Windows Event Logs (Event ID 4624)
                   ↓
            NXLog Forwarder
                   ↓
         Syslog over TLS (TCP 6514)
                   ↓
   Local Resolver AD Connector Service
                   ↓
   IP-to-Username Mapping Database
                   ↓
DNS/Firewall Logs (enriched with username)

Requirements#

Domain Controller Requirements

• Windows Server 2012 R2 or higher
• Security Event Log auditing enabled (default)
• Firewall permits outbound TCP 6514 to Local Resolver
• Administrative access to install NXLog forwarder

Local Resolver Requirements

• AD Connector service enabled (configured in Section 4.3.6 or 4.4.3)
• Firewall permits inbound TCP 6514 from Domain Controllers
• Sufficient disk space for user mapping database

Network Requirements

• Domain Controllers can reach Local Resolver VM on TCP port 6514
• Low latency connection (< 50ms recommended) for real-time correlation

5.3 Implementation Steps#

5.3.1 Enable AD Connector on Local Resolver#

AD Connector is enabled during policy creation:

1. Log in to the DNS Armor™ Protect (DNS Firewall) portal: https://dnsarmor.secure-domains.org
2. Navigate to: DNS Firewall → Setup → Local Resolvers
3. Edit the existing Local Resolver configuration (or enable during creation)
4. In the Advanced Settings step, check Enable Active Directory Connector
5. Save the policy
6. The Local Resolver VM will automatically:
   • Start the AD Connector service
   • Begin listening on TCP port 6514 for syslog over TLS
   • Create user mapping database
7. Verify AD Connector status in Local Resolver web interface:
   • Navigate to: Dashboard
   • Confirm AD Connector Service shows status: Running

5.3.2 Install NXLog on Domain Controllers#

NXLog is the recommended log forwarding agent for Windows Event Logs. The provided configuration has been tested and validated for this use case.

Installation Steps

1. Download NXLog Community Edition from: https://nxlog.co/products/nxlog-community-edition
2. Run the installer on each Domain Controller
3. Accept default installation path: C:\nxlog
4. Complete installation wizard

Configuration

1. Navigate to: C:\nxlog\conf\
2. Backup existing nxlog.conf:

copy nxlog.conf nxlog.conf.backup

3. Replace nxlog.conf with the following configuration:

###############################################################################
## NXLog Configuration - DNS Armor™ Active Directory Connector
## Event ID 4624 (Successful Logons) Only
## Location: C:\nxlog\conf\nxlog.conf
###############################################################################

define ROOT C:\nxlog
define RESOLVER_HOST 192.168.100.10
define RESOLVER_PORT 6514

Moduledir %ROOT%\modules
CacheDir %ROOT%\data
Pidfile %ROOT%\data\nxlog.pid
SpoolDir %ROOT%\data
LogFile %ROOT%\data\nxlog.log
LogLevel INFO

<Extension _syslog>
    Module xm_syslog
</Extension>

<Input security_log>
    Module im_msvistalog
    SavePos TRUE
    ReadFromLast TRUE
    Query <QueryList>\
            <Query Id="0">\
             <Select Path="Security">*[System[(EventID=4624)]]</Select>\
            </Query>\
          </QueryList>
    
    Exec if $EventID == 4624 \
         { \
          if not defined($IpAddress) $IpAddress = "LOCAL"; \
          if $IpAddress == "::1" $IpAddress = "127.0.0.1"; \
          if not defined($WorkstationName) $WorkstationName = "N/A"; \
          if not defined($TargetUserName) $TargetUserName = "SYSTEM"; \
          if not defined($TargetDomainName) $TargetDomainName = "LOCAL"; \
          $TimeStr = strftime($EventTime, "%Y-%m-%d %H:%M:%S"); \
          $Message = "[SUCCESS-LOGON] " + \
                     "EventID: " + $EventID + " | " + \
                     "Timestamp: " + $TimeStr + " | " + \
                     "User: " + $TargetUserName + "@" + $TargetDomainName + " | " + \
                     "Workstation: " + $WorkstationName + " | " + \
                     "SourceIP: " + $IpAddress + " | " + \
                     "LogonType: " + $LogonType; \
          delete($Keywords); \
          delete($EventType); \
          delete($SeverityValue); \
          delete($LevelValue); \
          delete($TaskValue); \
          delete($OpcodeValue); \
          delete($RecordNumber); \
          delete($ProviderGuid); \
          delete($Version); \
          delete($Channel); \
          delete($Category); \
          delete($Opcode); \
          delete($Level); \
          delete($SubjectUserSid); \
          delete($SubjectUserName); \
          delete($SubjectDomainName); \
          delete($SubjectLogonId); \
          delete($TargetUserSid); \
          delete($TargetLogonId); \
          delete($LogonProcessName); \
          delete($AuthenticationPackageName); \
          delete($LogonGuid); \
          delete($TransmittedServices); \
          delete($LmPackageName); \
          delete($KeyLength); \
          delete($ProcessName); \
          delete($ProcessId); \
          delete($IpPort); \
          delete($ImpersonationLevel); \
          delete($ImpersonationLevelResolved); \
          delete($EventReceivedTime); \
          delete($SourceModuleName); \
          delete($SourceModuleType); \
          delete($EventID); \
          delete($ExecutionThreadID); \
          delete($ExecutionProcessID); \
          delete($TargetUserName); \
          delete($TargetDomainName); \
          delete($LogonType); \
          delete($IpAddress); \
          delete($TimeStr); \
          delete($WorkstationName); \
         }
</Input>

<Output syslog_tls>
    Module om_ssl
    Host %RESOLVER_HOST%
    Port %RESOLVER_PORT%
    AllowUntrusted TRUE
    Exec to_syslog_ietf();
</Output>

<Route r1>
    Path security_log => syslog_tls
</Route>

4. Modify Configuration Variables:
   • Line 6: Change RESOLVER_HOST to your Local Resolver IP address
     • Example: define RESOLVER_HOST 192.168.100.10
   • Line 7: Verify RESOLVER_PORT is set to 6514 (default)

⚡ IMPORTANT Ensure the RESOLVER_HOST IP address is correct. Incorrect IP will prevent log forwarding.

5. Save the configuration file
6. Open Windows Services (services.msc)
7. Locate nxlog service
8. Right-click and select Restart

Verify NXLog Operation

1. Check NXLog log file for errors:

notepad C:\nxlog\data\nxlog.log

2. Verify events are being captured:
   • Log should show connection attempts to Local Resolver
   • Look for "connection established" or similar success messages
   • If errors appear, verify IP address, port, and firewall rules

5.3.3 Configure Event Forwarding#

Windows Event Log auditing is typically enabled by default on Domain Controllers. Verify configuration:

1. Open Group Policy Management
2. Edit the Default Domain Controllers Policy
3. Navigate to:
   • Computer Configuration
   • → Policies
   • → Windows Settings
   • → Security Settings
   • → Advanced Audit Policy Configuration
   • → Audit Policies
   • → Logon/Logoff
4. Verify Audit Logon is set to Success
5. If not configured, set to Success and click OK
6. Run gpupdate /force on Domain Controllers to apply immediately

5.3.4 Validation and Testing#

Test User Authentication

1. From a client workstation, authenticate to the domain:
   • Log out and log back in, or
   • Access a network resource requiring authentication
2. Verify Event ID 4624 is logged on Domain Controller:
   • Open Event Viewer on DC
   • Navigate to: Windows Logs → Security
   • Filter for Event ID 4624
   • Confirm recent authentication events appear
3. Verify log forwarding to Local Resolver:
   • Wait 1-2 minutes for log processing
   • Log in to the Protect portal
   • Navigate to: DNS Firewall → Monitoring → DNS Monitor
   • Verify log entries include the username and domain information
   • Username should appear as username@domain.local
4. Verify AD Connector service status:
   • Log in to the Protect portal
   • Navigate to: DNS Firewall → Setup → Local Resolvers
   • Locate your Local Resolver and open View Details
   • Confirm the resolver status shows Connected and the AD Connector is shown as enabled
   • Switch to the Monitoring tab and, under Services Status, confirm the AD Connector service shows Admin Enabled and Status Running

Example Enriched Log Entry

✅ SUCCESS If username and domain appear in logs and AD Connector service is running, AD integration is functioning correctly.

5.4 Troubleshooting AD Connector#

Issue: Usernames not appearing in DNS logs#

Possible Causes and Solutions

1. NXLog Service Not Running:
   • Check NXLog service status on Domain Controller
   • Review C:\nxlog\data\nxlog.log for errors
   • Verify configuration file syntax
2. Incorrect Local Resolver IP:
   • Verify RESOLVER_HOST in nxlog.conf matches Local Resolver IP
   • Test connectivity: telnet [resolver-ip] 6514
3. Firewall Blocking TCP 6514:
   • Verify Domain Controller firewall permits outbound TCP 6514
   • Verify Local Resolver firewall permits inbound TCP 6514
   • Test connectivity from DC: Test-NetConnection -ComputerName [resolver-ip] -Port 6514
4. AD Connector Service Not Enabled:
   • Verify AD Connector is enabled in Local Resolver policy
   • Check Local Resolver Dashboard shows AD Connector service running
5. Time Synchronization Issues:
   • Ensure Domain Controllers and Local Resolver have synchronized time (NTP)
   • Time drift > 5 minutes can cause correlation failures
6. Recent Authentication Events:
   • User-to-IP mapping requires recent authentication (Event 4624)
   • If user has been logged in for days without re-authentication, mapping may be stale
   • Force user logoff/logon to generate fresh Event 4624

Diagnostic Commands#

On Domain Controller

# Verify NXLog service status
Get-Service nxlog

# Test connectivity to Local Resolver
Test-NetConnection -ComputerName [resolver-ip] -Port 6514

# View recent Event 4624 logs
Get-WinEvent -FilterHashtable @{LogName='Security'; ID=4624} -MaxEvents 10

Section 6: High Availability Configuration

6. High Availability Configuration#

6.1 Design Principles#

High availability (HA) for the DNS Armor™ Protect (DNS Firewall) Local Resolver ensures continuous DNS security enforcement and eliminates single points of failure. The recommended HA approach leverages native DNS client failover mechanisms rather than introducing additional load balancing infrastructure.

Key Design Principles#

• Multiple Resolver Instances: Deploy at least 2 Local Resolver VMs per location
• Native DNS Failover: DNS clients automatically failover to secondary servers
• No External Dependencies: Avoid complexity of external load balancers when not required
• Consistent Configuration: Ensure all Resolvers have identical policies and settings

6.2 Deployment Architecture#

Recommended Minimum Configuration#

Deployment Sizing#

💡 TIP Sizing Reminder: Approximately every 5 IP addresses generates 1 QPS on average.

✅ BEST PRACTICE Deploy resolvers across different physical hosts or availability zones to protect against hypervisor or hardware failures.

6.3 DNS Client Configuration#

DNS clients (workstations, servers, devices) are configured with multiple DNS servers. Native DNS client behavior automatically provides failover.

DHCP Configuration (Recommended)#

Configure DHCP scope with multiple DNS servers:

1. Open DHCP Management Console
2. Navigate to your DHCP scope
3. Right-click Scope Options → Configure Options
4. Select 006 DNS Servers
5. Add Local Resolver IP addresses in priority order:
   • Primary: 192.168.100.10 (Resolver-01)
   • Secondary: 192.168.100.11 (Resolver-02)
   • Tertiary: 192.168.100.12 (Resolver-03) - if deployed
6. Click OK to apply

Group Policy Configuration (Alternative)#

For static DNS configuration via GPO:

1. Open Group Policy Management
2. Edit appropriate GPO
3. Navigate to:
   • Computer Configuration → Policies → Administrative Templates → Network → DNS Client
4. Configure DNS Servers policy
5. Enter Local Resolver IPs in priority order

Manual Configuration (Testing/Exceptions)#

For individual workstation configuration:

1. Open Network and Sharing Center
2. Click active network adapter
3. Click Properties
4. Select Internet Protocol Version 4 (TCP/IPv4)
5. Click Properties
6. Configure DNS servers:
   • Preferred: 192.168.100.10
   • Alternate: 192.168.100.11

Native Failover Behavior#

DNS clients automatically handle resolver failures:

1. Client sends query to Primary DNS (Resolver-01)
2. If no response within timeout (~2-3 seconds), client queries Secondary DNS (Resolver-02)
3. If Secondary responds, subsequent queries use Secondary as Primary temporarily
4. Client periodically retries original Primary to detect recovery
5. No user intervention or external monitoring required

⚡ IMPORTANT DNS client failover is automatic and transparent to users. No additional load balancing infrastructure is required for basic HA.

6.4 Optional Load Balancer Integration#

External load balancers are optional and typically not necessary for DNS HA. However, they may be beneficial in specific scenarios.

When to Consider Load Balancer#

• Active-Active Load Distribution: Distribute query load across all resolvers equally
• Advanced Health Checking: More sophisticated health monitoring than DNS timeouts
• Centralized Management: Single VIP simplifies client configuration
• Large Deployments: 4+ resolvers where even load distribution is critical

Load Balancer Configuration#

If deploying a load balancer (F5, HAProxy, Citrix ADC, etc.):

1. Create Virtual IP (VIP):
   • Assign a VIP that clients will use as their DNS server
   • Example: 192.168.100.50
2. Configure Health Checks:
   • Protocol: DNS query
   • Query: Send test DNS query (e.g., "healthcheck.local")
   • Expected Response: Valid DNS response (not timeout or error)
   • Interval: 10 seconds
   • Timeout: 3 seconds
   • Threshold: Mark unhealthy after 3 consecutive failures
3. Load Balancing Method:
   • Round Robin: Distribute queries evenly (recommended)
   • Least Connections: Send to least busy resolver
   • Least Response Time: Send to fastest resolver
4. Session Persistence:
   • Not Required: DNS is stateless protocol
   • Source IP persistence is optional but unnecessary
5. Pool Members:
   • Add all Local Resolver VMs to pool
   • Configure individual health checks per member

Client Configuration with Load Balancer#

• DHCP Option 006: 192.168.100.50 (VIP only)
• Alternate DNS: Optional backup (external DNS or remaining resolver IP)

ℹ️ NOTE Even with a load balancer, configure a secondary DNS server in DHCP (either another VIP or direct resolver IP) to protect against load balancer failure.

Load Balancer Not Recommended If#

• Small deployment (< 2000 users)
• Budget constraints (additional licensing costs)
• Limited operational resources (adds complexity)
• Native DNS failover meets requirements (typically sufficient)

✅ BEST PRACTICE Start with native DNS failover (2 resolvers, no load balancer). Add load balancer only if specific business requirements justify the additional complexity.

Section 7: Deployment Validation

7. Deployment Validation#

7.1 Pre-Production Testing#

Before migrating production traffic to the DNS Armor™ Protect (DNS Firewall) Local Resolver, conduct comprehensive testing in a controlled environment.

7.1.1 DNS Resolution Testing#

Test Internal Domain Bypass

Verify that internal domains are resolved correctly by bypass DNS servers:

1. Configure a test workstation to use Local Resolver as DNS server
2. Execute the following DNS lookups:

nslookup dc01.corp.local [Local-Resolver-IP]
nslookup fileserver.corp.local [Local-Resolver-IP]
nslookup intranet.corp.local [Local-Resolver-IP]

Expected Result

• Internal domains resolve to correct internal IP addresses
• No query delay or timeout
• DNS responses come from bypass DNS servers (not cloud or external)

✅ SUCCESS CRITERIA All internal domains resolve correctly with < 50ms response time.

Test External Domain Resolution

Verify external domains are resolved correctly:

nslookup google.com [Local-Resolver-IP]
nslookup cloudflare.com [Local-Resolver-IP]
nslookup microsoft.com [Local-Resolver-IP]

Expected Result

• External domains resolve to correct public IP addresses
• Response time < 100ms (Local Mode) or < 200ms (Proxy Mode)
• Queries are processed through security inspection

✅ SUCCESS CRITERIA All external domains resolve correctly without timeout or errors.

7.1.2 Policy Enforcement Testing#

Test Blocked Category

Verify that blocked categories are enforced:

1. Identify a test domain in a blocked category:
   • Gambling: casino.com, poker.com
   • Adult: (use appropriate test domains)
   • Malware: Use EICAR test domain (if available in portal)
2. Attempt to resolve blocked domain:

nslookup casino.com [Local-Resolver-IP]

Expected Result

• Query is blocked (NXDOMAIN response or block page IP)
• No resolution to actual IP address
• Event logged in the Protect portal

✅ SUCCESS CRITERIA Blocked domains do not resolve, and action is logged.

Test Allowed Category

Verify allowed domains resolve correctly:

nslookup google.com [Local-Resolver-IP]
nslookup github.com [Local-Resolver-IP]

Expected Result

• Domains resolve correctly
• Normal DNS response times
• Query logged as "allowed"

Test Custom Allow Rules (if configured)

If Local Rulesets are configured with allow (PASSTHRU) entries:

nslookup allowed-domain.com [Local-Resolver-IP]

Expected Result

• Domain resolves even if in blocked category
• Allow (PASSTHRU) rule takes precedence when its ruleset sits above the blocking feed in the Feed Priority Order

7.1.3 Bypass Domain Testing#

Test Bypass List

Verify bypass domains are not inspected:

1. Add a known malware test domain to bypass list temporarily
2. Attempt to resolve the domain
3. Expected result: Domain resolves (bypassed inspection)
4. Remove test domain from bypass list

⚠️ CAUTION Use extreme care when testing with actual malicious domains. Perform testing in isolated environment only.

7.2 Log Verification#

Verify that all query activity is properly logged:

1. Log in to the Protect portal: https://dnsarmor.secure-domains.org
2. Navigate to: DNS Firewall → Monitoring → DNS Monitor
3. Verify the following:
   • All test queries appear in logs
   • Source IP addresses are correct
   • Actions (allow/block) are correct
   • Timestamps are accurate
   • If AD Connector enabled: Usernames appear in logs

Sample Log Entry#

External Syslog Verification (if configured)#

If forwarding to external syslog/SIEM:

1. Access your syslog server or SIEM console
2. Search for records containing CEF:0|Secure Domains|Logs Connector
3. Verify all three streams are arriving: dns-rpz (SignatureID 1001), dns-query (1002), and audit (1003)
4. Verify field content is parsed correctly — tenant name (cs4), queried domain (dhost), client IP (src), and action (act) should appear as discrete fields, not one unparsed string
5. Confirm logs are arriving in real-time (< 30 second delay)

To inspect what is actually on the wire at the collector:

tcpdump -i any -A -n port 514 | grep -a 'CEF:0'

To inject a known-good test record into the collector (uses the sample from Appendix D):

logger -n 127.0.0.1 -P 514 -T -p local4.info "<paste a sample record from Appendix D.4>"

ℹ️ NOTE If records reach the collector but your SIEM shows nothing, check the facility filter first: the resolver sends on local4 (PRI 166). A collector filtering on a different facility silently drops every record.

7.3 Production Cutover#

After successful testing, migrate production traffic to the Protect Local Resolver:

Phased Rollout Approach (Recommended)#

Phase 1: Pilot Group

1. Identify 10-20 pilot users from IT department
2. Configure pilot user workstations with Local Resolver DNS
3. Monitor for 24-48 hours
4. Collect feedback and address any issues

Phase 2: Department Rollout

1. Select one business department (non-critical)
2. Update DHCP scope for department VLAN
3. Users automatically receive new DNS configuration on next DHCP renewal
4. Monitor for 3-5 business days

Phase 3: Site-Wide Deployment

1. Update all DHCP scopes to use Local Resolver
2. Optionally force DHCP renewal: ipconfig /release then ipconfig /renew
3. Monitor query volume and system performance
4. Verify all subnets are functioning correctly

Phase 4: Validation

1. Confirm 95%+ of clients are using Local Resolver
2. Verify query volumes match expectations
3. Review blocked threats and categories
4. Collect user feedback

Big Bang Approach (Alternative)#

For small sites (< 500 users):

1. Schedule maintenance window
2. Update all DHCP scopes simultaneously
3. Announce to users
4. Monitor closely for first 2-4 hours
5. Have rollback plan ready (revert DHCP to original DNS servers)

Rollback Plan#

If issues arise during cutover:

1. Update DHCP scopes to restore original DNS servers
2. Force DHCP renewal or wait for automatic renewal
3. Investigate and resolve issues
4. Re-attempt cutover after remediation

ℹ️ NOTE DHCP lease time determines how quickly changes propagate. Shorter lease times (e.g., 8 hours) enable faster rollout but increase DHCP server load.

Section 8: Monitoring & Operations

8. Monitoring and Operations#

8.1 Health Monitoring#

Regular monitoring ensures Local Resolver continues to operate optimally:

Cloud Portal Monitoring#

1. Log in to the DNS Armor™ Protect (DNS Firewall) portal: https://dnsarmor.secure-domains.org
2. Navigate to: DNS Firewall → Setup → Local Resolvers

Health Status Indicators#

The Local Resolvers page displays the connection status of every Local Resolver deployment, derived from each resolver's most recent heartbeat (Last Seen) — not a manual flag:

• Connected: The resolver has reported to the cloud within the last few minutes and is operational
• Disconnected: The resolver has not reported recently, or has never connected (investigate immediately)

The page's dashboard cards summarize how many resolvers are connected, the connected percentage, and the Local vs Proxy mode distribution.

8.2 Resource Utilization#

Monitor system resources to ensure adequate capacity:

Cloud Portal Resource View#

Navigate to: DNS Firewall → Setup → Local Resolvers, select the resolver, open View Details, and switch to the Monitoring tab

View Resource Statistics#

The Monitoring tab presents Resource Usage Statistics (CPU Usage and Memory Usage charts), Cache Performance Statistics, DNS Queries Overview, and Security & Performance Metrics for a selectable time range. Watch for:

• CPU Utilization: Should remain < 70% during normal operation
• Memory Usage: Should remain < 80% of allocated RAM
• Disk Space: Monitor log storage consumption
• Network Throughput: Monitor for bandwidth saturation
• Queries Per Second (QPS): Current query rate vs. capacity

Remediation Actions#

If resource constraints detected:

• CPU/Memory: Increase VM resources or deploy additional resolver
• Disk Space: Adjust log retention policy or increase disk size
• QPS: Deploy additional resolver for load distribution

8.3 DNS Tunnel Detection#

Monitor and respond to DNS tunneling attempts:

Navigate to: DNS Firewall → Setup → Local Resolvers, select the resolver, open View Details, and switch to the DNS Tunneling tab (available in Local Resolver mode)

DNS Tunneling Indicators#

• Unusually high query frequency from single source
• Queries with encoded data in subdomain labels
• Non-standard query patterns (e.g., TXT record queries)
• Queries to obscure or newly registered domains

Response Actions#

1. Investigate: Review source IP and user (if AD integrated)
2. Exempt (if legitimate): Some applications use DNS for legitimate purposes
   • Add the domain to the AI detection exception lists on the DNS Tunneling tab (separate lists for tunneling, infiltration, and fast-flux detections — Securedomains.AI.Tunneling, Securedomains.AI.Infiltration, and Securedomains.AI.FastFlux — one domain per line) and save, so the corresponding AI detector no longer flags it
   • Document business justification
3. Block (if malicious): Add a block rule (NXDOMAIN / DROP / REDIRECT) for the domain in a ruleset, or investigate the endpoint

Legitimate DNS Tunnel Use Cases#

• Fallback connectivity for captive portals
• IoT device communications
• Some VPN client keepalives

⚡ IMPORTANT Do not blindly block all DNS tunneling detections. Investigate to differentiate legitimate from malicious activity.

8.4 Remote Management#

Manage Local Resolver remotely from the cloud portal:

Navigate to: DNS Firewall → Setup → Local Resolvers, select the resolver, open View Details, and switch to the Actions tab (panel: Resolver Instructions & Actions). Select the desired instructions and click Submit All Instructions to send them to the resolver in a single submission; the current instructions are read back from the resolver when the tab loads. The resolver must be Connected to receive instructions.

Available Remote Actions#

Reboot Resolver

• Restarts the resolver service on the Local Resolver VM
• Use for: Applying updates, clearing temporary issues
• Downtime: brief service interruption (ensure HA configuration to maintain service)

Network Configuration (Change IP Address)

• Modify the Local Resolver's network interface settings (eth0 / eth1) and DNS server settings remotely (per-interface IPv4 and IPv6 configuration, DHCP or static)
• Use for: Network reconfiguration, IP conflicts

API Configuration (Replace API Code)

• The Actions tab shows the resolver's current API code and lets you enter a New API Code
• Use for: Key rotation, suspected key compromise
• Create or reset API codes under Administration → API Keys (see Section 4.2.5.1), then apply the new code here

Flush DNS Cache & Reload Services

• Clears the DNS cache and restarts DNS services
• Use for: Forcing a clean state after significant policy or bypass list changes
• Causes a brief service interruption (typically 5-15 seconds while the cache is flushed and services restart)

ℹ️ NOTE Ordinary configuration changes do not require a manual push — the resolver synchronizes its configuration from the portal automatically (approximately every 60 seconds).

⚡ IMPORTANT Remote reboot will cause brief DNS service interruption. Ensure secondary resolvers are available to maintain service continuity.

Deleting a Local Resolver#

To decommission a Local Resolver:

1. Navigate to: DNS Firewall → Setup → Local Resolvers
2. Open the resolver's Actions menu and select Delete
3. Confirm the deletion (this action cannot be undone)
4. Power off and remove the VM from your hypervisor

ℹ️ NOTE Deleting a resolver removes its cloud configuration but does not delete the objects it referenced (private networks, bypass configurations, rulesets). Those objects cannot be deleted while any resolver or security policy still uses them — the portal blocks such deletions with a clear in-use error that names the referencing objects, until every reference is removed.

Section 9: Troubleshooting Guide

9. Troubleshooting Guide#

9.1 Common Issues and Resolutions#

Issue 1: Local Resolver VM Cannot Reach Cloud Portal#

Symptoms

• Dashboard shows "Unable to sync with cloud"
• Policy updates not applying
• Resource statistics not updating in portal

Troubleshooting Steps

1. Verify internet connectivity from VM:

ping 8.8.8.8
ping dnsarmor.secure-domains.org

2. Test HTTPS connectivity:

curl -I https://dnsarmor.secure-domains.org

3. Check firewall rules permit outbound HTTPS (TCP 443)
4. Verify DNS resolution for portal hostname
5. Check proxy configuration if environment uses HTTP proxy

Resolution

• Configure firewall to permit VM outbound HTTPS access
• If using proxy, configure proxy settings in VM
• Verify API key is correct in System Setup

Issue 2: DNS Queries Not Being Forwarded#

Symptoms

• Clients cannot resolve any domains (internal or external)
• DNS queries timeout
• Network connectivity works but name resolution fails

Troubleshooting Steps

1. Verify Local Resolver service status:
   • Check Dashboard → System Configuration → Service Status
   • All critical services should show "Running"
2. Test DNS resolution directly from Local Resolver VM:

nslookup google.com 127.0.0.1

3. Verify DNS forwarders are configured and reachable
4. Check firewall permits outbound DNS (UDP/TCP 53) to forwarders
5. Review logs for errors

Resolution

• Restart DNS service via web interface or remote management
• Verify DNS forwarder IP addresses are correct
• Configure firewall rules to permit outbound DNS
• Ensure VM has internet connectivity

Issue 3: Internal Domains Not Resolving#

Symptoms

• Internal domains (e.g., corp.local) fail to resolve
• External domains work correctly
• Bypass list configured but not functioning

Troubleshooting Steps

1. Verify bypass domains are correctly configured in policy
2. Check bypass DNS servers are specified and reachable
3. Test bypass DNS server connectivity from Local Resolver:

nslookup dc01.corp.local [bypass-dns-server-ip]

4. Verify bypass list syntax (wildcard usage, domain format)
5. Check for DNS forwarding loops

Resolution

• Correct bypass domain list in portal policy
• Verify bypass DNS server IP addresses
• Ensure bypass DNS servers can reach Local Resolver
• Avoid circular DNS forwarding (Local Resolver → Bypass DNS → Local Resolver)

Issue 4: Policy Updates Not Applying#

Symptoms

• Policy changes made in portal do not take effect
• Blocked domains still resolve
• Configuration out of sync

Troubleshooting Steps

1. Verify Unique Identifier matches exactly between portal and VM
2. Check API key is valid and not expired
3. Verify cloud connectivity (see Issue 1)
4. Check policy synchronization status in Dashboard
5. Force manual sync if available

Resolution

• Correct Unique Identifier if mismatch exists
• Regenerate the API code (Administration → API Keys → Reset API Code) and apply the new code on the resolver
• Reboot Local Resolver VM to force configuration refresh
• Verify no firewall blocking HTTPS API calls

Issue 5: Active Directory Usernames Not Appearing in Logs#

Symptoms

• DNS logs show IP addresses but no usernames
• AD Connector enabled but not functioning
• Event logs not arriving from Domain Controllers

Troubleshooting Steps

1. Verify AD Connector service is running (Dashboard → Service Status)
2. Check NXLog service status on Domain Controllers:

Get-Service nxlog

3. Review NXLog log file on DC:

notepad C:\nxlog\data\nxlog.log

4. Test connectivity from DC to Local Resolver TCP 6514:

Test-NetConnection -ComputerName [resolver-ip] -Port 6514

5. Verify firewall permits DC → Resolver TCP 6514
6. Check Event 4624 is being generated in DC Security log

Resolution

• Start or restart NXLog service on Domain Controllers
• Correct RESOLVER_HOST IP in nxlog.conf if incorrect
• Configure firewall rules to permit TCP 6514
• Force user authentication to generate Event 4624
• Verify time synchronization between DC and Resolver

Issue 6: High CPU or Memory Utilization#

Symptoms

• CPU consistently > 80%
• Memory usage > 90%
• Slow DNS response times
• System unresponsive

Troubleshooting Steps

1. Review current QPS (Queries Per Second) vs. VM capacity
2. Check for unusually high query volume or attack (DNS amplification)
3. Review resource allocation vs. sizing table recommendations
4. Identify top querying clients (may indicate misconfiguration)
5. Check for DNS query loops

Resolution

• Increase VM CPU/memory allocation per sizing table
• Deploy additional Local Resolver for load distribution
• Investigate and address DNS query loops
• Block abusive clients if under attack
• Optimize cache settings if applicable

Issue 7: Queries Intermittently Failing#

Symptoms

• DNS queries succeed sometimes, fail other times
• Inconsistent behavior
• Users report sporadic connectivity issues

Troubleshooting Steps

1. Check for high resource utilization (CPU, memory, network)
2. Verify DNS forwarders are stable and reachable
3. Test for network connectivity issues (packet loss, latency)
4. Review logs for patterns in failures
5. Check for DNS query rate limiting

Resolution

• Add secondary DNS forwarders for redundancy
• Investigate and resolve network connectivity issues
• Increase VM resources if performance-related
• Configure multiple Local Resolvers for HA
• Adjust query timeout settings if needed

9.2 Diagnostic Commands#

Local Resolver VM Console#

# Check network connectivity
ping 8.8.8.8
ping dnsarmor.secure-domains.org
curl -I https://dnsarmor.secure-domains.org

# Test DNS resolution
nslookup google.com 127.0.0.1
nslookup google.com [dns-forwarder-ip]

# Check listening ports
sudo netstat -tunlp | grep 53
sudo netstat -tunlp | grep 6514

# Monitor resource usage
top
free -h
df -h

# Check time synchronization
timedatectl status

Windows Client Testing#

REM Test DNS resolution via Local Resolver
nslookup google.com [Local-Resolver-IP]

REM Display current DNS configuration
ipconfig /all

REM Flush DNS cache
ipconfig /flushdns

REM Renew DHCP configuration
ipconfig /release
ipconfig /renew

REM Test connectivity to Local Resolver
ping [Local-Resolver-IP]
Test-NetConnection -ComputerName [Local-Resolver-IP] -Port 53

PowerShell Diagnostics#

# Test DNS resolution with timing
Measure-Command { Resolve-DnsName google.com -Server [Local-Resolver-IP] }

# Test multiple domains
$domains = @("google.com", "microsoft.com", "cloudflare.com")
foreach ($domain in $domains) {
    Resolve-DnsName $domain -Server [Local-Resolver-IP]
}

# Check DNS server configuration
Get-DnsClientServerAddress

# View DNS cache
Get-DnsClientCache

9.3 Support Escalation#

If issues cannot be resolved using this guide, contact DNS Armor™ support:

Before Contacting Support, Collect#

1. Problem Description:
   • Detailed description of issue
   • When did issue start?
   • Has anything changed recently?
   • How many users affected?
2. Environment Details:
   • Local Resolver version (from Dashboard)
   • Operating mode (Local or Proxy)
   • VM resources (CPU, memory, disk)
   • Hypervisor platform
3. Configuration Details:
   • Unique Identifier
   • Private network configuration
   • Bypass domain list
   • DNS forwarder configuration
4. Diagnostic Information:
   • Screenshot of Dashboard showing resource utilization
   • Relevant log excerpts (from Section 9.2)
   • Network diagram showing DNS infrastructure
   • Recent changes or maintenance activities
5. Troubleshooting Steps Already Performed:
   • List all troubleshooting steps attempted
   • Results of diagnostic commands
   • Any temporary workarounds implemented

Contact Information#

• Email Support: support@secure-domains.org
• Portal: https://dnsarmor.secure-domains.org
• Phone Support: (Check portal for current phone number)
• Emergency Contact: (For critical production outages)

Support Ticket Priority Levels#

• P1 - Critical: Complete DNS outage, all users affected
• P2 - High: Partial DNS outage, significant user impact
• P3 - Medium: Degraded performance, limited user impact
• P4 - Low: Minor issue, cosmetic, or enhancement request

⚡ IMPORTANT For P1 critical issues, call phone support immediately in addition to submitting a ticket.

Section 10: Appendices

10. Appendices#

Appendix A: Quick Reference Card#

Essential Information#

Critical Commands#

# Test DNS resolution nslookup google.com 127.0.0.1 # Check network configuration ip addr show # Verify connectivity ping 8.8.8.8 ping dnsarmor.secure-domains.org # Monitor resources top free -h df -h

Emergency Contacts#

• Support Email: support@secure-domains.org
• Portal: https://dnsarmor.secure-domains.org

Appendix B: Glossary of Terms#

Appendix C: Sample Configurations#

Sample NXLog Configuration for Active Directory#

See Section 5.3.2 for complete configuration.

Sample DHCP Configuration#

Scope: 192.168.1.0/24
Option 006 DNS Servers:
  - 192.168.100.10 (Primary Local Resolver)
  - 192.168.100.11 (Secondary Local Resolver)
  - 192.168.1.1 (Fallback - Corporate DNS)

Sample Bypass Domain List#

corp.local
internal.company.com
dc01.corp.local
dc02.corp.local
fileserver.corp.local
lab.local

Sample DNS Forwarders#

Primary: 8.8.8.8 (Google Public DNS)
Secondary: 1.1.1.1 (Cloudflare DNS)

Appendix D: SIEM Integration Pack (Logs Connector Templates)#

This appendix is the canonical reference for the three log streams the Logs Connector ships to an external syslog server or SIEM (Section 4.2.6), together with ready-made, copy-paste onboarding templates for ArcSight, Microsoft Sentinel, Splunk, QRadar, and Elastic, plus the collector-side rsyslog configuration.

💡 TIP Every template below is downloadable and copyable as-is: click a filename to download the file, or use the Copy button next to it to copy the whole block to the clipboard. Downloads are generated in your browser from the page itself — no external links.

D.1 Wire Format#

Every record shipped by the Logs Connector has this shape:

<PRI>MMM dd HH:mm:ss HOSTNAME TAG: CEF:0|Secure Domains|Logs Connector|1.0.0|<SignatureID>|<Name>|<Sev>|<extension>

• PRI — 166 by default = facility local4 (20) × 8 + severity info (6). The facility is configurable (Section D.12). The syslog severity is deliberately fixed at info for every record: per-event severity lives in the CEF header's 7th field, and varying the syslog severity would let a collector filtering on local4.info silently drop the high-severity RPZ records.
• Framing — RFC 3164 by default. RFC 5424 keeps the year and millisecond precision. A legacy framing with no <PRI> is available for staged rollouts (Section D.12).
• Vendor / Product / Version — Secure Domains / Logs Connector / 1.0.0. SIEMs key parser and log-source selection on the vendor + product pair, so these values are a stable contract and will not change.

D.2 CEF Field Reference#

Standard CEF dictionary keys are used wherever one exists. Everything else uses the labelled custom-string mechanism (csN + csNLabel) — the CEF standard's own extension point — which makes each value self-describing in the SIEM UI. Slot numbering is consistent across streams: cs4 is always TenantName and cs6 is always EndpointAgent, so one correlation rule spans all streams.

D.2.1 RPZ — SignatureID 1001

D.2.2 DNS Query — SignatureID 1002

Same field set as RPZ minus act, cs2, cs3, and cs5.

D.2.4 The Queried Name Is in dhost, and Only dhost

The CEF key destinationDnsDomain was evaluated and deliberately rejected. It is a real CEF key, but it means "the DNS domain part of the FQDN" — icloud.com, not mask.icloud.com — and decoders act on that meaning before anything you control gets a say:

• the Logstash CEF codec maps it straight to destination.registered_domain
• Sentinel maps it to the DestinationDnsDomain column, which built-in ASIM and analytics content read as a registrable domain

Emitting the full FQDN there would silently feed mask.icloud.com into fields every consumer treats as a registrable domain, corrupting any aggregation or detection keyed on it. Producing the correct value needs a public-suffix list, which a log shipper has no business carrying. dhost (destinationHostName) is dictionary-defined as FQDN-shaped and is mapped natively by every SIEM, so it is sufficient on its own. A consumer needing the registrable domain should derive it downstream.

ℹ️ NOTE The per-SIEM templates below still contain defensive handling for destinationDnsDomain (a coalesce, a case() fallback, a guarded rename, an LSX pattern). Those are harmless no-ops against current output and are retained so the templates keep working if the key ever appears — from a future change or from a customer's historical data.

D.2.3 Audit — SignatureID 1003

D.3 Parsing Rules a Consumer Must Honour#

The per-SIEM templates below already implement these rules. If you write your own parser, honour all five:

1. Escaping. The extension escapes \ → \\, = → \=, newline → \n. The pipe | is escaped in the header only, never in the extension. Unescape in that order (backslash last) or values containing both will corrupt.
2. Values may contain spaces. CEF has no quoting; a value runs until the next key= token. Do not split the extension on whitespace — it will shred values such as cs6=M7mad MSP Test iPhone [iOS 26.5.2; iPhone16;2].
3. Typed keys may be absent. src, spt, sourceTranslatedAddress, and rt are omitted entirely when no valid value exists rather than being filled with na — SIEMs type-validate those columns and reject junk. Treat absence as "unknown"; do not assume presence.
4. String keys are always present, using na when unknown. The key set for a given SignatureID is stable.
5. Record size. RPZ records run ~650 bytes and can exceed 1024 with a long FQDN plus a long device name. RFC 3164 over UDP truncates at 1024 bytes in many collectors — prefer TCP, TLS, or RELP for RPZ.

D.4 Sample Records#

Byte-exact samples of all three streams. Use them to validate a parser or to inject test records with logger (Section 7.2).

RPZ (dns-rpz, 1001)

📄 File: sample-rpz.cef

<166>Aug  5 00:14:07 secure-domains-local-resolver dns-rpz: CEF:0|Secure Domains|Logs Connector|1.0.0|1001|DNS RPZ|7|rt=1785888847000 dhost=mask.icloud.com src=178.81.193.105 spt=53284 cs1Label=DnsRecordType cs1=A sourceTranslatedAddress=192.168.100.92 cs2Label=RpzPolicy cs2=doh.ioc2rpz cs3Label=RpzRule cs3=mask.icloud.com act=REDIRECT(blocked.secure-domains.org) suser=na shost=na cs4Label=TenantName cs4=Test778 cs5Label=RpzMode cs5=Blocking cs6Label=EndpointAgent cs6=M7mad MSP Test iPhone [iOS 26.5.2; iPhone16;2] flexString1Label=EndpointType flexString1=Mobile Agent v1.1 deviceExternalId=test-msp-lr-proxy dvchost=secure-domains-local-resolver

DNS Query (dns-query, 1002)

📄 File: sample-query.cef

<166>Aug  5 00:14:09 secure-domains-local-resolver dns-query: CEF:0|Secure Domains|Logs Connector|1.0.0|1002|DNS Query|2|rt=1785888849000 dhost=a.root-servers.net. src=178.81.193.105 spt=38172 cs1Label=DnsRecordType cs1=A suser=na shost=na cs4Label=TenantName cs4=Master-Tenant cs6Label=EndpointAgent cs6=M7mad MSP Test iPhone [iOS 26.5.2; iPhone16;2] flexString1Label=EndpointType flexString1=Mobile Agent v1.1 deviceExternalId=test-msp-lr-proxy dvchost=secure-domains-local-resolver

Audit (audit, 1003)

📄 File: sample-audit.cef

<166>Aug  5 00:14:11 secure-domains-local-resolver audit: CEF:0|Secure Domains|Logs Connector|1.0.0|1003|Audit Log|5|rt=1785888851000 act=Update cs1Label=ResourceType cs1=Policy cs2Label=ResourceName cs2=Default Policy suser=m7mad cs3Label=UserEmail cs3=m7mad@secure-domains.org src=178.81.193.105 msg=changed action from a\=b to c\=d cs4Label=TenantName cs4=Test778 cs5Label=CustomerName cs5=MSP Reseller deviceExternalId=test-msp-lr-proxy dvchost=secure-domains-local-resolver

D.5 Does My SIEM Need a Parser?#

Only ArcSight is genuinely zero-config. Sentinel and Elastic ingest with no work but show raw CEF slot names until the template is loaded; QRadar and Splunk need their template to be usable at all.

D.6 Collector Configuration (rsyslog)#

Place the following in /etc/rsyslog.d/60-secure-domains.conf on the log-forwarder host. It receives on UDP/TCP 514, raises the message-size limit, forwards to the local Azure Monitor Agent for Sentinel (or writes to a file for a file-tailing connector), and keeps the records out of /var/log/syslog:

📄 File: 60-secure-domains.conf

# Secure Domains -> collector forwarding (rsyslog)
# Place in /etc/rsyslog.d/60-secure-domains.conf on the log-forwarder host.
#
# The resolver emits RFC3164 on facility local4 (PRI 166 = local4.info).
# This is exactly what the Microsoft Sentinel CEF-via-AMA pipeline expects,
# and it is why the resolver defaults to local4 rather than leaving the PRI
# absent: with no <PRI>, rsyslog assigns facility "user" and a local4 filter
# silently drops every record.

# --- receive ---------------------------------------------------------
module(load="imudp")
input(type="imudp" port="514")
module(load="imtcp")
input(type="imtcp" port="514")

# Raise the max message size: RPZ records run ~650 bytes and can exceed the
# 1024-byte default with a long FQDN plus a long device name. Truncation is
# silent, and a truncated CEF record fails to parse entirely.
$MaxMessageSize 8k

# --- forward to the local Azure Monitor Agent (Sentinel) --------------
# The AMA CEF connector listens on 127.0.0.1:28330.
local4.* @@127.0.0.1:28330

# --- or: write to file for a file-tailing connector -------------------
# template(name="RawMsg" type="string" string="%rawmsg%\n")
# local4.*  action(type="omfile" file="/var/log/secure-domains-cef.log" template="RawMsg")

# Do not also send these to /var/log/syslog
local4.*  stop

⚡ IMPORTANT The resolver defaults to facility local4 rather than leaving the PRI absent for a reason: with no <PRI>, rsyslog assigns facility user, and a local4 filter silently drops every record.

D.7 ArcSight Onboarding#

CEF is ArcSight's native format, so no parser or FlexConnector is required:

1. Connector: SmartConnector for Syslog NG Daemon (or Syslog File)
2. The device is auto-identified from the CEF header: Device Vendor = Secure Domains, Device Product = Logs Connector, Device Version = 1.0.0
3. Standard keys map straight onto ArcSight fields: src → Source Address, spt → Source Port, dhost → Destination Host Name, act → Device Action, suser → Source User Name, shost → Source Host Name, msg → Message, rt → Device Receipt Time, deviceExternalId → Device External ID, dvchost → Device Host Name, sourceTranslatedAddress → Source Translated Address
4. cs1..cs6 render using their csNLabel values automatically, so the ESM/Logger UI shows "TenantName" rather than "Device Custom String 4"

Optional: Event Categorization

Save the following as securedomains_categorization.csv and drop it into $ARCSIGHT_HOME/user/agent/acp/categorizer/current/securedomains/logsconnector.csv on the connector host to populate the category fields, which is what most built-in correlation content keys on:

📄 File: securedomains_categorization.csv

Event Name,categoryObject,categoryBehavior,categoryTechnique,categoryDeviceGroup,categorySignificance,categoryOutcome
DNS RPZ,/Host/Application/Service,/Access/Start,/Exploit/Denial of Service,/Firewall,/Informational/Warning,/Failure
DNS Query,/Host/Application/Service,/Access/Start,,/IDS/Network,/Informational,/Success
Audit Log,/Host/Application,/Modify/Configuration,,/Application,/Informational,/Success

D.8 Microsoft Sentinel Onboarding#

The CEF-via-AMA connector already decodes CEF into CommonSecurityLog, so no custom parser is required to ingest. The KQL functions below only rename the generic CEF columns to meaningful ones so analysts and rules do not have to remember what DeviceCustomString4 holds. Save each block as a Workspace Function with the name given in its header comment. The QueriedDomain column resolves through a case() fallback chain (DestinationHostName → DestinationDnsDomain → raw AdditionalExtensions) so a single dropped key cannot blank out the most important column in the parser — see D.2.4 for why dhost is primary.

⚡ IMPORTANT Prerequisite: the AMA CEF collector must accept facility local4 — that is what the resolver sends (PRI 166 = local4.info). If your DCR filters facilities, include local4, or records are dropped before reaching the workspace and none of these functions will return anything.

📄 File: SecureDomains_Parsers.kql

// =====================================================================
// Secure Domains — Microsoft Sentinel parsers
// =====================================================================
// The CEF-via-AMA connector already decodes CEF into CommonSecurityLog, so
// NO custom parser is required to ingest. These functions only rename the
// generic CEF columns to meaningful ones so analysts and rules do not have to
// remember what DeviceCustomString4 holds.
//
// Save each block as a Workspace Function with the name in the header comment.
//
// Prerequisite: the AMA CEF collector must accept facility local4 — that is
// what the resolver sends (PRI 166 = local4.info). If your DCR filters
// facilities, include local4 or records are dropped BEFORE reaching the
// workspace and nothing here will run.
// =====================================================================


// --- Function name: SecureDomainsRPZ ---------------------------------
CommonSecurityLog
| where DeviceVendor == "Secure Domains"
    and DeviceProduct == "Logs Connector"
    and DeviceEventClassID == "1001"
| project
    TimeGenerated,
    EventTime            = ReceiptTime,
    ResolverId           = DeviceExternalID,
    ResolverHost         = DeviceName,
    TenantName           = DeviceCustomString4,
    // dhost and destinationDnsDomain carry the SAME queried FQDN (the resolver
    // emits the full name in both). dhost stays primary because FIELD-REFERENCE
    // documents it as always present; the fallbacks exist so a single dropped key
    // cannot blank out the most important column in the whole parser.
    // Fallback 2 is the mapped column: Microsoft's CEF-to-CommonSecurityLog table
    // maps CEF `destinationDnsDomain` -> `DestinationDnsDomain`, a real string
    // column in the fixed schema. Fallback 3 covers the case where a collector or
    // DCR does not apply that mapping and leaves the raw key in AdditionalExtensions.
    // case() rather than coalesce() because CommonSecurityLog fills absent keys with
    // empty strings, not nulls, and coalesce() would happily return the empty string.
    QueriedDomain        = case(
                               isnotempty(DestinationHostName),  DestinationHostName,
                               isnotempty(DestinationDnsDomain), DestinationDnsDomain,
                               extract(@"destinationDnsDomain=([^\s;]+)", 1, AdditionalExtensions)),
    ClientPublicIP       = SourceIP,
    ClientPort           = SourcePort,
    ClientPrivateIP      = SourceTranslatedAddress,
    RecordType           = DeviceCustomString1,
    RpzPolicy            = DeviceCustomString2,
    RpzRule              = DeviceCustomString3,
    RpzMode              = DeviceCustomString5,
    ActionApplied        = DeviceAction,
    UserName             = SourceUserName,
    ComputerName         = SourceHostName,
    EndpointAgent        = DeviceCustomString6,
    EndpointType         = FlexString1,
    Severity             = LogSeverity
| extend IsBlocked = ActionApplied startswith "REDIRECT"


// --- Function name: SecureDomainsDNSQuery ----------------------------
CommonSecurityLog
| where DeviceVendor == "Secure Domains"
    and DeviceProduct == "Logs Connector"
    and DeviceEventClassID == "1002"
| project
    TimeGenerated,
    EventTime            = ReceiptTime,
    ResolverId           = DeviceExternalID,
    ResolverHost         = DeviceName,
    TenantName           = DeviceCustomString4,
    // Same dhost / destinationDnsDomain duplication as the RPZ stream — see the
    // comment in SecureDomainsRPZ for why the fallback chain is shaped this way.
    // Kept identical on purpose so SecureDomainsAll unions a consistent column.
    QueriedDomain        = case(
                               isnotempty(DestinationHostName),  DestinationHostName,
                               isnotempty(DestinationDnsDomain), DestinationDnsDomain,
                               extract(@"destinationDnsDomain=([^\s;]+)", 1, AdditionalExtensions)),
    ClientPublicIP       = SourceIP,
    ClientPort           = SourcePort,
    ClientPrivateIP      = SourceTranslatedAddress,
    RecordType           = DeviceCustomString1,
    UserName             = SourceUserName,
    ComputerName         = SourceHostName,
    EndpointAgent        = DeviceCustomString6,
    EndpointType         = FlexString1


// --- Function name: SecureDomainsAudit -------------------------------
CommonSecurityLog
| where DeviceVendor == "Secure Domains"
    and DeviceProduct == "Logs Connector"
    and DeviceEventClassID == "1003"
| project
    TimeGenerated,
    EventTime            = ReceiptTime,
    ResolverId           = DeviceExternalID,
    ResolverHost         = DeviceName,
    TenantName           = DeviceCustomString4,
    CustomerName         = DeviceCustomString5,
    ActionType           = DeviceAction,
    ResourceType         = DeviceCustomString1,
    ResourceName         = DeviceCustomString2,
    OperatorUser         = SourceUserName,
    OperatorEmail        = DeviceCustomString3,
    OperatorIP           = SourceIP,
    Details              = Message


// --- Function name: SecureDomainsAll (union across streams) ----------
union
    (SecureDomainsRPZ      | extend Stream = "RPZ"),
    (SecureDomainsDNSQuery | extend Stream = "Query"),
    (SecureDomainsAudit    | extend Stream = "Audit")


// =====================================================================
// ASIM normalisation (optional)
// =====================================================================
// Map the DNS streams onto the ASIM DNS schema so built-in ASIM content works.
// Function name: ASimDnsSecureDomains
//
// The new destinationDnsDomain CEF key gets NO ASIM field of its own: ASIM DNS
// models the queried name as DnsQuery and nothing else, and the key is a verbatim
// duplicate of dhost. Feeding it in via QueriedDomain (which already resolves both
// keys) keeps DnsQuery single-valued and keeps built-in ASIM DNS content working.
union
    (SecureDomainsRPZ | extend _Blocked = true),
    (SecureDomainsDNSQuery | extend _Blocked = false, RpzMode = "", ActionApplied = "")
| extend
    EventVendor       = "Secure Domains",
    EventProduct      = "Logs Connector",
    EventType         = "lookup",
    EventSubType      = "response",
    EventSchema       = "Dns",
    EventSchemaVersion= "0.1.6",
    EventResult       = iff(_Blocked, "Failure", "Success"),
    DnsResponseCodeName = iff(_Blocked, "NXDOMAIN", "NOERROR"),
    DvcAction         = iff(_Blocked, "Block", "Allow"),
    SrcIpAddr         = ClientPublicIP,
    SrcPortNumber     = toint(ClientPort),
    DnsQuery          = QueriedDomain,   // queried FQDN, from dhost / destinationDnsDomain
    DnsQueryTypeName  = RecordType,
    Dvc               = ResolverHost,
    DvcHostname       = ResolverHost,
    DvcId             = ResolverId,
    SrcUsername       = UserName,
    SrcHostname       = ComputerName
| project-away _Blocked


// =====================================================================
// Example detections
// =====================================================================

// Endpoints with a spike in blocked lookups (possible C2 beaconing)
SecureDomainsRPZ
| where IsBlocked
| summarize Blocks = count(), Domains = dcount(QueriedDomain)
    by EndpointAgent, ClientPublicIP, TenantName, bin(TimeGenerated, 1h)
| where Blocks > 50
| order by Blocks desc

// A resolver that stopped reporting — silent-failure watchdog
SecureDomainsAll
| summarize LastSeen = max(TimeGenerated) by ResolverId
| where LastSeen < ago(30m)

// Portal changes made outside business hours
SecureDomainsAudit
| extend Hour = datetime_part("hour", TimeGenerated)
| where Hour < 6 or Hour > 20
| project TimeGenerated, OperatorUser, ActionType, ResourceType, ResourceName, TenantName

D.9 Splunk Onboarding#

Splunk has no native CEF parsing, so a small Technology Add-on (TA) defines the extraction. Create the app directory $SPLUNK_HOME/etc/apps/TA-secure-domains/, place the four .conf files below in its default/ folder and the lookup CSV in its lookups/ folder, then restart Splunk. Source types are split per stream so CIM tagging can differ (DNS vs Change). The CIM query field is a calculated field — coalesce(destinationDnsDomain, dhost) — rather than a field alias, so it stays single-valued (a double alias would break | stats count by query and dedup) and remains correct whether or not destinationDnsDomain is ever present (see D.2.4).

props.conf

📄 File: props.conf

# Secure Domains — Splunk props.conf
# Place in $SPLUNK_HOME/etc/apps/TA-secure-domains/default/
#
# Splunk has no native CEF parsing, so this defines the extraction. Source
# types are split per stream so CIM tagging can differ (DNS vs Change).

[secure_domains:cef]
SHOULD_LINEMERGE = false
LINE_BREAKER = ([\r\n]+)
TRUNCATE = 8192
TIME_PREFIX = \srt=
TIME_FORMAT = %s%3N
MAX_TIMESTAMP_LOOKAHEAD = 20
# rt is epoch MILLIseconds. If rt is absent (typed field omitted) Splunk falls
# back to the syslog header time, which is why the fallback is left enabled.
KV_MODE = none
REPORT-cef_header = cef_header_extract
REPORT-cef_extension = cef_extension_kv
EVAL-vendor = "Secure Domains"
EVAL-product = "Logs Connector"
FIELDALIAS-sd_common = src AS src_ip dhost AS query suser AS user shost AS src_host
LOOKUP-sd_signature = secure_domains_signature signature_id OUTPUT stream_name

# Per-stream sourcetypes. Route to these with a transform on the syslog TAG
# (dns-rpz / dns-query / audit) — see transforms.conf.
[secure_domains:dns-rpz]
SHOULD_LINEMERGE = false
LINE_BREAKER = ([\r\n]+)
TIME_PREFIX = \srt=
TIME_FORMAT = %s%3N
KV_MODE = none
REPORT-cef_header = cef_header_extract
REPORT-cef_extension = cef_extension_kv
FIELDALIAS-sd_rpz = src AS src_ip suser AS user cs1 AS record_type cs2 AS rpz_policy cs3 AS rpz_rule cs4 AS tenant_name cs5 AS rpz_mode cs6 AS endpoint_agent flexString1 AS endpoint_type
# query (CIM Network Resolution) is a calculated field, not a FIELDALIAS,
# because the FQDN now arrives twice: dhost and destinationDnsDomain hold the
# identical value. Aliasing both onto query would make it multivalue with the
# same string twice, which breaks `| stats count by query` and dedup. coalesce
# prefers the explicit DNS key but falls back to dhost so events indexed before
# destinationDnsDomain existed stay searchable on the same CIM field name.
# Calculated fields run after aliasing, so this wins regardless of ordering.
EVAL-query = coalesce(destinationDnsDomain, dhost)
EVAL-action = if(match(act,"^REDIRECT"),"blocked","allowed")
EVAL-vendor_product = "Secure Domains Logs Connector"

[secure_domains:dns-query]
SHOULD_LINEMERGE = false
LINE_BREAKER = ([\r\n]+)
TIME_PREFIX = \srt=
TIME_FORMAT = %s%3N
KV_MODE = none
REPORT-cef_header = cef_header_extract
REPORT-cef_extension = cef_extension_kv
FIELDALIAS-sd_query = src AS src_ip suser AS user cs1 AS record_type cs4 AS tenant_name cs6 AS endpoint_agent flexString1 AS endpoint_type
# Same duplicate-FQDN situation as dns-rpz — see the note in that stanza for why
# this is a coalesce EVAL instead of a second alias onto query.
EVAL-query = coalesce(destinationDnsDomain, dhost)
EVAL-action = "allowed"
EVAL-vendor_product = "Secure Domains Logs Connector"

[secure_domains:audit]
SHOULD_LINEMERGE = false
LINE_BREAKER = ([\r\n]+)
TIME_PREFIX = \srt=
TIME_FORMAT = %s%3N
KV_MODE = none
REPORT-cef_header = cef_header_extract
REPORT-cef_extension = cef_extension_kv
FIELDALIAS-sd_audit = src AS src_ip suser AS user cs1 AS object_category cs2 AS object cs3 AS user_email cs4 AS tenant_name cs5 AS customer_name msg AS command
EVAL-vendor_product = "Secure Domains Logs Connector"

transforms.conf

📄 File: transforms.conf

# Secure Domains — Splunk transforms.conf

# --- CEF header: the seven pipe-delimited fields -------------------------
# Pipes inside header values are escaped as \| so the negated class must allow
# an escaped pipe through: (?:[^|\\]|\\.)*
[cef_header_extract]
REGEX = CEF:(?<cef_version>\d+)\|(?<vendor>(?:[^|\\]|\\.)*)\|(?<product>(?:[^|\\]|\\.)*)\|(?<product_version>(?:[^|\\]|\\.)*)\|(?<signature_id>(?:[^|\\]|\\.)*)\|(?<name>(?:[^|\\]|\\.)*)\|(?<severity>(?:[^|\\]|\\.)*)\|
MV_ADD = false

# --- CEF extension: key=value, values may contain spaces -----------------
# A value runs until the next ' key=' token. The lookahead is what makes
# space-bearing values (device names, actions) parse correctly. Do NOT
# replace this with a whitespace split.
[cef_extension_kv]
REGEX = (?:^|\s)([A-Za-z][A-Za-z0-9]*)=((?:[^\s\\]|\\.)*(?:\s(?![A-Za-z][A-Za-z0-9]*=)(?:[^\s\\]|\\.)*)*)
FORMAT = $1::$2
MV_ADD = true

# --- Route each stream to its own sourcetype by syslog TAG ---------------
[secure_domains_route_sourcetype]
REGEX = \s(dns-rpz|dns-query|audit):\s+CEF:0\|
FORMAT = sourcetype::secure_domains:$1
DEST_KEY = MetaData:Sourcetype

[secure_domains_signature]
filename = secure_domains_signature.csv

eventtypes.conf

📄 File: eventtypes.conf

# Secure Domains — CIM eventtypes
[secure_domains_dns_rpz]
search = sourcetype=secure_domains:dns-rpz

[secure_domains_dns_query]
search = sourcetype=secure_domains:dns-query

[secure_domains_dns_all]
search = sourcetype=secure_domains:dns-rpz OR sourcetype=secure_domains:dns-query

[secure_domains_audit]
search = sourcetype=secure_domains:audit

tags.conf

📄 File: tags.conf

# Secure Domains — CIM data model tagging
# DNS streams -> Network Resolution (DNS)
[eventtype=secure_domains_dns_all]
network = enabled
resolution = enabled
dns = enabled

# RPZ blocks additionally satisfy Intrusion Detection / Alerts
[eventtype=secure_domains_dns_rpz]
attack = enabled

# Portal audit -> Change
[eventtype=secure_domains_audit]
change = enabled
audit = enabled

inputs.conf (example)

📄 File: inputs.conf.example

# Secure Domains — example input.
# The resolver sends RFC3164 syslog on facility local4 (PRI 166).
# Prefer TCP/TLS over UDP: RPZ records approach the 1024-byte UDP limit.

[tcp://514]
sourcetype = secure_domains:cef
index = netops
# The transforms.conf router re-assigns the sourcetype per stream using the
# syslog TAG, so this value is only the pre-routing default.

lookups/secure_domains_signature.csv

📄 File: secure_domains_signature.csv

signature_id,stream_name
1001,DNS RPZ
1002,DNS Query
1003,Audit Log

D.10 QRadar Onboarding#

1. Log Source
   • Log Source Type: Universal CEF
   • Protocol: Syslog (TCP recommended; see the UDP caveat in D.3)
   • Log Source Identifier: the resolver hostname, which is the syslog HOSTNAME field and also arrives as dvchost / deviceExternalId
2. Log Source Extension: Admin → Data Sources → Log Source Extensions → Add; upload the LSX below and attach it to the log source
3. QID mapping: import the QID map below with /opt/qradar/bin/qidmap_cli.sh -i -f SecureDomains_QIDmap.csv. Without this, every record lands as an unknown event and cannot be used in rules or reports by name
4. Custom Event Properties: create CEPs for the labelled custom strings so they are searchable by name — cs1 DnsRecordType, cs2 RpzPolicy, cs3 RpzRule, cs4 TenantName, cs5 RpzMode, cs6 EndpointAgent, flexString1 EndpointType (regex patterns are in the LSX; meanings in D.2)

⚡ IMPORTANT A CEP for the queried name is not optional if you intend to search on it. QRadar's normalised event model has no field for a DNS query name — the LSX matcher field list is network- and identity-oriented, and none of it describes a queried domain. A CEP is the correct mechanism (the same route IBM's own QRadar DNS Analyzer app takes for its DNS fields): use pattern ext_dst_dns_domain from the LSX, capture group 1, and enable Optimize parsing so the property is searchable without a payload scan. Scope the CEP to the DNS QIDs (1001/1002) — audit records (1003) carry no queried name, so a wider scope just wastes regex evaluation on every audit event. dhost is parsed natively by the Universal CEF DSM and remains the zero-configuration way to reach the queried name.

⚠️ CRITICAL Do not map the queried name onto the HostName matcher field to avoid the CEP. HostName is the identity host name and is already fed by shost (the client computer name); overwriting it with the queried FQDN would attach bogus asset identities like mask.icloud.com to the client IP and corrupt the asset database.

SecureDomains_LogSourceExtension.xml

📄 File: SecureDomains_LogSourceExtension.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
  Secure Domains - QRadar Log Source Extension (LSX)

  Import: Admin > Data Sources > Log Source Extensions > Add, upload this file,
  then attach it to the log source whose type is "Universal CEF".

  QRadar's Universal CEF DSM already parses standard CEF keys. This extension
  adds two things it cannot infer:
    1. EventCategory taken from the CEF SignatureID (1001/1002/1003), so each
       stream maps to its own QID instead of everything collapsing to one
       "Unknown CEF" event.
    2. Custom property extraction for the labelled cs1..cs6 / flexString1
       fields, plus destinationDnsDomain, which QRadar otherwise stores
       unparsed. QRadar's normalised event model has no DNS query name field,
       so these patterns exist to be reused verbatim as the regex of a Custom
       Event Property (see README.md) rather than to feed a matcher.
-->
<device-extension xmlns="event_parsing/device_extension">

  <pattern id="cef_signature_id"    xmlns=""><![CDATA[CEF:\d+\|[^|]*\|[^|]*\|[^|]*\|([^|]*)\|]]></pattern>
  <pattern id="cef_name"            xmlns=""><![CDATA[CEF:\d+\|[^|]*\|[^|]*\|[^|]*\|[^|]*\|([^|]*)\|]]></pattern>
  <pattern id="cef_severity"        xmlns=""><![CDATA[CEF:\d+\|[^|]*\|[^|]*\|[^|]*\|[^|]*\|[^|]*\|([^|]*)\|]]></pattern>

  <!-- Values may contain spaces; each stops at the next ' key=' token. -->
  <pattern id="ext_src"             xmlns=""><![CDATA[(?:^|\s)src=(\S+)]]></pattern>
  <pattern id="ext_spt"             xmlns=""><![CDATA[(?:^|\s)spt=(\d+)]]></pattern>
  <pattern id="ext_dhost"           xmlns=""><![CDATA[(?:^|\s)dhost=(\S+)]]></pattern>
  <!-- Same queried FQDN as dhost, under the CEF dictionary's DNS-specific key.
       Kept as its own pattern because a DNS-aware consumer keys on this name,
       and because dhost may be dropped from the stream later without this one
       following it. The lookahead (not \S+) is used for consistency with the
       other free-text keys: it is the form that stays correct if a value ever
       arrives with a space in it, e.g. an escaped or malformed name. -->
  <pattern id="ext_dst_dns_domain"  xmlns=""><![CDATA[(?:^|\s)destinationDnsDomain=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_suser"           xmlns=""><![CDATA[(?:^|\s)suser=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_shost"           xmlns=""><![CDATA[(?:^|\s)shost=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_act"             xmlns=""><![CDATA[(?:^|\s)act=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_stranslated"     xmlns=""><![CDATA[(?:^|\s)sourceTranslatedAddress=(\S+)]]></pattern>
  <pattern id="ext_devext_id"       xmlns=""><![CDATA[(?:^|\s)deviceExternalId=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_dvchost"         xmlns=""><![CDATA[(?:^|\s)dvchost=(\S+)]]></pattern>
  <pattern id="ext_cs1"             xmlns=""><![CDATA[(?:^|\s)cs1=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_cs2"             xmlns=""><![CDATA[(?:^|\s)cs2=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_cs3"             xmlns=""><![CDATA[(?:^|\s)cs3=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_cs4"             xmlns=""><![CDATA[(?:^|\s)cs4=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_cs5"             xmlns=""><![CDATA[(?:^|\s)cs5=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_cs6"             xmlns=""><![CDATA[(?:^|\s)cs6=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>
  <pattern id="ext_flex1"           xmlns=""><![CDATA[(?:^|\s)flexString1=(.*?)(?=\s[A-Za-z][A-Za-z0-9]*=|$)]]></pattern>

  <match-group order="1" description="Secure Domains Logs Connector" device-type-id-override="4000">

    <matcher field="EventCategory"   order="1" pattern-id="cef_signature_id" capture-group="1"/>
    <matcher field="EventName"       order="1" pattern-id="cef_name"         capture-group="1"/>
    <matcher field="Severity"        order="1" pattern-id="cef_severity"     capture-group="1"/>

    <matcher field="SourceIp"        order="1" pattern-id="ext_src"          capture-group="1"/>
    <matcher field="SourcePort"      order="1" pattern-id="ext_spt"          capture-group="1"/>
    <matcher field="UserName"        order="1" pattern-id="ext_suser"        capture-group="1"/>
    <matcher field="Identity HostName" order="1" pattern-id="ext_shost"      capture-group="1"/>
    <matcher field="PreNatSourceIp"  order="1" pattern-id="ext_stranslated"  capture-group="1"/>
    <matcher field="DeviceId"        order="1" pattern-id="ext_devext_id"    capture-group="1"/>

    <event-match-multiple device-event-category="1001" event-name="DNS RPZ"    severity="7"/>
    <event-match-multiple device-event-category="1002" event-name="DNS Query"  severity="2"/>
    <event-match-multiple device-event-category="1003" event-name="Audit Log"  severity="5"/>

  </match-group>
</device-extension>

ℹ️ NOTE device-type-id-override="4000" in the LSX is a placeholder. Replace it with the device type ID QRadar assigns your Universal CEF log source.

SecureDomains_QIDmap.csv

📄 File: SecureDomains_QIDmap.csv

name,description,severity,lowlevelcategory,eventid,vendorid
DNS RPZ Block,Secure Domains DNS firewall applied an RPZ policy to a lookup,7,18054,1001,0
DNS Query,Secure Domains resolver answered a DNS lookup,2,18051,1002,0
Portal Audit,Secure Domains portal configuration change,5,8054,1003,0

D.11 Elastic Onboarding#

The Elastic CEF integration already decodes the envelope, so nothing is required to ingest. The optional ingest pipeline below renames the decoded custom strings into meaningful ECS-style fields and sets event.dataset / event.category per stream. Create it with PUT _ingest/pipeline/secure-domains-cef (or via Kibana → Stack Management → Ingest Pipelines) and attach it to the CEF integration's data stream:

dns.question.name is fed from destinationHostName, with a guarded fallback rename from destinationDnsDomain only when the primary is absent (and a duplicate-value drop so the two never collide — see D.2.4). destinationDnsDomain is deliberately not mapped to dns.question.registered_domain: this producer would put the full FQDN in it, not a registrable domain — derive registered_domain downstream (e.g. a registered_domain processor over dns.question.name) if you need it. Caveat: a CEF decoder running in ECS mode may itself copy destinationDnsDomain to destination.registered_domain (the Logstash CEF codec documents that mapping); verify on your deployment and drop it there if present.

📄 File: secure-domains-cef-pipeline.json

{
  "description": "Secure Domains CEF -> ECS. The Elastic CEF integration already decodes the envelope; this pipeline renames the decoded custom strings into meaningful ECS-ish fields. DNS records (SignatureID 1001/1002) carry the queried FQDN twice, in dhost and destinationDnsDomain; audit records (1003) carry neither. destinationHostName is the authoritative source for dns.question.name; destinationDnsDomain is used only as a fallback when destinationHostName is absent, and is dropped when it duplicates the value already mapped, so the two never collide on one target. destinationDnsDomain is deliberately NOT mapped to dns.question.registered_domain: this producer puts the full FQDN in it, not a registrable domain. Derive registered_domain/top_level_domain downstream (e.g. a registered_domain processor over dns.question.name) if you need them. Caveat: if the upstream CEF decoder runs in ECS mode it may itself copy destinationDnsDomain to destination.registered_domain (the Logstash CEF codec documents that mapping); that copy would also hold the full FQDN, so verify on your deployment and drop it there if present.",
  "processors": [
    { "set": { "field": "event.module",  "value": "secure_domains" } },
    { "set": { "field": "observer.vendor", "value": "Secure Domains" } },
    { "set": { "field": "observer.product", "value": "Logs Connector" } },
    { "rename": { "field": "cef.extensions.deviceExternalId", "target_field": "observer.name", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.deviceHostName",   "target_field": "observer.hostname", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.destinationHostName", "target_field": "dns.question.name", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.destinationDnsDomain", "target_field": "dns.question.name", "ignore_missing": true, "if": "ctx.dns?.question?.name == null" } },
    { "remove": { "field": "cef.extensions.destinationDnsDomain", "ignore_missing": true, "if": "ctx.dns?.question?.name != null && ctx.dns.question.name == ctx.cef?.extensions?.destinationDnsDomain" } },
    { "rename": { "field": "cef.extensions.deviceCustomString1", "target_field": "dns.question.type", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.sourceAddress", "target_field": "source.ip", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.sourcePort",    "target_field": "source.port", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.sourceTranslatedAddress", "target_field": "source.nat.ip", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.sourceUserName", "target_field": "user.name", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.sourceHostName", "target_field": "host.name", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.deviceAction",   "target_field": "event.action", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.deviceCustomString4", "target_field": "organization.name", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.deviceCustomString2", "target_field": "rule.ruleset", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.deviceCustomString3", "target_field": "rule.name", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.deviceCustomString6", "target_field": "device.model.name", "ignore_missing": true } },
    { "rename": { "field": "cef.extensions.flexString1", "target_field": "device.manufacturer", "ignore_missing": true } },
    { "script": { "lang": "painless", "source": "def sid = ctx.cef?.device?.event_class_id; if (sid == '1001') { ctx.event.dataset = 'secure_domains.rpz'; ctx.event.category = ['network']; ctx.event.type = ['denied','info']; } else if (sid == '1002') { ctx.event.dataset = 'secure_domains.query'; ctx.event.category = ['network']; ctx.event.type = ['allowed','info']; } else if (sid == '1003') { ctx.event.dataset = 'secure_domains.audit'; ctx.event.category = ['configuration']; ctx.event.type = ['change']; }" } }
  ]
}

D.12 Advanced: Envelope Options and Rollback#

Both the CEF extension format and the syslog envelope replaced an older output format. If a downstream consumer is not yet ready, you can revert per shipper with no code change by adding flags to the shipper service unit's ExecStart line on the Local Resolver VM console (one systemd unit per stream: dns-rpz, dns-query, audit):

Use --legacy-extension --syslog-framing=legacy together for a complete revert to pre-change output.

⚠️ CRITICAL --syslog-framing=legacy emits no <PRI>, so rsyslog will classify the records under facility user — any local4 collector filter (including the D.6 template and the Sentinel DCR) will then silently drop them. Only use legacy framing with consumers that expect the old format.

END OF DOCUMENT

DNS Armor™ Local Resolver - Comprehensive 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