Ad-Blocking Repository

A comprehensive multi-language toolkit for ad-blocking, network protection, and AdGuard DNS management. Features filter rule compilers in 5 languages (TypeScript, .NET, Python, Rust, PowerShell), plus complete API SDKs for AdGuard DNS in both C# and Rust with interactive console interfaces.

Features

🔒 Security First: All compilers include mandatory validation to protect against malicious filter lists, tampering, and man-in-the-middle attacks. Learn why validation matters →

Rules Compilers (5 Languages)

Language	Runtime	Distribution	Key Features
TypeScript	Deno 2.0+	Deno	Secure by default, built-in TypeScript, optional Rust frontend
C#/.NET	.NET 10	NuGet/Binary	Interactive CLI, config validation, DI support
Python	Python 3.9+	pip	Type hints, PyPI-ready packaging
Rust	Native binary	Cargo/Binary	Zero-runtime deps, LTO optimization
PowerShell	PowerShell 7+	Module	Pipeline-friendly, Pester tests

All compilers wrap @adguard/hostlist-compiler with built-in security validation and support:

All 11 transformations: Deduplicate, Validate, RemoveComments, Compress, RemoveModifiers, etc.
Multi-format config: JSON, YAML, and TOML configuration files
Source-specific settings: Per-source transformations, inclusions, exclusions
Pattern matching: Wildcards, regex, file-based patterns
🔒 SHA-384 hash verification: Automatic tamper detection for all sources
🔒 URL security validation: HTTPS enforcement, domain validation, content verification
🔒 Runtime enforcement: Cryptographic proof that validation occurred

AdGuard DNS API SDKs

SDK	Language	Features
C# SDK	.NET 10	Full async/await, Polly resilience (retry on 408/429/5xx), DI support
TypeScript SDK	Deno 2.0+	Full API coverage, repository pattern, retry policies, interactive CLI
Rust SDK	Rust 2024	Auto-generated from OpenAPI, Tokio async runtime, single binary

Both SDKs provide complete coverage of AdGuard DNS API v1.11 including devices, DNS servers, query logs, statistics, filter lists, web services, and dedicated IP management.

Interactive Console Applications

C# Console UI - Spectre.Console menu-driven interface with rich formatting
Rust CLI - dialoguer-based interactive menus with TOML config persistence

Additional Features

Shell Scripts: Bash, Zsh, PowerShell Core, and Windows Batch wrappers
Docker Environment: Pre-configured container with .NET 10, Deno, PowerShell 7
Comprehensive Testing: Deno test, xUnit, pytest, cargo test, Pester across all components
CI/CD Integration: GitHub Actions for build, test, security scanning, and releases

Project Structure

ad-blocking/
├── .github/                           # GitHub configuration
│   ├── workflows/                     # CI/CD pipelines
│   │   ├── dotnet.yml                 # .NET build and test
│   │   ├── typescript.yml             # TypeScript lint and build
│   │   ├── powershell.yml             # PowerShell linting
│   │   ├── release.yml                # Build and publish binaries
│   │   ├── codeql.yml                 # CodeQL security scanning
│   │   ├── devskim.yml                # DevSkim security analysis
│   │   └── claude*.yml                # Claude AI integration
│   └── ISSUE_TEMPLATE/                # Issue templates
├── api/                               # OpenAPI specifications (centralized)
│   ├── README.md                      # API spec documentation
│   ├── openapi.json                   # AdGuard DNS API v1.11 (primary)
│   └── openapi.yaml                   # AdGuard DNS API v1.11 (optional)
├── docs/                              # Documentation
│   ├── api/                           # Auto-generated API reference
│   ├── guides/                        # Usage guides and tutorials
│   ├── getting-started.md             # Quick start guide
│   ├── compiler-comparison.md         # Compiler comparison matrix
│   ├── configuration-reference.md     # Configuration schema reference
│   ├── docker-guide.md                # Docker development guide
│   ├── AGENTS.md                      # AI agent documentation
│   ├── PHASE2_IMPLEMENTATION.md       # Modernization roadmap
│   ├── RUST_WORKSPACE.md              # Rust workspace documentation
│   ├── RUST_MODERNIZATION_SUMMARY.md  # Rust migration summary
│   ├── TEST_UPDATES_SUMMARY.md        # Testing updates
│   └── WARP.md                        # Warp terminal integration
├── data/                              # Filter rules and data
│   ├── input/                         # Source filter lists (local & remote refs)
│   │   ├── README.md                  # Input directory documentation
│   │   ├── example-custom-rules.txt   # Example local rules
│   │   ├── internet-sources.txt.example # Example remote sources config
│   │   └── .gitignore                 # Ignore large/sensitive files
│   ├── output/                        # Compiled filter output
│   │   └── adguard_user_filter.txt    # Main tracked filter list (adblock format)
│   ├── archive/                       # Archived processed input files
│   │   ├── README.md                  # Archive directory documentation
│   │   └── .gitignore                 # Ignore archive contents
│   └── Config/                        # Compiler configurations (optional)
├── src/                               # Source code
│   ├── rules-compiler-typescript/     # TypeScript/Deno compiler
│   ├── rules-compiler-dotnet/         # C#/.NET 10 compiler
│   ├── rules-compiler-python/         # Python 3.9+ compiler
│   ├── rules-compiler-rust/           # Rust compiler (single binary)
│   ├── shell-scripts/                 # Shell script wrappers
│   │   ├── bash/                      # Bash scripts
│   │   └── zsh/                       # Zsh scripts
│   ├── adguard-api-dotnet/            # C# API SDK + Console UI
│   │   ├── src/AdGuard.ApiClient/     # C# SDK library
│   │   ├── src/AdGuard.ConsoleUI/     # Spectre.Console interface
│   │   └── src/AdGuard.ApiClient.Tests/ # xUnit tests
│   ├── adguard-api-rust/              # Rust API SDK + CLI
│   │   ├── adguard-api-lib/           # Rust SDK library
│   │   └── adguard-api-cli/           # Interactive CLI application
│   ├── adguard-api-typescript/        # TypeScript API SDK + CLI
│   │   ├── src/api/                   # API client implementations
│   │   ├── src/cli/                   # Interactive CLI application
│   │   └── tests/                     # Deno test suite
│   ├── adguard-api-powershell/        # PowerShell API client (legacy)
│   ├── powershell-modules/            # PowerShell modules (modern)
│   │   ├── Common/                    # Shared utilities
│   │   ├── RulesCompiler/             # Rules compiler module
│   │   └── AdGuardWebhook/            # Webhook module
│   ├── adguard-validation/            # Rust validation library
│   │   ├── adguard-validation-core/   # Core validation logic
│   │   └── adguard-validation-cli/    # CLI tool
│   └── linear/                        # Linear integration scripts
├── tools/                             # Utility and build scripts
│   ├── README.md                      # Tools documentation
│   ├── test-build-scripts.sh          # Bash build script tests
│   ├── test-build-scripts.ps1         # PowerShell build script tests
│   ├── test-modules.ps1               # PowerShell module tests
│   ├── check-validation-compliance.sh # Validation compliance check
│   └── Migrate-To-NewStructure.ps1    # Structure migration script
├── Dockerfile.warp                    # Docker dev environment
├── CLAUDE.md                          # AI assistant instructions
├── CONTRIBUTING.md                    # Contribution guidelines
├── SECURITY.md                        # Security policy
├── README.md                          # This file
├── LICENSE                            # GPL-3.0 license
├── build.sh                           # Multi-language build script (Bash)
├── build.ps1                          # Multi-language build script (PowerShell)
├── launcher.sh                        # Interactive launcher (Bash)
└── launcher.ps1                       # Interactive launcher (PowerShell)

Quick Start

🚀 Interactive Launcher (Easiest Way)

The repository includes feature-rich interactive launchers that provide an intuitive menu system for all tools and tasks:

Bash Launcher (Linux/macOS):

./launcher.sh

PowerShell Launcher (Windows/Cross-platform):

.\launcher.ps1

Features:

🔨 Build Tools - Build projects with debug/release profiles
⚙️ Compile Filter Rules - Run compilers in any language
🌐 AdGuard API Clients - Launch interactive API tools
🔍 Validation & Testing - Run tests and compliance checks
📦 Project Management - Clean builds, update dependencies
ℹ️ System Information - Check installed tools and project status

The launcher provides guided navigation with numbered menus, colored output, and automatic tool detection. Perfect for newcomers and experienced users alike!

Prerequisites

Requirement	Version	Required For
Deno	2.0+	TypeScript compiler, TypeScript API client
hostlist-compiler	Latest	All compilers
.NET SDK	10.0+	.NET compiler, API client
Python	3.9+	Python compiler
Rust	1.83+	Rust workspace (all Rust projects)
PowerShell	7+	PowerShell scripts

Note: All Rust projects are now part of a unified workspace. See RUST_WORKSPACE.md for details.

Install Deno

# macOS/Linux
curl -fsSL https://deno.land/install.sh | sh

# Windows (PowerShell)
irm https://deno.land/install.ps1 | iex

The @adguard/hostlist-compiler package is accessed via Deno's npm compatibility.

Clone and Setup

git clone https://github.com/jaypatrick/ad-blocking.git
cd ad-blocking

# TypeScript compiler
cd src/rules-compiler-typescript && deno cache src/mod.ts

# .NET projects
cd ../rules-compiler-dotnet && dotnet restore RulesCompiler.slnx
cd ../adguard-api-dotnet && dotnet restore src/AdGuard.ApiClient.sln

# Python compiler
cd ../rules-compiler-python && pip install -e ".[dev]"

# Rust workspace (builds all Rust projects)
cd .. && cargo build --release

Rust Workspace: All Rust projects (adguard-validation, adguard-api-rust, rules-compiler-rust) are now unified in a single workspace at the repository root. Run cargo build from the root to build all Rust projects together. See RUST_WORKSPACE.md for more details.

Build All Projects

Root-level build scripts are available to build all projects or specific language ecosystems:

# Build all projects (debug mode - default)
./build.sh

# Build all projects in release mode
./build.sh --release

# Build specific language ecosystems
./build.sh --rust              # Build all Rust projects
./build.sh --dotnet            # Build all .NET projects
./build.sh --typescript        # Build all TypeScript/Deno projects
./build.sh --python            # Build Python projects

# Combine options
./build.sh --rust --dotnet --release   # Build Rust and .NET in release mode

PowerShell (Windows/Cross-platform):

# Build all projects (debug mode - default)
.\build.ps1

# Build all projects in release mode
.\build.ps1 -Profile release

# Build specific language ecosystems
.\build.ps1 -Rust              # Build all Rust projects
.\build.ps1 -DotNet            # Build all .NET projects
.\build.ps1 -TypeScript        # Build all TypeScript/Deno projects
.\build.ps1 -Python            # Build Python projects

# Combine options
.\build.ps1 -Rust -DotNet -Profile release

Available Options:

--all / -All: Build all projects (default if no specific project selected)
--rust / -Rust: Build Rust workspace (validation library, API clients, compilers)
--dotnet / -DotNet: Build .NET solutions (API client, rules compiler)
--typescript / -TypeScript: Build TypeScript/Deno projects (requires Deno)
--python / -Python: Build Python projects (requires Python 3.9+)
--debug: Use debug profile (default)
--release / -Profile release: Use release/optimized profile

The build scripts automatically:

Check for required tools (Rust, .NET, Deno, Python)
Restore dependencies
Build projects with appropriate configuration
Report build status with colored output
Exit with appropriate status codes for CI integration

Testing the Build Scripts:

Comprehensive test suites are available to validate build script functionality:

# Run Bash script tests (25+ unit and integration tests)
./tools/test-build-scripts.sh

# Run PowerShell script tests
pwsh -File tools/test-build-scripts.ps1

The test suites include:

Unit tests: Help output, argument parsing, error handling
Integration tests: Rust, .NET, TypeScript, Python builds
Combined tests: Multiple language ecosystems together
Profile tests: Debug and release build configurations

Tests run automatically in CI via the Build Scripts Tests workflow.

Compile Filter Rules (Any Language)

# TypeScript
cd src/rules-compiler-typescript && deno task compile

# .NET
cd src/rules-compiler-dotnet && dotnet run --project src/RulesCompiler.Console

# Python
cd src/rules-compiler-python && rules-compiler

# Rust
cd src/rules-compiler-rust && cargo run --release

# Or from repository root (using workspace)
cargo run --release -p rules-compiler

# PowerShell
Import-Module ./src/adguard-api-powershell/Invoke-RulesCompiler.psm1
Invoke-RulesCompiler

# Bash
./src/rules-compiler-shell/compile-rules.sh

Docker Development Environment

A pre-configured Docker environment is available with all dependencies installed.

Dockerfile.warp

FROM mcr.microsoft.com/dotnet/sdk:10.0-noble

# Includes:
# - .NET 10 SDK
# - Deno 2.0+
# - PowerShell 7
# - Git

WORKSPACE /workspace

Build and Run

# Build the image
docker build -f Dockerfile.warp -t ad-blocking-dev .

# Run interactive container
docker run -it -v $(pwd):/workspace ad-blocking-dev

# Inside container, cache Deno dependencies
cd /workspace/src/rules-compiler-typescript && deno cache src/mod.ts
cd /workspace/src/rules-compiler-dotnet && dotnet restore RulesCompiler.slnx

Warp Environment

For Warp terminal users, a pre-built environment is available:

Property	Value
Docker Image	`jaysonknight/warp-env:ad-blocking`
Environment ID	`Egji4sZU4TNIOwNasFU73A`

# Create Warp integrations
warp integration create slack --environment Egji4sZU4TNIOwNasFU73A
warp integration create linear --environment Egji4sZU4TNIOwNasFU73A

Data Directory Structure

The data/ directory organizes all filter-related files with a clear separation between inputs and outputs:

Input Directory (`data/input/`)

Source location for filter rules to be compiled:

Local rule files: Place custom filter lists in adblock or hosts format
- Examples: custom-rules.txt, company-blocklist.txt
- Supports .txt, .hosts extensions
- Automatic format detection (adblock vs hosts)
Internet source references: File containing URLs to remote filter lists
- Create internet-sources.txt with one URL per line
- Example sources: EasyList, StevenBlack hosts, AdGuard filters
- Lines starting with # are comments
- Security: Only HTTPS URLs allowed, content validated before use

Features:

✅ Hash verification: SHA-384 integrity checking for tampering detection
✅ Syntax validation: Automatic linting before compilation
✅ Multi-format support: Both adblock and hosts file formats
✅ Remote list fetching: Download and verify internet sources
✅ Error reporting: Clear messages with line numbers for invalid rules
✅ URL security: HTTPS enforcement, domain validation, content verification

Example structure:

data/input/
├── README.md                    # Documentation
├── custom-rules.txt             # Your custom adblock rules
├── internet-sources.txt         # URLs to remote lists
└── .gitignore                   # Ignore large/sensitive files

See data/input/README.md for detailed usage instructions.

Output Directory (`data/output/`)

Contains the final compiled filter list:

adguard_user_filter.txt: Main filter list in adblock format
- Merged from all input sources
- Deduplicated and validated
- Ready for use with AdGuard DNS or other blockers
- Tracked in version control

Compilation guarantees:

✅ Output is always in adblock syntax (not hosts format)
✅ Comments and metadata preserved from sources
✅ SHA-384 hash computed for verification
✅ Rule count validation

Archive Directory (`data/archive/`)

Stores processed input files after successful compilation for audit and rollback purposes:

Automatic archiving: Configurable via environment variables or CLI flags
Timestamp-based organization: Each compilation creates a dated subdirectory
Manifest tracking: JSON metadata with hashes, file info, and compilation stats
Retention policy: Automatic cleanup of archives older than 90 days (configurable)

Archiving modes:

🤖 Automatic (default): Archive after every successful compilation
🤔 Interactive: Prompt user whether to archive
🚫 Disabled: No archiving

Example structure:

data/archive/
├── 2024-12-27_14-30-45/
│   ├── manifest.json              # Compilation metadata
│   ├── custom-rules.txt           # Input file snapshot
│   └── internet-sources.txt
└── 2024-12-26_09-15-22/
    ├── manifest.json
    └── custom-rules.txt

Configuration:

# Environment variables
export ADGUARD_ARCHIVE_ENABLED=true
export ADGUARD_ARCHIVE_MODE=automatic  # or interactive, disabled
export ADGUARD_ARCHIVE_RETENTION_DAYS=90

# CLI flags (all compilers)
npm run compile -- --no-archive              # Disable
npm run compile -- --archive-interactive     # Prompt
npm run compile -- --archive-retention 365   # Custom retention

# Or configure in JSON/YAML/TOML config files

Config file example (JSON):

{
  "name": "My Filter",
  "output": {
    "path": "data/output/my-filter.txt",
    "conflictStrategy": "rename"
  },
  "archiving": {
    "enabled": true,
    "mode": "automatic",
    "retentionDays": 90
  },
  "sources": [...]
}

Use cases:

Track historical changes to filter rules
Rollback to previous working configuration
Audit what was compiled and when
Meet compliance requirements for data retention

See data/archive/README.md for detailed usage and restoration procedures.

Compilation Workflow

┌─────────────────────────────────────────────────────┐
│ 1. Discover all files in data/input/               │
│    - Scan for .txt, .hosts files                   │
│    - Parse internet-sources.txt                    │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│ 2. Validate & Hash Check                           │
│    - Syntax validation for each file               │
│    - Compute SHA-384 hashes                        │
│    - Detect tampering/modifications                │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│ 3. Fetch Internet Sources (if configured)          │
│    - Download remote lists                         │
│    - Verify with hashes                            │
│    - Cache for performance                         │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│ 4. Compile with @adguard/hostlist-compiler         │
│    - Merge all sources                             │
│    - Apply transformations (dedupe, validate, etc) │
│    - Convert hosts format to adblock if needed     │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│ 5. Output to data/output/adguard_user_filter.txt   │
│    - Write final adblock-format list               │
│    - Compute output hash                           │
│    - Log statistics (rule count, hash)             │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│ 6. Archive Input Files (optional)                  │
│    - Create timestamped archive directory          │
│    - Copy all input files to archive               │
│    - Generate manifest.json with metadata          │
│    - Cleanup old archives per retention policy     │
└─────────────────────────────────────────────────────┘

Rules Compilers

All compilers wrap @adguard/hostlist-compiler and support:

Multi-format config: JSON, YAML, TOML
All 11 transformations: Deduplicate, Validate, RemoveComments, Compress, etc.
Source-specific settings: Per-source transformations, inclusions, exclusions
Pattern matching: Wildcards, regex, file-based patterns

TypeScript Compiler

Location: src/rules-compiler-typescript/

cd src/rules-compiler-typescript

# Compile rules
deno task compile                   # Default config
deno task compile:yaml              # YAML config
deno task compile:toml              # TOML config

# CLI options
deno task compile -- -c config.yaml # Specific config
deno task compile -- -r             # Copy to data/
deno task compile -- -d             # Debug output
deno task compile -- --help         # Show help
deno task compile -- --version      # Show version

# Interactive console mode
deno task interactive               # Interactive menu

# Development
deno task dev                       # Run with watch mode
deno task lint                      # Deno lint
deno task test                      # Deno tests
deno task test:coverage             # With coverage

Features:

Deno 2.0+ runtime with secure-by-default permissions
Built-in TypeScript support, no build step required
Interactive console mode with menu-driven interface
Deno native testing and linting

.NET Compiler

Location: src/rules-compiler-dotnet/

cd src/rules-compiler-dotnet

# Build
dotnet restore RulesCompiler.slnx
dotnet build RulesCompiler.slnx

# Interactive mode (menu-driven)
dotnet run --project src/RulesCompiler.Console

# CLI mode
dotnet run --project src/RulesCompiler.Console -- --config config.yaml
dotnet run --project src/RulesCompiler.Console -- -c config.json --copy
dotnet run --project src/RulesCompiler.Console -- -c config.yaml --verbose
dotnet run --project src/RulesCompiler.Console -- -c config.yaml --validate
dotnet run --project src/RulesCompiler.Console -- --version

# Tests
dotnet test RulesCompiler.slnx

CLI Options:

Option	Short	Description
`--config`	`-c`	Configuration file path
`--output`	`-o`	Output file path
`--copy`		Copy to rules directory
`--verbose`		Detailed compiler output
`--validate`		Validate config only
`--version`	`-v`	Show version info

Features:

Interactive Spectre.Console menu
Configuration validation with error/warning reporting
Dependency injection support
Cross-platform (Windows, Linux, macOS)

See .NET Compiler README for library usage.

Python Compiler

Location: src/rules-compiler-python/

cd src/rules-compiler-python

# Install
pip install -e .                    # Basic install
pip install -e ".[dev]"             # With dev dependencies

# CLI usage
rules-compiler                      # Default config
rules-compiler -c config.yaml       # Specific config
rules-compiler -c config.json -r    # Compile and copy
rules-compiler -o output.txt        # Custom output
rules-compiler -V                   # Version info
rules-compiler -d                   # Debug output
rules-compiler --help               # Show help

# Tests
pytest                              # Run tests
pytest -v                           # Verbose
pytest --cov=rules_compiler         # Coverage

Features:

Python 3.9-3.12 support
Type hints with mypy checking
Ruff linting
PyPI-ready packaging

Python API:

from rules_compiler import RulesCompiler, compile_rules

# Simple usage
result = compile_rules("config.yaml")
print(f"Compiled {result.rule_count} rules")

# Class-based usage
compiler = RulesCompiler()
result = compiler.compile("config.yaml", output_path="output.txt")

Rust Compiler

Location: src/rules-compiler-rust/ (part of root workspace)

Rust Workspace: This compiler is part of a unified Rust workspace. All Rust projects can be built together from the repository root. See RUST_WORKSPACE.md for details.

# From repository root (recommended)
cargo build --release -p rules-compiler
cargo run --release -p rules-compiler -- -c config.yaml

# Or from project directory
cd src/rules-compiler-rust
cargo build --release
cargo run --release -- -c config.yaml

# CLI usage
./target/release/rules-compiler -c config.yaml   # Specific config
./target/release/rules-compiler -c config.json -r # Compile and copy
./target/release/rules-compiler -o output.txt     # Custom output
./target/release/rules-compiler -V                # Version info
./target/release/rules-compiler -d                # Debug output
./target/release/rules-compiler --help            # Show help

# Tests
cargo test -p rules-compiler                      # Run tests
cargo test -p rules-compiler -- --nocapture       # With output

Features:

Single statically-linked binary
LTO optimization for small binary size
Zero runtime dependencies (except Node.js for hostlist-compiler)
Cross-platform support
Part of unified workspace with shared dependencies

Rust API:

use rules_compiler::{RulesCompiler, CompilerConfiguration};

let compiler = RulesCompiler::new();
let result = compiler.compile("config.yaml", None)?;
println!("Compiled {} rules", result.rule_count);

Shell Scripts

Location: src/rules-compiler-shell/

Cross-platform shell scripts that wrap @adguard/hostlist-compiler for simple automation and CI/CD pipelines.

Script	Platform	Shell	Features
`compile-rules.sh`	Linux, macOS	Bash	Full feature support, YAML/TOML via yq/Python
`compile-rules.zsh`	Linux, macOS	Zsh	Native zsh features (zparseopts, EPOCHREALTIME)
`compile-rules.ps1`	All platforms	PowerShell 7+	Cross-platform, PowerShell pipeline support
`compile-rules.cmd`	Windows	Batch	Simple wrapper for Windows users

Bash (Linux/macOS)

# Make executable (first time)
chmod +x src/rules-compiler-shell/compile-rules.sh

# Run with defaults
./src/rules-compiler-shell/compile-rules.sh

# Use specific configuration
./src/rules-compiler-shell/compile-rules.sh -c config.yaml

# Compile and copy to rules directory
./src/rules-compiler-shell/compile-rules.sh -c config.yaml -r

# Show version/help
./src/rules-compiler-shell/compile-rules.sh -v
./src/rules-compiler-shell/compile-rules.sh -h

Zsh (macOS/Linux)

# Make executable (first time)
chmod +x src/rules-compiler-shell/compile-rules.zsh

# Run with defaults
./src/rules-compiler-shell/compile-rules.zsh

# Use YAML configuration
./src/rules-compiler-shell/compile-rules.zsh -c config.yaml

# Compile and copy to rules directory
./src/rules-compiler-shell/compile-rules.zsh -c config.yaml -r

# Debug mode
./src/rules-compiler-shell/compile-rules.zsh -c config.yaml -d

PowerShell Core (Cross-platform)

# Run with defaults
./src/rules-compiler-shell/compile-rules.ps1

# Use YAML configuration
./src/rules-compiler-shell/compile-rules.ps1 -ConfigPath config.yaml

# Compile and copy to rules directory
./src/rules-compiler-shell/compile-rules.ps1 -ConfigPath config.yaml -CopyToRules

# Show version
./src/rules-compiler-shell/compile-rules.ps1 -Version

Windows Batch

src\rules-compiler-shell\compile-rules.cmd -c config.json -r

CLI Options (all scripts):

Option	Short	Description
`--config PATH`	`-c`	Path to configuration file
`--output PATH`	`-o`	Path to output file
`--copy-to-rules`	`-r`	Copy output to rules directory
`--format FORMAT`	`-f`	Force format (json, yaml, toml)
`--version`	`-v`	Show version information
`--help`	`-h`	Show help message
`--debug`	`-d`	Enable debug output

See Shell Scripts README for detailed documentation.

PowerShell Modules

Location: src/adguard-api-powershell/

RulesCompiler Module

PowerShell API for compiling AdGuard filter rules.

# Import module
Import-Module ./src/adguard-api-powershell/Invoke-RulesCompiler.psm1

# Available functions
Get-CompilerVersion | Format-List           # Version info
Invoke-RulesCompiler                         # Compile rules
Invoke-RulesCompiler -CopyToRules            # Compile and copy

# Interactive harness
./src/adguard-api-powershell/RulesCompiler-Harness.ps1

# Run Pester tests
Invoke-Pester -Path ./src/adguard-api-powershell/Tests/

Exported Functions:

Function	Description
`Read-CompilerConfiguration`	Parse config file (JSON, YAML, TOML)
`Invoke-FilterCompiler`	Run hostlist-compiler
`Write-CompiledOutput`	Write output file
`Invoke-RulesCompiler`	Full compilation pipeline
`Get-CompilerVersion`	Get version info

Webhook Module (v1.0.0 - NEW!)

Modernized PowerShell module for invoking AdGuard DNS webhooks with rich features.

# Import module
Import-Module ./src/adguard-api-powershell/Invoke-WebHook.psm1

# Basic invocation
Invoke-AdGuardWebhook -WebhookUrl "https://api.adguard-dns.io/webhook/xxx"

# Continuous mode with statistics
Invoke-AdGuardWebhook -WebhookUrl $url -Continuous -ShowStatistics

# Load from configuration file
Invoke-AdGuardWebhook -ConfigFile webhook-config.json -ShowStatistics

# Save configuration
Invoke-AdGuardWebhook -WebhookUrl $url -SaveConfig config.json

# Quiet mode with JSON output
Invoke-AdGuardWebhook -WebhookUrl $url -Quiet -Format Json

New Features (v1.0.0):

✅ Rich console output with colored icons and emojis
📊 Progress bars for continuous operations
📊 Statistics tracking (success/failure rates, elapsed time)
💾 Configuration file support (JSON/YAML)
💾 Multiple output formats (Table, List, JSON)
⚙️ Quiet mode for scripting
🎯 Parameter validation with ranges
🔙 Backward compatible alias (Invoke-Webhook)

Configuration File Example:

{
  "WebhookUrl": "https://api.adguard-dns.io/webhook/xxx",
  "WaitTime": 500,
  "RetryCount": 10,
  "RetryInterval": 5,
  "Continuous": false
}

Utility Scripts (Enhanced)

All utility scripts have been enhanced with modern features:

Regenerate-Client.ps1 - New options:

-DryRun: Preview changes without modification
-Compare: Show detailed diffs
-Clean: Remove backup files
-LogFile: Persistent logging
-OutputFormat: Text, Json, or Markdown

Update-ApiClient.ps1 - New options:

-Force: Skip confirmations
-CI: Non-interactive mode
Step progress indicators with colored icons

See PowerShell Modules README for complete documentation

AdGuard API Clients

Complete SDK implementations for the AdGuard DNS API v1.11 in C#, TypeScript, and Rust.

C# SDK

Location: src/adguard-api-dotnet/

cd src/adguard-api-dotnet

# Build
dotnet restore src/AdGuard.ApiClient.sln
dotnet build src/AdGuard.ApiClient.sln

# Test
dotnet test src/AdGuard.ApiClient.sln

# Run benchmarks
dotnet run --project src/AdGuard.ApiClient.Benchmarks -c Release

Features:

Auto-generated from OpenAPI specification
Full async/await support with cancellation tokens
Polly resilience policies (automatic retry on 408/429/5xx with exponential backoff)
Dependency injection with ILogger support
Fluent configuration helpers for easy setup
Newtonsoft.Json serialization with JsonSubTypes support

Usage Example:

using AdGuard.ApiClient;
using AdGuard.ApiClient.Helpers;

// Configure client with fluent API
var config = new Configuration()
    .WithApiKey("your-api-key")
    .WithTimeout(TimeSpan.FromSeconds(30))
    .WithUserAgent("MyApp/1.0");

var apiClient = new ApiClient(config);
var devicesApi = new DevicesApi(apiClient);

// List all devices
var devices = await devicesApi.ListDevicesAsync();
foreach (var device in devices)
{
    Console.WriteLine($"{device.Name}: {device.Id}");
}

// Get account limits
var accountApi = new AccountApi(apiClient);
var limits = await accountApi.GetAccountLimitsAsync();
Console.WriteLine($"Devices: {limits.DevicesCount}/{limits.DevicesLimit}");

Rust SDK

Location: src/adguard-api-rust/ (part of root workspace)

Rust Workspace: This SDK is part of a unified Rust workspace. All Rust projects can be built together from the repository root. See RUST_WORKSPACE.md for details.

# From repository root (recommended)
cargo build --release -p adguard-api-lib
cargo build --release -p adguard-api-cli
cargo run --release -p adguard-api-cli

# Or from project directory
cd src/adguard-api-rust
cargo build --release
cargo test

Features:

Auto-generated from OpenAPI specification using OpenAPI Generator
Async/await support with Tokio runtime
Single statically-linked binary distribution
Configurable TLS: rustls (default) or native-tls
Memory-safe with zero-cost abstractions
Part of unified workspace with shared dependencies

Usage Example:

use adguard_api_lib::apis::configuration::Configuration;
use adguard_api_lib::apis::devices_api;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure the API client
    let mut config = Configuration::new();
    config.base_path = "https://api.adguard-dns.io".to_string();
    config.bearer_access_token = Some("your-api-token".to_string());

    // List devices
    let devices = devices_api::list_devices(&config).await?;
    for device in devices {
        println!("{}: {}", device.name, device.id);
    }

    Ok(())
}

TypeScript SDK

Location: src/adguard-api-typescript/

cd src/adguard-api-typescript

# Run tests
deno task test

# Run CLI
deno task start

Features:

Auto-generated types from OpenAPI specification
Repository pattern with high-level abstractions
Automatic retry with exponential backoff using axios-retry
Interactive CLI with inquirer prompts
Deno 2.0+ runtime with secure-by-default permissions
Full test coverage with Deno test

Usage Example:

import { AdGuardDnsClient } from './src/index.ts';

// Configure client
const client = AdGuardDnsClient.withApiKey('your-api-key');

// Or from environment variable
const client = AdGuardDnsClient.fromEnv('ADGUARD_API_KEY');

// List all devices
const devices = await client.devices.listDevices();
for (const device of devices) {
    console.log(`${device.name}: ${device.id}`);
}

// Get account limits
const limits = await client.account.getAccountLimits();
console.log(`Devices: ${limits.devices_count}/${limits.devices_limit}`);

// Use repositories for higher-level operations
const stats = await client.statisticsRepository.getSummary();

API Coverage (All SDKs)

API	Description
`AccountApi`	Account limits and information
`AuthenticationApi`	OAuth token generation
`DevicesApi`	Device CRUD operations
`DNSServersApi`	DNS server profile management
`DedicatedIPAddressesApi`	Dedicated IPv4 management
`FilterListsApi`	Filter list retrieval
`QueryLogApi`	Query log operations
`StatisticsApi`	DNS query statistics
`WebServicesApi`	Web services for blocking

See API Client Usage Guide for detailed C# examples.

Console Applications

Interactive terminal applications for managing AdGuard DNS.

.NET Console UI

Location: src/adguard-api-dotnet/src/AdGuard.ConsoleUI/

cd src/adguard-api-dotnet
dotnet run --project src/AdGuard.ConsoleUI

Features:

Menu-driven Spectre.Console interface with rich formatting
Device and DNS server management with detailed views
Query statistics and log viewing with filtering
Filter list browsing and management
Account limits with visual progress bars
API key configuration (environment variable or interactive prompt)

Rust CLI

Location: src/adguard-api-rust/adguard-api-cli/

cd src/adguard-api-rust

# Run directly
cargo run --bin adguard-api-cli

# Or build and run release binary
cargo build --release
./target/release/adguard-api-cli

Features:

Interactive menu-driven interface using dialoguer
Full feature parity with .NET Console UI
TOML configuration file persistence (~/.config/adguard-api-cli/config.toml)
Single binary distribution with no runtime dependencies
Cross-platform (Linux, macOS, Windows)

Configuration:

# ~/.config/adguard-api-cli/config.toml
api_url = "https://api.adguard-dns.io"
api_token = "your-api-token-here"

Or use environment variables (both .NET-compatible and legacy formats supported by Rust CLI):

# Recommended cross-platform format
export ADGUARD_API_BASE_URL="https://api.adguard-dns.io"
export ADGUARD_API_KEY="your-api-key-here"

# Alternative: .NET hierarchical format
export ADGUARD_AdGuard__BaseUrl="https://api.adguard-dns.io"
export ADGUARD_AdGuard__ApiKey="your-api-key-here"

# Deprecated (backward compatibility only)
# export ADGUARD_API_URL="https://api.adguard-dns.io"
# export ADGUARD_API_TOKEN="your-token-here"

Menu Options (both applications):

Menu	Description
Account Info	View account limits and usage statistics
Devices	List and view device details
DNS Servers	List and view DNS server configurations
User Rules	View and manage user rules
Query Log	View recent queries with time range filters
Statistics	View query statistics (24h, 7d, 30d)
Filter Lists	Browse available filter lists
Web Services	List blockable web services
Dedicated IPs	List and allocate dedicated IPv4 addresses
Settings	Configure API key, test connection

Environment Variables:

Both applications support standardized environment variable names for cross-compatibility:

Variable	Description
`ADGUARD_API_KEY`	API credential (recommended cross-platform format)
`ADGUARD_API_BASE_URL`	API base URL (optional, cross-platform format)
`ADGUARD_AdGuard__ApiKey`	API credential (.NET hierarchical format)
`ADGUARD_AdGuard__BaseUrl`	API base URL (.NET hierarchical format)

Deprecated (backward compatibility):

ADGUARD_API_TOKEN - Use ADGUARD_API_KEY instead
ADGUARD_API_URL - Use ADGUARD_API_BASE_URL instead

C# Console UI Configuration Example:

# Linux/macOS
export ADGUARD_AdGuard__ApiKey="your-api-key-here"

# Windows PowerShell
$env:ADGUARD_AdGuard__ApiKey="your-api-key-here"

TypeScript CLI

Location: src/adguard-api-typescript/

cd src/adguard-api-typescript

# Run interactively
deno task start

# Or with API key
deno task start -- --api-key your-key

# Sync rules from file
deno task start -- sync --file data/output/adguard_user_filter.txt

Features:

Interactive menu-driven interface using inquirer and ora
Full feature parity with .NET Console UI
Repository pattern with high-level abstractions
Automatic retry with exponential backoff
TypeScript types from OpenAPI specification
Deno's secure-by-default permission model

Configuration:

Set environment variable:

# Linux/macOS
export ADGUARD_API_KEY="your-api-key-here"

# Windows PowerShell
$env:ADGUARD_API_KEY="your-api-key-here"

Configuration

All compilers support the same configuration schema with JSON, YAML, or TOML syntax.

Configuration Properties

Property	Type	Required	Description
`name`	string	Yes	Filter list name
`description`	string	No	Description
`homepage`	string	No	Homepage URL
`license`	string	No	License identifier
`version`	string	No	Version number
`sources`	array	Yes	Filter sources
`transformations`	array	No	Global transformations
`inclusions`	array	No	Include patterns
`exclusions`	array	No	Exclude patterns

Source Properties

Property	Type	Required	Description
`source`	string	Yes	URL or file path
`name`	string	No	Source identifier
`type`	string	No	`adblock` or `hosts`
`transformations`	array	No	Source transformations
`inclusions`	array	No	Source include patterns
`exclusions`	array	No	Source exclude patterns

Available Transformations

Transformation	Description
`RemoveComments`	Remove comment lines
`Compress`	Convert hosts to adblock syntax
`RemoveModifiers`	Remove unsupported modifiers
`Validate`	Remove dangerous rules
`ValidateAllowIp`	Validate with IP rules allowed
`Deduplicate`	Remove duplicates
`InvertAllow`	Convert exceptions to blocking
`RemoveEmptyLines`	Remove blank lines
`TrimLines`	Trim whitespace
`InsertFinalNewLine`	Add final newline
`ConvertToAscii`	Convert IDN to punycode

Example Configurations

YAML

name: My Filter List
description: Custom ad-blocking filter
version: "1.0.0"

sources:
  - name: Local Rules
    source: data/local.txt
    type: adblock

  - name: EasyList
    source: https://easylist.to/easylist/easylist.txt
    transformations:
      - RemoveModifiers
      - Validate

transformations:
  - Deduplicate
  - RemoveEmptyLines
  - InsertFinalNewLine

exclusions:
  - "*.google.com"
  - "/analytics/"

JSON

{
  "name": "My Filter List",
  "sources": [
    {
      "name": "EasyList",
      "source": "https://easylist.to/easylist/easylist.txt"
    }
  ],
  "transformations": ["Deduplicate", "InsertFinalNewLine"]
}

TOML

name = "My Filter List"
transformations = ["Deduplicate", "InsertFinalNewLine"]

[[sources]]
name = "EasyList"
source = "https://easylist.to/easylist/easylist.txt"

Testing

TypeScript (Deno)

cd src/rules-compiler-typescript
deno task test                      # Run all tests
deno test src/cli.test.ts           # Specific file
deno task test:coverage             # With coverage

.NET (xUnit)

# Rules Compiler
cd src/rules-compiler-dotnet
dotnet test RulesCompiler.slnx
dotnet test --filter "FullyQualifiedName~ConfigurationValidatorTests"
dotnet test --filter "FullyQualifiedName~TransformationTests"

# API Client
cd ../adguard-api-dotnet
dotnet test src/AdGuard.ApiClient.sln
dotnet test --filter "FullyQualifiedName~DevicesApiTests"
dotnet test --filter "Name~GetAccountLimits"

Python (pytest)

cd src/rules-compiler-python
pytest                              # All tests
pytest -v                           # Verbose
pytest tests/test_config.py         # Specific file
pytest -k "test_read_yaml"          # By name
pytest --cov=rules_compiler         # Coverage

Rust (cargo test)

Rust Workspace: All Rust projects are now unified in a single workspace. Tests can be run from the repository root or individual project directories.

# From repository root (recommended) - runs all Rust tests
cargo test --workspace              # All tests in workspace
cargo test --workspace -- --nocapture  # With output

# Test specific packages
cargo test -p rules-compiler        # Rules compiler only
cargo test -p adguard-api-lib       # API library only
cargo test -p adguard-api-cli       # API CLI only
cargo test -p adguard-validation-core  # Validation core only

# From individual project directories
cd src/rules-compiler-rust
cargo test                          # All tests
cargo test -- --nocapture           # With output
cargo test test_count_rules         # Specific test
cargo test config::                 # Module tests

cd ../adguard-api-rust
cargo test                          # All workspace tests

PowerShell (Pester)

# Run all tests
Invoke-Pester -Path ./src/adguard-api-powershell/Tests/

# Run with detailed output
Invoke-Pester -Path ./src/adguard-api-powershell/Tests/ -Output Detailed

# Lint with PSScriptAnalyzer
Invoke-ScriptAnalyzer -Path src/adguard-api-powershell -Recurse

All Tests Summary

Component	Framework	Command
TypeScript Compiler	Deno test	`deno task test`
TypeScript API Client	Deno test	`deno task test`
.NET Compiler	xUnit	`dotnet test RulesCompiler.slnx`
.NET API Client	xUnit	`dotnet test src/AdGuard.ApiClient.sln`
Python Compiler	pytest	`pytest`
Rust Compiler	cargo test	`cargo test`
Rust API Client	cargo test	`cargo test`
PowerShell Module	Pester	`Invoke-Pester`

CI/CD

GitHub Actions workflows:

Workflow	Description
`dotnet.yml`	Build and test .NET projects with .NET 10
`typescript.yml`	TypeScript build, lint, and test
`powershell.yml`	PSScriptAnalyzer linting
`release.yml`	Build and publish binaries on version tags
`codeql.yml`	CodeQL security scanning
`devskim.yml`	DevSkim security analysis
`claude.yml`	Claude AI integration
`claude-code-review.yml`	Automated code review

Releases

The repository automatically builds and publishes binaries when a new version tag is pushed. See the Release Guide for details.

Pre-built binaries are available for:

AdGuard.ConsoleUI (Windows, Linux, macOS)
RulesCompiler.Console (Windows, Linux, macOS)
rules-compiler Rust binary (Windows, Linux, macOS)
rules-compiler Python wheel (cross-platform)

Download the latest release from the Releases page.

Documentation

Getting Started

Getting Started Guide - Quick installation and first compilation
Compiler Comparison - Choose the right compiler for your needs
Configuration Reference - Complete configuration schema
Docker Guide - Development with Docker containers

API Reference

Rules Compilers

TypeScript Compiler - Node.js/Deno compiler
.NET Compiler README - C# library and CLI
Python Compiler README - pip-installable package
Rust Compiler README - Single binary distribution
Shell Scripts README - Bash, Zsh, PowerShell, Batch
PowerShell Module - Full-featured PowerShell API

Development

Claude Instructions - AI assistant development guidelines
Security Policy - Vulnerability reporting
Release Guide - Release process and binary publishing
Centralized Package Management - NuGet package management
Shared Deno Configuration - Deno configuration pattern and guidelines

Test Your Ad Blocking

Environment Variables

API Clients

Both C# and Rust implementations support standardized environment variable names:

Variable	Description
`ADGUARD_API_KEY`	AdGuard DNS API credential (recommended cross-platform format)
`ADGUARD_API_BASE_URL`	API base URL (optional, cross-platform format)
`ADGUARD_AdGuard__ApiKey`	AdGuard DNS API credential (.NET hierarchical format)
`ADGUARD_AdGuard__BaseUrl`	API base URL (.NET hierarchical format)

Deprecated (backward compatibility only):

ADGUARD_API_TOKEN - Use ADGUARD_API_KEY instead
ADGUARD_API_URL - Use ADGUARD_API_BASE_URL instead

Cross-Compatibility: All API clients (C#, TypeScript, Rust) support both ADGUARD_API_KEY (recommended) and the .NET hierarchical format ADGUARD_AdGuard__ApiKey.

Note for .NET format: The ADGUARD_ prefix is required, and double underscore (__) represents colon (:) in configuration keys. Example: ADGUARD_AdGuard__ApiKey maps to AdGuard:ApiKey in configuration.

Rules Compilers

Variable	Application	Description
`DEBUG`	All compilers	Enable debug logging
`RULESCOMPILER_config`	.NET compiler	Default config file path
`RULESCOMPILER_Logging__LogLevel__Default`	.NET compiler	Log level (Debug, Information, Warning, Error)

Linear Integration

Variable	Description
`ADGUARD_LINEAR_API_KEY`	Linear integration scripts (recommended)
`LINEAR_API_KEY`	Legacy format (deprecated, use ADGUARD_LINEAR_API_KEY)

Contributing

Please see SECURITY.md for security policy and vulnerability reporting.

License

See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 398 Commits
.cargo		.cargo
.claude		.claude
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
api		api
data		data
docs		docs
src		src
tools		tools
.dockerignore		.dockerignore
.env.example		.env.example
.envrc.example		.envrc.example
.gitignore		.gitignore
.rustfmt.toml		.rustfmt.toml
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Directory.Build.props		Directory.Build.props
Directory.Packages.props		Directory.Packages.props
Dockerfile.warp		Dockerfile.warp
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
build.ps1		build.ps1
build.sh		build.sh
clippy.toml		clippy.toml
deno.base.json		deno.base.json
docker-compose.yml		docker-compose.yml
global.json		global.json
launcher.ps1		launcher.ps1
launcher.sh		launcher.sh
package-lock.json		package-lock.json
package.json		package.json
rust-toolchain.toml		rust-toolchain.toml

License

jaypatrick/ad-blocking

Folders and files

Latest commit

History

Repository files navigation

Ad-Blocking Repository

Table of Contents

Features

Rules Compilers (5 Languages)

AdGuard DNS API SDKs

Interactive Console Applications

Additional Features

Project Structure

Quick Start

🚀 Interactive Launcher (Easiest Way)

Prerequisites

Install Deno

Clone and Setup

Build All Projects

Compile Filter Rules (Any Language)

Docker Development Environment

Dockerfile.warp

Build and Run

Warp Environment

Data Directory Structure

Input Directory (data/input/)

Output Directory (data/output/)

Archive Directory (data/archive/)

Compilation Workflow

Rules Compilers

TypeScript Compiler

.NET Compiler

Python Compiler

Rust Compiler

Shell Scripts

Bash (Linux/macOS)

Zsh (macOS/Linux)

PowerShell Core (Cross-platform)

Windows Batch

PowerShell Modules

RulesCompiler Module

Webhook Module (v1.0.0 - NEW!)

Utility Scripts (Enhanced)

AdGuard API Clients

C# SDK

Rust SDK

TypeScript SDK

API Coverage (All SDKs)

Console Applications

.NET Console UI

Rust CLI

TypeScript CLI

Configuration

Configuration Properties

Source Properties

Available Transformations

Example Configurations

YAML

JSON

TOML

Testing

TypeScript (Deno)

.NET (xUnit)

Python (pytest)

Rust (cargo test)

PowerShell (Pester)

All Tests Summary

CI/CD

Releases

Documentation

Getting Started

API Reference

Rules Compilers

Development

Test Your Ad Blocking

Environment Variables

API Clients

Rules Compilers

Linear Integration

Input Directory (`data/input/`)

Output Directory (`data/output/`)

Archive Directory (`data/archive/`)

Packages