Adguard

Control AdGuard Home DNS filtering via HTTP API. Use when managing blocklists/allowlists, checking domain filtering status, toggling protection, or clearing DNS cache. Supports blocking/allowing domains, viewing statistics, and protecting/disabling DNS filtering.

Security Scan

The skill's code and instructions match the claimed purpose (controlling AdGuard Home) but the registry metadata omits required credentials and some runtime guidance (e.g., ADGUARD_PASSWORD, ADGUARD_URL), creating an incoherence you should verify before installing.

Purpose & Capability

The name/description (AdGuard Home controller) align with the code and SKILL.md: the script talks to AdGuard's HTTP API and performs expected actions (check, block, allow, status, toggle, clear cache). However, the registry metadata declares no required environment variables or primary credential, while both SKILL.md and scripts clearly require ADGUARD_PASSWORD (and optionally ADGUARD_URL and ADGUARD_USERNAME). This mismatch is an inconsistency in the package metadata.

Instruction Scope

SKILL.md instructs the agent/user to authenticate to a local AdGuard Home instance and to use curl and the provided script; runtime actions (login, set_rules, status, cache_clear) are within scope. It suggests network discovery methods (nmap, router admin) which are optional guidance but not required by the script itself. The instructions do direct storage of ADGUARD_PASSWORD in an env var and advise adding it to shell rc — this is expected for the tool but has security implications the user should consider.

Install Mechanism

No install spec; this is an instruction-only skill with an included shell script. Nothing is downloaded from external URLs and no archive extraction occurs, which is lower risk.

Credentials

The tool legitimately requires an admin password and optionally URL/username to contact AdGuard Home. Those credentials are proportionate to the stated functionality. However, the registry claims no required env vars/credentials while the script enforces ADGUARD_PASSWORD — a metadata omission. The script stores a session cookie in /tmp (ephemeral) and does not transmit credentials to external hosts beyond the configured ADGUARD_URL; still, ADGUARD_PASSWORD is sensitive and the SKILL.md recommends putting it in shell rc which may expose it in some setups.

Persistence & Privilege

The skill does not request permanent/global agent privileges: always is false, it does not modify other skills, and it only writes a temporary cookie file in /tmp which is cleaned up on exit. No evidence of elevated or persistent system-wide changes.

What to consider before installing

This skill appears to implement an AdGuard Home controller and the shell script performs expected API calls (login, get status, set rules). However, the registry metadata omits required environment variables (ADGUARD_PASSWORD, ADGUARD_URL, ADGUARD_USERNAME) which the script actually needs — confirm this discrepancy before installing. Review the included scripts yourself (scripts/adguard.sh) to verify there is no network endpoint besides your configured ADGUARD_URL and to ensure credentials are only sent to your local AdGuard instance. Avoid storing the admin password in plain text in shell rc if possible; consider using the suggested ~/.adguard/config.json for non-password fields and provide the password interactively or via a secure secret store. If you don't control the AdGuard host or you cannot verify the source of this skill, test it on an isolated machine or device first. If you want higher assurance, ask the publisher to update the registry metadata to declare required env vars and to explain why any network-scanning suggestions (nmap) are present.

AdGuard Home Controller

Manage AdGuard Home DNS filtering from the command line via the REST API.

Requirements

• AdGuard Home running with web interface
• Admin username and password
• curl installed (usually default on macOS/Linux)

Quick Start

# Set password once
export ADGUARD_PASSWORD=your_admin_password

# Use commands
./adguard.sh status
./adguard.sh check example.com
./adguard.sh allow broken-site.com
./adguard.sh block malware.ru

Configuration

Set environment variables for your AdGuard instance:

export ADGUARD_URL="http://192.168.1.100:3000"      # Your AdGuard IP and port
export ADGUARD_USERNAME="admin"                     # Usually 'admin' (default)
export ADGUARD_PASSWORD="your_admin_password"       # REQUIRED

Add to ~/.bashrc or ~/.zshrc for persistence.

Config File Alternative

Create ~/.adguard/config.json (optional):

{
  "url": "http://192.168.1.100:3000",
  "username": "admin"
}

Then set ADGUARD_PASSWORD separately for security.

Commands

check <domain>

Check if a domain is currently blocked or allowed.

./adguard.sh check doubleclick.net
# ✗ doubleclick.net IS BLOCKED
#   Blocked by: Adblock Plus filter

./adguard.sh check example.com
# ✓ example.com is NOT blocked (allowed)

allow <domain> | whitelist <domain>

Add a domain to the allowlist (whitelist). Creates an exception rule that overrides blocklists.

./adguard.sh allow broken-site.com
# ✓ Added rule: @@||broken-site.com^
#   Domain: broken-site.com
#   Action: allow

block <domain> | blacklist <domain>

Add a domain to the blocklist. Creates a custom blocking rule.

./adguard.sh block spyware-domain.ru
# ✓ Added rule: ||spyware-domain.ru^
#   Domain: spyware-domain.ru
#   Action: block

status | stats

Display DNS filtering statistics and protection state.

./adguard.sh status
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# AdGuard Home Status
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Protection: ✓ ENABLED
# 
# DNS Queries: 1,234
# Blocked by rules: 156
# Blocked by safe browsing: 23
# Safe search replacements: 5
# Block rate: 14%
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

toggle | protection

Enable or disable DNS protection. Useful for temporarily disabling filtering.

./adguard.sh toggle
# Disabling protection...
# ✓ Protection is now false

cache-clear

Clear the DNS cache to apply rule changes immediately.

./adguard.sh cache-clear
# Clearing DNS cache...
# ✓ Cache cleared

Finding Your AdGuard Home Device

If you don't know your AdGuard URL:

1. Router admin panel — Look for a device named "AdGuard Home" or check for port 3000
2. Local network scan — Use nmap or check "Connected Devices"
3. If running on same machine — Default is http://localhost:3000
4. mDNS/Bonjour — Try http://adguard-home.local:3000 (depends on network)

Filtering Rules Syntax

AdGuard uses a DNS filtering rule syntax:

Rule	Effect
||example.com^	Block example.com and subdomains
@@||example.com^	Allow example.com (exception/whitelist)
example.com	Block exact domain only
||ad.example.com^	Block only ad.example.com

See API Reference for complete syntax.

Common Scenarios

Allow a site that's blocked by accident

adguard.sh allow my-bank.com

Block a known malware domain

adguard.sh block malicious-tracker.xyz

Check if a domain is being filtered

adguard.sh check ads.google.com

View today's statistics

adguard.sh status

Temporarily disable filtering (e.g., for troubleshooting)

adguard.sh toggle

Troubleshooting

Error: Failed to authenticate → Check ADGUARD_PASSWORD is correct and set → Verify ADGUARD_URL points to the right IP and port

Error: API call failed (HTTP 401) → Authentication failed, check credentials

Rules don't take effect → Run adguard.sh cache-clear to flush DNS cache → Wait 5+ minutes for clients to refresh their cache → Restart your device's network connection

Can't connect to AdGuard → Verify device is on the same network → Check firewall isn't blocking port 3000 → Ping the device: ping <ip>

Advanced: Batch Operations

Block multiple domains:

for domain in tracker1.com tracker2.com tracker3.com; do
    adguard.sh block "$domain"
done

Check multiple domains:

for domain in example.com test.org my-site.net; do
    echo "Checking $domain..."
    adguard.sh check "$domain"
done

API Reference

See references/api.md for complete AdGuard Home API documentation.