adguard-monitor/README.md

AdGuard Monitor

Monitoring service for AdGuard DNS queries with notifications sent to Home Assistant.

Who is this for?

This is for me mainly, so let's see if you need it too. Adguard Monitor is designed for openclaw, which should usually NEVER make a request that needs to be blocked. If it does, I want to know about it immediately.

Features

• Multi-Client Support: Monitor specific IP addresses and receive nicknamed notifications (e.g., "BLOCKED: My Laptop").
• Strict Configuration: Fails fast if environment variables are missing.
• Home Assistant Notifications: Native mobile push messages for blocked queries.
• Custom Domain Monitoring: Monitor specific domains using list.txt (wildcards supported).
• Structured Logging: UTF-8 encoded logging for unicode emoji support.

Docker (Recommended)

You can run the monitor as a Docker container using the provided docker-compose.yml.

1. Configure environment: Copy .env.example to .env and fill in your details.
2. Start the container:

   docker compose up -d
   

Manual Setup

1. Clone the repository.

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment: Copy .env.example to .env and fill in your details:

   cp .env.example .env
   

4. Custom Domains (Optional): Copy list.example.txt to list.txt and add domains:

   cp list.example.txt list.txt
   

   • Lines starting with ! are negative filters (they will be ignored).
   • Wildcards like *.example.com are supported.

5. Run the monitor:

   python monitor.py --interval 15
   

Environment Variables

• ADGUARD_URL: Full URL of your AdGuard instance (e.g., http://192.168.1.50).
• ADGUARD_USER: API username.
• ADGUARD_PASSWORD: API password.
• CLIENTS: A JSON-formatted dictionary mapping IPs to display names.
  • Example: {"192.168.1.100": "My Laptop", "192.168.1.101": "My Phone"}
• HASS_URL: Home Assistant mobile notification endpoint (e.g. https://your-hass.com/api/services/notify/mobile_app_phone).
• HASS_TOKEN: Home Assistant Long-Lived Access Token.
• HASS_TITLE_TEMPLATE: (Optional) Template for notification title. Available: {event_type}, {client_name}, {host}, {reason}. Default: {event_type}.
• HASS_MSG_TEMPLATE: (Optional) Template for notification body. Available: same as title. Default: {client_name} tried to access "{host}".