Welcome to Power Remote Desktop for remote desktop access in pure PowerShell! This module offers a unique solution for remotely controlling one or multiple screens using only PowerShell. Unlike other remote desktop tools that rely on external protocols and software, our module utilizes its own remote desktop protocol.
The module consists of both a client and a server component, both of which are written entirely in PowerShell. Our protocol provides secure, encrypted communication using TLS and offers both challenge-based password authentication and certificate-based authentication.
In addition to providing full mouse and keyboard control over the remote desktop, our module also replicates the mouse cursor icon for the viewer, synchronizes the clipboard between the local and remote systems, and more. Despite the limitations of PowerShell, we have implemented techniques to optimize network traffic and improve the streaming experience, resulting in a smooth and efficient remote desktop experience.
At the time of writing, this is the only known entirely PowerShell-based remote desktop application. We hope you find it useful and we welcome any feedback or suggestions you may have.
Tested on:
- Windows 10
- Windows 11
Current version: 4.0.0 Stable
For a better streaming performance and overall experience, we recommend using PowerShell 7 instead of PowerShell 5.
You can install PowerShell 7 for Windows here
- Remote Desktop Streaming: This feature allows you to stream the desktop of the remote computer to your own device. The streaming supports HDPI and scaling, providing a high-quality display on various screens and resolutions.
- Remote Control: With this feature, you can control the mouse (including moves, clicks, and wheel) and keyboard of the remote computer as if you were sitting in front of it.
- Secure: To protect the privacy and security of your remote desktop sessions, the module uses TLSv1.2 or 1.3 to encrypt the network traffic. Access to the server is granted through a challenge-based authentication mechanism that requires a user-defined complex password.
- Network Traffic Encryption: The module supports encrypting the network traffic using either a default X509 certificate (which requires administrator privileges) or your own custom X509 certificate.
- Server Certificate Fingerprint Validation: To ensure the authenticity of the server, the module allows you to validate the fingerprint of the server certificate and optionally persist this validation between sessions.
- Clipboard Synchronization: This feature allows you to synchronize the clipboard text between the viewer (your device) and the server (the remote computer). You can easily copy and paste text between the two systems.
- Mouse Cursor Icon Synchronization: The module also synchronizes the state of the mouse cursor icon between the viewer (virtual desktop) and the server, providing a more seamless and intuitive remote desktop experience.
- Multi-Screen Support: If the remote computer has more than one desktop screen, you can choose which screen to capture and stream to your device.
- View Only Mode: This feature allows you to disable remote control abilities and simply view the screen of the remote computer. It can be useful for demonstrations or presentations.
- Session Concurrency: Multiple viewers can connect to a single server at the same time, allowing multiple users to collaborate on the same remote desktop.
- Sleep Mode Prevention: To ensure that the remote desktop remains active and responsive, the module prevents the remote computer from entering sleep mode while it is waiting for viewers to connect.
- Streaming Optimization: To improve the streaming speed, the module only sends updated pieces of the desktop to the viewer, reducing the amount of data transmitted over the network.
Install-Module -Name PowerRemoteDesktop_Server
Invoke-RemoteDesktopServer -CertificateFile "<certificate_location>"If you want to avoid using your own certificate and prefer not to go through the process of creating one, you can remove the 'CertificateFile' option and run PowerShell as an administrator instead.
Install-Module -Name PowerRemoteDesktop_Viewer
Invoke-RemoteDesktopViewer -ServerAddress "<ip_address>" -Password "<the_one_displayed_on_server>"Thats it 😉
There are several ways to use this PowerShell application. The recommended method is to install both the server and viewer components using the PowerShell Gallery. Alternatively, you can install them as modules or import them as scripts manually. Choose the method that best fits your needs and preferences.
You can install Power Remote Desktop from the PowerShell Gallery, which is similar to Aptitude for Debian or Brew for MacOS. To do so, run the following commands:
Install-Module -Name PowerRemoteDesktop_Server
Install-Module -Name PowerRemoteDesktop_ViewerAllowPrerelease is mandatory when current version is marked as a Prerelease
When you run the command, you may see the following warning in your command prompt:
Untrusted repository
You are installing the modules from an untrusted repository. If you trust this repository, change its
InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure you want to install the modules from
'PSGallery'?
Type 'Y' to confirm and proceed with the installation. When the installation is complete, both modules should be available. You can verify this by running the following command:
Get-Module -ListAvailableExample Output:
PS C:\Users\Phrozen\Desktop> Get-Module -ListAvailable
Directory: C:\Users\Phrozen\Documents\WindowsPowerShell\Modules
ModuleType Version Name ExportedCommands
---------- ------- ---- ----------------
Manifest 1.0.0 PowerRemoteDesktop_Server Invoke-RemoteDesktopServer
Manifest 1.0.0 PowerRemoteDesktop_Viewer Invoke-RemoteDesktopViewer
<..snip..>
If the modules are not showing up, try running the following commands and then check again:
Import-Module PowerRemoteDesktop_Server
Import-Module PowerRemoteDesktop_ViewerIn order for a module to be available, it must be located in a registered module path. You can view the registered module paths by running the following command:
Write-Output $env:PSModulePathExample Output:
C:\Users\Phrozen\Documents\WindowsPowerShell\Modules;C:\Program Files\WindowsPowerShell\Modules;C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules
Clone PowerRemoteDesktop repository or download a Github release package.
git clone https://github.com/DarkCoderSc/PowerRemoteDesktop.git
Copy both PowerRemoteDesktop_Viewer and PowerRemoteDesktop_Server folders to desired module path
Example:
C:\Users\<USER>\Documents\WindowsPowerShell\Modules
Both modules should now be available, you can verify using the command:
Get-Module -ListAvailableExample Output:
PS C:\Users\Phrozen\Desktop> Get-Module -ListAvailable
Directory: C:\Users\Phrozen\Documents\WindowsPowerShell\Modules
ModuleType Version Name ExportedCommands
---------- ------- ---- ----------------
Manifest 1.0.0 PowerRemoteDesktop_Server Invoke-RemoteDesktopServer
Manifest 1.0.0 PowerRemoteDesktop_Viewer Invoke-RemoteDesktopViewer
<..snip..>
If you don't see them, run the following commands and check back.
Import-Module PowerRemoteDesktop_Server
Import-Module PowerRemoteDesktop_ViewerNotice: Manifest files are optional (*.psd1) and can be removed.
It is not mandatory to install this application as a PowerShell module (Even if file extension is *.psm1)
You can also load it as a PowerShell Script. Multiple methods exists including:
Invoking Commands Using:
IEX (Get-Content .\PowerRemoteDesktop_[Server/Viewer].psm1 -Raw)Loading script from a remote location:
IEX (New-Object Net.WebClient).DownloadString('http://127.0.0.1/PowerRemoteDesktop_[Server/Viewer].psm1')etc...
PowerRemoteDesktop_Viewer.psm1 needs to be imported / or installed on local machine.
Invoke-RemoteDesktopViewer
Get-TrustedServers
Remove-TrustedServer
Clear-TrustedServers Create a new remote desktop session with a Power Remote Desktop Server.
| Parameter | Type | Default | Description |
|---|---|---|---|
| ServerAddress | String | 127.0.0.1 | Remote server host or address |
| ServerPort | Integer | 2801 | Port number for the remote server |
| SecurePassword | SecureString | None | SecureString object containing the password used for authenticating with the remote server (recommended) |
| Password | String | None | Plain-text password used for authenticating with the remote server (not recommended; use SecurePassword instead)) |
| DisableVerbosity | Switch | False | If specified, the program will suppress verbosity messages |
| UseTLSv1_3 | Switch | False | If specified, the program will use TLS v1.3 instead of TLS v1.2 for encryption (recommended if both systems support it) |
| Clipboard | Enum | Both | Specify the clipboard synchronization mode (options include 'Both', 'Disabled', 'Send', and 'Receive'; see below for more detail) |
| ImageCompressionQuality | Integer (0-100) | 75 | JPEG compression level ranging from 0 (lowest quality) to 100 (highest quality) |
| Resize | Switch | False | If specified, the remote desktop will be resized according to the 'ResizeRatio' option |
| ResizeRatio | Integer (30-99) | 90 | Used in conjunction with the 'Resize' option, specify the resize ratio as a percentage |
| AlwaysOnTop | Switch | False | If specified, the virtual desktop window will be displayed above all other windows |
| PacketSize | Enum | Size9216 | Specify the network packet size for streams. Choose a size that is appropriate for your network constraints. |
| BlockSize | Enum | Size64 | Specify the size of the screen grid blocks. Choose a size that is appropriate for the remote screen size and the computer's resources (such as CPU and network capabilities) |
| LogonUI | Switch | False | Request the server to open the LogonUI/Winlogon desktop instead of the default user desktop (requires SYSTEM privilege in the active session) |
| Value | Description |
|---|---|
| Disabled | Clipboard synchronization is disabled on both the viewer and server sides |
| Receive | Only incoming clipboard data is allowed |
| Send | Only outgoing clipboard data is allowed |
| Both | Clipboard synchronization is allowed on both the viewer and server sides |
| Value | Description |
|---|---|
| Size1024 | 1024 Bytes (1KiB) |
| Size2048 | 2048 Bytes (2KiB) |
| Size4096 | 4096 Bytes (4KiB) |
| Size8192 | 8192 Bytes (8KiB) |
| Size9216 | 9216 Bytes (9KiB) |
| Size12288 | 12288 Bytes (12KiB) |
| Size16384 | 16384 Bytes (16KiB) |
| Value | Description |
|---|---|
| Size32 | 32x32 |
| Size64 | 64x64 |
| Size96 | 96x96 |
| Size128 | 128x128 |
| Size256 | 256x256 |
| Size512 | 512x512 |
It is recommended to use SecurePassword instead of a plain-text password, even if the plain-text password is being converted to a SecureString
Open a new remote desktop session to '127.0.0.1:2801' using the password 'urCompl3xP@ssw0rd'
Invoke-RemoteDesktopViewer -ServerAddress "127.0.0.1" -ServerPort 2801 -SecurePassword (ConvertTo-SecureString -String "urCompl3xP@ssw0rd" -AsPlainText -Force)When connecting to a new remote server for the first time, the viewer will ask if you want to trust the server's fingerprint. If you select the option to 'Always' trust this fingerprint, it will be saved in the local user registry. You can revoke the trust for this fingerprint at any time using the appropriate function.
Get-TrustedServersExample output:
PS C:\Users\Phrozen\Desktop\Projects\PowerRemoteDesktop> Get-TrustedServers
Detail Fingerprint
------ -----------
@{FirstSeen=18/01/2022 19:40:24} D9F4637463445D6BB9F3EFBF08E06BE4C27035AF
@{FirstSeen=20/01/2022 15:52:33} 3FCBBFB37CF6A9C225F7F582F14AC4A4181BED53
@{FirstSeen=20/01/2022 16:32:14} EA88AADA402864D1864542F7F2A3C49E56F473B0
@{FirstSeen=21/01/2022 12:24:18} 3441CE337A59FC827466FC954F2530C76A3F8FE4
Remove-TrustedServer -Fingerprint "<target_ingerprint>"Clear-TrustedServersPowerRemoteDesktop_Server.psm1 needs to be imported / or installed on local machine.
Invoke-RemoteDesktopServer| Parameter | Type | Default | Description |
|---|---|---|---|
| ServerAddress | String | 0.0.0.0 | IP address representing the local machine's IP address |
| ServerPort | Integer | 2801 | The port number on which to listen for incoming connections |
| SecurePassword | SecureString | None | SecureString object containing the password used for authenticating remote viewers (recommended) |
| Password | String | None | Plain-text password used for authenticating remote viewers (not recommended; use SecurePassword instead) |
| DisableVerbosity | Switch | False | If specified, the program will suppress verbosity messages |
| UseTLSv1_3 | Switch | False | If specified, the program will use TLS v1.3 instead of TLS v1.2 for encryption (recommended if both systems support it) |
| Clipboard | Enum | Both | Specify the clipboard synchronization mode (options include 'Both', 'Disabled', 'Send', and 'Receive'; see below for more detail) |
| CertificateFile | String | None | A file containing valid certificate information (x509) that includes the private key |
| EncodedCertificate | String | None | A base64-encoded representation of the entire certificate file, including the private key |
| ViewOnly | Switch | False | If specified, the remote viewer will only be able to view the desktop and will not have access to the mouse or keyboard |
| PreventComputerToSleep | Switch | False | If specified, this option will prevent the computer from entering sleep mode while the server is active and waiting for new connections |
| CertificatePassword | SecureString | None | Specify the password used to access a password-protected x509 certificate provided by the user |
| Value | Description |
|---|---|
| 127.0.0.1 | Only listen for connections from the localhost (usually for debugging purposes) |
| 0.0.0.0 | Listen for connections on all network interfaces, including the local network and the internet |
| Value | Description |
|---|---|
| Disabled | Clipboard synchronization is disabled on both the viewer and server sides |
| Receive | Only incoming clipboard data is allowed |
| Send | Only outgoing clipboard data is allowed |
| Both | Clipboard synchronization is allowed on both the viewer and server sides |
- It is recommended to use SecurePassword instead of a plain-text password, even if the plain-text password is being converted to a SecureString.
- If you do not specify a custom certificate using 'CertificateFile' or 'EncodedCertificate', a default self-signed certificate will be generated and installed on the local machine (if one does not already exist). This requires administrator privileges. To run the server with a non-privileged account, you must provide your own certificate location.
- If you do not specify a SecurePassword or Password, a random, complex password will be generated and displayed in the terminal (this password is temporary).
Invoke-RemoteDesktopServer -ListenAddress "0.0.0.0" -ListenPort 2801 -SecurePassword (ConvertTo-SecureString -String "urCompl3xP@ssw0rd" -AsPlainText -Force)
Invoke-RemoteDesktopServer -ListenAddress "0.0.0.0" -ListenPort 2801 -SecurePassword (ConvertTo-SecureString -String "urCompl3xP@ssw0rd" -AsPlainText -Force) -CertificateFile "c:\certs\phrozen.p12"As of version 4.0.0, it is possible to capture the LogonUI/Winlogon (UAC Prompt, Windows Login Window, CTRL+ALT+DEL, etc.).
However, in order to capture the LogonUI, the server must be run under the context of 'NT AUTHORITY/System' in the current active session.
There are multiple methods for spawning a process as the SYSTEM user in the active session (e.g., PsExec, Process Hacker), but for simplicity I recommend using my PowerRunAsSystem project (available on GitHub and installable through the PowerShell Gallery).
Install-Module -Name PowerRunAsSystemThen run bellow command as Administrator.
Invoke-InteractiveSystemPowerShellA new PowerShell terminal should appear on your desktop as NT AUTHORITY/System
If you follow the steps above, a new PowerShell terminal should appear on your desktop running as the 'NT AUTHORITY/System' user.
From this terminal, you can run the Power Remote Desktop server command and enable the 'LogonUI' option for future Power Remote Desktop viewer connections.
It's worth noting that if you don't use your own X509 certificate, you will need administrator privileges to create a new server. However, you can easily create your own X509 certificate using tools such as the OpenSSL command line tool.
openssl req -x509 -sha512 -nodes -days 365 -newkey rsa:4096 -keyout phrozen.key -out phrozen.crt
Then export the new certificate (must include private key).
openssl pkcs12 -export -out phrozen.p12 -inkey phrozen.key -in phrozen.crt
Use CertificateFile. Example: c:\tlscert\phrozen.crt
Encode an existing certificate using PowerShell
[convert]::ToBase64String((Get-Content -path "c:\tlscert\phrozen.crt" -Encoding byte))or on Linux / Mac systems
base64 -i /tmp/phrozen.p12
You can then pass the output base64 certificate file to parameter EncodedCertificate (One line)
- Desktop images are now transported in raw bytes instead of base64 string thus slightly improving performances.
- Protocol has drastically changed. It is smoother to read and less prone to errors.
- TLS v1.3 option added (Might not be supported by some systems).
- Several code optimization, refactoring and fixes.
- Password complexity check implemented to avoid lazy passwords.
- Possibility to disable verbose.
- Server & Viewer version synchronization. Same version must be used between the two.
- HDPI is completely supported.
- Possibility to change desktop image quality.
- Possibility to choose which screen to capture if multiple screens (Monitors) are present on remote machine.
- Password is stored as SecureString on Viewer. I don't see the point of implementing SecureString sever-side, if you do see the point, please change my mind.
- Server Fingerprint Validation.
- Possibility to trust a server for current PowerShell Instance or persistantly using a local storage.
- Possibility to manage trusted servers (List, Remove, Remove All)
- Multiple code improvements to support incoming / outgoing events.
- Global cursor state synchronization implemented (Now virtual desktop mouse cursor is the same as remote server).
- Password Generator algorithm fixed.
- Virtual keyboard
]and)correctly sent and interpreted. - Clipboard synchronization Viewer <-> Server added.
- Server support a new option to only show desktop (Mouse moves, clicks, wheel and keyboard control is disabled in this mode).
- TransportMode option removed.
- Desktop streaming performance / speed increased.
- Protocol was completely revisited, protocol is now more stable and modular.
- Session concurrency is now supported, multiple viewers can connect at the same time to a server.
- Possibility to stop the server using CTRL+C
- Image quality is now requested by viewer.
- Desktop resize is now made server-side.
- Desktop resize can now be forced and requested by viewer.
- Center virtual desktop glitch fixed.
- Handshake calls (auth + session / worker negociation) will now timeout to avoid possible dead locks.
- Virtual Desktop Form can now be set always on top of other forms.
- Server finally use secure string to handle password-authentication.
- Prevent computer to sleep in server side.
- Motion Update now supported in its very first version to increase desktop streaming speed.
- Mouse move works as expected in certain circumstances.
- Keyboard simulation improved.
- Various Optimization and fixes.
- Code refactoring and improvement.
- Desktop streaming improvement to gain few more FPS.
- Support password-protected external x509 Certificates.
- Huge desktop streaming optimization, FPS rate increased by 65% (even more if tuning BlockSize)
- Desktop resize is now made viewer-side and automatically to simplify the code and efficiency.
- FastResize option is not required anymore.
- Various code optimization / fix.
- WIN Keyboard Key supported.
- Virtual Desktop window opens above the terminal.
- Server now support LogonUI / Winlogon (Beta)
- 🟢 Mutual Authentication for SSL/TLS (Client Certificate)
- 🟠 Interrupt sessions when local resolution has changed.
- 🔴 LogonUI Support.
🟢 = Easy 🟠 = Medium 🔴 = Hard
Made with ❤️ in 🇫🇷
