{"id":20635853,"url":"https://github.com/tholian-network/warps","last_synced_at":"2025-08-28T16:35:25.469Z","repository":{"id":255306310,"uuid":"848729825","full_name":"tholian-network/warps","owner":"tholian-network","description":":telescope: Warping your own Internet everywhere you go :satellite:","archived":false,"fork":false,"pushed_at":"2024-10-17T07:10:19.000Z","size":185,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T01:34:18.477Z","etag":null,"topics":["dns-exfiltration","edr-bypass","edr-evasion","firewall-bypass","http-smuggling","peer-to-peer","proxy-bypass"],"latest_commit_sha":null,"homepage":"","language":"Go","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/tholian-network.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":"2024-08-28T09:52:09.000Z","updated_at":"2024-12-14T18:44:20.000Z","dependencies_parsed_at":"2024-08-29T07:27:09.939Z","dependency_job_id":"12b91f37-55a3-401c-ac63-3fcb62e8aabc","html_url":"https://github.com/tholian-network/warps","commit_stats":null,"previous_names":["tholian-network/warps"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tholian-network%2Fwarps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tholian-network%2Fwarps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tholian-network%2Fwarps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tholian-network%2Fwarps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tholian-network","download_url":"https://codeload.github.com/tholian-network/warps/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249155912,"owners_count":21221678,"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":["dns-exfiltration","edr-bypass","edr-evasion","firewall-bypass","http-smuggling","peer-to-peer","proxy-bypass"],"created_at":"2024-11-16T15:07:46.548Z","updated_at":"2025-04-15T21:26:13.473Z","avatar_url":"https://github.com/tholian-network.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Tholian® Warps\n\nTholian® Warps is a proactive and adaptive Mesh Network Router.\n\nIt tries to automatically detect and bypass censorship and throttling\nmeasurements at all cost. Programmable routing, traffic compression,\ntraffic scattering, dynamic encryption rotation and other features\nare part of this experimental research project.\n\nThe goal of this project is to find out how feasible common NAT breaking\nand firewall bypassing techniques are and whether they can be used to\nbuild a reliable mesh network that's based on a peer-to-peer architecture.\n\n\n# Network Architecture\n\n1. A `tunnel` instance tunnels network traffic through a `forward` or `gateway` instance to access the internet.\n2. A `tunnel` uses the initial configured network protocol.\n3. A `forward` instance tunnels network traffic through other `forward` or `gateway` instances.\n4. All `gateway` instances use `optimizers` to reduce web asset file sizes.\n5. All `gateway` instances use `DNS over TLS` to resolve relayed DNS queries.\n6. All instances use a local [ProxyCache](./source/structs/ProxyCache.go) and [ResolverCache](./source/structs/ResolverCache.go).\n7. All instances can rotate encryption keys and can scatter network traffic on-demand.\n\n\n## How to use Tunnels and Gateways\n\nThe easiest way to use Warps is with running a Warps `gateway` on your own VPS that is connected to the internet,\nand a locally running Warps `tunnel`.\n\nAs a defaulted network protocol, it is best to use `dns`, as that usually works to bypass typical firewall setups.\nAlternative supported network protocols are documented further down in this document.\n\n![network-architecture.png](https://github.com/tholian-network/warps/blob/master/assets/network-chart.png?raw=true)\n\n```bash\n# On your VPS server (1.3.3.7)\ntholian-warps gateway \"dns://0.0.0.0:1053\";\n\n# On your local machine\ntholian-warps tunnel \"any\" \"dns://1.3.3.7:1053\";\ncurl -x localhost:1080 http://google.com;\n```\n\n\n## How to use Proxy Chains\n\nWarps can be chained via multiple proxies, without a limit on how many network hops you want to the public internet.\nIn this example, we are routing local web traffic through 3 instances before the traffic hits the clearnet.\n\n```bash\n# On your first VPS server (1.3.3.7)\ntholian-warps gateway \"dns://0.0.0.0:1337\";\n\n# On your second VPS server (1.3.3.8)\ntholian-warps forward \"http://1.3.3.8:1338\" \"dns://1.3.3.7:1337\";\n\n# On your third VPS server (1.3.3.9)\ntholian-warps forward \"dns://1.3.3.9:1339\" \"http://1.3.3.8:1338\";\n\n# On your local machine\n# local -\u003e dns -\u003e 1.3.3.9 -\u003e http -\u003e 1.3.3.8 -\u003e dns -\u003e 1.3.3.7 -\u003e * -\u003e internet\ntholian-warps tunnel \"any\" \"dns://1.3.3.9:1339\";\ncurl -x localhost:1080 http://google.com;\n```\n\n\n# Usage\n\n:construction: Highly Experimental at this point - Use at own risk! :construction:\n\n```bash\nbash build.sh;\nsudo cp ./build/tholian-warps /usr/bin/tholian-warps;\n\n# Show CLI usage help\ntholian-warps;\n```\n\n\n# Data Compressors\n\nThese are the data compressors that have been implemented:\n\n- [ ] [compressors/text/css](/source/compressors/text/css)\n- [ ] [compressors/text/html](/source/compressors/text/html)\n- [ ] [compressors/text/js](/source/compressors/text/js)\n- [ ] [compressors/image/jpeg](/source/compressors/image/jpeg)\n- [ ] [compressors/image/png](/source/compressors/image/png)\n\n\n# Network Protocols\n\nThese are the transport protocols that have been implemented:\n\n- [x] `dns` or [protocols/dns](/source/protocols/dns) implements DNS Exfiltration\n- [x] `http` or [protocols/http](/source/protocols/http) implements HTTP Smuggling and DNS over HTTP\n- [x] `https` or [protocols/https](/source/protocols/https) implements HTTPS Smuggling and DNS over HTTPS\n- [ ] `icmp` or [protocols/icmp](/source/protocols/icmp) implements ICMP Knocking and DNS over ICMP\n- [ ] `ssh` or [protocols/ssh](/source/protocols/ssh) implements SSH Tunneling and DNS over SSH\n- [ ] `socks` or [protocols/socks](/source/protocols/socks) implements SOCKS Routing (e.g. for TOR/I2P usage)\n- [x] [protocols/test](/source/protocols/test) implements the `Spy` testing data structures\n\n\n# Test Coverage\n\nThese are the `go test` files that have been implemented:\n\n- [x] [structs/ProxyCache](/source/structs/ProxyCache_test.go)\n- [x] [structs/ResolverCache](/source/structs/ResolverCache_test.go)\n- [ ] [utils/net/url/IsTrackingParameter](/source/utils/net/url/IsTrackingParameter_test.go)\n- [ ] [utils/net/url/IsXSSParameter](/source/utils/net/url/IsXSSParameter_test.go)\n- [x] [utils/net/url/ResolveCache](/source/utils/net/url/ResolveCache_test.go)\n- [x] [utils/net/url/ToHostAndPort](/source/utils/net/url/ToHostAndPort_test.go)\n- [x] [utils/net/url/ToHost](/source/utils/net/url/ToHost_test.go)\n- [ ] [utils/protocols/http/IsFilteredHeader](/source/protocols/http/IsFilteredHeader_test.go)\n- [x] [protocols/dns/Resolver](/source/protocols/dns/Resolver_test.go)\n- [x] [protocols/dns/Proxy](/source/protocols/dns/Proxy_test.go)\n- [ ] [protocols/dns/Tunnel](/source/protocols/dns/Tunnel_test.go)\n- [x] [protocols/dns/tunnel/ToRecordName](/source/protocols/dns/tunnel/ToRecordName_test.go)\n- [x] [protocols/http/Proxy](/source/protocols/http/Proxy_test.go)\n- [ ] [protocols/http/Tunnel](/source/protocols/http/Tunnel_test.go)\n\n\n# License\n\nAGPL3\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftholian-network%2Fwarps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftholian-network%2Fwarps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftholian-network%2Fwarps/lists"}