{"id":13813650,"url":"https://github.com/StanfordSNR/guardian-agent","last_synced_at":"2025-05-15T00:34:01.276Z","repository":{"id":52185581,"uuid":"105204337","full_name":"StanfordSNR/guardian-agent","owner":"StanfordSNR","description":"[beta] Guardian Agent: secure ssh-agent forwarding for Mosh and SSH","archived":false,"fork":false,"pushed_at":"2023-07-20T00:34:28.000Z","size":6866,"stargazers_count":435,"open_issues_count":22,"forks_count":30,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-08-04T04:04:26.713Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StanfordSNR.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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-28T22:15:46.000Z","updated_at":"2024-07-31T15:44:47.000Z","dependencies_parsed_at":"2024-06-18T21:18:33.144Z","dependency_job_id":"bbe1a8de-9b97-45c8-9dec-8c8ca687390a","html_url":"https://github.com/StanfordSNR/guardian-agent","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StanfordSNR%2Fguardian-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StanfordSNR%2Fguardian-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StanfordSNR%2Fguardian-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StanfordSNR%2Fguardian-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StanfordSNR","download_url":"https://codeload.github.com/StanfordSNR/guardian-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225319294,"owners_count":17455743,"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":[],"created_at":"2024-08-04T04:01:24.365Z","updated_at":"2024-11-19T08:30:52.594Z","avatar_url":"https://github.com/StanfordSNR.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"## Guardian Agent: secure agent forwarding for Mosh or SSH\n\nGuardian Agent (now in beta) allows users to securely empower remote\nhosts to take actions on their behalf, using their SSH credentials. It\nallows Mosh and SSH users to enable agent forwarding for every\nconnection, even to hosts they may not fully trust.\n\nGuardian Agent is an alternative to traditional `ssh-agent`\nforwarding, which can only safely be enabled when connecting to\ntrusted hosts. The traditional `ssh-agent` protocol doesn't give\nthe agent information about which host is asking to perform a command\non the user's behalf, which server that hosts wants to connect to,\nor which command the host wants to perform:\n\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"doc/ssh-askpass-default.svg\" width=\"50%\"\u003e\n\u003c/p\u003e\n\nBy contrast, Guardian Agent provides more-constrained agent forwarding\nthat can safely be enabled on any connection. It can be used\nalongside Mosh or SSH.\n\nTo use Guardian Agent, a user runs `sga-guard` on her local machine to establish\na secure forwarding channel to an intermediary host (e.g. in EC2). On\nthe intermediary machine, she can then use `sga-ssh` as a drop-in\nreplacement for `ssh`. The local `sga-guard` verifies the identity of\n(a) the **intermediary** host, (b) the **remote server**, and (c) the\n**command**[\u003csup\u003e*\u003c/sup\u003e](#command-verification), either by prompting\nthe user or based on a stored policy. No changes to the server are\nrequired, but full functionality is only available when connecting to\nservers running OpenSSH.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"doc/ssh-askpass-sga.svg\" width=\"50%\"\u003e\n\u003c/p\u003e\n\nBased on feedback to this beta/prototype, we may incorporate the techniques behind Guardian Agent more deeply into [Mosh](https://mosh.org).\n\n## How does Guardian Agent work?\n\nGuardian Agent allows an **SSH client** (`sga-ssh`), running on a\npartially trusted machine, to request the **SSH agent** (`sga-guard`),\nrunning on a trusted machine, to execute commands on an **SSH server**\n(e.g., GitLab), such that the identity of the server as well as the\nSSH session command can be verified by the SSH agent, with the\nserver's own code unaltered.\n\nThe scheme works by first having `sga-ssh` (on the intermediary host)\nrequest that the user's agent allow it to run a particular command on\na particular server. The user approves or denies the request, or the request\nis auto-approved according to a pre-existing policy. (These policies are stored\nin the `~/.ssh/sga_policy` file.)\n\nIf approved, `sga-ssh` then establishes a TCP connection to the\nserver, and securely tunnels it back to `sga-guard`. `sga-guard` then\nestablishes an end-to-end authenticated SSH connection directly with\nthe server, over the forwarded TCP connection. The local machine\nallows the delegate to issue the approved command, and then to\n``lock'' the session by using the `no-more-sessions` request, so that\nno more commands may be issued on this connection.\n\nAfter the session is locked, `sga-guard` allows `sga-ssh` to rekey the\nsession, taking over in the middle of the connection, and reusing the\nexisting TCP connection to the server. From this point, `sga-ssh` can complete the operation, with data flowing directly between the intermediary and the server (as in traditional `ssh-agent` forwarding).\n\nFor more, please read our \u003ca href=\"doc/hotnets17.pdf\"\u003eresearch\npaper\u003c/a\u003e or the detailed [design document](doc/design.md).\n\n\u003cp align=\"center\"\u003e\nResearch paper (to appear at ACM HotNets 2017)\n\u003cbr\u003e\n\u003ca href=\"doc/hotnets17.pdf\"\u003e\n\u003cimg src=\"doc/paper-page1.svg\" alt=\"Paper\" width=\"40%\" align=\"middle\" display=\"block\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n## Installation\n\n**Warning: this tool is in beta and is intended as a technology prototype. It was first released in October 2017.\nFeedback is greatly appreciated, but please use at your own risk.**\n\nUsing Guardian Agent requires installation **both on your local machine** (the\none with your SSH private keys) and on each of the **intermediary machines** you\nwant to securely forward `ssh-agent` to (the machines on which you want to run an\nSSH client without having the keys on them). **No installation is required on the\nserver side.**\n\n\u003cdetails\u003e\u003csummary\u003eUbuntu installation\u003c/summary\u003e\u003cp\u003e\n\n```\nsudo apt-get install openssh-client autossh ssh-askpass\ncurl -L https://api.github.com/repos/StanfordSNR/guardian-agent/releases/latest | grep browser_download_url | grep 'linux' | cut -d'\"' -f 4 | xargs curl -Ls | tar xzv\nsudo cp sga_linux_amd64/* /usr/local/bin\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eCentOS / Fedora installation\u003c/summary\u003e\u003cp\u003e\n\n```\nsudo yum install -y mosh openssh-clients autossh openssh-askpass\ncurl -L https://api.github.com/repos/StanfordSNR/guardian-agent/releases/latest | grep browser_download_url | grep 'linux' | cut -d'\"' -f 4 | xargs curl -Ls | tar xzv\nsudo cp sga_linux_amd64/* /usr/local/bin\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003emacOS installation\u003c/summary\u003e\u003cp\u003e\n\n```\nbrew tap theseal/ssh-askpass\nbrew tap theseal/guardian-agent\nbrew install guardian-agent\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\u003c/p\u003e\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eOther\u003c/summary\u003e\u003cp\u003e\n\n1. Install the following dependencies: OpenSSH client, autossh, ssh-askpass.\n2. Obtain the [latest\n   release](https://github.com/StanfordSNR/guardian-agent/releases/latest) for\n   your platform. Alternatively, you may opt to [build from source](#building-from-source).\n3. Extract the executables (`sga-guard`, `sga-guard-bin`, `sga-ssh`, and\n   `sga-stub`) from the tarball to a **directory in the user's PATH**.\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n## Basic Usage\n\nMake sure Guardian Agent is installed on both your local and intermediary machine.\n\n### On your local machine\nStart guarded agent forwarding to the intermediary machine:\n\n```\n[local]$ sga-guard \u003cintermediary\u003e\n```  \n\nYou should then expect to see the following message:\n```\n[local]$ sga-guard aws-ubu\nConnecting to aws-ubu to set up forwarding...\nForwarding to aws-ubu setup successfully. Waiting for incoming requests...\n```\n\nGuarded agent forwarding is now enabled on the intermediary.\n\n### On the intermediary\nConnect to the intermediary (e.g., using standard ssh or mosh). \n[Install](#installation) guardian-agent.\nTo enable several common tools (scp, git, rsync, mosh) to use the guardian agent instead of the default\n`ssh` program:\n```\n[intermediary]$ source sga-env.sh\n```\nYou can also add this line to your `~/.bashrc`/`~.zshrc`/... file on the intermediary hosts.\n\nYou can then use `git`, `scp`, `rsync`, `mosh` as you would normally do.\n\n```\n[intermediary]$ git clone git@github.com:user/repo\n...\n[intermediary]$ scp foo.txt remote-host:Documents/foo.txt\n...\n```\n\n\nYou can also use `sga-ssh` as a drop-in replacement to an ssh client:\n\n```\n[intermediary]$ sga-ssh \u003cserver\u003e [command]\n```\n\n\n## Advanced Usage\n\n### Command verification\n\nCommand verification requires the server to support the `no-more-sessions`\nextension. This extension is present on OpenSSH servers, but\nunfortunately not implemented on other SSH servers (including GitHub, which uses `libssh`). When\nexecuting a command on a server that does not support this extension, only the\nidentity of the intermediary and the identity of the server can be constrained and verified by the agent\n(but not the contents of the command).\n\n### Prompt types\n\nGuardian Agent supports two types of interactive prompts: graphical and\nterminal-based. The graphical prompt requires the `DISPLAY` environment variable\nto be set to the appropriate X11 server.  \nIf running in a terminal-only session (in which the `DISPLAY` environment\nvariable is not set), a textual prompt will be used instead.\n\n### Customizing the SSH command\n\nWhen using `sga-guard`, the default SSH client on the local machine is used to\nset up the connection. This requires `ssh` to be found in the user's `PATH`. To\nspecify an alternative SSH client or specifying additional argument to the\nclient, use the `--ssh` command-line flag.\n\n### Stub location\n\nIf the `sga-stub` is not installed in the user's `PATH` on the intermediary\nmachine, its location must be specified when setting up secure agent forwarding\nfrom the local machine:\n\n```\n[local]$ sga-guard --stub=\u003cPATH-TO-STUB\u003e \u003cintermediary\u003e\n```\n## Building from Source\n1. [Install go 1.8+](https://golang.org/doc/install)\n2. Get and build the sources:\n```\ngo get github.com/StanfordSNR/guardian-agent/...\n```\n3. Copy the built binaries (`sga-guard-bin`, `sga-ssh`, and `sga-stub`) from `$GOPATH/bin` to a directory in the user's PATH.\n4. Copy the scripts `$GOPATH/src/github.com/StanfordSNR/guardian-agent/scripts/sga-guard` and `$GOPATH/src/github.com/StanfordSNR/guardian-agent/scripts/sga-env.sh` to a directory in the user's PATH.\n\n## Troubleshooting\n\nIn case of [unexpected behavior](https://en.wikipedia.org/wiki/Bug_(software)), please consider opening an issue in our [issue tracker](https://github.com/StanfordSNR/guardian-agent/issues).\nWe'd also greatly appreciate if you could run the tool in debug mode by setting the `--debug` and `--logfile=\u003cLOG-FILE\u003e` flags and attach the log file to the issue.\n\n## FAQ\n\nQ: Is `ssh-agent` forwarding really insecure? What is the point of Guardian Agent?\n\nA: The ssh(1) man page warns that \"Agent forwarding should be enabled with caution,\" because\nthe `ssh-agent` protocol does not allow the agent to verify (a) which intermediary machine is making the request, (b)\nwhich remote server the intermediary wants to authenticate to, or (c) what command the\nintermediary plans to run on the remote server. The agent signs a blank check---\nan opaque challenge from an unknown server that will allow the intermediary to execute\nany sequence of commands on the user's behalf.\n\nAs a result, ssh-agent forwarding can be used safely only when the\nuser trusts the remote host.  Several\n[commentators](https://heipei.github.io/2015/02/26/SSH-Agent-Forwarding-considered-harmful/)\n[have](https://news.ycombinator.com/item?id=9425805)\n[noted](https://lyte.id.au/2012/03/19/ssh-agent-forwarding-is-a-bug/)\nthat this creates risks that may not be widely appreciated.\n\nGuardian Agent is a prototype of a system for secure agent forwarding\nthat could safely be enabled on every outgoing connection, because the local agent can\nverify and enforce security policies regarding who wants to do what to whom.\n\nQ: What's the exact attack scenario where I could get burned with traditional `ssh-agent` forwarding?\n\nA: A compromised or malevolent intermediary can send rogue challenges and\nuse the user's identity to authenticate to other servers or to run\nunauthorized commands. A user that enables ssh-agent forwarding will be\nasked yes or no on signing \"something,\" and may think she is allowing an\nEC2 machine to run \"git push\" to GitHub. Unbeknownst to the user, she is allowing a\ndifferent machine (that she is also logged in to) to connect to\nsome other sensitive server that she has permissions on and do something evil.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"doc/badflow2.png\" alt=\"Example\" width=\"70%\" align=\"middle\" display=\"block\"\u003e\n\u003c/p\u003e\n\nQ: What if I only use `ssh-agent` forwarding when I SSH to intermediaries that I trust?\n\nA: If the user trusts the software and system administrators on the\nintermediary host, it is probably fine to use ssh-agent forwarding\nas it exists today. However, with this level of trust, it may also be\nfine to simply place a private key on the intermediary's hard drive.\nGuardian Agent is a prototype of an approach that could safely be enabled\nby default.\n\nQ: Can I use Guardian Agent to constrain an intermediary to only pull from (or only push to) a limited\nset of remote Git repositories?\n\nA: Yes, if the remote Git server is running an SSH server (such as OpenSSH) that supports the `no-more-sessions` extension. (The name of the repository, and the difference between pulling and pushing,\nare both represented in the command.) Among popular Git-hosting services that we\nare aware of, currently only GitLab\nappears to support this currently. GitHub and Bitbucket use other SSH implementations and\ndo not allow Guardian Agent to constrain the intermediary to only push or pull from certain\nrepositories.\n\nQ: Is Guardian Agent secure?\n\nA: Guardian Agent is a beta that was first released for beta testing in October 2017.\nIt has not accumulated enough testing and scrutiny to make claims that the implementation is\nbulletproof.\n\nQ: What language is Guardian Agent written in?\n\nA: Go! Guardian Agent is a beta intended to solicit feedback from the community,\nespecially with regards to the basic design of a secure protocol\nthat works with unmodified remote SSH servers. We found Go and the Go SSH library to be helpful\nin prototyping this tool.\n\nQ: What is the connection to Mosh (mobile shell)?\n\nA: Many Mosh users have \u003ca\nhref=\"https://github.com/mobile-shell/mosh/issues/120\"\u003easked for\nssh-agent forwarding support\u003c/a\u003e. Guardian Agent was developed by some of the Mosh developers\nand can be used with Mosh today. Based on feedback to this prototype, we may integrate Guardian\nAgent more fully into Mosh as a system for secure ssh-agent forwarding that is safe enough\nto leave on by default.\n\nQ: Who wrote Guardian Agent?\n\nA: Guardian Agent was developed by students and faculty in the\nStanford University Department of Computer Science (Dima Kogan and\nHenri Stern, advised by Keith Winstein and David Mazières).\n\nQ: Where should I send feedback?\n\nA: Please file an issue on GitHub.\n\nQ: Where can I read more about how Guardian Agent works?\n\nA: Please read our \u003ca href=\"doc/hotnets17.pdf\"\u003eresearch\npaper\u003c/a\u003e or the detailed [design document](doc/design.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStanfordSNR%2Fguardian-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStanfordSNR%2Fguardian-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStanfordSNR%2Fguardian-agent/lists"}