{"id":13645688,"url":"https://github.com/stealth/fraud-bridge","last_synced_at":"2025-05-08T21:16:33.055Z","repository":{"id":9216581,"uuid":"11029600","full_name":"stealth/fraud-bridge","owner":"stealth","description":"ICMP and DNS tunneling via IPv4 and IPv6","archived":false,"fork":false,"pushed_at":"2025-04-04T09:52:30.000Z","size":721,"stargazers_count":205,"open_issues_count":1,"forks_count":42,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-05-08T21:16:24.329Z","etag":null,"topics":["anti-censorship","censorship-circumvention","censorship-resistance","dns","dns-tunneling","icmp","icmp-tunnel","icmpv6","privacy","proxy","tunneling","udp-tunnel"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stealth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2013-06-28T15:09:32.000Z","updated_at":"2025-04-15T21:50:51.000Z","dependencies_parsed_at":"2024-01-07T22:49:10.681Z","dependency_job_id":"9752bb6e-61f6-4efd-9bf2-0b928c9e5c99","html_url":"https://github.com/stealth/fraud-bridge","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stealth%2Ffraud-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stealth%2Ffraud-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stealth%2Ffraud-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stealth%2Ffraud-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stealth","download_url":"https://codeload.github.com/stealth/fraud-bridge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253149621,"owners_count":21861740,"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":["anti-censorship","censorship-circumvention","censorship-resistance","dns","dns-tunneling","icmp","icmp-tunnel","icmpv6","privacy","proxy","tunneling","udp-tunnel"],"created_at":"2024-08-02T01:02:39.747Z","updated_at":"2025-05-08T21:16:33.048Z","avatar_url":"https://github.com/stealth.png","language":"C++","funding_links":[],"categories":["C++","\u003ca id=\"01e6651181d405ecdcd92a452989e7e0\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"9d6789f22a280f5bb6491d1353b02384\"\u003e\u003c/a\u003e隧道\u0026\u0026穿透"],"readme":"\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/stealth/fraud-bridge/blob/master/fraud-bridge.jpg\" /\u003e\n\u003c/p\u003e\n\n\nIntro\n-----\n\n*fraud-bridge* helps bypassing restrictive censorship environments that block direct TCP or UDP connections,\nby setting up ICMP, NTP or DNS (over IPv4 or IPv6) tunnels.\n\nIt automatically patches TCP MSS option to achieve a non-fragmented stream of packets (known as MSS-clamping) to gain\nperformance that allows to use web-sessions across the bridge.\n\nIt uses MD5 to (HMAC-)integrity protect the tunnel from evil injected TCP packets. If you need privacy,\nyou have to use encryption yourself. Its assumed that you use SSH over the tunnel anyways.\nEither directly or with the SSH proxy option if you need HTTP tunneled.\n\nWhen DNS tunneling, *fraud-bridge* uses `EDNS0` extension headers to put as many bytes into the `TXT` reply as possible.\n\n*fraud-bridge* also includes some other techniques to cope with certain *bind* limitations, e.g. quotas/limiting.\n\n**You can also use it to get full roaming/mobility support into your SSH sessions without any patch.**\n\nOnce you have set up the tunnel, you might want to read [how to get your messenger working across the tunnel.](https://github.com/stealth/crash/blob/master/contrib/proxywars.md)\n\nAlso note that `c-\u003eskills` is providing the full chain of censorship fucking equipment you may be interested in: [crash](https://github.com/stealth/crash) and [psc](https://github.com/stealth/psc)\n\nBuild\n-----\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/stealth/fraud-bridge/blob/master/bridge.jpg\" /\u003e\n\u003c/p\u003e\n\nJust do `make` on Linux.\n\nRun\n---\n\nThe usage is as follows:\n\n```\nfraud-bridge -- https://github.com/stealth/fraud-bridge\n\nUsage: fraud-bridge \u003c-k key\u003e [-R IP] [-L IP] [-pP port] [-iIuUnN] [-s sz]\n\t[-E sz] [-d dev] [-D domain] [-S usec] [-X user] [-r dir] [-t type] [-v]\n\n\t-k -- HMAC key to protect tunnel packets\n\t-R -- IP or IPv6 addr of (outside) peer when started inside\n\t-L -- local IP addr to bind to if started outside (can be omitted)\n\t-p -- remote port when in DNS/NTP mode (default: 53/123)\n\t-P -- local port when in DNS/NTP mode (outside default: 53/123)\n\t-i -- use ICMP tunnel\n\t-I -- use ICMPv6 tunnel\n\t-u -- use DNS tunnel over IP\n\t-U -- use DNS tunnel over IPv6\n\t-n -- use NTP4 tunnel over IP\n\t-N -- use NTP4 tunnel over IPv6\n\t-E -- set EDNS0 size (default: 1024)\n\t-s -- set MSS size (default: 1024)\n\t-d -- tunnel device to use (default: tun1)\n\t-D -- DNS domain to use when DNS tunneling\n\t-S -- usec slowdown for DNS ping (default: 5000)\n\t-X -- user to run as (default: nobody)\n\t-r -- chroot directory (default: /var/empty)\n\t-t -- override ICMP/ICMP6 type (usually no need to change)\n\t-v -- enable verbose mode\n```\n\nSome definitions: *inside* refers to the machine inside the censored network,\nmost likely your laptop/PC. *outside* refers to a VPS or machine outside the\ncensored network, i.e. what people call \"free internet\".\n\nAfter start, *fraud-bridge* opens a point-to-point tunnel: `1.2.3.4` \u003c-\u003e `1.2.3.5`\n\nThen you need to start `inside.sh` on the inside and `outside.sh` outside.\n\nLooks like so:\n\nOn outside end of tunnel (e.g. a server at the internet):\n```\n# ./fraud-bridge -u -L 192.168.2.222 -D f.sub.dnstunnel.com -k key\n```\n(and starting outside.sh)\n\nAnd inside:\n\n```\n# ./fraud-bridge -u -R 127.0.0.1 -D f.sub.dnstunnel.com -k key\n```\n(and starting inside.sh)\n\nas an example for a DNS tunnel with a local `127.0.0.1` *named* running and\nthe outside peer being at `192.168.2.222`. As said, outside part of\ntunnel can (and actually needs to) be started beforehand and will just\nlisten for the peer to open the tunnel. Example zone-files are included if\nyou want to experiment with your own bind setups. For running ITW tunnels\nthey are not necessary.\n\nThe default tunnel device is `tun1`. Make sure to not run multiple instances of\n*fraud-bridge* at the same time or any other tunnel software that is using this\ntunnel device. After each kill/restart of *fraud-bridge* daemon you have to execute the\ninside/outside scripts again at the particular end where you restarted it.\n\nImportant notes\n---------------\n\nThe `-L` parameter at outside can (should) be omitted. In real setups the `-R` parameter\non inside setups contains the IP or IP6 address of the outside server, or if\nDNS recursion is used, the IP address of the DNS server of your provider or\npublic recursive DNS resolver. If you do not have your own DNS server,\nyou can still use DNS tunneling by using your VPS IP as `-R` parameter\non inside and using any (but the same) `-D` domain paramater on both ends\nthat look legit for an censorship regime, e.g. `-D blah.gov`.\n\n**Before trying DNS tunneling, you most likely want to try with ICMP or NTP tunneling.**\nIf you see `chroot` warnings in the syslog, you can ignore them or provide\nvalid arguments to `-r`.\n\nYou can then use `ssh -D 1234 1.2.3.5` to get a SSH connection to `192.168.2.222`\nin above example and use the SOCKS5 proxy on port `:1234` for your web browser session\nthat then runs across the tunnel.\n\nYou can also do that with ICMP: `-i` and ICMP on IPv6: `-I` or DNS on UDP via\nIPv6: `-U` or NTP via UDP: `-n` or NTP via UDP/IPv6: `-N`.\n\nIt's also possible to switch the kind of tunnel (DNS to ICMP or ICMP to NTP) beyond your SSH connection,\nor to roam to another local IP (e.g. switching from wifi to 5G) as the TCP state is kept in local and remote\nkernel and not in the bridge. This allows full SSH roaming/mobility support without any patch to SSH.\n\nIn verbose mode, *fraud-bridge* will leave `stdout` open for reporting errors or messages,\nso you need to run it on a screen or redirect output to `/dev/null` if you need\nit running in (verbose) background. Keep that in mind since you need to start the inside/outside\nscripts after invoking *fraud-bridge*. If not using `-v`, it goes to background and logs\nerrors to syslog.\n\nBefore using any ICMP tunnels, make sure to relax your cable-modem's firewalling rules\nin order to receive the reply packets from your remote peer. *fraud-bridge* works behind\nNAT, but it needs to receive the reply packets at last. When using ICMP tunneling and ICMP echos\nare blocked, you can set the type parameter via `-t`. For instance using `-t 13` inside and `-t 14`\noutside to get timestamp request/reply pairs.\n\nWhen DNS tunneling, *fraud-bridge* uses `EDNS0` extension headers to put as many bytes into\nthe `TXT` reply as possible. In my tests, as it tries to answer any timing\npackets, it produces no logs in a *bind9* system log-file. If you change\nthe `EDNS0` (-E), you need to do it on both ends with the same value.\n(As inside announces maximum UDP payload size to the nameserver and outside\nendpoint calculates the MSS from that what was given with -E.)\n\nWhen using NTP tunneling, some providers with CGN block large NTP packets (on IPv4 only). In a common german\nISP, any NTP packets \u003e 256 bytes were blocked. So you have to set the MSS accordingly to get smaller packets\nlike `-s 100` so that the TCP stack is sending the segments in smaller sizes.\n\nPerformance considerations\n--------------------------\n\nSince *fraud-bridge* opens a PtP tunnel, it can strip the IP header off the packets\nthat it transmits and synthesize it at each end. So for ICMP tunneling you just have\nan overhead of 8 (ICMP) + 16 (HMAC) bytes, which is acceptable. DNS tunneling has still good latency and\nbandwidth when doing directly, thanks to MSS clamping. When tunneling indirectly via public\nDNS resolvers, the default values are good enough to have a reasonable session, but of course\nICMP tunneling is to prefer whenever possible.\n\nBy using `ssh -D [0.0.0.0]:1234 1.2.3.5` you can setup a local SOCKS proxy on your machine\nport 1234 (inside) and distribute it via WLAN to your neighborhood for censorship-free web sessions.\n\nYou may also setup a local *tor* on the outside box, offering a SOCKS port on `127.0.0.1:9150`\nas you normally do and then using `ssh -L 9150:127.0.0.1:9150 1.2.3.5` to forward this outside\nport to your inside machine, so to exactly mirror the outside *tor* setup locally and distribute it\nas *tor* SOCKS port via WLAN to your users. This way we do not need to implement pluggable transports\nand you can still use *tor* as before. The same also works with *crash* or *psc* sessions or any other\ntunneling mechanism.\n\nThe `-S` parameter has a reasonable default value for the DNS timer packets that need to be sent\nto the server in constant interval. Lower values give a better tunnel latency but may overload\nthe recursive DNS server and produce more noise.\n\n\n*proudly sponsored by:*\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/c-skills/welcome\"\u003e\n\u003cimg src=\"https://github.com/c-skills/welcome/blob/master/logo.jpg\"/\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstealth%2Ffraud-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstealth%2Ffraud-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstealth%2Ffraud-bridge/lists"}