{"id":27117093,"url":"https://github.com/a904guy/vpn-chainer","last_synced_at":"2025-08-25T07:06:57.811Z","repository":{"id":280502899,"uuid":"941054277","full_name":"a904guy/VPN-Chainer","owner":"a904guy","description":"VPN-Chainer – Chain multiple WireGuard VPNs dynamically, select the fastest with --fastest, and rotate them via API. Includes auto-routing, firewall rules, and systemd service support. 🚀","archived":false,"fork":false,"pushed_at":"2025-03-03T19:02:43.000Z","size":6,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-03T20:22:06.568Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/a904guy.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}},"created_at":"2025-03-01T11:24:42.000Z","updated_at":"2025-03-03T19:02:46.000Z","dependencies_parsed_at":"2025-03-03T20:22:08.841Z","dependency_job_id":"bf7187ab-7a3c-4bcf-a712-c3f4bb296f93","html_url":"https://github.com/a904guy/VPN-Chainer","commit_stats":null,"previous_names":["a904guy/vpn-chainer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a904guy%2FVPN-Chainer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a904guy%2FVPN-Chainer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a904guy%2FVPN-Chainer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a904guy%2FVPN-Chainer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/a904guy","download_url":"https://codeload.github.com/a904guy/VPN-Chainer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601458,"owners_count":20964864,"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","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":[],"created_at":"2025-04-07T05:53:59.172Z","updated_at":"2025-08-25T07:06:57.790Z","avatar_url":"https://github.com/a904guy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **VPN-Chainer 🛡️**\n\n## *A powerful WireGuard VPN chaining tool with dynamic routing, automated service control, and API support.*\n\n![VPN-Chainer](https://img.shields.io/badge/Built%20for-Debian%20%7C%20Ubuntu-blue.svg?style=flat-square)\n![WireGuard](https://img.shields.io/badge/Powered%20by-WireGuard-orange.svg?style=flat-square)\n![Python](https://img.shields.io/badge/Made%20with-Python%203-yellow.svg?style=flat-square)\n![PyPI](https://img.shields.io/badge/Available%20on-PyPI-green.svg?style=flat-square)\n\n## **🔹 Overview**\n\nVPN-Chainer allows you to **chain multiple WireGuard VPNs together**, dynamically reordering routes for improved anonymity and security. It includes **auto-installation as a system service**, API-based VPN rotation, and a customizable **pre/post spin-up/down hook system**.\n\nNow, you can **optionally test VPN speeds** and **select the fastest VPNs** using `--fastest`.  \n\n**📦 Available on PyPI** - Install easily with `pip install vpn-chainer`  \n\n---\n\n## **⚡ Features**\n\n✅ **Multi-Hop VPN Chaining** – Connect through multiple WireGuard VPNs in random order.  \n✅ **Speed-Tested VPN Selection** – Use `--fastest` to pick the top VPNs based on download speed.  \n✅ **Automatic Routing \u0026 Firewall Rules** – Seamless packet forwarding between VPN interfaces.  \n✅ **Pre/Post Execution Hooks** – Run custom scripts **before and after** VPN chain events.  \n✅ **Remote API Support** – Securely rotate VPNs via a web API.  \n✅ **Auto-Installation as a Systemd Service** – Persistently run VPN-Chainer in the background.  \n\n---\n\n## **🚀 Installation**\n\n### **🌟 Automated Setup Script (Recommended)**\n\nThis script automatically installs all prerequisites (WireGuard, systemd-resolved, iptables), VPN-Chainer via pipx, and sets up sudo access:\n\n```bash\ncurl -s https://raw.githubusercontent.com/a904guy/VPN-Chainer/main/scripts/setup.sh | sudo bash\n```\n\n### ** Prerequisites (Manual Installation)**\n\nIf you prefer manual installation, ensure you have **Python 3** and **WireGuard** installed:\n\n```bash\nsudo apt update  \nsudo apt install -y python3 python3-pip wireguard  \n```\n\n### ** Install VPN-Chainer from PyPI**\n\n**Easy installation via pip:**\n\n```bash\nsudo pip install vpn-chainer\n```\n\n### ** Alternative: Install from Source**\n\nIf you prefer to install from source:\n\n```bash\ngit clone https://github.com/a904guy/VPN-Chainer.git  \ncd VPN-Chainer  \nsudo python3 setup.py install\n```\n\n---\n\n## **🛠️ Usage**\n\n### **🔹 Basic Usage**\n\n```bash\nsudo vpn-chainer \u003cnumber_of_vpns\u003e  \n```\n\nFor example, to create a **3-hop VPN chain**:  \n\n```bash\nsudo vpn-chainer 3  \n```\n\n### **🔹 Use Speed Testing to Select Fastest VPNs**\n\nTo **test all VPNs first** and **pick the top N fastest VPNs**, use `--fastest`:  \n\n```bash\nsudo vpn-chainer 3 --fastest  \n```\n\n🚀 **This will:**\n- Test **all available VPNs** in `/etc/wireguard/`\n- Select **the top 3 fastest VPNs**\n- Use them in the **VPN chain**\n\n### **🔹 Install as a Systemd Service**\n\nAutomatically install and enable the VPN-Chainer service:  \n\n```bash\nsudo vpn-chainer 3 --auto-install  \n```\n\nOnce installed, it will **start automatically on boot**.\n\nTo **stop or restart** the service:  \n\n```bash\nsudo systemctl stop vpn-chainer  \nsudo systemctl restart vpn-chainer  \n```\n\nTo **view logs**:  \n\n```bash\nsudo journalctl -u vpn-chainer -f  \n```\n\n---\n\n## **📋 Example Execution**\n\nHere's what a typical VPN-Chainer session looks like when chaining 5 VPNs: (Note: PII has been randomized)\n\n```bash\n$ sudo vpn-chainer 5\n[HOOK] No pre-spin-up script found. Skipping.\n[DEBUG] Checking directory: /etc/wireguard\n[DEBUG] Found 12 config files\n\n[SETUP] Establishing VPN Chain...\n  [INFO] Saved original default route: default via 192.168.1.1 dev eth0 proto dhcp src 192.168.1.100 metric 100\n  [INFO] Parsed gateway: 192.168.1.1, interface: eth0\n  [INFO] VPN Chain Order: Singapore -\u003e Germany -\u003e Netherlands -\u003e Canada -\u003e Japan\n  [INFO] Endpoint IPs: 45.76.123.45 -\u003e 185.220.101.67 -\u003e 91.132.144.89 -\u003e 198.244.131.205 -\u003e 103.195.236.78\n  - Setting up VPN [Singapore] at 10.13.9.142/24...\nnet.ipv4.conf.Singapore.forwarding = 1\n    [INFO] Waiting for WireGuard handshake...\n    [ROUTE] Setting up first VPN Singapore\n    [ROUTE] Adding endpoint route for 45.76.123.45 via original gateway\n  - Setting up VPN [Germany] at 10.13.79.88/24...\nnet.ipv4.conf.Germany.forwarding = 1\n    [INFO] Waiting for WireGuard handshake...\n    [ROUTE] Setting up chaining: Germany -\u003e Singapore -\u003e Internet\n    [ROUTE] Adding endpoint route for 185.220.101.67 through Singapore\n  - Setting up VPN [Netherlands] at 10.13.58.203/24...\nnet.ipv4.conf.Netherlands.forwarding = 1\n    [INFO] Waiting for WireGuard handshake...\n    [ROUTE] Setting up chaining: Netherlands -\u003e Germany -\u003e Internet\n    [ROUTE] Adding endpoint route for 91.132.144.89 through Germany\n  - Setting up VPN [Canada] at 10.13.114.51/24...\nnet.ipv4.conf.Canada.forwarding = 1\n    [INFO] Waiting for WireGuard handshake...\n    [ROUTE] Setting up chaining: Canada -\u003e Netherlands -\u003e Internet\n    [ROUTE] Adding endpoint route for 198.244.131.205 through Netherlands\n  - Setting up VPN [Japan] at 10.13.80.177/24...\nnet.ipv4.conf.Japan.forwarding = 1\n    [INFO] Waiting for WireGuard handshake...\n    [ROUTE] Setting up chaining: Japan -\u003e Canada -\u003e Internet\n    [ROUTE] Adding endpoint route for 103.195.236.78 through Canada\n\n  [FINAL ROUTE] Routing all internet traffic through final VPN: Japan\n  [FINAL ROUTE] Added internet routes through Japan\nnet.ipv4.ip_forward = 1\n[HOOK] No post-spin-up script found. Skipping.\n\n[INFO] VPN Chain Established Successfully!\n  [VPN Route]  Singapore -\u003e Germany -\u003e Netherlands -\u003e Canada -\u003e Japan\n  [IP Route]   10.13.9.142/24 -\u003e 10.13.79.88/24 -\u003e 10.13.58.203/24 -\u003e 10.13.114.51/24 -\u003e 10.13.80.177/24\n  [INFO] All internet traffic now routed through VPN chain\n\n[INFO] VPN-Chainer API running at: http://192.168.1.100:5000/rotate_vpn?key=a1b2c3d4-e5f6-7890-abcd-ef1234567890\n\n * Serving Flask app 'vpn_chainer.vpn_chainer'\n * Debug mode: off\n * Running on all addresses (0.0.0.0)\n * Running on http://127.0.0.1:5000\n * Running on http://10.13.80.177:5000\nPress CTRL+C to quit\n^C[HOOK] No pre-spin-down script found. Skipping.\n\n[SHUTDOWN] Cleaning up VPNs...\n  - Deactivating VPN [Singapore]...\n  - Deactivating VPN [Germany]...\n  - Deactivating VPN [Netherlands]...\n  - Deactivating VPN [Canada]...\n  - Deactivating VPN [Japan]...\n  - Removed route: 45.76.123.45 via 192.168.1.1\n  - Route 185.220.101.67 dev Singapore already removed\n  - Route 91.132.144.89 dev Germany already removed\n  - Route 198.244.131.205 dev Netherlands already removed\n  - Route 103.195.236.78 dev Canada already removed\n  - Route 0.0.0.0/1 dev Japan already removed\n  - Route 128.0.0.0/1 dev Japan already removed\n  - Cleaning up iptables rules...\n  - Restarted DNS resolver\n[HOOK] No post-spin-down script found. Skipping.\n```\n\n**Key Points from the Output:**\n- 🔍 **Discovery**: Found 12 WireGuard config files in `/etc/wireguard/`\n- 🌐 **Chain Creation**: Established 5-hop VPN chain: Singapore → Germany → Netherlands → Canada → Japan\n- 🔒 **Security**: Each VPN's endpoint is routed through the previous VPN to prevent leaks\n- 📡 **API Access**: Web API available for remote VPN rotation with unique key\n- 🧹 **Clean Shutdown**: Proper cleanup when interrupted with Ctrl+C\n\n---\n\n## **🔗 API Usage**\n\n### **Rotate VPN Remotely**\n\nVPN-Chainer provides an **API to trigger VPN rotations**. The API key is displayed on startup:\n\n```bash\n[INFO] VPN-Chainer API running at:  \n🔗 http://127.0.0.1:5000/rotate_vpn?key=6a1f-45e9...  \n```\n\nTo rotate VPNs:  \n\n```bash\ncurl -X GET \"http://127.0.0.1:5000/rotate_vpn?key=YOUR_API_KEY\"  \n```\n\nThis will:\n- **Tear down** the current VPN chain.  \n- **Randomly select new VPN configs** *(or use fastest if started with `--fastest`)*.  \n- **Reestablish routing and firewall rules**.  \n\n---\n\n## **⚙️ Hook System (Pre/Post Execution Scripts)**\n\nVPN-Chainer allows you to **run scripts before and after VPN activation/deactivation**.\n\n### **🔹 Hook Script Locations**\n\nScripts should be placed in:\n\n```bash\n/etc/vpn-chainer/hooks/  \n```\n\n| Hook Script Name       | Triggered When |\n|------------------------|------------------------------------|\n| pre-spin-up.sh      | Before the VPN chain starts |\n| post-spin-up.sh     | After the VPN chain is established |\n| pre-spin-down.sh    | Before VPNs are torn down |\n| post-spin-down.sh   | After all VPNs have shut down |\n\n### **🔹 Example Hook: Restart Tor After VPN Starts**\n\nEdit `/etc/vpn-chainer/hooks/post-spin-up.sh`:  \n\n```bash\n# !/bin/bash  \n\necho \"[HOOK] Restarting Tor for anonymity...\"  \nsystemctl restart tor  \n```\n\nThen **enable the hook**:  \n\n```bash\nchmod +x /etc/vpn-chainer/hooks/post-spin-up.sh  \n```\n\n---\n\n## **📂 Configuration Files**\n\nVPN-Chainer automatically selects **random WireGuard config files** from:  \n/etc/wireguard/*.conf  \n\nEnsure that **at least the number of VPN configs requested exists**.\nAdditionally the **Address** line is required.\n\nExample VPN config:\n\n```yaml\n[Interface]  \nPrivateKey = \u003cYOUR_PRIVATE_KEY\u003e  \nAddress = 10.13.36.109/24  \nDNS = 10.8.0.1  \n\n[Peer]  \nPublicKey = \u003cPEER_PUBLIC_KEY\u003e  \nEndpoint = 10.10.10.24:51820  \nAllowedIPs = 0.0.0.0/0  \nPersistentKeepalive = 25  \n```\n\n---\n\n## **❓ Troubleshooting**\n\n### **🔸 VPN Doesn't Start**\n\n- Check that you have **WireGuard installed**:  \n\n```bash\nwhich wg  \n```\n\nIf missing, install it:  \n\n```bash\nsudo apt install wireguard  \n```\n\n- Ensure you have **enough VPN config files** in `/etc/wireguard/`.\n\n### **🔸 Systemd Service Not Running**\n\n- Check status:  \n\n```bash\nsudo systemctl status vpn-chainer  \n```\n\n- Restart it:  \n\n```bash\nsudo systemctl restart vpn-chainer  \n```\n\n### **🔸 API Not Responding**\n\n- Ensure VPN-Chainer is running:  \n\n```bash\nsudo systemctl status vpn-chainer  \n```\n\n- Check firewall rules (port `5000` must be open):  \n\n```bash\nsudo ufw allow 5000/tcp  \n```\n\n---\n\n## **📜 Roadmap**\n\n✔️ **Multi-Hop Randomization**  \n✔️ **Pre/Post Execution Hooks**  \n✔️ **Auto-Install as a Systemd Service**  \n✔️ **Speed-Tested VPN Selection (`--fastest`) (Added in v1.1)**  \n🔜 **Web Dashboard for Control \u0026 Logs**  \n🔜 **VPN Failover Detection ❓❓**  \n🔜 **Split-Tunneling (Selective Routing) ❓❓**  \n🔜 **Submit Your Ideas Via Issues**  \n\n---\n\n## **🤝 Contributing**\n\nWant to improve VPN-Chainer? Contributions are welcome! Fork the repository and submit a PR.\n\n1. **Fork \u0026 Clone**  \ngit clone https://github.com/a904guy/VPN-Chainer.git \ncd vpn-chainer  \n\n2. **Make Changes \u0026 Test**  \nsudo python3 vpn-chainer.py 3  \n\n3. **Submit a Pull Request**  \n\n---\n\n## **📜 License**\n\nThis project is licensed under the **MIT License**.\n\n---\n\n## **👨‍💻 Author**\n\n💡 Created by **Andy Hawkins**  \n🌐 GitHub: [a904guy GitHub Profile](https://github.com/a904guy)  \n\n---\n\n🚀 **VPN-Chainer is your ultimate tool for anonymous, multi-hop VPN tunneling!** 🔥\n💬 Have questions or feature requests? Open an **Issue** on GitHub! 😎\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa904guy%2Fvpn-chainer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa904guy%2Fvpn-chainer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa904guy%2Fvpn-chainer/lists"}