ShieldDNS for Home Assistant

Monitor and manage your privately hosted ShieldDNS ad-blocking and DNS resolver directly from Home Assistant. Track DNS queries, monitor blocklist effectiveness, and instantly toggle global web-filtering protection with ease.

ShieldDNS provides high-performance encrypted DoH/DoT DNS resolution with powerful ad and malware blocking. This integration provides native monitoring via the ShieldDNS API, allowing you to track daily queries, view how many ads were blocked, and control the entire protection mechanism (On/Off) instantly from your Home Assistant dashboard.

No manual script-polling or complex setup is required — everything is handled via a modern, auto-discovering Config Flow.

• DNS Monitoring:
  • Total Queries: Track exactly how many DNS requests were made across your network today.
  • Blocked Queries: See how many ads, trackers, and malicious domains were stopped.
  • Block Percentage: Real-time ratio of blocked vs allowed traffic.
  • Unique Clients: Monitor how many individual devices are currently utilizing ShieldDNS.
  • Real-time QPS: Monitor your current Queries Per Second (10s average) for instant load feedback.
  • Performance Metrics: Monitor Average Response Time (latency) and Cache Hit Ratio to ensure peak resolution speed.
• Instance Management:
  • Global Filtering (Toggle): Instantly suspend or resume all blocklists and filtering across your entire network with a single switch.
  • Maintenance Buttons:
    • Refresh Blocklists: Sync and update your filter lists.
    • Reload Filters & DNS: Full synchronization and DNS engine restart.
    • Recheck Upstreams: Trigger a health check for upstream DNS servers.
    • Clear Query Logs: Flush the SQLite query history with one click.
• Diagnostics:
  • Download Diagnostics: Native support for Home Assistant diagnostic reports (redacted for privacy).
• System Information:
  • Track your ShieldDNS instance performance directly via sensors.
• Native Experience:
  • Full Localization: English translations included (more coming soon).
  • Modern UI: High-quality icons and branding for a premium dashboard look.

I maintain this integration in my free time alongside my regular job — bug hunting, new features, and keeping up with OCI updates. Every donation helps me stay independent and dedicate more time to open-source work.

This project is and will always remain 100% free.

Donations are completely voluntary — but the more support I receive, the more time I can realistically invest into these projects. 💪

1. Open HACS in Home Assistant.
2. Click the three dots -> Custom repositories.
3. Add FaserF/ha-shielddns with category Integration.
4. Search for ShieldDNS.
5. Install and restart Home Assistant.

1. Download the latest release from the Releases page.
2. Extract the custom_components/shielddns folder to your Home Assistant custom_components directory.
3. Restart Home Assistant.

The integration requires an API Token to communicate with your ShieldDNS instance securely.

1. Open the ShieldDNS Web UI and navigate to Settings > API Keys.
2. Create a new API key with the following permissions:
   • read:stats (Required for sensors and status)
   • read:diagnostics (Required for diagnostic reports)
   • write:rules (Required for toggling protection, adding/removing rules, and client management)
   • write:maintenance (Required for maintenance buttons like Refresh, Reload, Clear Logs, etc.)
3. Copy the generated token.
4. Note down the generated API Token.

1. Go to Settings > Devices & Services.
2. Click Add Integration and search for ShieldDNS.
3. Enter the following details:
   • Host: The IP address or hostname of your ShieldDNS server (e.g. 192.168.1.100).
   • Port: The Admin port of your ShieldDNS instance (usually 443 or 8080).
   • API Token: The token you generated in Step 1.
4. The integration will now connect, authenticate, and automatically add your sensors and switches.

The integration provides the following entities to monitor and control your DNS network:

• Total Queries Today: Absolute count of all DNS requests processed today.
• Blocked Queries Today: Absolute count of requests blocked by your filter lists.
• Block Percentage: The percentage of today's total traffic that was blocked.
• Unique Clients: How many client IPs have made queries in the last 24 hours.
• Avg. Response Time: The average latency of DNS resolutions in milliseconds.
• Cache Hit Ratio: Effectiveness of the local cache (percentage of queries served from cache).
• CPU Load (1m): The current 1-minute system load average.
• Memory Usage: Amount of RAM currently utilized by the system (in MB).
• Database Size: Current size of the SQLite query database on disk.
• Auto-Blocked Clients: Number of clients currently under automated abuse protection.
• Connected Clients: Real-time count of all unique devices that have utilized ShieldDNS for resolution.
• Current QPS: Real-time Queries Per Second processed by the engine (10s rolling average).
• Blocked Domains (Total): Total number of unique domains currently blocked across all active lists.
• System Uptime: The duration since the ShieldDNS service was last started.

• Abuse Protection Active: On if any client is currently blocked due to malicious behavior patterns.
• DNS Server Health: On if the CoreDNS engine is healthy and responding to queries.

• ShieldDNS Update: Monitor and trigger updates for the ShieldDNS core application.

• Global Filtering: Turn this off to temporarily disable all ad-blocking and filtering. Turn it back on to resume normal protection.

• Refresh Blocklists: Fetch the latest updates for all subscribed filter lists.
• Reload Filters & DNS: Performs a full sync of configuration and restarts the DNS engine.
• Recheck Upstreams: Triggers a manual health and latency check for configured upstream servers.
• Clear Query Logs: Deletes all recorded DNS query history from the database.

• shielddns.block_domain: Instantly add a domain to the blocklist.
• shielddns.allow_domain: Instantly add a domain to the allowlist.
• shielddns.remove_rule: Remove a domain rule from both lists.
• shielddns.set_client_alias: Assign a friendly name (alias) to a client's IP address.
• shielddns.block_client: Toggle blocking status for a specific client device by its IP.

Maximize your network control with these advanced automation examples.

alias: "ShieldDNS: Temporary Device Bypass"
description: "Unblocks a client IP for 1 hour"
trigger:
  - platform: state
    entity_id: input_boolean.bypass_gaming_pc
    to: "on"
action:
  - service: shielddns.block_client
    data:
      ip: "192.168.1.50"
      block: false
  - delay: "01:00:00"
  - service: shielddns.block_client
    data:
      ip: "192.168.1.50"
      block: true
  - service: input_boolean.turn_off
    target:
      entity_id: input_boolean.bypass_gaming_pc

alias: "ShieldDNS: High Block-Rate Warning"
trigger:
  - platform: numeric_state
    entity_id: sensor.shielddns_block_percentage
    above: 40
    for: "00:05:00"
action:
  - service: notify.mobile_app_your_phone
    data:
      title: "🛡️ ShieldDNS Security Alert"
      message: "High block rate detected! {{ states('sensor.shielddns_block_percentage') }}% of queries are being blocked."
      data:
        clickAction: "/config/devices/dashboard"

alias: "ShieldDNS: Night-time Console Block"
trigger:
  - platform: time
    at: "20:00:00"
    id: "night"
  - platform: time
    at: "08:00:00"
    id: "morning"
action:
  - service: shielddns.block_client
    data:
      ip: "192.168.1.135"
      block: "{{ trigger.id == 'night' }}"

alias: "ShieldDNS: Release Notification"
trigger:
  - platform: state
    entity_id: update.shielddns_update
    from: "off"
    to: "on"
action:
  - service: notify.mobile_app_your_phone
    data:
      title: "🚀 Update Available: ShieldDNS"
      message: "A new version ({{ state_attr('update.shielddns_update', 'latest_version') }}) is available. Current: {{ state_attr('update.shielddns_update', 'installed_version') }}"

alias: "ShieldDNS: Maintenance Protection Toggle"
trigger:
  - platform: state
    entity_id: binary_sensor.backup_running
    to: "on"
    id: "disable"
  - platform: state
    entity_id: binary_sensor.backup_running
    to: "off"
    id: "enable"
action:
  - service: switch.turn_{{ 'off' if trigger.id == 'disable' else 'on' }}
    target:
      entity_id: switch.shielddns_global_filtering

alias: "ShieldDNS: Switch to Strict Mode"
trigger:
  - platform: state
    entity_id: binary_sensor.guest_wifi_active
    to: "on"
action:
  - service: shielddns.block_domain
    data:
      domain: "tiktok.com"
  - service: shielddns.block_domain
    data:
      domain: "roblox.com"

• Double-check your Host and Port. If your ShieldDNS is behind a reverse proxy, ensure the port matches the external proxy port.
• Ensure the API Token was copied correctly and hasn't been revoked.

• This usually indicates a permissions issue. Ensure your API Token has the write:filtering permission to toggle state modifications.

# Setup development environment
pip install requirements_test.txt

# Run tests
pytest

# Run linter
ruff check .

MIT License. See LICENSE for details.