Emergency Restoration Script
Relevant source files
The following files were used as context for generating this wiki page:
The Emergency Restoration Script is a critical recovery utility within the dns-hardening-parrot project designed to restore basic DNS functionality if hardened configurations fail. It serves as a fail-safe mechanism that reverts the system to standard public resolvers, ensuring network connectivity is maintained even when complex security layers like Unbound or DNS over TLS (DoT) encounter issues.
The script primarily addresses the "immutable" protection applied to system files and stops conflicting services that might prevent standard DNS resolution. It is intended for use when the system-wide hardening—which typically places a user in the top 1-2% of global DNS security—becomes an obstacle due to misconfiguration or service failure.
Sources: scripts/dns_restore.sh:1-6, DNS_Hardening_Complete_Guide.md:1-15, README.md:94-110
Core Logic and Execution Flow
The restoration process follows a strict sequential logic to dismantle hardening layers safely while preserving the current (broken) state for later analysis.
Restoration Sequence
The script performs the following primary actions:
- Service Suspension: It stops
unboundandsystemd-resolvedto clear the path for standard resolution. - Configuration Backup: It creates timestamped backups of
/etc/resolv.conf,/etc/unbound/unbound.conf, and/etc/systemd/resolved.confin/root/dns_backups/. - Bypassing Protection: It removes the immutable attribute (
chattr -i) from/etc/resolv.conf, which is a key security feature applied by the hardening script. - Resolver Reset: It overwrites the local resolver settings with a list of trusted public nameservers (Cloudflare, Quad9, Google).
Sources: scripts/dns_restore.sh:54-100, CHANGELOG.md:12-25, scripts/dns_harden.sh:42-45
The following flowchart illustrates the internal logic of the restoration script:
The diagram shows the transition from a hardened, protected state to an emergency recovery state.
Sources: scripts/dns_restore.sh:54-140
Service and Configuration Management
The script manages specific system services and configuration files to ensure the recovery is persistent across reboots until manual intervention occurs.
| Target Element | Action Taken during Restoration | Purpose |
|---|---|---|
unbound | Stopped and Masked | Prevents the hardened local resolver from starting and failing queries. |
systemd-resolved | Stopped, Reset, and Masked | Prevents conflicts with the static resolv.conf and resets its internal configuration. |
/etc/resolv.conf | chattr -i then Overwritten | Removes write protection so the file can be pointed to public resolvers. |
/etc/systemd/resolved.conf | Overwritten with defaults | Disables DNSOverTLS and DNSSEC at the systemd level to ensure baseline compatibility. |
Sources: scripts/dns_restore.sh:57-60, scripts/dns_restore.sh:91-110, DNS_Hardening_Complete_Guide.md:58-95
Monitoring Integration
During execution, the script checks if automated monitoring (installed via dns_monitoring_install.sh) is active. If dns_monitor.sh or dns_alert.sh are found in the crontab, the user is prompted to disable them. This prevents the monitoring system from immediately flagging the emergency restoration as a "compromise."
Sources: scripts/dns_restore.sh:163-176, MONITORING.md:46-60
Key Functions
The script's implementation relies on several utility functions for logging, validation, and testing.
# DNS test function used to verify resolution during and after restoration
test_dns() {
local hostname=${1:-google.com}
timeout 2 nslookup "$hostname" >/dev/null 2>&1
}
# Restoration sequence implementation (Step 3: Removing immutable flag)
chattr -i /etc/resolv.conf 2>/dev/null || true
rm -f /etc/resolv.conf 2>/dev/null || true
Sources: scripts/dns_restore.sh:48-51, scripts/dns_restore.sh:78-80
Diagnostic and Validation Steps
The script performs sequential DNS tests against multiple domains (google.com, example.com, cloudflare.com) to ensure the emergency nameservers are reachable and functional. It provides a final system status report including active nameservers and service states.
Sources: scripts/dns_restore.sh:113-130
Data Infrastructure
The script interacts with several directories and log locations to ensure a traceable recovery process.
- Log Location:
/tmp/dns_restore_YYYYMMDD_HHMMSS.log - Backup Root:
/root/dns_backups/backup_YYYYMMDD_HHMMSS/ - State Management: It interacts with
/etc/resolv.confand/etc/systemd/resolved.conf.
Sources: scripts/dns_restore.sh:18-20, CHANGELOG.md:44-48
Conclusion
The Emergency Restoration Script is the primary safety net for the dns-hardening-parrot project. By automating the removal of kernel-level file protections (immutable flags) and reverting service configurations to known-good defaults, it reduces recovery time from minutes of manual troubleshooting to under 30 seconds. This utility is essential for maintaining system availability in the event of upstream TLS failures or local configuration errors.