High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The DNS Hardening Parrot project implements a multi-layered security architecture designed to provide enterprise-grade DNS security and privacy on Parrot OS. The system centers around a local Unbound recursive resolver that enforces DNS over TLS (DoT) and DNSSEC validation, shielded by kernel-level file protections to prevent unauthorized configuration changes by system services like NetworkManager or Portmaster.
The architecture is composed of three primary functional domains: the Resolution Layer (Unbound), the Protection Layer (Immutable configurations), and the Monitoring & Recovery Layer (Automation scripts). This structure ensures that DNS queries are encrypted, authenticated, and resilient against local or network-based tampering.
Sources: README.md:1-20, DNS_Hardening_Complete_Guide.md:3-15
Core System Components
The architecture relies on the orchestration of local services, system configurations, and maintenance scripts to maintain a hardened state.
Resolution Layer: Unbound Resolver
The heart of the architecture is the Unbound DNS Resolver. It is configured to act as the primary nameserver (127.0.0.1) for the local system. It handles recursive lookups by forwarding queries to trusted upstream providers (Cloudflare and Quad9) strictly via Port 853 using TLS encryption.
Sources: configs/unbound.conf:4-10, configs/unbound.conf:65-75
Protection Layer: Immutable Configuration
To prevent "DNS hijacking" by local services, the system employs the chattr +i command on /etc/resolv.conf. This creates a kernel-level lock that prevents even the root user or automated services from modifying the DNS settings until the flag is explicitly removed.
Sources: scripts/dns_harden.sh:42-43, README_SHORT.md:38-40
Monitoring & Recovery Layer
The architecture includes a suite of scripts that provide continuous state verification and emergency restoration.
| Component | File Path | Function |
|---|---|---|
| Hardening Engine | scripts/dns_harden.sh | Configures NetworkManager, sets up Unbound, and applies immutable flags. |
| Status Checker | scripts/dns_status.sh | Provides a real-time visual report of the hardening state. |
| State Monitor | scripts/dns_monitor.sh | Periodic script that tracks state changes in a statefile. |
| Emergency Restore | scripts/dns_restore.sh | Removes protections and reverts to public DNS in case of failure. |
| Sources: README.md:35-70, CHANGELOG.md:13-25 |
Logical Data Flow
The following diagram illustrates how a DNS query travels from a local application through the hardened infrastructure to the internet.
The flow ensures that every query is validated for authenticity via DNSSEC and encrypted via DoT before leaving the local machine.
Sources: configs/unbound.conf:28-32, DNS_Hardening_Complete_Guide.md:162-175
Security Implementation Details
Unbound Hardening Configuration
The Unbound configuration utilizes several security directives to minimize the attack surface and maximize privacy.
- Query Minimization:
qname-minimisation: yesensures only the minimum necessary information is sent to upstream servers. - Rebinding Protection:
private-addressdirectives block DNS responses containing private IP ranges (e.g.,192.168.0.0/16), preventing attacks on internal network resources. - Identity Protection:
hide-identityandhide-versionare enabled to prevent fingerprinting of the DNS service.
Sources: configs/unbound.conf:18-19, configs/unbound.conf:53-62
System Integration and Locking
The architecture modifies the system's network management behavior to ensure the hardened state persists across reboots and network changes.
By setting dns=none in NetworkManager and making resolv.conf immutable, the architecture creates a redundant lock against configuration drift.
Sources: scripts/dns_harden.sh:45-53, TEST_RESULTS.md:12-14
Monitoring and Alerting Architecture
The monitoring system uses a "State vs. Alert" model to maintain visibility into the system's security posture.
Conclusion
The High-Level Architecture of the DNS Hardening Parrot project establishes a robust, self-monitoring defense-in-depth strategy. By combining the cryptographic strengths of DNSSEC and DNS over TLS with the administrative finality of immutable file attributes, the system ensures that DNS remains a secure and private utility, resistant to both external network attacks and local software interference.
Sources: DNS_Hardening_Complete_Guide.md:155-160, README.md:105-110