Documentation
¶
Overview ¶
Package ssh provides SSH operations for remote system management.
Index ¶
- Constants
- Variables
- func HostKeyAlgorithmsFor(key ssh.PublicKey) []string
- func HostKeyReason(err error) string
- func ParseHostKey(line string) (ssh.PublicKey, error)
- func Ping(host string, port int, timeout time.Duration) bool
- func ProbeHostKey(ctx context.Context, host string, port int, timeout time.Duration, ...) (ssh.PublicKey, error)
- func SSHVerificationFailed(output string) bool
- type Client
- func (c *Client) CheckPort(ctx context.Context, port int) bool
- func (c *Client) Close() error
- func (c *Client) Connect() error
- func (c *Client) CopyFile(ctx context.Context, localPath, remotePath string) error
- func (c *Client) DirExists(ctx context.Context, remotePath string) bool
- func (c *Client) FileExists(ctx context.Context, remotePath string) bool
- func (c *Client) GetHost() string
- func (c *Client) GetSystemInfo(ctx context.Context) (*models.SystemInfo, error)
- func (c *Client) IsConnected() bool
- func (c *Client) MkdirAll(ctx context.Context, remotePath string) error
- func (c *Client) ReadFile(ctx context.Context, remotePath string) ([]byte, error)
- func (c *Client) Run(ctx context.Context, command string) (string, string, error)
- func (c *Client) RunWithSudo(ctx context.Context, command string) (string, string, error)
- func (c *Client) WriteFile(ctx context.Context, remotePath string, content []byte, mode os.FileMode) error
- type ClientOption
- func WithAutoAddHostKeys(auto bool) ClientOption
- func WithHost(host string) ClientOption
- func WithKeyPath(keyPath string) ClientOption
- func WithKnownHostsPath(path string) ClientOption
- func WithPort(port int) ClientOption
- func WithSSHTimeout(timeout time.Duration) ClientOption
- func WithUser(user string) ClientOption
- type HostKeyError
- type HostKeyPin
Constants ¶
const ( // ReasonHostKeyRequired means no expected host key was supplied and the // explicit first-contact mode was not requested. ReasonHostKeyRequired = "ssh_host_key_required" // ReasonHostKeyInvalid means the supplied host key is not one OpenSSH // public key. ReasonHostKeyInvalid = "ssh_host_key_invalid" // ReasonHostKeyMismatch means the target presented a different host key // than the one the caller pinned. ReasonHostKeyMismatch = "ssh_host_key_mismatch" // ReasonHostKeyUnreachable means first-contact pinning could not observe a // host key at all. ReasonHostKeyUnreachable = "ssh_host_key_unreachable" )
Typed reasons for refusing an SSH target before any operation runs.
Variables ¶
var HostKeyProbe = ProbeHostKey
HostKeyProbe observes the host key a target presents. It is a variable so tests can stand in for the network.
Functions ¶
func HostKeyAlgorithmsFor ¶ added in v0.52.5
HostKeyAlgorithmsFor returns the SSH host key signature algorithms a probe must offer to be shown the given key. A client that offers its defaults is shown ECDSA or RSA first by a stock sshd, which holds several host keys, so a pinned ed25519 key would be reported as a mismatch.
func HostKeyReason ¶ added in v0.52.5
HostKeyReason returns the typed reason of a host key refusal, or "".
func ParseHostKey ¶ added in v0.52.5
ParseHostKey parses one OpenSSH public key line (authorized_keys format, the shape Techstack persists at enrolment).
func ProbeHostKey ¶ added in v0.52.5
func ProbeHostKey(ctx context.Context, host string, port int, timeout time.Duration, algorithms []string) (ssh.PublicKey, error)
ProbeHostKey completes the SSH key exchange with host:port, captures the presented host key and aborts before any authentication. algorithms limits the host key signature algorithms offered to the server; nil keeps the library defaults.
func SSHVerificationFailed ¶ added in v0.52.5
SSHVerificationFailed reports whether ssh(1) output names a host key verification refusal, so retry loops stop instead of waiting for a host that will never match.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client handles SSH connections
func (*Client) FileExists ¶
FileExists checks if a file exists on the remote host
func (*Client) GetSystemInfo ¶
GetSystemInfo retrieves system information from the remote host
func (*Client) IsConnected ¶
IsConnected returns whether the client is connected
func (*Client) RunWithSudo ¶
RunWithSudo runs a command with sudo. Multi-line commands are wrapped in sudo bash -c to ensure all lines run with elevated privileges.
type ClientOption ¶
type ClientOption func(*Client)
ClientOption configures the SSH client
func WithAutoAddHostKeys ¶
func WithAutoAddHostKeys(auto bool) ClientOption
WithAutoAddHostKeys automatically adds unknown host keys
func WithKnownHostsPath ¶
func WithKnownHostsPath(path string) ClientOption
WithKnownHostsPath sets custom known_hosts file path
func WithSSHTimeout ¶
func WithSSHTimeout(timeout time.Duration) ClientOption
WithSSHTimeout sets the connection timeout
type HostKeyError ¶ added in v0.52.5
HostKeyError is the typed refusal for host key pinning. It never carries the private key material, only public fingerprints.
func (*HostKeyError) Error ¶ added in v0.52.5
func (e *HostKeyError) Error() string
func (*HostKeyError) Unwrap ¶ added in v0.52.5
func (e *HostKeyError) Unwrap() error
type HostKeyPin ¶ added in v0.52.5
type HostKeyPin struct {
Key ssh.PublicKey
Fingerprint string
Address string
// FirstContact is true when the key was observed rather than supplied by
// the caller. Callers must record this in the operation receipt.
FirstContact bool
}
HostKeyPin is the host key every later SSH connection to the target must present.
func ResolveHostKey ¶ added in v0.52.5
func ResolveHostKey(ctx context.Context, host string, port int, expected string, firstContact bool) (*HostKeyPin, error)
ResolveHostKey returns the pin every connection to host:port must satisfy.
- expected set: it is parsed and, when the target is reachable, compared with the key the target presents. A different key is ReasonHostKeyMismatch. An unreachable target is not an error here; the later connection still enforces the pin through StrictHostKeyChecking.
- expected empty and firstContact false: ReasonHostKeyRequired. There is no silent trust on first use.
- expected empty and firstContact true: the presented key is observed and pinned for this operation; the caller must record the fingerprint.
func (HostKeyPin) KnownHostsLine ¶ added in v0.52.5
func (p HostKeyPin) KnownHostsLine() string
KnownHostsLine renders the pin as one known_hosts entry (unhashed).
func (HostKeyPin) WriteKnownHosts ¶ added in v0.52.5
func (p HostKeyPin) WriteKnownHosts(path string) error
WriteKnownHosts writes the pin as a private known_hosts file for ssh(1).
Source Files