{"id":20677257,"url":"https://github.com/operatorfoundation/shapeshifter-dispatcher","last_synced_at":"2025-08-24T06:07:45.679Z","repository":{"id":13195427,"uuid":"73853237","full_name":"OperatorFoundation/shapeshifter-dispatcher","owner":"OperatorFoundation","description":"Shapeshifter Dispatcher converts Pluggable Transports that implement the Go API from the Pluggable Transports 2.1 specification into proxies usable by applications. Several proxy modes are provided, including proxying of both TCP and UDP traffic.","archived":false,"fork":false,"pushed_at":"2024-07-09T22:40:06.000Z","size":1065,"stargazers_count":181,"open_issues_count":15,"forks_count":28,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-07-21T23:47:03.967Z","etag":null,"topics":["anticensorship","censorship-circumvention","golang","internet-freedom","pluggable-transports"],"latest_commit_sha":null,"homepage":"https://OperatorFoundation.org/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OperatorFoundation.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":"LICENSE","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":"2016-11-15T20:39:05.000Z","updated_at":"2025-07-11T17:35:27.000Z","dependencies_parsed_at":"2023-12-13T22:11:11.230Z","dependency_job_id":"923fb230-c2f8-4200-abd8-681e43f6e6fd","html_url":"https://github.com/OperatorFoundation/shapeshifter-dispatcher","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/OperatorFoundation/shapeshifter-dispatcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OperatorFoundation%2Fshapeshifter-dispatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OperatorFoundation%2Fshapeshifter-dispatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OperatorFoundation%2Fshapeshifter-dispatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OperatorFoundation%2Fshapeshifter-dispatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OperatorFoundation","download_url":"https://codeload.github.com/OperatorFoundation/shapeshifter-dispatcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OperatorFoundation%2Fshapeshifter-dispatcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271803829,"owners_count":24824521,"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-24T02:00:11.135Z","response_time":111,"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":["anticensorship","censorship-circumvention","golang","internet-freedom","pluggable-transports"],"created_at":"2024-11-16T21:15:00.292Z","updated_at":"2025-08-24T06:07:45.633Z","avatar_url":"https://github.com/OperatorFoundation.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"### The Operator Foundation\n\n[Operator](https://operatorfoundation.org) makes useable tools to help people around the world with censorship, security, and privacy.\n\n## Shapeshifter\n\nThe Shapeshifter project provides network protocol shapeshifting technology\n(also sometimes referred to as obfuscation). The purpose of this technology is\nto change the characteristics of network traffic so that it is not identified\nand subsequently blocked by network filtering devices.\n\nThere are two components to Shapeshifter: transports and the dispatcher. Each\ntransport provide different approach to shapeshifting. These transports are\nprovided as a Go library which can be integrated directly into applications.\nThe dispatcher is a command line tool which provides a proxy that wraps the\ntransport library. It has several different proxy modes and can proxy both\nTCP and UDP traffic.\n\nIf you are a tool developer working in the Go programming language, then you\nprobably want to use the transports library directly in your application.\n\u003chttps://github.com/OperatorFoundation/shapeshifter-transports\u003e\n\nIf you want an end user that is trying to circumvent filtering on your network, or\nyou are a developer that wants to add pluggable transports to an existing tool\nthat is not written in the Go programming language, then you probably want the\ndispatcher. Please note that familiarity with executing programs on the command\nline is necessary to use this tool.\n\u003chttps://github.com/OperatorFoundation/shapeshifter-dispatcher\u003e\n\nIf you are looking for a complete, easy-to-use VPN that incorporates\nshapeshifting technology and has a graphical user interface, consider\n[Moonbounce](https://github.com/OperatorFoundation/Moonbounce), an application for macOS which incorporates shapeshifting without\nthe need to write code or use the command line.\n\n# Shapeshifter Dispatcher\n\nThis is the repository for the shapeshifter-dispatcher command line proxy tool.\nIf you are looking for the transports is provides, they are here:\n\u003chttps://github.com/OperatorFoundation/shapeshifter-transports\u003e\n\nThe purpose of the dispatcher is to provide different proxy interfaces to using\ntransports. Through the use of these proxies, application traffic can be sent\nover the network in a shapeshifted form that bypasses network filtering, allowing\nthe application to work on networks where it would otherwise be blocked or\nheavily throttled.\n\nThe dispatcher currently supports the following proxy modes:\n * SOCKS5 (with optional PT 2.0 authentication protocol)\n * Transparent TCP\n * Transparent UDP\n * STUN UDP\n\nThe transports used by shapeshifter-dispatcher follow the Go Transport API in the [Pluggable Transports Specification v3.0](https://github.com/Pluggable-Transports/Pluggable-Transports-spec/blob/main/releases/PTSpecV3.0/Pluggable%20Transport%20Specification%20v3.0%20-%20Go%20Transport%20API%20v3.0.md).  \nThe dispatcher currently supports the following transports:\n * Replicant\n * Optimizer\n * shadow (Shadowsocks)\n \n Note: obs4 is no longer supported.  We recommend using Shadow in it's place.\n\n#### Installation\n\nThe dispatcher is written in the Go programming language. To compile it you need\nto install Go 1.17 or higher:\n\n\u003chttps://golang.org/doc/install\u003e\n\nIf you already have Go installed, make sure it is a compatible version:\n\n    go version\n\nThe version should be 1.17 or higher.\n\nIf you get the error \"go: command not found\", then trying exiting your terminal\nand starting a new one.\n\nGet the git repository for shapeshifter-disptacher:\n\n    git clone https://github.com/OperatorFoundation/shapeshifter-dispatcher.git\n\nGo into that directory and build the command line executable:\n\n    cd shapeshifter-dispatcher\n    go install\n\n\nThis will fetch the source code for shapeshifter-dispatcher, and all the\ndependencies, compile everything, and put the result in\n\u003cGOPATH\u003e/bin/shapeshifter-dispatcher\n\nYou can find your GOPATH with:\n\n    go env GOPATH\n\n\n#### Running\n\nUse either -client or -server to place the proxy into client or server mode,\nrespectively. Use -state to specify a directory to put transports state\ninformation. Use -transports to specify which transports to launch.  Use -optionsFile to specify the directory where your config file is located\n\nThe default proxy mode is SOCKS5 (with optional PT 2.1 authentication protocol),\nwhich can only proxy SOCKS5-aware TCP connections. For some transports, the\nproxied connection will also need to know how to speak the PT 1.0 authentication\nprotocol. This requirement varies by the transport used.\n\nAnother TCP proxy mode is available, Transparent TCP, by using the -transparent\nflag. In this mode, the proxy listens on a socket and any data from incoming\nconnections is forwarded over the transport.\n\nUDP proxying can be enabled with the -udp flag. The default UDP mode is STUN\npacket proxying. This requires that the application only send STUN packets, so\nworks for protocols such as WebRTC, which are based on top of STUN.\n\nAnother UDP proxy mode is available, Transparent UDP, by using the -transparent\nflag with the -udp flag. In this mode, the proxy listens on a UDP socket and\nany incoming packets are forwarded over the transport.\n\nOnly one proxy mode can be used at a time.\n\n#### Running with Replicant\n\nReplicant is Operator's flagship transport which can be tuned for each adversary.\n\nHere are example command lines to run the dispatcher with the Replicant transport:\n\n##### Server\n\nFor this example to work, you need an application server running. You can use netcat to run a simple server on port 3333:\n \n    nc -l 3333\n\nNow launch the transport server, telling it where to find the application server:\n\n    \u003cGOPATH\u003e/bin/shapeshifter-dispatcher -transparent -server -state state -target 127.0.0.1:3333 -transports Replicant -bindaddr Replicant-127.0.0.1:2222 -optionsFile ConfigFiles/ReplicantServerConfigV3.json -logLevel DEBUG -enableLogging\n\nThis runs the server in transparent TCP proxy mode. The directory \"state\" is used\nto hold transport state. The destination that the server will proxy to is\n127.0.0.1, port 3333. The Replicant transport is enabled and bound to the address 127.0.0.1 and the port 2222. Logging is enabled and set to DEBUG level.\nTo access the Log for debugging purposes, look at state/dispatcher.log\n\nTo use Replicant, a config file is needed. A sample config file, located in ConfigFiles/ReplicantServerConfigV3.json, is provided purely for educational purposes and should not be used in actual production.\n\n##### Client\n\n    \u003cGOPATH\u003e/bin/shapeshifter-dispatcher -transparent -client -state state -transports Replicant -proxylistenaddr 127.0.0.1:1443 -optionsFile ConfigFiles/ReplicantClientConfigV3.json -logLevel DEBUG -enableLogging\n\nThis runs the client in transparent TCP proxy mode. The directory \"state\" is\nused to hold transport state. The address of the server is specified as\n127.0.0.1, port 2222. This is the same address as was specified on the server\ncommand line above. For this demo to work, the dispatcher server needs to be\nrunning on this host and port. The Replicant transport is enabled and bound to the\naddress 127.0.0.1 and the port 1443.\n\nTo use Replicant, a config file is needed. A sample config file, located in ConfigFiles/ReplicantClientConfigV3.json, is provided purely for educational purposes and should not be used in actual production.\n\nOnce the client is running, you can connect to the client address, which in this\ncase is 127.0.0.1, port 1443. For instance, you can telnet to this address:\n\n    telnet 127.0.0.1 1443\n\nAny bytes sent over this connection will be forwarded through the transport\nserver to the application server, which in the case of this demo is a netcat\nserver. You can also type bytes into the netcat server and they will appear\non the telnet client, once again being routed over the transport.\n\n### Using Environment Variables\n\nUsing command line flags is convenient for testing. However, when launching the\ndispatcher automatically from inside of an application, another option is to\nuse environment variables. Most of the functionality specified by command line\nflags can also be set using environment variables instead.\n\n### Running in SOCKS5 Mode\n\nSOCKS5 mode is an older mode inherited from the PT1.0 specification and updated in PT2.0. Despite the name,\nSOCKS5 mode does not provide a SOCKS proxy for use with SOCKS clients such as Firefox. Rather it uses the\nSOCKS5 protocol as a way to communicate between a host application and Shapeshifter Dispatcher. The host application\nmust be aware of the special semantics used by this mode. While it is possible to configure Shapeshifter Dispatcher\nto provide a traditional SOCKS proxy for use with SOCKS clients such as Firefox, that is not covered here.\n\nSOCKS5 mode is not recommended for most users, use Transparent TCP mode instead.\n\nHere are example command lines to run the dispatcher in SOCKS5 mode with the Replicant transport:\n\n##### Server\n\nFor this example to work, you need an application server running. You can use netcat to run a simple server on port 3333:\n \n    nc -l 3333\n\nNow launch the transport server, telling it where to find the application server:\n\n    \u003cGOPATH\u003e/bin/shapeshifter-dispatcher -server -state state -target 127.0.0.1:3333 -bindaddr shadow-127.0.0.1:2222 -transports shadow -optionsFile ConfigFiles/shadowServer.json -logLevel DEBUG -enableLogging\n\nThis runs the server in the default mode, which is SOCKS5 mode. The directory \"state\" is used\nto hold transport state. The destination that the server will proxy to is 127.0.0.1, port 3333.\nThe Replicant transport is enabled and bound to the address 127.0.0.1 and the port\n2222. Logging is enabled and set to DEBUG level. To access the Log for debugging purposes,\nlook at state/dispatcher.log\n\nTo use Replicant, a config file is needed. A sample config file, ReplicantServerConfigV3.json, is provided purely for educational purposes and should not be used in actual production.\n\n##### Client\n\n    \u003cGOPATH\u003e/bin/shapeshifter-dispatcher -client -state state -transports shadow -proxylistenaddr 127.0.0.1:1443 -optionsFile ConfigFiles/shadowClient.json -logLevel DEBUG -enableLogging\n\nThis runs the client in the default mode, which is SOCKS5 mode. The directory \"state\" is\nused to hold transport state. The Replicant transport is enabled and bound to the\naddress 127.0.0.1 and the port 1443. Please note that you do not specify the server address with -target in SOCKS5\nmode. This happens below, in the tsocks step.\n\nTo use Replicant, a config file is needed. A sample config file, ReplicantClientConfigV3.json, is provided purely for educational purposes and should not be used in actual production.\n\nOnce the client is running, you can connect to the client address, which in this\ncase is 127.0.0.1, port 1443. You will need to use a SOCKS5 client. Normally, this would be a host application\nthat you would write. For basic testing, you can install a tool such as tsocks.\n\nFor instance, on macOS, install tsocks:\n\n    brew tap Anakros/homebrew-tsocks\n    brew install --HEAD tsocks\n    nano /usr/local/etc/tsocks.conf        \n    \nIn your tsocks configuration file, add the following lines to tell it where to find the dispatcher client:\n\n    server = 127.0.0.1\n    server_port = 1443\n    server_type = 5\n    \nIt is important to check to make sure that your tsocks configuration is correct. If you have the wrong server\naddress or port, tsocks will connect you directly to the transport server and this will give confusing results.\n\nNow you can use telnet to connect to the server and tsocks to route the traffic through SOCKS:\n\n    tsocks telnet 127.0.0.1 2222\n\nIt is important to note that the address and port you telnet to is the address of the transport server. This\ninformation is passed through the SOCKS5 protocol to the client by tsocks and it is how the client learns where\nthe server is located.\n\nAt this point, you should have a normal connection through the transport to the application server. Any bytes sent\nover this connection will be forwarded through the transport server to the application server, which in the case of\nthis demo is a netcat server. You can also type bytes into the netcat server and they will appear\non the telnet client, once again being routed over the transport.\n\nPlease note that this is not an open SOCKS proxy that allows you to connect to any address on the Internet. You\ncan only connect to the application server associated with the transport server. The SOCKS protocol is only\nused as a method of communication between a host application and the transport client. While we use tsocks as\nthe host application for this explanation, normally the host application would be a custom application provided by\nyou.\n\nSOCKS5 mode is not recommended for most users, use Transparent TCP mode instead.\n\n### Config generator\n\nTo generate a new pair of configs for any of the supported transports, run the following command:\n\n    \u003cGOPATH\u003e/bin/shapeshifter-dispatcher -generateConfig -transport \u003ctransport name\u003e -serverIP \u003cserverIP:Port\u003e\n\nFor Replicant, you can also add the flags -toneburst and/or -polish if you would like to enable the Starburst toneburst and the Darkstar polish respectively\n\n### Credits\n\nshapeshifter-dispatcher is descended from the Tor project's \"obfs4proxy\" tool.\n\n * David Fifield for goptlib\n * Adam Langley for the Go Elligator implementation.\n * Philipp Winter for the ScrambleSuit protocol.\n * [Shadowsocks](https://shadowsocks.org/guide/what-is-shadowsocks.html) was developed by the Shadowsocks team. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foperatorfoundation%2Fshapeshifter-dispatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foperatorfoundation%2Fshapeshifter-dispatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foperatorfoundation%2Fshapeshifter-dispatcher/lists"}