sshclient

package
v0.3.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 5, 2026 License: MIT Imports: 41 Imported by: 0

Documentation

Overview

Package sshclient provides SSH client dialing, SFTP, tunnels, and known_hosts helpers for honey.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DialHoneyHost added in v0.3.4 

func DialHoneyHost(user, hostAlias string, overridePort int, identityFile string) (hostexec.HostClient, error)

DialHoneyHost connects to the remote host using SSH.

func DialSSHClient 

func DialSSHClient(userOverride, hostAlias string, overridePort int, recipeIdentityFile string) (*ssh.Client, func(), error)

DialSSHClient returns the leaf *ssh.Client and a cleanup that closes the full ProxyJump chain.

func ParseLocalForward added in v0.3.0 

func ParseLocalForward(spec string) (localPort, remoteHost, remotePort string, err error)

ParseLocalForward splits a tunnel mapping "localPort:remoteHost:remotePort".

func RunTunnelGo 

func RunTunnelGo(ctx context.Context, user, host string, sshPort int, localFwd string, out io.Writer) error

RunTunnelGo listens on 127.0.0.1:<localPort> and forwards to remoteHost:remotePort via the SSH server (host). sshPort is 0 to use ~/.ssh/config Port / default 22 only, or 1..65535 to override the leaf SSH server port.

func StartDynamicForward added in v0.3.0 

func StartDynamicForward(ctx context.Context, client *ssh.Client, bindHost string, localPort int) (socksHost string, socksPort int, stop func(), err error)

StartDynamicForward starts a SOCKS5 proxy on bindHost:localPort that tunnels via client.

func StartDynamicForwardMulti added in v0.3.3 

func StartDynamicForwardMulti(ctx context.Context, clients []WeightedClient, bindHost string, localPort int) (socksHost string, socksPort int, stop func(), err error)

StartDynamicForwardMulti starts a SOCKS5 proxy that distributes connections across clients using smooth weighted round-robin (NGINX algorithm via mr-karan/balance). Weight <= 0 defaults to 1. Single-client slices work correctly.

func StartLocalForward added in v0.3.0 

func StartLocalForward(ctx context.Context, client *ssh.Client, bindHost string, localPort int, remoteHost string, remotePort int) (listenHost string, listenPort int, stop func(), err error)

StartLocalForward listens locally and dials remoteHost:remotePort via client.

func StartPTYResizeForwarding 

func StartPTYResizeForwarding(fd int, sess *ssh.Session, onResize func(cols, rows int)) (stop func())

StartPTYResizeForwarding sends SIGWINCH-driven size updates to the remote PTY.

func StartRemoteForward added in v0.3.0 

func StartRemoteForward(ctx context.Context, client *ssh.Client, remoteBind string, remoteListenPort int, localHost string, localPort int) (remoteAddr string, stop func(), err error)

StartRemoteForward listens on the remote side and dials localHost:localPort locally.

func StartTerminalResize 

func StartTerminalResize(fd int, onSize func(cols, rows int)) (stop func())

StartTerminalResize invokes onSize(cols, rows) whenever the terminal receives SIGWINCH.

func StartTunForward added in v0.3.0 

func StartTunForward(ctx context.Context, user, hostAlias string, sshPort, tunLocal, tunRemote int) (tunName string, stop func(), err error)

StartTunForward starts an OpenSSH tunnel device forward (ssh -w local:remote -N).

func StartUDPRelay added in v0.3.0 

func StartUDPRelay(ctx context.Context, client *ssh.Client, bindHost string, localPort int, remoteHost string, remotePort int, remoteSocat bool) (listenHost string, listenPort int, stop func(), err error)

StartUDPRelay bridges a local UDP listener to a remote UDP target via SSH. When remoteSocat is true, a remote socat TCP listener relays to the UDP target.

Types

type ForwardKind added in v0.3.0 

type ForwardKind int

ForwardKind identifies an SSH port-forwarding directive. 

const (
	ForwardKindLocal ForwardKind = iota
	ForwardKindRemote
	ForwardKindDynamic
)

ForwardKind values identify SSH config forward directive types.

type ForwardSet added in v0.3.0 

type ForwardSet struct {
	Local   []ForwardSpec
	Remote  []ForwardSpec
	Dynamic []ForwardSpec
}

ForwardSet holds parsed forwards grouped by kind.

func ForwardsForHost added in v0.3.0 

func ForwardsForHost(alias, user string, matchEnv map[string]string) (ForwardSet, error)

ForwardsForHost resolves LocalForward/RemoteForward/DynamicForward for alias using ssh -G, or a fallback parser when HONEY_SSH_OPENSSH_G disables ssh -G.

func ParseOpenSSHGForwards added in v0.3.0 

func ParseOpenSSHGForwards(data []byte) ForwardSet

ParseOpenSSHGForwards parses localforward/remoteforward/dynamicforward lines from ssh -G output.

func (ForwardSet) All added in v0.3.0 

func (s ForwardSet) All() []ForwardSpec

All returns every forward in a stable order: local, remote, dynamic.

type ForwardSpec added in v0.3.0 

type ForwardSpec struct {
	Kind ForwardKind

	// BindHost is the local bind address for Local/Dynamic forwards, or the
	// remote bind address for RemoteForward when set.
	BindHost string
	BindPort int

	// RemoteHost/RemotePort are the destination for LocalForward.
	RemoteHost string
	RemotePort int

	// LocalHost/LocalPort are the local-side target for RemoteForward.
	LocalHost string
	LocalPort int

	Source       string
	FallbackWarn bool
}

ForwardSpec is one LocalForward, RemoteForward, or DynamicForward entry.

func ParseForwardSpecLine added in v0.3.0 

func ParseForwardSpecLine(line string) (ForwardSpec, error)

ParseForwardSpecLine parses one OpenSSH config forward directive line.

func PickForward added in v0.3.0 

func PickForward(specs []ForwardSpec, match string) (ForwardSpec, error)

PickForward selects a forward from specs by bind port or remote port (match is a decimal port string).

type HoneyClient 

type HoneyClient struct {
	*goph.Client
	// contains filtered or unexported fields
}

HoneyClient wraps goph.Client so Close() also shuts down ProxyJump bastion clients.

func DialHoneyClient 

func DialHoneyClient(userOverride, hostAlias string, overridePort int, recipeIdentityFile string) (*HoneyClient, error)

DialHoneyClient opens SSH using ~/.ssh/config (User, HostName, Port, IdentityFile, ProxyJump, StrictHostKeyChecking, UserKnownHostsFile, GlobalKnownHostsFile) and known_hosts verification via golang.org/x/crypto/ssh/knownhosts (see hostKeyCallbackForHostSSH). When system OpenSSH is available, resolution uses `ssh -G` so Match blocks apply; set HONEY_SSH_OPENSSH_G=0 to disable. Auth also uses HONEY_SSH_IDENTITY_FILES and default ~/.ssh key names (see buildAuthWithIdentityFiles). If overridePort is in 1..65535, it replaces the leaf port from resolution (e.g. from record meta.ssh_port). When recipeIdentityFile is non-empty, auth uses only that private key (see buildAuthExclusiveIdentityFile).

func (*HoneyClient) Close 

func (h *HoneyClient) Close() error

Close closes the target session transport, then any bastion SSH clients (reverse order).

func (*HoneyClient) Download 

func (h *HoneyClient) Download(remotePath, localPath string) error

Download copies a remote file to a local path over SFTP.

func (*HoneyClient) LeafSSH 

func (h *HoneyClient) LeafSSH() *ssh.Client

LeafSSH returns the leaf *ssh.Client used for sessions/SFTP on the target host (ProxyJump hops are parents).

func (*HoneyClient) ListRemoteDir 

func (h *HoneyClient) ListRemoteDir(path string) ([]hostexec.RemoteFileEntry, error)

ListRemoteDir returns sorted directory entries for the given remote path.

func (*HoneyClient) MkdirAllRemote 

func (h *HoneyClient) MkdirAllRemote(path string) error

MkdirAllRemote creates a remote directory tree via SFTP.

func (*HoneyClient) RemoveRemote 

func (h *HoneyClient) RemoveRemote(path string, recursive bool) error

RemoveRemote deletes a remote file or directory (recursive walks children first).

func (*HoneyClient) RunWithStreams 

func (h *HoneyClient) RunWithStreams(cmd string, stdin io.Reader, stdout, stderr io.Writer) error

RunWithStreams runs cmd on the remote (non-interactive session) with stdin/stdout/stderr attached. stderr may be nil to discard remote stderr.

func (*HoneyClient) StatRemote 

func (h *HoneyClient) StatRemote(path string) (hostexec.RemoteFileEntry, error)

StatRemote returns metadata for a single remote filesystem object.

func (*HoneyClient) Upload 

func (h *HoneyClient) Upload(localPath, remotePath string) error

Upload copies a local file to the remote path over SFTP.

func (*HoneyClient) UploadWithProgress 

func (h *HoneyClient) UploadWithProgress(localPath, remotePath string, onProgress func(written, total int64)) error

UploadWithProgress copies a local file to the remote path over SFTP, calling onProgress with cumulative bytes written to the remote and the local file size (throttled). onProgress may be nil.

type SSHDialer added in v0.3.3 

type SSHDialer interface {
	Dial(network, addr string) (net.Conn, error)
}

SSHDialer is the minimal interface for routing SOCKS5 connections over SSH. *gossh.Client satisfies this interface without any wrapping.

type SSHPool added in v0.3.3 

type SSHPool struct {
	// contains filtered or unexported fields
}

SSHPool maintains up to size parallel HoneyClient connections to one host. puddle manages the resource lifecycle; a background goroutine probes idle connections and destroys dead ones before any dial hits them.

func NewSSHPool added in v0.3.3 

func NewSSHPool(ctx context.Context, size int, dialFn func() (*HoneyClient, error)) (*SSHPool, error)

NewSSHPool creates and eagerly warms a pool of size SSH connections using dialFn. All size connections are established before the call returns.

func (*SSHPool) Close added in v0.3.3 

func (sp *SSHPool) Close() error

Close stops the keepalive loop and destroys all connections in the pool.

func (*SSHPool) Dial added in v0.3.3 

func (sp *SSHPool) Dial(network, addr string) (net.Conn, error)

Dial implements SSHDialer using a background context. The SOCKS5 path calls DialContext directly to avoid goroutine leaks.

func (*SSHPool) DialContext added in v0.3.3 

func (sp *SSHPool) DialContext(ctx context.Context, network, addr string) (net.Conn, error)

DialContext acquires a pool entry, opens an SSH channel, then immediately releases the entry back to the pool. ctx cancellation stops the retry loop immediately so no goroutine outlives the caller.

func (*SSHPool) RunWithClient added in v0.3.3 

func (sp *SSHPool) RunWithClient(ctx context.Context, fn func(*gossh.Client) error) error

RunWithClient acquires a pool entry and calls fn with its underlying ssh.Client. Useful for one-shot SSH operations (e.g. remote route discovery) that need a session without going through the SOCKS5 path.

type WeightedClient added in v0.3.3 

type WeightedClient struct {
	Client SSHDialer
	Weight int
}

WeightedClient pairs an SSH dialer with a routing weight for StartDynamicForwardMulti. *ssh.Client satisfies SSHDialer; *SSHPool also satisfies it.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.