[](https://github.com/fkantelberg/socket-proxy/actions/workflows/main.yaml)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
# socket-proxy
This tool allows to forward TCP ports through a proxy server. The proxy server can expose
the listening port directly or bridge the port between two clients allowing the bridge client
to expose the listening port. Afterwards the applications can connect directly to the
exposed ports like they were connected to the listening port. For easier handling
HTTP ports can directly be addressed and the proxy server exposed those throw sub-domains
as a simple reverse proxy.
### Security
With this tool you can publish local service which might cause security issues for non-hardened
ports. You should consider further security measurements to harden critical systems if used. The
HTTP implementation is very basic. It's recommended to use a reverse proxy
like nginx with SSL and a wildcard certificate if HTTPS is required.
### Features
- TLS encryption of the tunnel
- Support for client certificates if CA is specified on the server
- Support for token authentication. These tokens are rotating automatically
- Bridge mode to allow to forward a port from one client to another bridge client
- Support for IPv4 and IPv6
- Proxy generic TCP ports or more specific HTTP servers
- Limitation of number of tunnels, clients per tunnel, and connections per IP
- Limit the access to specific IP's
- Configuration on server and client side and negotiation of the used settings
- Web API with support of bearer authentication. The API allows to look into the proxy server, client or bridge client
- Event system to send HTTP POST requests to a webhook with information about the event
### Usage
The below examples are assuming the minimal necessary certificates. You can generate CA and
certificates to be used on the server and client (e.g. using certs.sh of the package,
easy-rsa, or openssl directly).
#### Direct exposure on the proxy server
1. Start a proxy server using a certificate and matching private key
```
$ socket_proxy server --cert certificate.pem --key certificate.key
```
2. Start a tunnel client and connect to a server. Tunnelled connections can access server reachable under TARGET:PORT
```
$ socket_proxy client --ca ca.pem -c SERVER -d TARGET:PORT
```
3. Connect clients to the opened ports on the server (see the log or the API for the correct port)
#### Bridge mode and exposure on a bridge client
1. Start a proxy server using a certificate and matching private key
```
$ socket_proxy server --cert certificate.pem --key certificate.key
```
2. Start a tunnel client and connect to a server. Tunnelled connections can access server reachable under TARGET:PORT. Additional we specify that we want to bridge it using `--protocol`. See the log or API for the bridge token
```
$ socket_proxy client --ca ca.pem -c SERVER -d TARGET:PORT --protocol bridge
```
3. Connect an additional client to bridge the port and expose it locally
```
$ socket_proxy bridge --ca ca.pem -c SERVER --bridge BRIDGE_TOKEN
```
4. Connect clients to the opened ports on the bridge client (see the log or the API for the correct port)
### Web API Client
`GET /` returns the state of the server as JSON dictionary. Use the path to get only specific information.
E.g. `/clients` only returns the sub-dictionary `clients` and `/clients/edcb13dc0c7c6c64` returns only
information about the client `edcb13dc0c7c6c64`.
`DELETE /<client>` disconnects the client `<client>`.
The client side API doesn't support SSL!
### Web API Server
`GET /` returns the state of the server as JSON dictionary. Use the path to get only specific information.
E.g. `/tunnels` only returns the sub-dictionary `tunnels` and `/tunnels/edcb13dc0c7c6c64` returns only
information about the tunnel `edcb13dc0c7c6c64`.
`GET /api/token` returns a new authentication token as JSON string.
`DELETE /<tunnel>/<client>` disconnects the client `<client>` of the tunnel `<tunnel>`.
`DELETE /<tunnel>` disconnects the tunnel `<tunnel>`.
Raw data
{
"_id": null,
"home_page": "https://github.com/fkantelberg/socket-proxy",
"name": "socket-proxy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "proxy socket network",
"author": "Florian Kantelberg",
"author_email": "florian.kantelberg@mailbox.org",
"download_url": null,
"platform": null,
"description": "[](https://github.com/fkantelberg/socket-proxy/actions/workflows/main.yaml)\n\n[](https://opensource.org/licenses/MIT)\n\n[](https://github.com/psf/black)\n\n# socket-proxy\n\nThis tool allows to forward TCP ports through a proxy server. The proxy server can expose\nthe listening port directly or bridge the port between two clients allowing the bridge client\nto expose the listening port. Afterwards the applications can connect directly to the\nexposed ports like they were connected to the listening port. For easier handling\nHTTP ports can directly be addressed and the proxy server exposed those throw sub-domains\nas a simple reverse proxy.\n\n### Security\n\nWith this tool you can publish local service which might cause security issues for non-hardened\nports. You should consider further security measurements to harden critical systems if used. The\nHTTP implementation is very basic. It's recommended to use a reverse proxy\nlike nginx with SSL and a wildcard certificate if HTTPS is required.\n\n### Features\n\n- TLS encryption of the tunnel\n- Support for client certificates if CA is specified on the server\n- Support for token authentication. These tokens are rotating automatically\n- Bridge mode to allow to forward a port from one client to another bridge client\n- Support for IPv4 and IPv6\n- Proxy generic TCP ports or more specific HTTP servers\n- Limitation of number of tunnels, clients per tunnel, and connections per IP\n- Limit the access to specific IP's\n- Configuration on server and client side and negotiation of the used settings\n- Web API with support of bearer authentication. The API allows to look into the proxy server, client or bridge client\n- Event system to send HTTP POST requests to a webhook with information about the event\n\n### Usage\n\nThe below examples are assuming the minimal necessary certificates. You can generate CA and\ncertificates to be used on the server and client (e.g. using certs.sh of the package,\neasy-rsa, or openssl directly).\n\n#### Direct exposure on the proxy server\n\n1. Start a proxy server using a certificate and matching private key\n```\n$ socket_proxy server --cert certificate.pem --key certificate.key\n```\n\n2. Start a tunnel client and connect to a server. Tunnelled connections can access server reachable under TARGET:PORT\n```\n$ socket_proxy client --ca ca.pem -c SERVER -d TARGET:PORT\n```\n\n3. Connect clients to the opened ports on the server (see the log or the API for the correct port)\n\n#### Bridge mode and exposure on a bridge client\n\n1. Start a proxy server using a certificate and matching private key\n```\n$ socket_proxy server --cert certificate.pem --key certificate.key\n```\n\n2. Start a tunnel client and connect to a server. Tunnelled connections can access server reachable under TARGET:PORT. Additional we specify that we want to bridge it using `--protocol`. See the log or API for the bridge token\n```\n$ socket_proxy client --ca ca.pem -c SERVER -d TARGET:PORT --protocol bridge\n```\n\n3. Connect an additional client to bridge the port and expose it locally\n```\n$ socket_proxy bridge --ca ca.pem -c SERVER --bridge BRIDGE_TOKEN\n```\n\n4. Connect clients to the opened ports on the bridge client (see the log or the API for the correct port)\n\n### Web API Client\n\n`GET /` returns the state of the server as JSON dictionary. Use the path to get only specific information.\nE.g. `/clients` only returns the sub-dictionary `clients` and `/clients/edcb13dc0c7c6c64` returns only\ninformation about the client `edcb13dc0c7c6c64`.\n\n`DELETE /<client>` disconnects the client `<client>`.\n\nThe client side API doesn't support SSL!\n\n### Web API Server\n\n`GET /` returns the state of the server as JSON dictionary. Use the path to get only specific information.\nE.g. `/tunnels` only returns the sub-dictionary `tunnels` and `/tunnels/edcb13dc0c7c6c64` returns only\ninformation about the tunnel `edcb13dc0c7c6c64`.\n\n`GET /api/token` returns a new authentication token as JSON string.\n\n`DELETE /<tunnel>/<client>` disconnects the client `<client>` of the tunnel `<tunnel>`.\n\n`DELETE /<tunnel>` disconnects the tunnel `<tunnel>`.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Proxy TCP ports of local systems",
"version": "6.0.0",
"project_urls": {
"Homepage": "https://github.com/fkantelberg/socket-proxy"
},
"split_keywords": [
"proxy",
"socket",
"network"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "093b2adeb74e949aec9b1639472ec7d31ed6d64ce6bbde70acca851f95df70d3",
"md5": "417f62eefd12d644df50f8b3654230d3",
"sha256": "6c95c0f09b4db7c31c116cd14eca81a9e38634be5f2fbf540a81e658f46378e2"
},
"downloads": -1,
"filename": "socket_proxy-6.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "417f62eefd12d644df50f8b3654230d3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 36957,
"upload_time": "2025-08-29T18:19:54",
"upload_time_iso_8601": "2025-08-29T18:19:54.766092Z",
"url": "https://files.pythonhosted.org/packages/09/3b/2adeb74e949aec9b1639472ec7d31ed6d64ce6bbde70acca851f95df70d3/socket_proxy-6.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 18:19:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fkantelberg",
"github_project": "socket-proxy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "socket-proxy"
}
JSON
