TLS Connection Monitor
Relevant source files
The following files were used as context for generating this wiki page:
The TLS Connection Monitor is a specialized auditing component within the DNS Hardening project designed to ensure that DNS traffic is consistently encrypted via DNS over TLS (DoT). Its primary purpose is to verify that the Unbound resolver is actively maintaining encrypted tunnels to upstream providers on port 853 and to alert the user if the system falls back to unencrypted communication.
This system monitors the operational state of the Unbound service, validates active network sockets, and triggers synthetic queries to confirm that encryption is functional rather than just configured. It integrates with the broader Monitoring System to provide persistent security assurance.
Core Logic and Architecture
The monitor operates by performing a sequential check of the resolver's health and its network connections. It first ensures the service is active, then forces DNS activity to generate observable TLS traffic, and finally inspects the system's network state for active port 853 connections.
Verification Workflow
The monitoring logic follows a strict hierarchy of checks to differentiate between idle resolvers and broken encryption.
The diagram above illustrates the decision-making process used to determine if a lack of TLS connections is a critical failure or expected behavior during idle periods.
Sources: scripts/dns_tls_monitor.sh:17-54, UNBOUND_TLS_STATUS.md:43-55
Monitoring Components
| Component | Description | Reference File |
|---|---|---|
| Active Sockets | Monitors ss -tnp output for established connections to port 853. | UNBOUND_TLS_STATUS.md:6-12 |
| Synthetic Queries | Uses dig to query Cloudflare, Google, and Example.com to force TLS handshakes. | scripts/dns_tls_monitor.sh:23-27 |
| Alerting Engine | Logs critical failures to /var/log/dns_hardening_alerts.log and sends desktop notifications. | scripts/dns_tls_monitor.sh:7-15 |
| Cron Integration | Manages periodic execution (recommended every 30 minutes). | scripts/dns_monitoring_install.sh:34-45 |
Implementation Details
Unbound Configuration Requirements
For the monitor to report a successful state, Unbound must be configured with specific TLS parameters. This includes the tls-cert-bundle for certificate validation and the forward-tls-upstream: yes directive within the forward zone.
# Required configuration for successful TLS monitoring
forward-zone:
name: "."
forward-addr: 1.1.1.1@853#cloudflare-dns.com
forward-addr: 9.9.9.9@853#dns.quad9.net
forward-first: yes
forward-tls-upstream: yes
Sources: configs/unbound.conf:75-87, scripts/dns_tls_monitor.sh:36-39
Connection States
The monitor distinguishes between "Good" and "Bad" states based on the presence of specific network indicators. A "Good" state is characterized by multiple connections to upstream providers like Cloudflare (1.1.1.1) or Quad9 (9.9.9.9) specifically on port 853.
This sequence shows how the monitor active triggers the state it needs to verify before checking the socket table.
Sources: UNBOUND_TLS_STATUS.md:6-12, scripts/dns_tls_monitor.sh:23-31
Detection of Fallback and Compromise
A critical feature of the monitor is detecting when the system bypasses the hardened resolver. This "Fallback Mode" occurs if Unbound is stopped and the system begins using the secondary nameservers defined in resolv.conf over unencrypted port 53.
Indicators of Failure
- Empty Socket Table:
ss -tnp | grep :853returns no output despite active DNS queries. - Missing ad Flag: Queries to
127.0.0.1lack the "Authenticated Data" (ad) flag in the header, indicating DNSSEC/TLS validation failure. - Unbound Inactivity: The
unbound.servicereports a state ofinactive (dead).
Sources: UNBOUND_TLS_STATUS.md:29-41, scripts/dns_tls_monitor.sh:17-21
Installation and Maintenance
The TLS Monitor is typically deployed via the dns_monitoring_install.sh script, which places the monitor in /usr/local/bin/ and configures a root crontab entry.
Configuration Options
Users can select the monitoring frequency during installation, with 30 minutes being the recommended interval to balance security with system overhead.
| Option | Cron Syntax | Use Case |
|---|---|---|
| 5 Minutes | */5 * * * * | High-security environments |
| 30 Minutes | */30 * * * * | Recommended standard |
| Hourly | 0 * * * * | Low-resource systems |
Sources: scripts/dns_monitoring_install.sh:34-45, MONITORING.md:14-23
The TLS Connection Monitor serves as the final validation layer in the DNS hardening stack. By combining service checks, synthetic traffic generation, and network socket inspection, it provides a reliable mechanism to ensure that DNS privacy is maintained through active encryption.