Posh-SSH

Posh-SSH is a PowerShell module that leverages a custom version of the SSH.NET library to provide SSH functionality. It is designed to facilitate automating actions against one or multiple SSH-enabled Linux servers from a Windows host. As of version 3.x, it can also be used on Linux and macOS via .NET Standard.

Key capabilities include:

• Automating SSH, SFTP, and SCP actions.
• Support for SOCKS4, SOCKS5, and HTTP Proxy.
• Remote, dynamic, and local port forwarding.

When connecting to a remote host, you can manage host key fingerprints using the following parameters:

• -AcceptKey: Automatically adds the host key fingerprint to the list of trusted host/fingerprint pairs.
• -Force: Skips the remote host fingerprint check entirely. Also allows overwriting existing local files if they already exist at the destination.
• -ErrorOnUntrusted: Raises an exception if the host's fingerprint is not found in the trusted store.
• -KnownHost: Specifies a KnownHost IStore (e.g., created via New-SSHMemoryKnownHost, Get-SSHJsonKnownHost, or Get-SSHOpenSSHKnownHost) to use for verification.

The Test-SFTPPath cmdlet supports two distinct parameter sets for specifying the remote session:

1. Index (Default): Uses the -SessionId parameter. This accepts an Int32[] (an array of integers) representing the ID of an existing session.
2. Session: Uses the -SFTPSession parameter. This accepts an SftpSession[] (an array of SFTP session objects) and allows you to pass the session object directly via the pipeline.

You can authenticate using private keys instead of passwords. New-SSHSession provides three parameter sets for key-based authentication:

1. Key File: Use -KeyFile <String> to specify a path to an OpenSSH format private key file. If a -Credential is provided, the password in that credential object will be used as the passphrase for the key.
2. Key String: Use -KeyString <String[]> to provide the OpenSSH key as a string array.
3. No Key (Default): Uses standard username/password authentication via the -Credential parameter.

New-SSHSession -ComputerName "example.com" -Credential (Get-Credential) -KeyFile "C:\path\to\id_rsa"

Depending on your security requirements, you can authenticate in several ways:

• Password Authentication: Provide a PSCredential object to the -Credential parameter.
• Private Key File: Use the -KeyFile <String> parameter to specify an OpenSSH format private key file. This requires the -KeyFile parameter set.
• Private Key Content: Use the -KeyString <String[]> parameter to pass the raw content of an OpenSSH key as a string array. This requires the -KeyString parameter set.

When using keys, the password field of the -Credential object acts as the passphrase for the key.

To manage host key validation, use the -KnownHost parameter. This parameter accepts an IStore object, which can be generated from:

• New-SSHMemoryKnownHost
• Get-SSHJsonKnownHost
• Get-SSHOpenSSHKnownHost

The Invoke-SSHStreamExpectAction cmdlet automates interactions with an SSH ShellStream by executing a command and waiting for a specific pattern (either a literal string or a regular expression) to appear in the output. Once the pattern is matched, it executes a subsequent action command.

This function returns $true if the action was successfully executed, and $false otherwise.

There are two primary ways to use this cmdlet:

1. String Matching (Default): Uses -ExpectString to look for an exact match.
2. Regex Matching: Uses -ExpectRegex to look for a pattern match.

Invoke-SSHStreamExpectAction -ShellStream $ShellStream -Command "config" -ExpectRegex '[\$%#>] $' -Action 'set interface eth0 address 10.10.10.240\24' -Verbose

To install the Posh-SSH module, use the standard PowerShell Install-Module command. This module is compatible with Windows PowerShell 5.1 and PowerShell 7.x. On Windows Server versions 1709 or older, .NET Framework 4.8 or above is required.

Install-Module -Name Posh-SSH

Use the Convert-SSHRegistryToJSonKnownHost cmdlet to convert Windows registry key storage (used for SSH known hosts) into a JSON format.

Note: This cmdlet is only compatible with Windows.

To remove all currently active SSH sessions, pipe the output of Get-SSHSession directly into Remove-SSHSession. This is the most efficient way to clean up all open connections.

### EXAMPLE 2
# Remove all sessions
Get-SSHSession | Remove-SSHSession

You can pipe the output of Get-SSHHostKey directly into New-SSHTrustedHost to automatically add a server's host key to your trusted hosts list. This is a common pattern for automating SSH connections to new servers.

'server' | Get-SSHHostKey | New-SSHTrustedHost

To find sessions associated with a specific host, use the -ComputerName parameter. If you want to avoid partial matches (e.g., matching 'server1' when searching for 'server'), use the -ExactMatch switch.

# List all sessions
Get-SSHSession

# List sessions for a specific host
Get-SSHSession -ComputerName 192.168.1.180

# List sessions using an exact match for the hostname
Get-SSHSession -ComputerName "my-server" -ExactMatch