go.bigb.es/auxilia

v0.4.0
Doc Versions Source

Documentation

Package transport is the SSH side-effect layer (PC1) for legatus. It implements legatus.Conn/legatus.Dialer over golang.org/x/crypto/ssh and github.com/pkg/sftp, with three hard guarantees:

  • IV2: remote command arguments and environment are passed STRUCTURALLY — every value is individually shell-quoted (see command.go) so the remote login shell, which parses the exec string, can never re-split or re-evaluate caller data.
  • IV5: no secret (key material, passphrase) is ever written to logs; this package logs nothing and folds key bytes only into the ssh library.
  • IV6: non-root commands are sudo-wrapped and non-root file uploads stage to a private /tmp path then `sudo mv` into place.

Authentication is key/agent only (AS1): no password auth is offered. The core legatus package stays SSH-free; this package is exactly how legatus.Conn is satisfied (PC1).

Types

T type Dialer

src 
type Dialer struct {
	// contains filtered or unexported fields
}

Dialer opens SSH connections, implementing legatus.Dialer. It is safe to reuse across hosts; each Dial produces an independent legatus.Conn.

f func New

src 
func New(opts ...Option) *Dialer

New builds a Dialer from the given options. At least one auth option (WithAgent / WithIdentityFile / WithSSHConfig) must be supplied; Dial fails loudly otherwise (no silent fallback, AS1).

m func (*Dialer) Dial

src 
func (d *Dialer) Dial(ctx context.Context, h *legatus.Host) (legatus.Conn, error)

Dial opens an SSH connection to h, returning a legatus.Conn. It requires at least one auth method and a host-key callback; both missing are hard errors (no insecure default — the caller must opt into InsecureIgnoreHostKey via WithHostKeyCallback). Only key/agent auth is offered (AS1).

T type Option

src 
type Option func(*Dialer)

Option configures a Dialer. Auth methods accumulate in the order supplied and are tried in that order by the ssh handshake.

f func WithAgent

src 
func WithAgent() Option

WithAgent authenticates via the ssh-agent at $SSH_AUTH_SOCK. The agent's signers are resolved lazily at Dial time so a Dialer can be constructed before the agent is reachable. Key material never leaves the agent (IV5).

f func WithHostKeyCallback

src 
func WithHostKeyCallback(cb xssh.HostKeyCallback) Option

WithHostKeyCallback sets an explicit host-key verification callback, overriding any WithKnownHosts. Callers that intentionally skip verification can pass xssh.InsecureIgnoreHostKey().

f func WithIdentityFile

src 
func WithIdentityFile(path string) Option

WithIdentityFile authenticates with the private key at path (with a leading ~ expanded). The key is parsed at Dial time; an encrypted or missing key surfaces as a Dial error (AS1 — no password prompt).

f func WithKnownHosts

src 
func WithKnownHosts(path string) Option

WithKnownHosts verifies host keys against the OpenSSH known_hosts file at path (with a leading ~ expanded). A key mismatch or unknown host fails the dial.

f func WithProxyJump

src 
func WithProxyJump(spec string) Option

WithProxyJump routes the connection through one or more jump hosts, given as an ssh ProxyJump value (`[user@]host[:port]`, comma-separated, applied left to right). It overrides any ProxyJump in ~/.ssh/config for the target.

f func WithSSHConfig

src 
func WithSSHConfig() Option

WithSSHConfig resolves each host through ~/.ssh/config (HostName, Port, User, IdentityFile) at Dial time, mirroring how the system ssh client behaves. The host's own Addr/Port/User remain authoritative when set; config fills the gaps.

f func WithTimeout

src 
func WithTimeout(timeout time.Duration) Option

WithTimeout sets the TCP connect plus SSH handshake timeout.

Source Files