WinRM Operator

intent

Use this skill to execute remote PowerShell commands over WinRM with secure defaults. Run this when you need to execute commands on remote Windows hosts, transfer files via PSSession, enable or configure WinRM listeners, select authentication modes (Kerberos, NTLM, CredSSP, Basic), or diagnose WinRM connectivity and authorization failures. Always verify connectivity first, pick authentication intentionally, and report exact commands plus per-host outcomes.

inputs

• Target hostnames or IPs: list of Windows machines to connect to.
• Domain status: whether targets are domain-joined or workgroup.
• Allowed authentication methods: Kerberos, NTLM, Negotiate, CredSSP, or Basic (influences credential strategy).
• Double-hop requirement: boolean, whether the remote session needs to access downstream resources (determines auth mode constraints).
• Action type: one-shot command, script run, file transfer, or multi-host fan-out (influences remoting pattern).
• Credentials: username/password or managed service account (collected via Get-Credential or passed as PSCredential object).
• Network connectivity: SSH/RDP/firewall access to port 5985 (HTTP) or 5986 (HTTPS) on targets.
• WinRM listener state (optional): whether WinRM service is running and listening on targets (discovered via Test-WSMan).
• TrustedHosts configuration (workgroup only): regex or host list for client-side trust (stored in WSMan:\localhost\Client\TrustedHosts).

procedure

1. Gather required inputs

   • Input: target hostnames/IPs, domain status, allowed auth methods, action type.
   • Output: input checklist validated locally.
   • Ask the user to confirm each: target list, whether hosts are domain-joined or workgroup, which auth methods are allowed in their environment, whether double-hop is required, and the action type (one-shot, script, file transfer, or fan-out).

2. Run preflight network checks from the controlling machine

   • Input: target hostname or IP.
   • Output: port reachability status (5985 or 5986) and WSMan listener status.
   • Execute on the controlling machine (not the target):

     Test-NetConnection <host> -Port 5985
     Test-NetConnection <host> -Port 5986
     Test-WSMan <host>
     

   • Capture success/failure for each port and Test-WSMan result.
   • If network checks fail (TcpTestSucceeded = $false), stop and report routing, firewall, or listener reachability issues. Do not proceed to credential collection.
   • If ports are reachable but Test-WSMan fails (HTTP or HTTPS), proceed to step 3 but flag that listener or authentication configuration may need diagnosis.

3. Choose transport and authentication mode

   • Input: domain status, allowed auth methods, double-hop requirement, network trust posture.
   • Output: transport choice (HTTP port 5985 or HTTPS port 5986), authentication mode, and credential object.
   • Decision tree (see decision points section below).
   • Collect credentials via Get-Credential if not already provided.

4. Execute with the least invasive pattern

   • Input: auth mode, transport, credentials, target host(s), action type, script/command content.
   • Output: command execution result, errors per host, session handle (if persistent session created).
   • For one-shot actions: use Invoke-Command with -ComputerName and -ScriptBlock. Example:

     Invoke-Command -ComputerName <host> -Credential $cred -Authentication Kerberos -ScriptBlock {
         hostname
         Get-Service WinRM
     }
     

   • For repeated commands or file copy: use New-PSSession, then Invoke-Command -Session $s or Copy-Item -ToSession $s. Example:

     $s = New-PSSession -ComputerName <host> -Credential $cred -Authentication Kerberos
     Copy-Item .\local.ps1 -ToSession $s -Destination C:\Temp\local.ps1
     Invoke-Command -Session $s -ScriptBlock { powershell -ExecutionPolicy Bypass -File C:\Temp\local.ps1 }
     Remove-PSSession $s
     

   • For fan-out to many hosts: use Invoke-Command with -ComputerName @(list) and -ThrottleLimit <number> to cap parallel execution. Example:

     Invoke-Command -ComputerName @('host1','host2','host3') -Credential $cred -ThrottleLimit 5 -ScriptBlock { hostname }
     

   • Capture stdout, stderr, and exit codes per host.

5. Validate and summarize results

   • Input: execution results, errors, per-host status.
   • Output: host-by-host status summary with remediation actions.
   • For each host, return: hostname, command(s) executed, success/failure status, key error text (if failed), and next remediation step.
   • Example format:

     host1: SUCCESS - hostname returned 'host1', WinRM service running.
     host2: FAILED - Access is denied. Next: verify credential scope and local admin rights.
     host3: FAILED - Test-WSMan timeout. Next: check firewall rule for port 5986 and WinRM listener state.
     

decision points

• If domain-joined and Kerberos is allowed: use -Authentication Kerberos with HTTP (port 5985). Skip credential prompt if running as domain-joined user. If Kerberos fails, check SPN registration on target via setspn -L <hostname> and verify delegation trust.

• If workgroup or untrusted network: use HTTPS (-UseSSL -Port 5986) with -Authentication Negotiate. Require manual TrustedHosts entry on the client:

  Set-Item WSMan:\localhost\Client\TrustedHosts -Value "<host-or-pattern>" -Force
  

  Treat broad TrustedHosts values as temporary and reduce scope after work completes.

• If double-hop is required: do not use Basic auth or NTLM (they do not support delegation). use Kerberos with constrained delegation (domain admin request) or CredSSP only when explicitly approved by the user (CredSSP exposes plaintext credential in memory on the first hop).

• If Test-WSMan fails but port is reachable: diagnose listener state:

  • On the target (via local console or out-of-band access), run:

    Get-Service WinRM | Select-Object Status
    Get-ChildItem WSMan:\localhost\Listener
    

  • If WinRM service is stopped, propose Start-Service WinRM.
  • If no HTTPS listener exists and user requested HTTPS, ask user permission to configure it (see WinRM configuration section).
  • If authentication mismatch (e.g., Kerberos requested but target only has Basic enabled), propose auth mode adjustment or listener reconfiguration.

• If Access is denied: verify credential scope (user must be local admin on target), auth mode alignment (Kerberos requires domain, NTLM requires matching domain or workgroup TrustedHosts), and whether CredSSP is required for the action. Do not retry with higher privilege without explicit user approval.

• If timeout or connection refused: verify DNS resolution, routing to target, firewall rules (inbound on 5985/5986), and listener state via Test-WSMan. Propose firewall rule adjustment or WinRM service restart only on explicit user request.

• If HTTPS certificate error (e.g., "untrusted root"): verify cert trust chain on client (certmgr.msc), check CN/SAN match in the certificate, and verify listener certificate mapping on target via Get-ChildItem WSMan:\localhost\Listener\HTTPS. Propose cert update or SkipCACheck flag only if user acknowledges the risk.

• If no error but command output is empty: check that script or command produces output (some PowerShell commands produce no stdout by default). Ask user to add Write-Host or pipe to Out-String if needed.

• If rate limit or session limit hit: reduce -ThrottleLimit for fan-out, add delays between commands, or batch commands into fewer sessions. PowerShell WinRM has no documented hard rate limit, but firewalls or load balancers may throttle concurrent sessions.

output contract

Always return:

• Exact commands executed or proposed: full PowerShell syntax, auth mode, and transport (HTTP port 5985 or HTTPS port 5986).
• Chosen authentication and transport: one of (Kerberos, NTLM, Negotiate, CredSSP, Basic) and HTTP or HTTPS. Include port and any TrustedHosts entries if workgroup.
• Per-host result status: table or list with columns (hostname, command, status, error text if failed, remediation).
• Next remediation step for each failed host: specific action (e.g., "check firewall inbound rule on port 5986", "verify SPN registration", "confirm local admin membership", "reconfigure WinRM listener").
• Credential redaction: never include plaintext passwords or token values in output. Log credential type only (e.g., "Kerberos delegation", "explicit PSCredential", "CredSSP").

outcome signal

The skill worked if:

• All target hosts return a clear status (success or failure with reason).
• Commands execute and produce expected output on successful hosts.
• Failed hosts have a concrete next step proposed (not generic advice).
• Preflight checks run without error and accurately identify reachability or listener issues.
• User can paste the "exact commands executed" into a PowerShell console and reproduce the result.