{"id":48125010,"url":"https://github.com/micro-nova/support_tunnel","last_synced_at":"2026-04-04T16:25:25.977Z","repository":{"id":239204702,"uuid":"798836718","full_name":"micro-nova/support_tunnel","owner":"micro-nova","description":"A secure implementation of a support tunnel infrastructure","archived":false,"fork":false,"pushed_at":"2025-12-19T18:17:33.000Z","size":120,"stargazers_count":3,"open_issues_count":13,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-12-22T07:36:59.723Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/micro-nova.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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":"2024-05-10T15:18:09.000Z","updated_at":"2025-03-06T17:18:05.000Z","dependencies_parsed_at":"2024-05-10T17:45:39.413Z","dependency_job_id":"2d5cb5ab-d8e8-482b-82a0-b706a0cc794f","html_url":"https://github.com/micro-nova/support_tunnel","commit_stats":null,"previous_names":["micro-nova/support_tunnel"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/micro-nova/support_tunnel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-nova%2Fsupport_tunnel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-nova%2Fsupport_tunnel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-nova%2Fsupport_tunnel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-nova%2Fsupport_tunnel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micro-nova","download_url":"https://codeload.github.com/micro-nova/support_tunnel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-nova%2Fsupport_tunnel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: 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-04-04T16:25:22.210Z","updated_at":"2026-04-04T16:25:25.952Z","avatar_url":"https://github.com/micro-nova.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `support-tunnel`\n\nThis repo contains a secure implementation of a support tunnel. Its implementation emphasizes user consent, privacy, and security for all parties. At a high level, it instantiates a quantum-resistant Wireguard tunnel between an ephemerally launched cloud server and a remote device, using an API as a bookkeeping intermediary and some additional key material exchanged out of band.\n\nIt uses a couple of technologies:\n* [Fabric](https://www.fabfile.org/) - used to control the remote tunnel server\n* [Invoke](https://www.pyinvoke.org/) - used to run commands on localhost\n* [SQLModel](https://sqlmodel.tiangolo.com/) - a nice ORM from [tiangolo](https://github.com/tiangolo), built on [Pydantic](https://docs.pydantic.dev/latest/) and [SQLAlchemy](https://www.sqlalchemy.org/)\n* [FastAPI](https://fastapi.tiangolo.com/) - a nice web framework from [tiangolo](https://github.com/tiangolo)\n\n## How to use this\n\nSome quick terms:\n* `device` is the remote thing you'd like access to\n* `admin` is the support user's context, both on their local laptop and the launched tunnel server.\n* `api` is the HTTP API that runs in the cloud. It's main purpose is to do bookkeeping and exchange bootstrapping data.\n\n### Setup\nFirst, if this is a greenfield deployment, launch the cloud network and an instance of the API. See more detailed instructions in the `opentofu/README.md` documentation on how to accomplish this. If you're a Micro-Nova employee, you can skip this step.\n\nIf you're a Windows user taking the role of `admin`, ensure you've got [WSL](https://www.microsoft.com/store/productId/9PDXGNCFSCZV?ocid=pdpshare) installed and set to [mirrored networking mode](https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking), and have a browser of your choice installed within WSL (for example, running `sudo apt install firefox`). Note that without mirrored networking, you may not be able to properly authenticate, and without a browser you will not be able to sign in in the first place.\n\nThen, on both the device you'd like a tunnel on and on your admin computer:\n```\napt install libsystemd-dev wireguard wireguard-tools\ngit clone https://github.com/micro-nova/support_tunnel\npushd support_tunnel\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\n### `device`\n\nCreate a `support` group. Certain functions require root, like opening a wireguard device. Others don't. We use a `support` group for the backing SQLite database to share this between both contexts. For any non-root user calling these services, add them to this group.\n\n```\ngroupadd support\n```\n\nRequest a tunnel on your `device`. If you are a Micro-Nova employee, this is more or less what the updater does when you press the \"Request support tunnel\" button.\n\n```\ninv --list                          # see what commands are available\n# request a tunnel and wait until approval\ninv request-and-connect-tunnel      # there are also separate request and connect commands\n```\nThis will print both a tunnel ID and a preshared key. These should be transmitted to the `admin` out of band, likely through a typical support channel.\n\nThe `device` context supports a configuration file at `/etc/support_tunnel/config.ini`. An example config with comments is available at `device/example_config.ini`.\n\n### `admin`\n\nOn your `admin`, you probably need to log in to a cloud provider so you can start and configure instances. For Micro-Nova, this is Google Cloud Platform. Install the [`gcloud` utility](https://cloud.google.com/sdk/docs/install-sdk) and run these steps:\n```\ngcloud init\ngcloud auth application-default login\ngcloud compute os-login ssh-keys add --ttl=120d --key-file=$(realpath ~/.ssh/id_ed25519.pub)\n```\nTo note, your public key may live someplace else or be in a different format; please modify the command to suit. Also to note - authenticating to tunnel servers will fail unless you have 2FA configured on your Google account. Please [configure 2FA](https://support.google.com/accounts/answer/185839).\n\n\n```\nfab --list # see what commands are e\n# create the tunnel server, using the preshared key and tunnel id from the device\nfab create\nfab show $TUNNEL_ID\nfab connect $TUNNEL_ID\nfab command $TUNNEL_ID 'cat /etc/hostname'\n```\n\nThe above takes a while. When it completes though, you should be logged in as root on the remote device!\n\n## Code structure\n* `api/` - all the API server code\n* `device/` - all the client (ie AmpliPi) code\n* `admin/` - all the launched tunnel server code\n* `common/` - code that is shared, notably data models\n* `opentofu/` - code to deploy the API server, LB, network, etc in Google Cloud Platform using OpenTofu\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicro-nova%2Fsupport_tunnel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicro-nova%2Fsupport_tunnel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicro-nova%2Fsupport_tunnel/lists"}