Ghostunnel

👻

Ghostunnel is a simple TLS proxy with mutual authentication support for securing non-TLS backend applications.

Ghostunnel supports two modes, client mode and server mode. Ghostunnel in server mode runs in front of a backend server and accepts TLS-secured connections, which are then proxied to the (insecure) backend. A backend can be a TCP domain/port or a UNIX domain socket. Ghostunnel in client mode accepts (insecure) connections through a TCP or UNIX domain socket and proxies them to a TLS-secured service.

Supported platforms: Ghostunnel is developed primarily for Linux and Darwin (macOS), although it should run on any UNIX system that exposes SO_REUSEPORT, including FreeBSD, OpenBSD and NetBSD. Ghostunnel also supports running on Windows, though with a reduced feature set.

Features

Access control: Ghostunnel enforces mutual authentication by requiring a valid client certificate for all connections. Policies can enforce checks on the peer certificate in a connection, either via simple flags or declarative policies using Open Policy Agent. This is useful for restricting access to services that don't have native access control.

Certificate hotswapping: Ghostunnel can reload certificates at runtime without dropping existing connections. Certificates can be loaded from disk, the SPIFFE Workload API, or a PKCS#11 module. This allows short-lived certificates to be used with Ghostunnel as you can pick up new certificates transparently.

ACME Support: In server mode, Ghostunnel can optionally obtain and automatically renew a public TLS certificate via the ACME protocol, such as through Let's Encrypt. Note that this requires a valid FQDN accessible on the public internet for verification.

Monitoring and metrics: Ghostunnel has a built-in status feature that can be used to collect metrics and monitor a running instance. Metrics can be fed into Graphite or Prometheus to see number of open connections, rate of new connections, connection lifetimes, timeouts, and other info.

Emphasis on security: We have put some thought into making Ghostunnel secure by default and prevent accidental misconfiguration. For example, we always negotiate TLS v1.2 (or greater) and only use safe cipher suites. Ghostunnel also supports loading certificates from the Windows/macOS keychains or via PKCS#11 which makes it possible to use Hardware Security Modules (HSMs) to protect private keys.

Getting Started

To get started and play around with the Ghostunnel you will need X.509 client and server certificates. If you don't already maintain a PKI, a good way to get started is to use a package like cloudflare/cfssl.

For testing and development purposes, you can generate test certificates using:

# Generate test certificates and keys
mage test:keys

This will create a test-keys directory with all the necessary certificates and keys for testing. Note: These are test certificates only and should NOT be used in production.

Install

Ghostunnel is available through GitHub releases and through Docker Hub.

Please note that the official release binaries are best effort, and are usually built directly via Github Actions on the latest available images. If you need compatibility for specific OS versions we recommend building yourself.

Ghostunnel uses the mage build system, a make/rake-like build tool using Go. You can build Ghostunnel with the mage commands shown below.

# Compile binary
mage go:build

# Build containers
mage docker:build

You can also run mage -l to view all build targets and add -v to mage commands to get more verbose output.

Develop

Ghostunnel has an extensive suite of integration tests. Our integration test suite requires Python 3.

To run tests:

# Option 1: run unit & integration tests locally
mage test:all

# Option 2: run unit & integration tests in a Docker container
# This also runs PKCS#11 integration tests using SoftHSM in the container
mage test:docker

# Open coverage information in browser
go tool cover -html coverage/all.profile

For more information on how to contribute, please see the CONTRIBUTING file.

Usage

To see available commands and flags, run ghostunnel --help. You can get more information about a command by adding --help to the command, like ghostunnel server --help or ghostunnel client --help. There's also a man page.

By default, Ghostunnel runs in the foreground and logs to stdout. You can set --syslog to log to syslog instead of stdout. If you want to run Ghostunnel in the background, we recommend using a service manager.

Certificates

Ghostunnel accepts certificates in multiple different file formats.

The --keystore flag can take a PKCS#12 keystore or a combined PEM file with the certificate chain and private key as input (format is auto-detected). The --cert / --key flags can be used to load a certificate chain and key from separate PEM files (instead of a combined one).

Ghostunnel also supports loading identities from the macOS keychain or the SPIFFE Workload API and having private keys backed by PKCS#11 modules, see the "Advanced Features" section below for more information.

Server mode

This is an example for how to launch Ghostunnel in server mode, listening for incoming TLS connections on localhost:8443 and forwarding them to localhost:8080. Note that while we use TCP sockets on localhost in this example, both the listen and target flags can also accept paths to UNIX domain sockets as their argument.

To set allowed clients, you must specify at least one of --allow-all, --allow-cn, --allow-ou, --allow-dns, --allow-uri or --allow-policy. All checks are made against the certificate of the client. Multiple flags are treated as a logical disjunction (OR), meaning clients can connect as long as any of the flags matches. See ACCESS-FLAGS for more information. In this example, we assume that the CN of the client cert we want to accept connections from is client.

Note: Before running the examples below, make sure you have generated the test certificates by running mage test:keys (see the Getting Started section above).

Start a backend server:

nc -l localhost 8080

Start a Ghostunnel in server mode to proxy connections:

ghostunnel server \
    --listen localhost:8443 \
    --target localhost:8080 \
    --keystore test-keys/server-keystore.p12 \
    --cacert test-keys/cacert.pem \
    --allow-cn client

Verify that clients can connect with their client certificate:

openssl s_client \
    -connect localhost:8443 \
    -cert test-keys/client-combined.pem \
    -key test-keys/client-combined.pem \
    -CAfile test-keys/cacert.pem

Now we have a TLS proxy running for our backend service. We terminate TLS in Ghostunnel and forward the connections to the insecure backend.

Client mode

This is an example for how to launch Ghostunnel in client mode, listening on localhost:8080 and proxying requests to a TLS server on localhost:8443.

By default, Ghostunnel in client mode verifies targets based on the hostname. Various access control flags exist to perform additional verification on top of the regular hostname verification. See ACCESS-FLAGS for more information.

Start a backend TLS server:

openssl s_server \
    -accept 8443 \
    -cert test-keys/server-combined.pem \
    -key test-keys/server-combined.pem \
    -CAfile test-keys/cacert.pem

Start a Ghostunnel with a client certificate to forward connections:

ghostunnel client \
    --listen localhost:8080 \
    --target localhost:8443 \
    --keystore test-keys/client-combined.pem \
    --cacert test-keys/cacert.pem

Verify that we can connect to 8080:

nc -v localhost 8080

Now we have a TLS proxy running for our client. We take the insecure local connection, wrap them in TLS, and forward them to the secure backend.

Full tunnel (client plus server)

We can combine the above two examples to get a full tunnel. Note that you can start the tunnels in either order.

Start netcat on port 8001:

nc -l localhost 8001

Start the Ghostunnel server:

ghostunnel server \
    --listen localhost:8002 \
    --target localhost:8001 \
    --keystore test-keys/server-combined.pem \
    --cacert test-keys/cacert.pem \
    --allow-cn client

Start the Ghostunnel client:

ghostunnel client \
    --listen localhost:8003 \
    --target localhost:8002 \
    --keystore test-keys/client-keystore.p12 \
    --cacert test-keys/cacert.pem

Verify that we can conne