RDP Diagnostic & Remediation Tool#

A comprehensive PowerShell-based diagnostic and remediation tool for Remote Desktop Protocol (RDP) connectivity on Windows 10/11 and Windows Server. One script, zero dependencies: it audits every RDP-related subsystem, repairs what it finds, proves the RDP stack actually answers with a real protocol handshake, and exports HTML/JSON reports for humans and automation alike.

📋 Table of Contents#

• What's new in v5

• Quick Start

• Installation

• Features

• Command-Line Reference

• Command Examples

• The RDP Protocol Handshake Probe

• Auto-Update

• Reporting & Automation

• Exit Codes

• Supported Windows Editions

• Architecture & Design

• Safety Model

• Development & CI

• Releasing (Maintainers)

• Troubleshooting

• Support

What's new in v5#

v5.0.0 is a full production refactor of v4.2.0. Highlights (see CHANGELOG.md for the complete list):

Quick Start#

# 1) Get the tool - npm channel (Node.js 18+)
npx rdp-diagnostic-tool -Version          # try it without installing
npm install -g rdp-diagnostic-tool        # permanent: rdp-tool on PATH

#    ... or download RDP-Tool.ps1 from the latest Release, or:
git clone https://github.com/paulmann/RDP-Diagnostic-Tool

# 2) Audit this machine (read-only, works unelevated)
rdp-tool                                  # npm channel
pwsh -NoProfile -File .\RDP-Tool.ps1       # script channel

# 3) Enable + repair RDP end-to-end (elevated, no prompts)
pwsh -NoProfile -File .\RDP-Tool.ps1 -EnableRDP -Force

# 4) Prove RDP answers on a remote host without credentials
pwsh -NoProfile -File .\RDP-Tool.ps1 -TestRdpTarget "srv01.contoso.com:3390"

# 5) Full reference
pwsh -NoProfile -File .\RDP-Tool.ps1 -Help

If script execution is restricted, launch through pwsh -File ... as shown above (bypasses ExecutionPolicy for that invocation) or use Unblock-File .\RDP-Tool.ps1 after downloading.

Installation#

Any one channel is enough - every channel ships the same RDP-Tool.ps1.

PowerShell 7 (pwsh) is required on every channel; install it with winget install Microsoft.PowerShell. Through npm and the package managers the command is on PATH as rdp-tool:

rdp-tool                                  # full read-only audit
rdp-tool -TestRdpTarget "srv01:3389"       # prove the listener really speaks RDP
rdp-tool -EnableRDP -Force                # elevated repair

Self-update (-CheckUpdate / -Update) behaves identically on all channels: the script refreshes itself in place from GitHub Releases. npm-specific details: docs/NPM.md.

Features#

Diagnostics (50+ checks, individually guarded)#

Remediation (explicit, safe, reversible)#

• -EnableRDP - one-shot enable & repair: registry baseline (incl. NLA enforcement, SecurityLayer=Negotiate, High encryption), trigger-aware service repair, firewall enable/create, current-user rights, listener rebind

• -DisableRDP - secure disable with remote-session lockout guard

• -SetPort <n> - listener port change incl. firewall rules and safe listener restart

• -AddUser <u1,u2> - validated, idempotent group membership grants

• -RestartServices - service-stack cycle with self-disconnect protection

• -ForcePrivateNetwork - opt-in network re-categorization

• Everything honors -WhatIf / -Confirm; -Force for unattended runs; GPO-managed settings are detected and skipped with precise guidance; firewall block rules are disabled, not deleted (reversible)

Reporting#

• Color-coded console output with emoji and automatic ASCII fallback (-NoEmoji, NO_COLOR, -Quiet)

• HTML report: verdict banner, KPI tiles, per-check remedies, remediation log, connection instructions (-ExportReport)

• JSON report for CI/monitoring (-ExportJson)

• Plain-text run log, complete even in quiet mode (-LogPath)

Command-Line Reference#

.\RDP-Tool.ps1 [<mode>] [<actions>] [<probes>] [<reporting>] [<update>] [<misc>]

Modes (pick at most one)#

Configuration actions (require elevation)#

Probes & inspection#

Reporting#

Update & misc#

Command Examples#

# Daily-driver audit with all reports for a support ticket
.\RDP-Tool.ps1 -ExportReport .\rdp-report.html -ExportJson .\rdp-report.json -LogPath .\rdp.log

# Unattended fleet repair (SCCM/Intune/RMM): enable RDP, custom port, grant helpdesk
.\RDP-Tool.ps1 -EnableRDP -SetPort 3390 -AddUser 'CONTOSO\rdp-helpdesk' -Force -Quiet -ExportJson C:\Temp\rdp.json

# Dry run: show exactly what would be changed, touch nothing
.\RDP-Tool.ps1 -EnableRDP -WhatIf

# Probe a remote host: is that port REALLY RDP, and does it demand NLA?
.\RDP-Tool.ps1 -TestRdpTarget 10.0.0.5:3390

# Who is connected right now?
.\RDP-Tool.ps1 -ShowSessions

# Incident response: lock the machine down immediately
.\RDP-Tool.ps1 -DisableRDP -Force

# CI: fail the pipeline when RDP is broken or a newer tool version exists
.\RDP-Tool.ps1 -DiagnoseOnly -ExportJson report.json     # exit 1/2 = broken
.\RDP-Tool.ps1 -CheckUpdate                              # exit 5 = update available

# Keep the tool current
.\RDP-Tool.ps1 -Update -Force

The RDP Protocol Handshake Probe#

Most tools stop at "port 3389 is open". RDP-Tool goes one layer deeper and speaks
just enough of the protocol to prove the RDP stack itself is answering:

Client ──► TPKT + X.224 Connection Request + RDP Negotiation Request (TLS|CredSSP)
Server ──► X.224 Connection Confirm + Negotiation Response
             ├─ selectedProtocol: Standard RDP | TLS | CredSSP (NLA)
             └─ or failure code: SSL_REQUIRED_BY_SERVER, HYBRID_REQUIRED_BY_SERVER, ...

$ rdp-tool -TestRdpTarget "srv01.contoso.com:3389"

  ════════════════════════════════════════════════════════════════════════════
  🔌  RDP PROTOCOL HANDSHAKE PROBE
  ════════════════════════════════════════════════════════════════════════════

  Target                : srv01.contoso.com:3389
  TCP connect           : OK (18 ms)
  X.224 CR sent         : 19 bytes (TLS | CredSSP requested)
  mstshash cookie       : aG9zdFxcUkRQ     (from the calling account)

  Server response       : X.224 Connection Confirm + RDP_NEG_RSP
  Negotiated protocol   : CredSSP (NLA)     <- enforced on the wire
  Certificate           : TLS handshake available (no auth attempted)
  Registry / GPO says   : UserAuthentication=1  (matches the wire)

  ✅  The RDP stack answers and requires Network Level Authentication.
      No credentials were sent.

This is the same negotiation mstsc.exe performs before authentication - no
credentials are sent or needed. The probe:

• distinguishes "some TCP service owns the port" from "RDP answers"

• reports whether NLA/CredSSP is enforced on the wire (and flags mismatches with the registry/GPO configuration)

• surfaces exact protocol failure codes that explain classic errors like "CredSSP encryption oracle remediation" or "The local security settings don't allow..."

• works against localhost (after the listener check) and any remote host[:port]

Auto-Update#

The tool carries a machine-readable version marker and knows its own repository:

.\RDP-Tool.ps1 -CheckUpdate     # exit 0 = up to date, 5 = update available, 6 = check failed
.\RDP-Tool.ps1 -Update          # interactive; add -Force for unattended

How -Update works:

1. Resolve the newest version: GitHub Releases API (releases/latest) → if the asset RDP-Tool.ps1 exists, it is used; otherwise the tagged raw file; if the API is unavailable/rate-limited → raw-file probe of the default branch with version-marker parsing.

2. Download over TLS and validate: non-empty, minimum size, not an HTML error page, version marker present and matching the release, full PowerShell syntax parse of the payload.

3. Back up the current script next to it (RDP-Tool.ps1.bak-<timestamp>; falls back to %TEMP%).

4. Replace atomically (temp file + move). Re-run the tool to use the new version.

Enterprise mirrors/air-gapped networks:

.\RDP-Tool.ps1 -Update -UpdateSource https://intranet/tools/RDP-Tool.ps1   # direct file
.\RDP-Tool.ps1 -Update -UpdateSource contoso/RDP-Diagnostic-Tool           # fork slug

Reporting & Automation#

• JSON (-ExportJson) - stable schema: tool, version, reportId, systemInfo, summary (counts + exit code), results[] (component/status/details/remedy/severity/category), remediations[], tests[]. Pipe into ConvertFrom-Json, ship to SIEM/dashboards, diff between runs.

• HTML (-ExportReport) - self-contained (inline CSS), safe to attach to tickets; HTML-encodes all dynamic data.

• Log (-LogPath) - appended, timestamped, includes every check and change even under -Quiet.

• Exit codes - designed for schedulers/CI (table below).

Example (fail a build on any RDP error):

pwsh -NoProfile -File .\RDP-Tool.ps1 -DiagnoseOnly -Quiet -ExportJson rdp.json
if ($LASTEXITCODE -ge 1 -and $LASTEXITCODE -le 2) { throw "RDP misconfigured (exit $LASTEXITCODE)" }

Exit Codes#

Supported Windows Editions#

The v4 edition regex misidentified Home N (CoreN) as RDP-capable. v5 uses an explicit, tested edition matrix (see tests/).

Architecture & Design#

RDP-Tool.ps1 (single file, ~4300 lines, UTF-8 BOM, PowerShell 7+)
│
├─ Metadata           single version marker (release & update contract)
├─ Console/Logging    color+emoji auto-detection, ASCII fallback, file logger
├─ State              script-scoped result/remediation/test stores (no $global:)
├─ Validation         parameter-combination matrix with actionable errors
├─ Help/Version       built-in reference + comment-based help for Get-Help
├─ Update engine      releases API → raw probe fallback, validate → backup → atomic swap
├─ Checks (Test-*)    each wrapped in Invoke-Check (isolated failures)
│   └─ registry(+GPO) · services · firewall · network · listener · handshake ·
│      certificate · permissions · security · resources · event logs
├─ Session engine     WTS P/Invoke (Unicode-correct) + qwinsta fallback
├─ Remediation        ShouldProcess-aware, GPO-aware, idempotent, recorded
├─ Reporting          HTML / JSON / console summary / exit-code mapping
└─ Main               phase pipeline: prereqs → remediate → verify → report

Design rules the codebase follows:

1. Never abort early - every check is guarded; a dead WMI or firewall API degrades the report, it doesn't kill it.

2. Never guess - localized systems are handled via well-known SIDs and language-independent firewall rule names; GPO-managed values are detected instead of being silently overwritten.

3. Never surprise - no changes without explicit action switches; -WhatIf end-to-end; dangerous actions (NLA off, service restart in a live session, disabling RDP remotely) require confirmation or -Force.

4. Be testable - pure logic (protocol codecs, edition matrix, validators) is unit-tested; RDPDIAG_LIB=1 enables dot-sourcing without side effects.

Safety Model#

• Read-only by default; elevation only required for actions (diagnostics run unelevated with reduced coverage).

• -WhatIf shows the full remediation plan without touching the system.

• GPO-locked settings are reported with exact policy paths instead of futile local edits.

• Remote-session guards prevent self-lockout on -DisableRDP / -RestartServices / port changes.

• The tool never reads, stores, or transmits credentials; the handshake probe stops before authentication.

• Updates: TLS only, content validation incl. syntax parse, timestamped backup, atomic replace.

Development & CI#

# Lint
Invoke-ScriptAnalyzer -Path .\RDP-Tool.ps1 -Settings .\ScriptAnalyzerSettings.psd1

# Test (Pester 5+)
Invoke-Pester .\tests -Output Detailed

CI (.github/workflows/ci.yml) runs on every push/PR:
syntax parse gate (Windows + Ubuntu), PSScriptAnalyzer gate (zero Error/Warning with project settings), and the Pester suite on windows-latest (integrity, help coverage, parameter surface, protocol codec, edition matrix, update validation, CLI behavior incl. exit codes).

Releasing (Maintainers)#

1. Bump $script:ToolVersion and the .NOTES version in the comment help and add the CHANGELOG.md entry (the test-suite enforces marker ↔ changelog consistency). tools/npm/package.json is checked against both by tools/npm/check-npm-version.mjs.

2. Merge to main; CI must be green (the package job builds the npm tarball, the release assets and validates the winget manifests).

3. Build and publish the release assets:

   pwsh -NoLogo -NoProfile -NonInteractive -File .\tools\release\make-release-assets.ps1      # RDP-Tool.ps1, ZIP, SHA256SUMS.txt
   pwsh -NoLogo -NoProfile -NonInteractive -File .\tools\release\make-package-manifests.ps1   # winget + Scoop manifests
   pwsh -NoLogo -NoProfile -NonInteractive -File .\tools\release\publish-release.ps1          # tag + GitHub Release (needs gh auth login)

   Tag the release as X.Y.Z (a v prefix is tolerated). Asset names matter: the self-updater downloads the asset named exactly RDP-Tool.ps1, and the winget/Scoop manifests download the ZIP.

4. Publish the npm package (first release only, interactive): node tools/npm/build-npm-package.mjs, then cd dist/npm; npm publish --access public with the one-time password. Afterwards, configure a Trusted Publisher on npmjs.com and let the publish-npm.yml workflow publish on tag pushes.

5. Update the winget and Scoop manifests' URLs/hashes (step 3 regenerates them) and submit the winget manifest via a PR to microsoft/winget-pkgs (see winget/README.md).

6. Verify: .\RDP-Tool.ps1 -CheckUpdate from an older copy must report "update available" (exit 5), and npx rdp-diagnostic-tool@X.Y.Z -Version must print the new version.

Troubleshooting#

More: wiki/Troubleshooting

Support#

• 📖 Wiki: https://github.com/paulmann/RDP-Diagnostic-Tool/wiki

• 🐞 Issues: https://github.com/paulmann/RDP-Diagnostic-Tool/issues - attach an -ExportReport HTML and the -LogPath log

• 📜 Changelog · License (PolyForm Noncommercial 1.0.0)

• ✍️ Author: Mikhail Deynekin [ Deynekin.com ]