Posh-SSH: Open Source SSH PowerShell Module

Posh-SSH is a PowerShell 3.0 or newer module for automating tasks against system using the SSH protocol. The module supports only a subset of the capabilities that the different SSH RFCs http://en.wikipedia.org/wiki/Secure_Shell define but it allows for:

  • Establish SSH and SFTP sessions using credentials or OpenSSH keys.
  • Connecting through SOCKS and HTTP proxies for both SSH and SFTP sessions.
  • Execution of commands in a remote host using SSH Exec command.
  • Uploading and downloading of files using SCP and SFTP.

From the SSH standards it supports the following:

  • Supports DIFFIE-HELLMAN-GROUP-EXCHANGE-SHA256, DIFFIE-HELLMAN-GROUP-EXCHANGE-SHA1, DIFFIE-HELLMAN-GROUP14-SHA1 and DIFFIE-HELLMAN-GROUP1-SHA1 key exchange methods.
  • Supports 3DES-cbc, AES128-CBC, AES192-CBC, AES256-CBC, AES128-CTR, AES192-CTR, AES256-CTR, BlowFish-CBC, CAST128-CBC, ARCFour and TwoFish encryptions.
  • Supports HMAC-MD5, HMAC-SHA1, HMAC-RIPEMD160, HMAC-SHA2-256, HMAC-SHA2-256-96, HMAC-MD5-96 and HMAC-SHA1-96 hashing algorithms.
  • Supports public key, password, and keyboard-interactive authentication methods
    Supports RSA and DSA private key
  • Supports DES-EDE3-CBC, DES-EDE3-CFB, DES-CBC, AES-128-CBC, AES-192-CBC and AES-256-CBC algorithms for private key encryption
  • Supports SOCKS4, SOCKS5 and HTTP proxy

Installation

The module is hosted in GitHub at https://github.com/darkoperator/Posh-SSH; all source code for the cmdlets and for the module is available there and it is licensed under the BSD 3-Clause License. The module requires PowerShell 3.0 and .NET Framework 4.0. The quickest way to install the module is by running:

iex (New-Object Net.WebClient).DownloadString("https://gist.github.com/darkoperator/6152630/raw/c67de4f7cd780ba367cccbc2593f38d18ce6df89/instposhsshdev")

Connecting

The way the module works is by establishing sessions to each of the hosts we want to run against. By allowing multiple sessions at once it allows me to control and automate tasks against more than one hosts and not have to re-login to each one. The command to create a new session is New-SSHSession.

PS C:\help New-SSHSession

NAME
    New-SSHSession

SYNOPSIS
    Creates an SSH Session against a SSH Server

SYNTAX
    New-SSHSession [-ComputerName] <String[]> [-Credential] <PSCredential> [-Port <Int32>] [-ProxyServer <String>] [-ProxyPort <Int32>] [-ProxyCredential <PSCredential>] [-ProxyType <String>]
    [-ConnectionTimeOut <Int32>] [-KeepAliveInterval <Int32>] [-AcceptKey [<Boolean>]] [-PipelineVariable <String>] [<CommonParameters>]

    New-SSHSession [-ComputerName] <String[]> [-Credential] <PSCredential> [-Port <Int32>] [-ProxyServer <String>] [-ProxyPort <Int32>] [-ProxyCredential <PSCredential>] [-ProxyType <String>]
    [-KeyFile <String>] [-ConnectionTimeOut <Int32>] [-KeepAliveInterval <Int32>] [-AcceptKey [<Boolean>]] [-PipelineVariable <String>] [<CommonParameters>]

DESCRIPTION
    Creates an SSH Session against a remote server. The command supports creating connection thru a Proxy and allows for authentication to the server using username and password. If a key file is
    specified the command will use the password in the credentials parameter as the paraphrase of the key.

RELATED LINKS

REMARKS
    To see the examples, type: "get-help New-SSHSession -examples".
    For more information, type: "get-help New-SSHSession -detailed".
    For technical information, type: "get-help New-SSHSession -full".

When we establish a new session for the first time it will check SSH server certificate fingerprint and IP address combination to those saved in HKEY_CURRENT_USER\Software\PoshSSH registry key; if there is a mismatch it will generate an error that the fingerprint did not match and if it is not present it will show the fingerprint and ask if you want to trust or not the host before connecting:

PS C:\New-SSHSession -ComputerName "192.168.2.1" -Credential (Get-Credential root)

Server SSH Fingerprint
Do you want to trust the fingerprint 62:ef:96:b6:f8:a9:6c:7c:34:29:e6:d6:ba:59:ad:2f
[] Y  [] N  [?] Help (default is "N"): Y

Index Host             Connected
----- ----             ---------
  0   192.168.2.1      True

We can see all the hosts we trust using the Get-SSHTrustedHost command and one can remove hosts from the trusts list using Remove-SSHTrustedHost:

PS C:\Get-SSHTrustedHost | fl

SSHHost     : 192.168.2.1
Fingerprint : 62:ef:96:b6:f8:a9:6c:7c:34:29:e6:d6:ba:59:ad:2f

When the session is created, we can look at the session using the Get-SSHSession command:

PS C:\Get-SSHSession | fl

Connected : True
Index     : 0
Host      : 192.168.2.1
Session   : Renci.SshNet.SshClient

Each session has the Index property that can be used with other commands or the object that is returned.

To disconnect from the hosts we use the Remove-SSHSession:

PS C:\Remove-SSHSession -Index 0 -Verbose

VERBOSE: 0
VERBOSE: Removing session 0
True
VERBOSE: Session 0 Removed

Executing Command

We can execute commands against a session or sessions using the Invoke-SSHCommand command. When a command is executed an object representing the results of the execution is returned. When executed it instantiates on the system a new instance of the default shell configured on the system, executes the command and returns an object and the exit status of the last command executed.

PS C:\Invoke-SSHCommand -Index 0 -Command "uname -a"

Host       : 192.168.2.1
Output     : Linux testdebian7 3.2.0-4-amd64 #1 SMP Debian 3.2.51-1 x86_64 GNU/Linux
ExitStatus : 0

Uploading and Downloading Files with SCP

The module also provides SCP commands for uploading and downloading files. SCP works by establishing a connection and copying or downloading the file specified depending on the action selected.

For uploading a file we use the Set-SCPFile cmdlet. We need to specify a server, credentials, a local file that we want to upload, and the full path and name of the full path of the destination file.

PS C:\Set-SCPFile -LocalFile .\Downloads\VMware-PowerCLI-5.5.0-1671586.exe -RemoteFile "/tmp/powercliinstaller.exe" -ComputerName 192.168.2.15 -Credential (Get-Credential root)

To download a file the process is similar, but we use the Get-SCPFile cmdlet.

PS C:\Get-SCPFile -LocalFile .\Downloads\VMware-PowerCLI.exe -RemoteFile "/tmp/powercliinstaller.exe" -ComputerName 192.168.2.16 -Credential (Get-Credential root)

Using SFTP

The module also provides SFTP support. The SFTP commands also work with sessions. To create a SFTP session we use the New-SFTPSession cmdlet. It uses the same list of trusted hosts as the one for SSH sessions.

PS C:\> New-SFTPSession -ComputerName 192.168.2.16 -Credential (Get-Credential root) -Verbose | fl
VERBOSE: Using Username and Password authentication for connection.
VERBOSE: Connecting to 192.168.2.16 with user root

Connected : True
Index     : 0
Host      : 192.168.2.16
Session   : Renci.SshNet.SftpClient

When working with files we can move, delete, upload, and download a specified files on a SFTP:

  • Get-SFTPFile – Download a specified file from a remote SFTP session.
  • Move-SFTPFile – Moves a specified file in a remote hosts through SFTP (Can be used to rename a file)
  • Remove-SFTPFile – Deletes a specified file in a remote hosts through SFTP.
  • Set-SFTPFile – Uploads a specified file to a given path using SFTP.

We can also create and delete directories on a target system:

  • New-SFTPDirectory – Creates a directory in a remote hosts through SFTP.
  • Remove-SFTPDirectory – Deletes a specified directory in a remote hosts through SFTP.

The Posh-SSH module should cover most of the basic needs. Each of the sessions include the session object that provides additional methods and properties. Most commands also return objects with additional methods and properties not shown by default that can be leveraged by an advanced user. I hope you find the module useful and if you come up with a new command or a bug fix do not hesitate to contribute.

More information: Posh-SSH: Open Source SSH PowerShell Module

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s