README
¶
proxyssh
A golang package based on https://github.com/gliderlabs/ssh that enables easily running commands via ssh. Also includes Docker support.
Use Cases
The main use case of this package is to provide a simple interface to build an ssh server that runs commands on the host it is running on.
See the cmd/simplesshd package.
A secondary use case is to provide an ssh server that runs commands in matching docker containers.
See the cmd/dockersshd package.
For a more detailed overall documentation, see the godoc.
Dockerfiles
This repository contains Dockerfiles for both of the examples, called Dockerfile.simple and Dockerfile respectively.
These are available as the GitHub Packages dockersshd and simplesshd respectively.
The dockersshd image can be run as follows:
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -p 2222:2222 docker.pkg.github.com/tkw1536/proxyssh/dockersshd:latest
For legacy reasons, the dockersshd Image is also available as the automated build tkw01536/proxyssh.
Documentation
¶
Overview ¶
Package proxyssh provides facilities to create an ssh server that executes commands on the local machine.
This package is very much a wrapper around github.com/gliderlabs/ssh. However it additionally provides convenient functions to build a local server that behaves much like an OpenSSH server.
Index ¶
- func AllowForwardFrom(logger utils.Logger, addresses []utils.NetworkAddress) ssh.ReversePortForwardingCallback
- func AllowForwardTo(logger utils.Logger, addresses []utils.NetworkAddress) ssh.LocalPortForwardingCallback
- func AllowPortForwarding(logger utils.Logger, server *ssh.Server, toAddresses []utils.NetworkAddress, ...)
- func AuthorizeKeys(logger utils.Logger, ...) ssh.PublicKeyHandler
- func EnablePortForwarding(server *ssh.Server, localCallback ssh.LocalPortForwardingCallback, ...)
- func HandleShellCommand(logger utils.Logger, ...) ssh.Handler
- func NewProxySSHServer(logger utils.Logger, opts Options) (server *ssh.Server)
- func ReadOrMakeHostKey(logger utils.Logger, privateKeyPath string, algorithm HostKeyAlgorithm) (key gossh.Signer, err error)
- func UseOrMakeHostKey(logger utils.Logger, server *ssh.Server, privateKeyPath string, ...) error
- type CommandSession
- type HostKey
- type HostKeyAlgorithm
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AllowForwardFrom ¶
func AllowForwardFrom(logger utils.Logger, addresses []utils.NetworkAddress) ssh.ReversePortForwardingCallback
AllowForwardFrom returns a ssh.ReversePortForwardingCallback that allows reading traffic to the provided addresses only.
logger is called whenever a request from a caller is allowed or denied.
func AllowForwardTo ¶
func AllowForwardTo(logger utils.Logger, addresses []utils.NetworkAddress) ssh.LocalPortForwardingCallback
AllowForwardTo returns a ssh.LocalPortForwardingCallback that allows forwarding traffic to the provided addresses only.
logger is called whenever a request from a caller is allowed or denied.
func AllowPortForwarding ¶
func AllowPortForwarding(logger utils.Logger, server *ssh.Server, toAddresses []utils.NetworkAddress, fromAddresses []utils.NetworkAddress)
AllowPortForwarding enables port forwarding on the provided server only to and from the given addresses. This function also calls EnablePortForwarding, please see appropriate documentation
See also AllowForwardTo, AllowForwardFrom and EnablePortForwarding.
func AuthorizeKeys ¶
func AuthorizeKeys(logger utils.Logger, keyfinder func(ctx ssh.Context) (keys []ssh.PublicKey, err error)) ssh.PublicKeyHandler
AuthorizeKeys returns an ssh.PublicKeysHandler that calls keyfinder() and authorizes all keys returned by the handler.
logger is a logger that is called when the keyfinder returns an error. keyfinder is a function that is called for a provided context and should return a list of keys that are authorized.
This function protects against timing attacks by always checking all keys even though a quicker implementation could be possible. To further improve against timing attacks, keyfinder should always return the same number of keys (for any session).
func EnablePortForwarding ¶
func EnablePortForwarding(server *ssh.Server, localCallback ssh.LocalPortForwardingCallback, reverseCallback ssh.ReversePortForwardingCallback)
EnablePortForwarding enables portforwarding with the given callbacks on the ssh Server server. This includes tcpip forward requests as well as direct-tcpip channels.
This function overwrites any already configured LocalPortForwardingCallback and ReversePortForwardingCallback functions. It will furthermore remove the 'tcpip-forward' and 'cancel-tcpip-forward' request handlers along with the 'direct-tcpip' channel handler.
func HandleShellCommand ¶
func HandleShellCommand(logger utils.Logger, shellCommand func(session ssh.Session) (command []string, err error)) ssh.Handler
HandleShellCommand creates an ssh.Handler that runs a shell command for every ssh.Session that connects.
shellCommand is a function. It is called for every ssh session and should return the shell command along with any arguments to execute for the provided session. The returned array must be at least of length 1. The first argument will be passed to exec.LookPath. When shell command returns a non-nil error, no command will be executed and the session will be aborted.
logger is called for every significant event that occurs.
See also the CommandSession struct and NewCommandSession func.
func NewProxySSHServer ¶
NewProxySSHServer makes a new OpenSSH-like ssh server.
When a user connects to the server, it executes a shell and proxies the session input and ouput streams accordingly. It furthermore allows sending traffic to and from specific ip addresses. This can be configured using Options.
It uses the provided options, and returns the new server that was created. It returns the new server that was created.
func ReadOrMakeHostKey ¶
func ReadOrMakeHostKey(logger utils.Logger, privateKeyPath string, algorithm HostKeyAlgorithm) (key gossh.Signer, err error)
ReadOrMakeHostKey attempts to load a host key from the given privateKeyPath. If the path does not exist, a new key is generated.
This function assumes that if there is a host key in privateKeyPath it uses the provided HostKeyAlgorithm. It makes no attempt at verifiying this; the key mail fail to load and return an error, or it may load incorrect data.
logger is called whenever a new host key algorithm is being generated.
func UseOrMakeHostKey ¶
func UseOrMakeHostKey(logger utils.Logger, server *ssh.Server, privateKeyPath string, algorithm HostKeyAlgorithm) error
UseOrMakeHostKey attempts to load a host key from the given privateKeyPath. If the path does not exist, a new host key is generated. It then adds this hostkey to the priovided server.
All parameters except the server are passed to ReadOrMakeHostKey. Please see the appropriate documentation for that function.
logger is called whenever a new host key algorithm is being generated.
Types ¶
type CommandSession ¶
type CommandSession struct {
ssh.Session // the underlying ssh.session
Logger utils.Logger
// contains filtered or unexported fields
}
CommandSession represents an ongoing ssh.Session executing a shell command.
func NewCommandSession ¶
func NewCommandSession(logger utils.Logger, session ssh.Session, command string, args []string) (*CommandSession, error)
NewCommandSession creates a new command session to execute a shell command. It prepares all resources, but does not actually start the session.
The command and arguments describe the process to be running in this session. command will be passed to exec.LookPath.
func (*CommandSession) Run ¶
func (c *CommandSession) Run() error
Run runs this session and waits for it to complete. After a call to this function ssh.Session will have closed.
If this session was already started, immediatly returns an error. If something goes wrong when starting the session also returns an error.
type HostKey ¶
type HostKey interface {
ssh.Signer
// Algorithm is the Algorithm used by this HostKey implementation.
Algorithm() HostKeyAlgorithm
// Generate generates a new HostKey, discarding whatever was previsouly contained.
//
// keySize is the desired public key size in bits. When keySize is 0, a sensible default is used.
// random is the source of randomness. If random is nil, crypto/rand.Reader will be used.
Generate(keySize int, random io.Reader) error
// MarshalPEM marshals the private key into a pem.Block to be used for exporting.
// The format is not guaranteed to follow any kind of standard, only that it is readable with the corresponding UnmarshalPEM.
MarshalPEM() (*pem.Block, error)
// UnmarshalPEM unmarshals the private key from a pem.Block.
// It is only compatible with whatever MarshalPEM() outputted.
UnmarshalPEM(block *pem.Block) error
}
HostKey represents an pair of ssh private key and algorithm. Once the hostkey is generated or loaded, it is safe for concurrent accesses.
func NewHostKey ¶
func NewHostKey(algorithm HostKeyAlgorithm) HostKey
NewHostKey returns a new empty HostKey for the provided HostKey Algorithm. An unsupported HostKeyAlgorithm will result in a call to panic().
type HostKeyAlgorithm ¶
type HostKeyAlgorithm string
HostKeyAlgorithm is an enumerated value that represents a specific algorithm used for host keys.
const ( // RSAAlgorithm represents the RSA Algorithm RSAAlgorithm HostKeyAlgorithm = "rsa" // ED25519Algorithm represents the ED25519 algorithm ED25519Algorithm HostKeyAlgorithm = "ed25519" )
type Options ¶
type Options struct {
// ListenAddress is the address to listen on.
// It should be of the form 'address:port'.
ListenAddress string
// Shell is the shell to use for the server
// This is called like `shell -c "command"“ when an ssh command is provided or like `shell` when not.
// The shell is passed to exec.LookPath().
Shell string
// ForwardAddresses are addresses that port forwarding is allowed for.
ForwardAddresses []utils.NetworkAddress
// ReverseAddresses are addresses that reverse port forwarding is allowed for.
ReverseAddresses []utils.NetworkAddress
// IdleTimeout is the timeout after which a connection is considered idle.
IdleTimeout time.Duration
}
Options are options for the NewProxySSHServer function.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
dockersshd
command
Command dockersshd provides an ssh server that executes commands inside docker.
|
Command dockersshd provides an ssh server that executes commands inside docker. |
|
simplesshd
command
Command simplesshd provides a simple ssh daemon that works similar to OpenSSH.
|
Command simplesshd provides a simple ssh daemon that works similar to OpenSSH. |
|
Package dockerproxy provides an ssh server that can run a command within an existing docker container.
|
Package dockerproxy provides an ssh server that can run a command within an existing docker container. |
|
Package legal contains legal notices of packages used by proxyssh.
|
Package legal contains legal notices of packages used by proxyssh. |
|
Package testutils contains functions used as utility code for tests.
|
Package testutils contains functions used as utility code for tests. |
|
Package utils contains various utility functions that are used by dockerproxy and proxyssh.
|
Package utils contains various utility functions that are used by dockerproxy and proxyssh. |