WinRM is a great tool for remotely managing Windows computers. It's built into Windows, and is easy to use. However, its configuration is not straightforward.
By default, all computers are in a workgroup. If you're using a personal computer, then you're on a workgroup. Most offices use a Windows domain, which helps with managing computers and users. Using WinRM on domain-joined computers is easy, but trying to configure WinRM on non-domain computers is a bit more complicated. You need to configure WinRM, its listener, firewall rules, an HTTPS certificate, and figure out the right commands to use.
Sometimes winrm quickconfig has a bad day. 😆
These two little scripts make this whole process easy.
- You want to use WinRM at home or at work, but don't want to use HTTP
- You want to use WinRM with HTTPS, but don't have a Windows domain server
- You're getting crazy errors when trying to use WinRM with HTTPS
| Term | Definition |
|---|---|
| Source | The computer you are connecting from (typically an Administrator's computer). |
| Target | The computer you are connecting to (usually a server or another user's computer). |
| HTTP | Hypertext Transfer Protocol (HTTP) is used for transmitting data over a network. It is unencrypted and insecure. Information is transmitted over the network in plain text. |
| HTTPS | Hypertext Transfer Protocol Secure (HTTPS) is HTTP encrypted using TLS or SSL. Used for secure communication over a network. |
| Listener | A WinRM listener responds to WinRM service requests. Defined by IP address, port, and protocol (HTTP/HTTPS, IPv4/IPv6). Can listen on any or specific IP address and port. |
| Certificate | A digital certificate is essential for enabling HTTPS encryption. It certifies the ownership of a public key by the certificate's subject, allowing secure communication through encryption. Issued by a Certificate Authority (CA) or self-signed, it links the public key with its owner and provides identity information. |
- WinRM uses port 5985 for HTTP and port 5986 for HTTPS.
- You can change the ports if you want, but it's not recommended.
- For HTTPS connections, WinRM listens on
https://HOSTNAME:5986/wsman. - Below is a very simplified representation of WinRM's network traversal so you can understand what's happening when you initiate a WinRM connection from PowerShell. Certain steps are omitted for simplicity such as the source computer, TLS/SSL negotiation, etc.
- PowerShell
- Administrative rights
- LAN/VPN connectivity between the Source and Target
- Windows 10/11 Pro or Windows Server 2016/2019/2022
- Shows you a list of network adapters and their categories.
- Allows you to select a network adapter to change to Private.
- Enables WinRM.
- Disables all default WinRM Rules.
- Creates a firewall rule to allow WinRM HTTPS traffic on port 5986 from any IP address.
- Disables the HTTP listener if it exists.
- Creates a self-signed HTTPS certificate (valid for 15 years).
- Creates a WinRM HTTPS listener.
- Restarts the WinRM service.
- Prompts for the target hostname, and downloads the certificate.
- Imports the certificate into the Trusted Root Certification Authorities store.
- Shows you the command to connect to the target machine.
- Optionally tests the connection.
Warning
Do NOT expose a machine with WinRM enabled to the internet. WinRM is not designed to be secure enough for internet use. If you need to use WinRM over the internet, use a VPN.
- Run
Target-Machine.ps1on the Target machine, which is the computer you want to connect to - Windows Firewall allows all local subnet IPs to access WinRM. To change this, edit the 'Windows Remote Management (HTTPS-In)' firewall rule.
- Run
Source-Machine.ps1on the Source, which is the computer you want to connect from
HTTP is insecure because information is transmitted in plain text over the network (unencrypted). In terms of WinRM, it means anyone can see the data you're sending and receiving. This is a security risk, and is not recommended.
"I shouldn't use HTTP even in my own home?"
Correct! I avoid using HTTP if at all possible, even at home or a small office. Sure, you may trust the other people in your home, but do you trust all of the other devices in your home? What about that smart TV, or that smart fridge? What about that smart lightbulb? Although it's unlikely, if a bad actor had access to one of these device through say, some cloud-connected management system, it could be possible to intercept WinRM traffic, see what you're doing, then gain access to your computers, servers, and data. With additional lateral movement, who knows, they could even gain access to your bank account. Again, it's unlikely, but it's technically possible.
While HTTPS doesn't offer foolproof security, it's undeniably a step in the right direction and a prudent practice to adopt. This habit is particularly beneficial for system administrators and IT professionals. It helps in reducing the chances of bad actors intercepting traffic and gaining insights.
Creating a new self-signed certificate effectively severs the dependence on existing certificates. It establishes a dedicated certificate exclusively for WinRM use, eliminating the need to repurpose or create additional certificates for your computer. Moreover, self-signed certificates provide the convenience of easy removal when required.
In future versions this functionality may be expanded to allow the use of existing certificates.
Kerberos authentication is a great way to authenticate users and computers on a Windows domain. However, it's not available for non-domain computers. If you're using WinRM at home or at work on a non-domain computer, you can't use Kerberos authentication.
By creating new firewall rules rather than modifying existing ones, it allows us to ignore any potential misconfigurations or issues with existing rules. It also allows us to easily remove the rules if needed. Default rules are not deleted but simply disabled.
It will be soon!
Get-Item WSMan:\localhost\Client\TrustedHostsor just the values
(Get-Item WSMan:\localhost\Client\TrustedHosts).ValueSet-Item WSMan:localhost\client\trustedhosts -Value *Set-Item WSMan:\localhost\Client\TrustedHosts -Value 'machineA,machineB'Set-Item WSMan:\localhost\Client\TrustedHosts -Value 'machineC' -Concatenate- Get the list of trusted hosts
- Adjust the command separated list as needed, removing the unneeded host
- Use the commands to set the trusted hosts
winrm enumerate winrm/config/listenerwinrm get winrm/config- As always, restart the computer (both) and try again. 🤓
- Make sure you can ping the computers both ways. Use IP addresses first, then try hostnames.
- Test the connectivity using Test-NetConnection.
Test-NetConnection -ComputerName HOSTNAME -Port 5986 -InformationLevel Detailed
- As a test of some port accessibility, enable RDP on the target machine and see if you can connect.
- If RDP is enabled and you can't connect over RDP, then the issue is unrelated WinRM as is likely a network/firewall issue.
- The reason for this test is that RDP reliably enables firewall rules and opens ports.
- If you are unable to connect, try temporarily disabling Windows Firewall on the target machine (only if it is safe to do so).
- If you can connect after disabling Windows Firewall — good news! — simply adjust the Windows Firewall rules!
- Enumerate the WinRM listeners on the target machine.
- If you don't see a listener, then for some reason the
Target-Machine.ps1script failed to create it. - You can try running the script again, or manually creating the listener.
- If you see an error message please open an issue and include the full error message so that that script can be improved.
- If you don't see a listener, then for some reason the
- Create consistent grammar for the script output
- Add a check for the WinRM service
- More options for security on firewall, listener configuration, and certificate creation
- Ability to use existing certificate, listener, and/or firewall rule
If you'd like to help develop this project: fork the repo, edit, then submit a pull request. 😊