{"id":37122667,"url":"https://github.com/vmware-archive/ghostunnel","last_synced_at":"2026-01-14T14:10:36.669Z","repository":{"id":61839485,"uuid":"198672419","full_name":"vmware-archive/ghostunnel","owner":"vmware-archive","description":null,"archived":true,"fork":false,"pushed_at":"2019-07-24T19:38:35.000Z","size":4223,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-19T00:04:05.162Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vmware-archive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-24T16:30:43.000Z","updated_at":"2023-01-27T22:59:55.000Z","dependencies_parsed_at":"2022-10-22T05:00:30.753Z","dependency_job_id":null,"html_url":"https://github.com/vmware-archive/ghostunnel","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/vmware-archive/ghostunnel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-archive%2Fghostunnel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-archive%2Fghostunnel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-archive%2Fghostunnel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-archive%2Fghostunnel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vmware-archive","download_url":"https://codeload.github.com/vmware-archive/ghostunnel/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-archive%2Fghostunnel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28422408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T13:30:50.153Z","status":"ssl_error","status_checked_at":"2026-01-14T13:29:08.907Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-14T14:10:35.831Z","updated_at":"2026-01-14T14:10:36.652Z","avatar_url":"https://github.com/vmware-archive.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"Ghostunnel\n==========\n\n[![license](http://img.shields.io/badge/license-apache_2.0-blue.svg?style=flat)](https://raw.githubusercontent.com/square/ghostunnel/master/LICENSE) [![release](https://img.shields.io/github/release/square/ghostunnel.svg?style=flat)](https://github.com/square/ghostunnel/releases) [![docker](https://img.shields.io/badge/docker-hub-blue.svg?style=flat)](https://hub.docker.com/r/squareup/ghostunnel) [![travis](https://img.shields.io/travis/square/ghostunnel/master.svg?maxAge=3600\u0026logo=travis\u0026label=travis)](https://travis-ci.org/square/ghostunnel) [![appveyor](https://img.shields.io/appveyor/ci/csstaub/ghostunnel-58e7k.svg?maxAge=3600\u0026logo=appveyor\u0026label=appveyor)](https://ci.appveyor.com/project/csstaub/ghostunnel-58e7k) [![coverage](https://coveralls.io/repos/github/square/ghostunnel/badge.svg?branch=master)](https://coveralls.io/r/square/ghostunnel) [![report](https://goreportcard.com/badge/github.com/square/ghostunnel)](https://goreportcard.com/report/github.com/square/ghostunnel)\n\n👻\n\nGhostunnel is a simple TLS proxy with mutual authentication support for\nsecuring non-TLS backend applications.\n\nGhostunnel supports two modes, client mode and server mode. Ghostunnel in\nserver mode runs in front of a backend server and accepts TLS-secured\nconnections, which are then proxied to the (insecure) backend. A backend can be\na TCP domain/port or a UNIX domain socket. Ghostunnel in client mode accepts\n(insecure) connections through a TCP or UNIX domain socket and proxies them to\na TLS-secured service. In other words, ghostunnel is a replacement for stunnel.\n\n**Supported platforms**: Ghostunnel is developed primarily for Linux on x86-64\nplatforms, although it should run on any UNIX system that exposes `SO_REUSEPORT`,\nincluding Darwin (macOS), FreeBSD, OpenBSD and NetBSD. Ghostunnel also supports\nrunning on Windows, though with a reduced feature set. We recommend running on\nx86-64 to benefit from constant-time implementations of cryptographic algorithms\nthat are not available on other platforms.\n\nSee `ghostunnel --help`, `ghostunnel server --help` and `ghostunnel client --help`.\n\nFeatures\n========\n\n**[Access control](#access-control-flags)**: Ghostunnel enforces mutual\nauthentication by requiring a valid client certificate for all connections. We\nalso support access control via checks on the subject (or subject alternative\nnames) of a client certificate. This is useful for restricting access to\nservices that don't have native access control.\n\n**[Certificate hotswapping](#certificate-hotswapping)**: Ghostunnel can reload\ncertificates at runtime without dropping existing connections. Certificate\nreloading can be triggered with a signal or on a regular time interval. This\nallows short-lived certificates to be used with ghostunnel, new certificates\nwill get picked up transparently. And on platforms with `SO_REUSEPORT` support,\nrestarts can be done with minimal downtime.\n\n**[Monitoring and metrics](#metrics--profiling)**: Ghostunnel has a built-in\nstatus feature that can be used to collect metrics and monitor a running\ninstance. Metrics can be fed into Graphite (or other systems) to see number of\nopen connections, rate of new connections, connection lifetimes, timeouts, and\nother info.\n\n**[Emphasis on security](BUG-BOUNTY.md)**: We have put some thought into making ghostunnel\nsecure by default and prevent accidental misconfiguration. For example,  we\nalways negotiate TLS v1.2 and only use safe cipher suites. Ghostunnel also\nsupports PKCS#11 which makes it possible to use Hardware Security Modules\n(HSMs) to protect private keys, and we have a bug bounty that\npays rewards for security findings. \n\nGetting Started\n===============\n\nTo get started and play around with the implementation, you will need to\ngenerate some test certificates. If you want to bootstrap a full PKI, one\ngood way to get started is to use a package like\n[square/certstrap](https://github.com/square/certstrap). If you only need\nsome test certificates for playing around with the tunnel, you can find\nsome pre-generated ones in the `test-keys` directory (alongside instructions\non how to generate new ones with OpenSSL).\n\n### Install\n\nGhostunnel is available through [GitHub releases][rel] and through [Docker Hub][hub].\n\nBinaries can be built from source as follows (cross-compile requires Docker and [xgo][xgo]):\n\n    # Compile for local architecture\n    make ghostunnel\n\n    # Cross-compile release binaries\n    make -f Makefile.dist dist\n\nNote that ghostunnel requires Go 1.12 or later to build, and CGO is required for\nPKCS#11 support.  See also [CROSS-COMPILE](docs/CROSS-COMPILE.md) for\ninstructions on how to cross-compile a custom build with CGO enabled.\n\n[rel]: https://github.com/square/ghostunnel/releases\n[hub]: https://hub.docker.com/r/squareup/ghostunnel\n[xgo]: https://github.com/karalabe/xgo\n\n### Develop\n\nGhostunnel has an extensive suite of integration tests. Our integration test\nsuite requires Python 3.5 (or later) and [gocovmerge][gcvm] to run. We use [Go\nmodules][gomod] for managing vendored dependencies. \n\nTo run tests:\n\n    # Option 1: run unit \u0026 integration tests locally\n    make test\n\n    # Option 2: run unit \u0026 integration tests in a Docker container\n    GO_VERSION=1.12.4 make docker-test\n\n    # Open coverage information in browser\n    go tool cover -html coverage-merged.out\n\nFor more information on how to contribute, please see the [CONTRIBUTING](CONTRIBUTING.md) file.\n\n[gcvm]: https://github.com/wadey/gocovmerge\n[gomod]: https://github.com/golang/go/wiki/Modules\n\nUsage\n=====\n\nBy default, ghostunnel runs in the foreground and logs to stderr. You can set\n`--syslog` to log to syslog instead of stderr. If you want to run ghostunnel\nin the background, we recommend using a service manager such as [systemd][systemd] or\n[runit][runit], or use a wrapper such as [daemonize][daemonize] or [dumb-init][dumb-init].\n\n[runit]: http://smarden.org/runit\n[systemd]: https://www.freedesktop.org/wiki/Software/systemd\n[daemonize]: http://software.clapper.org/daemonize\n[dumb-init]: https://github.com/Yelp/dumb-init\n\n### Certificates\n\nGhostunnel accepts certificates in multiple different file formats.\n\nThe `--keystore` flag can take a PKCS#12 keystore or a combined PEM file with the\ncertificate chain and private key as input (format is auto-detected). The `--cert` /\n`--key` flags can be used to load a certificate chain and key from separate PEM files\n(instead of a combined one).\n\nGhostunnel also supports loading identities from the macOS keychain and having\nprivate keys backed by PKCS#11 modules, see the \"Advanced Features\" section below\nfor more information.\n\n### Server mode \n\nThis is an example for how to launch ghostunnel in server mode, listening for\nincoming TLS connections on `localhost:8443` and forwarding them to\n`localhost:8080`. Note that while we use TCP sockets on `localhost` in this\nexample, both the listen and target flags can also accept paths to UNIX domain\nsockets as their argument.\n\nTo set allowed clients, you must specify at least one of `--allow-all`,\n`--allow-cn`, `--allow-ou`, `--allow-dns` or `--allow-uri`. All checks are made\nagainst the certificate of the client. Multiple flags are treated as a logical\ndisjunction (OR), meaning clients can connect as long as any of the flags\nmatches (see [ACCESS-FLAGS](docs/ACCESS-FLAGS.md) for more information). In\nthis example, we assume that the CN of the client cert we want to accept\nconnections from is `client`.\n\nStart a backend server:\n\n    nc -l localhost 8080\n\nStart a ghostunnel in server mode to proxy connections:\n\n    ghostunnel server \\\n        --listen localhost:8443 \\\n        --target localhost:8080 \\\n        --keystore test-keys/server-keystore.p12 \\\n        --cacert test-keys/cacert.pem \\\n        --allow-cn client\n\nVerify that clients can connect with their client certificate:\n\n    openssl s_client \\\n        -connect localhost:8443 \\\n        -cert test-keys/client-combined.pem \\\n        -key test-keys/client-combined.pem \\\n        -CAfile test-keys/cacert.pem\n\nNow we have a TLS proxy running for our backend service. We terminate TLS in\nghostunnel and forward the connections to the insecure backend.\n\n### Client mode\n\nThis is an example for how to launch ghostunnel in client mode, listening on\n`localhost:8080` and proxying requests to a TLS server on `localhost:8443`. \n\nStart a backend TLS server:\n\n    openssl s_server \\\n        -accept 8443 \\\n        -cert test-keys/server-combined.pem \\\n        -key test-keys/server-combined.pem \\\n        -CAfile test-keys/cacert.pem\n\nStart a ghostunnel with a client certificate to forward connections:\n\n    ghostunnel client \\\n        --listen localhost:8080 \\\n        --target localhost:8443 \\\n        --keystore test-keys/client-combined.pem \\\n        --cacert test-keys/cacert.pem\n\nVerify that we can connect to `8080`:\n\n    nc -v localhost 8080\n\nNow we have a TLS proxy running for our client. We take the insecure local\nconnection, wrap them in TLS, and forward them to the secure backend.\n\n### Full tunnel (client plus server)\n\nWe can combine the above two examples to get a full tunnel. Note that you can\nstart the ghostunnels in either order.\n\nStart netcat on port `8001`:\n\n    nc -l localhost 8001\n\nStart the ghostunnel server:\n\n    ghostunnel server \\\n        --listen localhost:8002 \\\n        --target localhost:8001 \\\n        --keystore test-keys/server-combined.pem \\\n        --cacert test-keys/cacert.pem \\\n        --allow-cn client\n\nStart the ghostunnel client:\n\n    ghostunnel client \\\n        --listen localhost:8003 \\\n        --target localhost:8002 \\\n        --keystore test-keys/client-keystore.p12 \\\n        --cacert test-keys/cacert.pem\n\nVerify that we can connect to `8003`:\n\n    nc -v localhost 8003\n\nNow we have a full tunnel running. We take insecure client connections, \nforward them to the server side of the tunnel via TLS, and finally terminate\nand proxy the connection to the insecure backend.\n\nAdvanced Features\n=================\n\n### Access Control Flags\n\nGhostunnel supports different types of access control flags in both client and\nserver modes.  All checks are made against the certificate of the client or\nserver. Multiple flags are treated as a logical disjunction (OR), meaning\nclients can connect as long as any of the flags matches. Ghostunnel is\ncompatible with [SPIFFE][spiffe] [X.509 SVIDs][svid].\n\nSee [ACCESS-FLAGS](docs/ACCESS-FLAGS.md) for details.\n\n[spiffe]: https://spiffe.io/\n[svid]: https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md\n\n### Logging Options\n\nYou can silence specific types of log messages using the `--quiet=...` flag,\nsuch as `--quiet=conns` or `--quiet=handshake-errs`. You can pass this flag\nrepeatedly if you want to silence multiple different kinds of log messages.\n\nSupported values are:\n* `all`: silences **all** log messages\n* `conns`: silences log messages about new and closed connections. \n* `conn-errs`: silences log messages about connection errors encountered (post handshake). \n* `handshake-errs`: silences log messages about failed handshakes. \n\nIn particular we recommend setting `--quiet=handshake-errs` if you are\nrunning TCP health checks in Kubernetes on the listening port, and you\nwant to avoid seeing error messages from aborted connections on each health\ncheck.\n\n### Certificate Hotswapping\n\nTo trigger a reload, simply send `SIGUSR1` to the process or set a time-based\nreloading interval with the `--timed-reload` flag. This will cause ghostunnel\nto reload the certificate and private key from the files on disk. Once\nsuccessful, the reloaded certificate will be used for new connections going\nforward.\n\nAdditionally, ghostunnel uses `SO_REUSEPORT` to bind the listening socket on\nplatforms where it is supported (Linux, Apple macOS, FreeBSD, NetBSD, OpenBSD\nand DragonflyBSD). This means a new ghostunnel can be started on the same\nhost/port before the old one is terminated, to minimize dropped connections (or\navoid them entirely depending on how the OS implements the `SO_REUSEPORT`\nfeature).\n\nNote that if you are using an HSM/PKCS#11 module, only the certificate will\nbe reloaded. It is assumed that the private key in the HSM remains the same.\nThis means the updated/reissued certificate much match the private key that\nwas loaded from the HSM previously, everything else works the same.\n\n### Metrics \u0026 Profiling\n\nGhostunnel has a notion of \"status port\", a TCP port (or UNIX socket) that can\nbe used to expose status and metrics information over HTTPS. The status port\nfeature can be controlled via the `--status` flag. Profiling endpoints on the\nstatus port can be enabled with `--enable-pprof`.\n\nSee [METRICS](docs/METRICS.md) for details.\n\n### HSM/PKCS#11 support\n\nGhostunnel has support for loading private keys from PKCS#11 modules, which\nshould work with any hardware security module that exposes a PKCS#11 interface.\n\nSee [HSM-PKCS11](docs/HSM-PKCS11.md) for details.\n\n### Socket Activation (experimental)\n\nGhostunnel supports socket activation via both systemd (on Linux) and launchd\n(on macOS). Socket activation is support for the `--listen` and `--status`\nflags, and can be used by passing an address of the form `systemd:\u003cname\u003e` or\n`launchd:\u003cname\u003e`, where `\u003cname\u003e` should be the name of the socket as defined in\nyour systemd/launchd configuration.\n\nSee [SOCKET-ACTIVATION](docs/SOCKET-ACTIVATION.md) for examples.\n\n### PROXY Protocol (experimental)\n\nGhostunnel in server mode supports signalling of transport connection information\nto the backend using the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)\n(v2), just pass the `--proxy-protocol` flag on startup. Note that the backend must\nalso support the PROXY protocol and must be configured to use it when setting\nthis option.\n\n### MacOS Keychain Support (experimental)\n\nIf ghostunnel has been compiled with build tag `certstore` (off by default,\nrequires macOS 10.12+) a new flag will be available that allows for loading\ncertificates from the macOS keychain. This is useful if you have identities\nstored in your local keychain that you want to use with ghostunnel, e.g. if you\nwant your private key(s) to be backed by the SEP on newer Touch ID MacBooks.\nCertificates from the keychain can be loaded by selecting them based on the\nCommon Name (CN) of the subject.\n\nFor example, if you have an identity with CN 'example' in your login keychain:\n\n    ghostunnel client \\\n        --keychain-identity example \\\n        --listen unix:/path/to/unix/socket \\\n        --target example.com:443 \\\n        --cacert test-keys/cacert.pem\n\nThe command above launches a ghostunnel instance that uses the certificate and\nprivate key with Common Name 'example' from your login keychain to proxy plaintext\nconnections from a given UNIX socket to example.com:443.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmware-archive%2Fghostunnel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvmware-archive%2Fghostunnel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmware-archive%2Fghostunnel/lists"}