README.rst 2.9 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485
  1. SSHecret
  2. ========
  3. .. image:: https://photos.tylercipriani.com/thumbs/2f/ad8870548f45148167f0b41d6e0539/medium.jpg
  4. :alt: Don't worry, I can keep a sshecret (photo credit: the Nationaal Archief, the Dutch National Archives, and Spaarnestad Photo, via Wikimedia Commons)
  5. If you have an encrypted ssh key for each domain you access (you should), and
  6. you keep your unlocked keys in a single ssh-agent (you maybe shouldn't),
  7. **AND** you've ever decided you need to forward your ssh-agent, then you should
  8. feel bad.
  9. If you forward an ssh-agent with all your unique keys for every domain to a ssh
  10. server that is compromised - all those unique keys for all those unique domains
  11. you access? **Kablooie!** Done. Have fun rotating them all.
  12. ``sshecret`` is a tool that creates an ssh-agent for each identity file found
  13. in your ``ssh_config(5)`` and executes ssh commands for a particular host using
  14. an environment that has access to **only the key for that one host**.
  15. If a server to which you've forwarded your ssh-agent is compromised, then only
  16. the key used for that domain will be affected.
  17. ``sshecret`` is a wrapper around ssh that automatically manages multiple
  18. ``ssh-agent(1)`` sockets each containing only a single unlocked ssh key.
  19. ``sshecret`` accepts the same parameters as ``ssh(1)`` - fundamentally
  20. ``sshecret`` uses ``execve(2)`` to wrap ssh, modifying the environment to
  21. ensure that each key in your ``ssh_config(5)`` uses its own ssh-agent.
  22. Install
  23. -------
  24. Install via pip::
  25. pip install --user sshecret
  26. Wherever ssh is accepted
  27. ------------------------
  28. To use ``sshecret`` with git, point ``GIT_SSH`` to use ``sshecret`` by adding
  29. this to your shell initialization file (``~/.bashrc`` or the like)::
  30. if command -v sshecret > /dev/null 2>&1; then
  31. export GIT_SSH=sshecret
  32. fi
  33. To use ``sshecret`` with scp add this alias to your shell initialization file::
  34. if command -v sshecret > /dev/null 2>&1; then
  35. alias scp='scp -S sshecret'
  36. fi
  37. Limitations
  38. -----------
  39. ``sshecret`` obviously won't help you if you're using the same ssh key for
  40. multiple domains. You are clearly beyond help.
  41. ``sshecret`` depends on a correct ``ssh_config(5)`` for your user (found at
  42. ``~/.ssh/config`` or wherever ``$SSH_CONF`` is pointing), so it'll get weird if
  43. that file is weird or nonexistent. Sorry, I guess.
  44. **Requirements**:
  45. * Paramiko_
  46. .. _Paramiko: http://www.paramiko.org/
  47. **Usage**::
  48. usage: sshecret [whatever you want to pass to ssh]
  49. sshecret is a wrapper around ssh that automatically manages multiple
  50. ssh-agent(1)s each containing only a single ssh key.
  51. EXAMPLE: sshecret -A -L8080:localhost:80 -l johndoe -p2222 example.com
  52. sshecret accepts the same parameters as ssh(1) - fundamentally sshecret uses
  53. execve(2) to wrap ssh, modifying the environment to ensure that each key in
  54. your ssh_config(5) uses its own ssh- agent.
  55. optional arguments:
  56. -h, --help show this help message and exit
  57. -v Increase verbosity of output