{"id":29417971,"url":"https://github.com/opensecurity/wireadguard","last_synced_at":"2025-08-10T08:10:42.977Z","repository":{"id":303892051,"uuid":"1017040524","full_name":"opensecurity/wireadguard","owner":"opensecurity","description":"Docker Compose to launch a WireGuard VPN that routes your traffic through an AdGuard Home DNS sinkhole and a private Unbound recursive DNS resolver.","archived":false,"fork":false,"pushed_at":"2025-07-10T00:19:35.000Z","size":7,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-10T10:06:33.608Z","etag":null,"topics":["adblock","adguard-home","adguardhome","dns","privacy","unbound","unbound-dns","vpn","vpn-server","wireguard","wireguard-vpn"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opensecurity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-09T23:55:23.000Z","updated_at":"2025-07-10T00:23:49.000Z","dependencies_parsed_at":"2025-07-10T10:06:41.621Z","dependency_job_id":"27940030-27d2-4ef2-a520-c3bd20f541d5","html_url":"https://github.com/opensecurity/wireadguard","commit_stats":null,"previous_names":["opensecurity/wireadguard"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/opensecurity/wireadguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensecurity%2Fwireadguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensecurity%2Fwireadguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensecurity%2Fwireadguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensecurity%2Fwireadguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opensecurity","download_url":"https://codeload.github.com/opensecurity/wireadguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensecurity%2Fwireadguard/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269693593,"owners_count":24460248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adblock","adguard-home","adguardhome","dns","privacy","unbound","unbound-dns","vpn","vpn-server","wireguard","wireguard-vpn"],"created_at":"2025-07-11T23:00:30.209Z","updated_at":"2025-08-10T08:10:42.950Z","avatar_url":"https://github.com/opensecurity.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wiradeguard: your self-hosted dns sinkhole \u0026 privacy core\n\nThis project provides the blueprints to forge your own hardened network core. The goal is to achieve **digital sovereignty** by aggressively filtering network traffic and eliminating data exfiltration at its source. You will build a system that you own and control, making your network actively hostile to advertisers, trackers, and malicious actors.\n\nThe stack is composed of three key layers:\n\n  * **Encrypted transport (`WireGuard`)**: A high-speed, kernel-level VPN that acts as a secure, encrypted transport layer. All traffic from your devices is forced through this tunnel, preventing any local network or ISP-level snooping.\n\n  * **DNS sinkhole (`AdGuard Home`)**: The filtering engine and traffic controller. It intercepts all DNS queries and cross-references them against curated blocklists. Requests to advertising, malware, or tracking domains are **black-holed** sent to a null route, effectively ceasing to exist from your devices' perspective.\n\n  * **Recursive resolver (`Unbound`)**: A zero-knowledge DNS resolver that you control. Instead of forwarding your Browse habits to a third-party service (like Google's `8.8.8.8`), Unbound performs **recursive lookups** itself, querying the internet's root DNS servers directly. This ensures your DNS history remains private.\n\n-----\n\n## Architecture: the data flow\n\nThe architecture is designed as a strict, sequential pipeline. Data must pass through each layer of inspection before it's allowed to reach the public internet.\n\n```mermaid\ngraph LR\n    subgraph Your Device\n        A[Client Device]\n    end\n\n    subgraph Wiradeguard Core\n        A -- 1 DNS Query --\u003e B(WireGuard)\n        B -- 2 Decrypt Query --\u003e C[AdGuard Home]\n        C -- 3a Malicious Query --\u003e D[Sinkhole Block]\n        C -- 3b Safe Query --\u003e E[Unbound Resolver]\n        E -- 4 Resolve IP --\u003e C\n        C -- 5 Return IP --\u003e B\n        B -- 6 Send IP to Client --\u003e A\n    end\n\n    subgraph Public Internet\n        F[Website]\n    end\n\n    A -- 7 Data Connection --\u003e B\n    B -- 8 Route to Website --\u003e F\n```\n\n-----\n\n## Understanding your DNS choices\n\nTo understand why this project is built this way, it's crucial to know who can see your Browse history in different setups.\n\n### **Scenario 1: The default internet**\n\nWhen you don't use a VPN, your Internet Service Provider (ISP) handles your DNS requests.\n\n  * **What happens:** Your ISP sees every website you visit and can log this history. This data can be monetized or shared.\n\n### **Scenario 2: Using a VPN with a public DNS (e.g., Cloudflare)**\n\nThis common setup involves routing your traffic through a WireGuard server, which then asks a public resolver like Cloudflare or Google for DNS records.\n\n  * **What happens:**\n    1.  Your **home ISP** is blinded. They only see encrypted traffic going to your server.\n    2.  Your server then forwards your DNS query (e.g., \"what is the IP for `site.com`?\") to Cloudflare.\n  * **The privacy issue:** You've simply shifted trust. Now, your **server's ISP** can see your server asking Cloudflare for information, and **Cloudflare** itself can log your entire Browse history.\n\n### **Scenario 3: The Wiradeguard way (full privacy with Unbound)**\n\nThis project uses Unbound as your own private resolver, which is the key to maximizing privacy.\n\n  * **What happens:**\n    1.  Your **home ISP** is blinded, same as before.\n    2.  Your server's AdGuard Home passes the DNS query to your **own Unbound resolver**.\n    3.  Unbound does **not** forward the question to a single company. Instead, it communicates directly with the internet's authoritative root servers to find the answer itself.\n  * **The privacy benefit:** What your server's ISP sees is completely different. Instead of a neat stream of requests to a single company like Cloudflare, they see scattered, low-level DNS chatter to many different high-level servers across the internet. This pattern is much harder to track and doesn't create a clean log of your Browse habits for any single entity.\n\n### **Summary: Who sees your history?**\n\n| Setup | Your Home ISP | Your Server's ISP | Third-Party DNS (Cloudflare) |\n| :--- | :--- | :--- | :--- |\n| **Default Internet** | ✅ Yes | (not applicable) | (if used) |\n| **VPN + Public DNS** | ❌ No | ✅ Yes | ✅ Yes |\n| **Wiradeguard (VPN + Unbound)**| ❌ No | (only scattered traffic) | ❌ No |\n\nThis project defaults to Scenario 3 because it prevents any single company from easily logging your entire digital life.\n\n-----\n\n## Deployment\n\n### Prerequisites\n\n  * A Linux host (VPS or local machine) with root/sudo access.\n  * **Docker** and **Docker Compose** installed.\n  * `git` and `wget` installed.\n\n### Step 1: initial configuration\n\nClone the repository and instantiate your local environment file.\n\n```bash\ngit clone https://github.com/opensecurity/wiradeguard\ncd wiradeguard\ncp .env-example .env\n```\n\nNext, **edit the `.env` file**. Set your `C_TZ` (timezone), the number of WireGuard peers (`C_WIREGUARD_PEERS`), and the external VPN port (`C_WIREGUARD_PORT`).\n\n### Step 2: system preparation \u0026 deployment\n\nThe `Makefile` automates the setup. First, prime the system by fetching the root hints file required by Unbound. Then, launch the stack.\n\n```bash\n# Fetch the root hints file for unbound\nmake get-root-hints\n\n# (Optional but recommended) Apply kernel performance tuning\nmake tune-host\n\n# Build and launch the full stack in detached mode\nmake up\n```\n\nThis command will pull the required images, build the containers, and generate your WireGuard client configurations in the `./wireguard/conf/` directory.\n\n### Step 3: finalizing the dns sinkhole\n\nThis crucial one-time step directs AdGuard Home to use your private Unbound resolver instead of a public one.\n\n1.  Navigate to your AdGuard Home console at `http://\u003cyour_server_ip\u003e:3000`.\n2.  Complete the initial setup wizard to create your admin account.\n3.  Go to **Settings -\\\u003e DNS settings**.\n4.  Under **Upstream DNS servers**, delete any default entries and add **only** your Unbound container:\n    ```\n    theoracle:53\n    ```\n5.  Under **Private reverse DNS servers**, add the same entry:\n    ```\n    theoracle:53\n    ```\n6.  Click **Apply**. Your DNS resolution is now fully self-contained.\n\n### Step 4: connecting clients\n\nImport a generated `.conf` file from `./wireguard/conf/` into your WireGuard client on your phone, laptop, or other devices. Once connected, all your traffic is being filtered through your Wiradeguard core.\n\n-----\n\n## Operations\n\nAll stack management is handled via the `Makefile`:\n\n  * `make up`: Deploys and starts the entire stack.\n  * `make down`: Shuts down the stack and destroys its data volumes.\n  * `make logs`: Tails the aggregated logs from all running services in real-time.\n  * `make restart`: Performs a clean restart of all services.\n\n\u003c!-- DOCKUMENTOR START --\u003e\n\n### 🐳 Service: theoracle\n- **Image**: mvance/unbound:latest\n- **Ports**: \n- **Volumes**: ./unbound/:/opt/unbound/etc/unbound/\n- **Depends On**: \n- **Command**: No command specified\n#### Environment Variables\n\n| Variable | Value |\n|----------|-------|\n\n### 🐳 Service: blackhole\n- **Image**: adguard/adguardhome:latest\n- **Ports**: 127.0.0.1:3000:3000\n- **Volumes**: adguard_work:/opt/adguardhome/work, ./adguard/conf:/opt/adguardhome/conf\n- **Depends On**: theoracle\n- **Command**: No command specified\n#### Environment Variables\n\n| Variable | Value |\n|----------|-------|\n\n### 🐳 Service: stargate\n- **Image**: linuxserver/wireguard:latest\n- **Ports**: 0.0.0.0:${C_WIREGUARD_PORT}:51820/udp\n- **Volumes**: ./wireguard/conf:/config, /lib/modules:/lib/modules:ro\n- **Depends On**: blackhole\n- **Command**: No command specified\n#### Environment Variables\n\n| Variable | Value |\n|----------|-------|\n| PUID | ${C_PUID} |\n| PGID | ${C_PGID} |\n| TZ | ${C_TZ} |\n| PEERS | ${C_WIREGUARD_PEERS} |\n| PEERDNS | 10.13.37.10 |\n| INTERNAL_SUBNET | 10.42.42.0/24 |\n| ALLOWEDIPS | 0.0.0.0/0 |\n\n\n\n## Networks\n\n\n### Network: vpn_dns_net\n\n\n\n## Graphs\n\n### Network depend\n```mermaid\nflowchart TD\ntheoracle[\"theoracle\u003cbr\u003emvance/unbound:latest\"]\nblackhole[\"blackhole\u003cbr\u003eadguard/adguardhome:latest\u003cbr\u003ePorts: 127.0.0.1:3000:3000\"]\ntheoracle --\u003e blackhole\nstargate[\"stargate\u003cbr\u003elinuxserver/wireguard:latest\u003cbr\u003ePorts: 0.0.0.0:${C_WIREGUARD_PORT}:51820/udp\"]\nblackhole --\u003e stargate\nsubgraph vpn_dns_net\ntheoracle\nblackhole\nstargate\nend\n\n```\n\n### Services depend\n```mermaid\nsankey-beta\nblackhole, stargate, 1\ntheoracle, blackhole, 1\n```\n\n### Services ports\n```mermaid\nsankey-beta\nExternal, blackhole, 1\nExternal, stargate, 1\nvpn_dns_net, theoracle, 1\n```\n\n## Service Interaction Sequence Diagram\n\n```mermaid\nsequenceDiagram\n    participant theoracle as theoracle\u003cbr\u003emvance/unbound:latest\n    participant blackhole as blackhole\u003cbr\u003eadguard/adguardhome:latest\n    participant stargate as stargate\u003cbr\u003elinuxserver/wireguard:latest\n    theoracle-\u003e\u003eblackhole: request/response\n    blackhole-\u003e\u003estargate: request/response\n\n```\n\n## Example Commands\n\n- **Start Services**: `docker compose up -d`\n- **Stop Services**: `docker compose down`\n- **View Logs for a Service**: `docker compose logs [service]`\n\n## Troubleshooting\n\n\n- Ensure Docker is running before starting services.\n\n- Check container logs if a service fails to start.\n\n- Verify network connections if services can't communicate.\n\n\n## Maintenance Tips\n\n\n- To update a service, modify the image tag and run `docker-compose up -d`.\n\n- Review and apply environment variable changes without rebuilding containers.\n\n\u003c!-- DOCKUMENTOR END --\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopensecurity%2Fwireadguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopensecurity%2Fwireadguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopensecurity%2Fwireadguard/lists"}