SimpleGuardHome

A modern web application for checking and adding domains to custom filtering rules in AdGuard Home. Built with FastAPI and modern JavaScript, following the official AdGuard Home OpenAPI specification. Meant as a simple AdGuard Home web interface for users to check if a domain is blocked, and then add it.

Quick Start

# Using Docker
docker run -d -p 8000:8000 -e ADGUARD_HOST=http://localhost -e ADGUARD_PORT=3000 pacnpal/simpleguardhome:latest

# Or using Python
pip install simpleguardhome
python -m uvicorn simpleguardhome.main:app --port 8000

Then visit http://localhost:8000 to start managing your AdGuard Home filtering.

Features

Core Features

• 🔍 Real-time domain filtering status checks
• 🚫 One-click domain unblocking
• 💻 Modern, responsive web interface with Tailwind CSS
• 🌓 Support for light and dark modes
• 🔄 Live feedback and error handling
• 📝 Comprehensive logging
• 🏥 Health monitoring endpoint
• ⚙️ Environment-based configuration
• 📚 Full OpenAPI/Swagger documentation
• ✅ Implements official AdGuard Home API spec
• 🐳 Docker support

Requirements

System Requirements

• Python 3.7 or higher (for local installation)
• Running AdGuard Home instance
• AdGuard Home API credentials
• Docker (optional, for containerized deployment)

Python Dependencies

• FastAPI - Web framework for building APIs
• Uvicorn - ASGI server implementation
• Python-dotenv - Environment variable management
• HTTPX - Modern HTTP client
• Pydantic - Data validation using Python type annotations
• Jinja2 - Template engine for the web interface

Docker Installation

The easiest way to get started is using Docker:

1. Pull the Docker image:

docker pull pacnpal/simpleguardhome:latest

1. Create a .env file with your AdGuard Home settings:

ADGUARD_HOST=http://localhost    # AdGuard Home host URL
ADGUARD_PORT=3000               # AdGuard Home API port
ADGUARD_USERNAME=admin          # Required: AdGuard Home username
ADGUARD_PASSWORD=password       # Required: AdGuard Home password

1. Run the container:

docker run -d \
  --name simpleguardhome \
  -p 8000:8000 \
  --env-file .env \
  pacnpal/simpleguardhome:latest

The application will be available at http://localhost:8000

Docker Compose

Alternatively, you can use Docker Compose. Create a docker-compose.yml file:

version: '3'
services:
  simpleguardhome:
    image: pacnpal/simpleguardhome:latest
    container_name: simpleguardhome
    ports:
      - "8000:8000"
    env_file:
      - .env
    restart: unless-stopped

Then run:

docker-compose up -d

Local Installation

1. Clone this repository:

git clone https://github.com/pacnpal/simpleguardhome.git
cd simpleguardhome

1. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

1. Install dependencies:

pip install -r requirements.txt

Configuration

1. Copy the example environment file:

cp .env.example .env

1. Edit .env with your AdGuard Home settings:

ADGUARD_HOST=http://localhost    # AdGuard Home host URL
ADGUARD_PORT=3000               # AdGuard Home API port
ADGUARD_USERNAME=admin          # Required: AdGuard Home username
ADGUARD_PASSWORD=password       # Required: AdGuard Home password

Running the Application

Local Development

Start the application:

python -m uvicorn src.simpleguardhome.main:app --reload

The application will be available at http://localhost:8000

API Documentation

The API documentation is automatically generated by FastAPI using:

• Type hints in endpoint definitions
• Pydantic models for request/response validation
• Function docstrings for descriptions
• Response models and status codes

Documentation is available at:

• Swagger UI: http://localhost:8000/api/docs - Interactive API documentation
• ReDoc: http://localhost:8000/api/redoc - Alternative documentation UI
• OpenAPI Schema: http://localhost:8000/api/openapi.json - Raw OpenAPI specification

API Endpoints

All endpoints follow the official AdGuard Home API specification:

Web Interface

• GET / - Main web interface for domain checking and unblocking

Filtering Endpoints

• GET /control/filtering/check_host - Check if a domain is blocked

  • Parameters: name (query parameter)
  • Returns: Detailed filtering status and rules

• GET /control/filtering/unblock_host - Unblock a domain by adding it to whitelist

  • Parameters: name (query parameter)
  • Returns: Success message with domain status
  • Status: Returns whether domain was unblocked, already unblocked, or not blocked

• POST /control/filtering/set_rules - Add domains to the filtering rules

  • Parameters: Array of rules in request body
  • Returns: Success message on successful update
  • Note: Used internally by unblock_host endpoint

• GET /control/filtering/status - Get current filtering configuration

  • Returns: Complete filtering status including rules and filters

System Status

• GET /control/status - Check application and AdGuard Home connection status
  • Returns: Health status with filtering state

Project Structure

simpleguardhome/
├── src/
│   └── simpleguardhome/
│       ├── __init__.py
│       ├── main.py          # FastAPI application
│       ├── config.py        # Configuration management
│       ├── adguard.py       # AdGuard Home API client
│       └── templates/
│           └── index.html   # Web interface
├── static/
│   └── simpleguardhome.png  # Project logo
├── rules_backup/          # Backup storage location
├── requirements.txt
├── setup.py
├── pyproject.toml        # Project metadata and dependencies
├── .env.example
├── Dockerfile
└── README.md

Security Notes

• API credentials are handled via environment variables
• Connections use proper error handling and timeouts
• Input validation is performed on all endpoints
• CORS protection with proper headers
• Rate limiting on sensitive endpoints
• Session-based authentication with AdGuard Home
• Sensitive information is not exposed in responses

Error Handling

The application implements comprehensive error handling according to endpoint:

GET /control/filtering/check_host:

• 400: Invalid domain format or missing name parameter
• 503: AdGuard Home service unavailable

GET /control/filtering/unblock_host:

• 400: Invalid domain format or missing name parameter
• 500: Failed to unblock domain
• 503: AdGuard Home service unavailable

POST /control/filtering/set_rules:

• 400: Invalid rule format or missing rules
• 500: Failed to update rules
• 503: AdGuard Home service unavailable

All endpoints return an ErrorResponse model with a descriptive message.

Response Models

The application uses Pydantic models that match the AdGuard Home API specification:

FilterStatus

{
    "enabled": bool,
    "filters": [
        {
            "enabled": bool,
            "id": int,
            "name": str,
            "rules_count": int,
            "url": str
        }
    ],
    "user_rules": List[str],
    "whitelist_filters": List[Filter]
}

FilterCheckHostResponse

{
    "reason": str,      # Filtering status (e.g., "FilteredBlackList", "NotFilteredNotFound")
    "filter_id": int,   # Optional: ID of the filter containing the rule (deprecated)
    "rule": str,        # Optional: Applied filtering rule (deprecated)
    "rules": [          # List of applied rules with details
        {
            "filter_list_id": int,  # Filter list ID
            "text": str            # Rule text
        }
    ],
    "service_name": str,  # Optional: For blocked services
    "cname": str,        # Optional: For CNAME rewrites
    "ip_addrs": List[str] # Optional: For A/AAAA rewrites
}

SetRulesRequest

{
    "rules": List[str]  # List of filtering rules to set
}

ErrorResponse

{
    "message": str  # Error description
}

License

MIT License - See LICENSE file for details