Swiftpack.co - Package - OperatorFoundation/Moonbounce

The Operator Foundation

Operator makes useable tools to help people around the world with censorship, security, and privacy.


Moonbounce is graphical user interface for using an OpenVPN client and server with Pluggable Transport support. The goal of Moonbounce is to provide a usability-focused, streamlined user experience to using PT-enabled OpenVPN.

OpenVPN on macOS

Much of the technical work for Moonbounce had to do with OpenVPN integration. The initial version of Moonbounce was developed for macOS and unfortunately OpenVPN has not entirely kept up with the changes in the VPN interfaces for macOS. The preferred method for VPN integration on macOS is now to use IPSec with IKEv3. OpenVPN’s protocol is not supported natively. The prefered way on macOS to integrate a custom VPN protocol is using the Network Extension API. However, OpenVPN does not provide such an extension. Therefore, the only way to integrate OpenVPN into an application currently is to run the openvpn command line tool in a separate process and allow it to access to kernel’s TUN API. Fortunately, recent version of OpenVPN support the UTUN interface on macOS, so a kernel module is no longer needed. However, unfortunately, UTUN access still requires that the openvpn command line tool be run as root. Generally, running commands as root is a deprecated and discouraged process on macOS. Apple has switched to a more fine-grained permissions model instead. As there is no special permission for accessing UTUN (since the Network Extension API is the preferred interface), the deprecated and coarse-grained approach of running the command as root is still needed. This requires some complex maneuvering is graphical applications such as the Moonbounce interface cannot be run as root and therefore do not have the permission to run openvpn as root. What Operator was required to do is to develop a helper tool that is installed by the Moonbounce interface as a launchd service. Responsibility for running the helper tool is delegating to launchd, which also takes care of giving it root user permission. The Moonbounce application communicates with the helper tool using Apple’s XPC protocol, which is a type of remote procedure call. The helper tool essentially exposes an API that the Moonbounce application can call remotely. This API is used to tell the helper out when to start and stop the openvpn command line tool. Using this complex array of mostly undocumented Apple APIs, Operator was able to get OpenVPN correctly working on OS X inside of the Moonbounce application. A benefit of this work is that the Moonbounce application and helper tool can serve as a guide and example for future developers attempting to deploy OpenVPN on macOS.

Shapeshifter Dispatcher

In addition to OpenVPN, Moonbounce also integrates shapeshifter-dispatcher, Operator's implementation of Pluggable Transport technology. This was relatively straightforward compared to OpenVPN, as shapeshifter-dispatcher does not require root access. A wrapper was created that launches both openvpn and shapeshifter-dispatcher with the correct arguments so that they work together and OpenVPN connections are made using Pluggable Transports. This was all integrated into the Moonbounce application using a straightforward interface to connect and disconnect from an OpenVPN over a Pluggable Transport.

Shapeshifter Server

In addition to the client-side work of configuring OpenVPN to work with Pluggable Transports, Operator also created wrappers to do the same thing on the server side. This code was based on Dlshad Othman’s published scripts for making OpenVPN work with obfsproxy. Operator wrapped up these scripts into a Terraform script, with specific provisioning created for Digital Ocean servers. This server provisioning tool was released at https://github.com/OperatorFoundation/shapeshifter-server. This functionality was included in the Moonbounce interface as well. The “Launch Server” button allows the user to input a Digital Ocean authentication token and subsequently launch an OpenVPN server with shapeshifter-dispatcher running as well. The Moonbounce “Connect” button can then be used to connect to this user-created server. A feature was also added that allows users to import servers. In the future, Operator plans to add a feature that allows user-created server to be exported so that they can be used with the import feature. In the meantime, test servers are available for trying out this feature.


Stars: 5
Help us keep the lights on