{"id":13645213,"url":"https://github.com/Apache553/ssh-agent-bridge","last_synced_at":"2025-04-21T13:32:14.904Z","repository":{"id":134655795,"uuid":"382559282","full_name":"Apache553/ssh-agent-bridge","owner":"Apache553","description":"A tool that enable multiple ssh client implementations to use a common ssh agent on Windows.","archived":false,"fork":false,"pushed_at":"2021-09-16T14:06:12.000Z","size":3457,"stargazers_count":67,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-02T01:25:14.487Z","etag":null,"topics":["ssh","windows"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Apache553.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-07-03T07:58:38.000Z","updated_at":"2023-06-19T03:16:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"84e112ee-90d2-4452-81ef-377dd38c3e43","html_url":"https://github.com/Apache553/ssh-agent-bridge","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apache553%2Fssh-agent-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apache553%2Fssh-agent-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apache553%2Fssh-agent-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apache553%2Fssh-agent-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Apache553","download_url":"https://codeload.github.com/Apache553/ssh-agent-bridge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223867891,"owners_count":17216974,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["ssh","windows"],"created_at":"2024-08-02T01:02:31.304Z","updated_at":"2024-11-09T18:30:32.629Z","avatar_url":"https://github.com/Apache553.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"ssh-agent-bridge\n=====\n[中文](README.zh.md)\n\nA tool that enable multiple ssh client implementations to use a common ssh agent on Windows.\n\nThe tool provides a daemon can forward ssh agent requests sent via different IPC methods to a common agent instance.\n\nCurrent Supported Methods:\n - Windows 10 OpenSSH *\n - Putty (Pageant) *\n - Windows Unix Domain Socket\n - libassuan emulated Unix Domain Socket\n - HyperV Socket\n - Cygwin Socket\n\nMethods with asterisk(*) means it can be an upstream agent instance, or it can listen requests only.\n\nAdditionally, the tool provides a way to forward GnuPG sockets on Windows. You can use your gpg-agent instance under WSL environment.\n\nHow to use\n-----\n\n### Prerequisite\nDownload pre-build binary or build your own, put it in the folder you prefer.\nBuilding requires MSVC toolchain. MinGW is not supported.\n\n### Create your config\nThe tool will try reading config from `%USERPROFILE%\\ssh-agent-bridge\\ssh-agent-bridge.ini` first if no config path is specified in command line. If that failed, it will try reading `ssh-agent-bridge.ini` in the directory of the executable.\nYou need to create those folders manually if they don't exist.\nRefer to the example config in the project root and descriptions below for details.\n\n### Auto start\nYou can use various methods to start the tool. \nThe tool supports running as a service for better management.\n\nTo install service, execute in administrator shell:\n```\nssh-agent-bridge.exe /InstallService\n```\nThe default mode of the service is OnDemand, you need to start the service manually.\nRun following command to set the mode to auto:\n```\nSet-Service ssh-agent-bridge -StartupType auto\n```\n\nTo uninstall service, execute in administrator shell:\n```\nssh-agent-bridge.exe /UninstallService\n```\n\nThose operations all requires a re-login to take effect.\nIf you changed the path of the executable, you need to uninstall then install the service again.\n\n### Manual start\nYou can start the tool directly if you don't want to taint Windows.\nIn that case, a script might be needed to pass command line parameters to the tool.\n\n### Logging\nLog will be written to `%APPDATA%\\ssh-agent-bridge.log`.\n\nIn case of realtime inspection, use powershell command:\n```\nStart-Process -Wait .\\ssh-agent-bridge.exe '/Console'\n```\n\n### Aggregation\nCreate more than one client in config to enable aggregation feature.\nThe feature will make the tool to request all configured upstream agents in lexicographical order respectively until succeeded or get enough infomation, then assemble replies into one reply.\n\nSome agent implementations (like gpg-agent) have strange behaviors when add/remove keys to/from it. You may avoid doing such operations on those agents.\n\n#### Supported Operations\nAlthough ssh agent may have many features, only those operations are supported.\n\n- Add a key\n- Remove a key\n- Remove all keys\n- List keys\n- Sign with a key\n\nDetails\n-----\n\n### Command Line Options\n```\n/Loglevel debug|info|warn|error\n```\nOverride log output level.\n\n```\n/Service\n```\nRequired when running as a service.\n\n```\n/Debug\n```\nOutput log with `OutputDebugString`\n\n```\n/Console\n```\nCreate or attach to a console to output log. Illegal when running as a service.\n\n```\n/Config \u003cpath\u003e\n```\nOverride default config path.\n\n```\n/InstallService\n```\nInstall service.\n\n```\n/UninstallService\n```\nUninstall service.\n\n### Config File\nConfig file a simple ini file.\nSections except `[general]` define a client/listener.\n\nThe descriptions about `[general]` section:\n```\n[general]\n; Set log output level\n; Optional\n; Available Options:\n;   - debug\n;   - info [default]\n;   - warn\n;   - error\nloglevel = info\n\n; Add extra string at the end of a key's comment to reflect its source\n; Optional\n; Available Options:\n;   - true [default]\n;   - false\nmangle-key-comment = true\n```\n\nTo define a client/listener:\n```\n; Define a client/listener with name 'namedpipe'\n[namedpipe]\n\n; Set type\n; Required\n; Available Options:\n;   - namedpipe    ; listener, client\n;                  ; Windows 10 OpenSSH\n;   - pageant      ; listener, client\n;                  ; Putty\n;   - unix         ; listener\n;                  ; Windows Unix Domain Socket\n;   - assuan_emu   ; listener\n;                  ; libassuan emulated Unix Domain Socket, can be used for gpg-agent and WSL\n;   - hyperv       ; listener\n;                  ; HyperV Socket\n;   - cygwin       ; listener\n;                  ; Cygwin Socket\n; NOTE: You need to guarantee the whole config is legal.\ntype = namedpipe\n\n; Set role\n; Required\n; Available Options:\n;   - client       ; A client forwards requests to a running agent.\n;   - listener     ; A listener receives requests from ssh clients.\nrole = client\n\n; Set socket path\n; Required\n; Apply to: namedpipe, pageant, unix, assuan_emu, cygwin\n; NOTE: For clients, the path specifies the agent instance they forwards requests to.\n;       For listeners, the path specifies the socket file's path.\npath = \\\\.\\pipe\\openssh-ssh-agent\n\n; Enable permission checks, denying access from other users\n; Optional\n; Apply to: namedpipe, pageant, unix, assuan_emu, cygwin\n; Available Options:\n;   - true [default]\n;   - false\nenable-permission-check = true\n\n; Set listening address of socket\n; Optional\n; Apply to: assuan_emu, hyperv\n; NOTE: For assuan_emu, it means the listening address. \n;         The default value is '0.0.0.0'.\n;       For hyperv, it means virtual mechine id which is allowed to connect. \n;         The default value is '{00000000-0000-0000-0000-000000000000}' (HV_GUID_WILDCARD).\n;         You can also put several placeholders there: wildcard, children, loopback, wsl2\n;         Or a GUID represents a virtual mechine.\n;         When set to 'wsl2', the tool will detect WSL2 virtual mechine id automatically.\n;         For details, refer to https://bit.ly/3Cnml21\nlisten-address = 0.0.0.0\n\n; Set listening port\n; Optional\n; Apply to: hyperv\n; Default Value: 0x44417A9F\nlisten-port = 0x44417A9F\n\n; Allow non-elevated process to access when tool process is elevated\n; Optional\n; Apply to: pageant\n; Available Options:\n;   - true\n;   - false [default] ; Pageant's behavior\nallow-non-elevated-access = false\n\n; Restrict pageant client's target process name\n; Optional\n; Apply to: pageant\n; NOTE: The tool always ignores self when requesting pageant upstream.\nrestrict-process = pageant.exe\n\n; Set the gpg socket path\n; Optional\n; Apply to: unix, assuan_emu, hyperv, cygwin\n; NOTE: If you don't want to use the listener to forward gpg socket, you must not set this property.\nforward-socket-path = %APPDATA%\\gnupg\\S.gpg-agent\n\n; Write LXSS metadata\n; Optional\n; Apply to: unix, assuan_emu\n; Available Options:\n;   - true\n;   - false [default]\n; NOTE: For 'unix' listeners, the metadata will be written to its parent directory.\n;       For other listeners, the metadata will be written to the file.\nwrite-lxss-metadata = false\n\n; LXSS metadata will be written\n; Options\n; Apply to: unix, assuan_emu\n; NOTE: Not specified metadata property or null property will be written.\nmetadata-uid = 1000\nmetadata-gid = 1000\nmetadata-mode = 0600\n```\n\n## WSL Support\n\n### WSL1 Support\nIn WSL1 environment, the Windows Unix Domain Socket can interoperate with WSL.\nDefine a `unix` listener, then set right environment variable to the socket should work.\n\n### WSL2 Support\nIn WSL2 environment, the only ways to communicate with the host is HyperV Sockets and Tcp/Ip Sockets.\nSo a helper program is needed to create a Unix Domain Socket.\n\n#### HyperV Socket: socat\nIn this way, you need to register your own Integration Service with powershell script `hyperv_register.ps1`.\nThe script will also output the parameter used by socat to connect the host.\n\n##### Example\nPut the snippet into `.bashrc`:\n```\nexport SSH_AUTH_SOCK=$HOME/.ssh/agent.socket\nSOCAT_OPT=\"SOCKET-CONNECT:40:0:x0000x9f7a4144x02000000x00000000\"\nss -lnx | grep -q $SSH_AUTH_SOCK\nif [ $? -ne 0 ]; then\n    rm -f $SSH_AUTH_SOCK\n    (setsid nohup socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork $SOCAT_OPT \u003e/dev/null 2\u003e\u00261 \u0026)\nfi\n```\n**Don't forget to replace `SOCAT_OPT`'s content with the script's output.**\n\n#### Tcp/Ip Socket: simple helper\nTo use this method, you need to compile program under `wsl2_helper` directory.\nThe helper programs can be used in both WSL1 and WSL2 since it uses libassuan's scheme to work.\nAnd it is possible to forward gpg-agent standalone.\n\n##### Usage\n```\nUsage: ./ssh-agent-bridge-wsl2-helper -r \u003cremote\u003e [-l local] [-a remoteAddress] [-b] [-p pidFile] [-c] [-h]\nOption:\n        -l local\n                socket path in wsl environment. generated randomly if not specified, path written to stdout\n        -r remote\n                socket path of listener in wsl environment\n        -a remoteAddress\n                windows host ip, deduced from default route if not specified\n        -d\n                delete local socket file if exists\n        -b\n                fork to background\n        -p pidFile\n                write main process pid to file, if process in the file is alive, this instance will exit.\n        -c\n                enable refcount, increase refcount when started, decrease refcount when parent process exit\n        -h\n                display this help message\n```\n\n##### Example\nPut the snippet into `.bashrc`:\n\n```\nexport SSH_AUTH_SOCK=$HOME/.ssh/agent.socket\nssh-agent-bridge-wsl2-helper -b \\\n    -l $SSH_AUTH_SOCK \\ \n    -r /mnt/c/Users/John/ssh-agent-bridge/wsl2-ssh-agent.socket \\\n    -p $HOME/.ssh/helper-ssh-agent.pid 2\u003e/dev/null\n```\n**Don't forget to replace the path with your own one.**\n\n## GPG Forwarding\nSet `forward-socket-path` property in listener's config to make the listener a gpg forwarding listener.\n\nIn case of WSL1, you can use the helper directly or setup a `unix` listener.\n\nIn case of WSL2, you can only setup a `hyperv` or `assuan_emu` listener and setup the corresponding helper program to make forwarding work.\n\n### Redirect GPG Socket\nGPG can only access socket files placed under `$GNUPGHOME` (or `$HOME/.gnupg` in case the environment variable is not set). When the socket is placed in other place, you need some extra work to redirect the socket.\n\nCreate a plain text file with the same file name with the socket under `$GNUPGHOME`.\nWrite the snippet to the file:\n```\n%Assuan%\nsocket=/home/user/whatever.socket\n```\nThen accesses to the socket will be redirected to `/home/user/whatever.socket`.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FApache553%2Fssh-agent-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FApache553%2Fssh-agent-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FApache553%2Fssh-agent-bridge/lists"}