From f4052359801640e68b33ab5ca26c7bd43c3e4a7c Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Fri, 4 Sep 2026 13:07:59 +0200 Subject: [PATCH] Update Readme.md --- README.md | 388 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 285 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 5794f56..1adc732 100644 --- a/README.md +++ b/README.md @@ -2,119 +2,200 @@ A dependency-free, non-GUI Windows diagnostics and maintenance-information collector written in PowerShell. -`WindowsMaintenanceReport.ps1` collects useful system, hardware, software, startup, storage, networking, security, and maintenance information into a text report. +`WindowsMaintenanceReport.ps1` provides three levels of reporting: -No Python, third-party modules, or installation is required. +* **Compact** — quick maintenance snapshot, default +* **Mid** — useful hardware, software, startup and driver inventory +* **Full** — comprehensive diagnostics + +No Python, third-party PowerShell modules, or installation is required on the Windows machine. ## Quick Start -### Run directly from the repository +### Compact report -From **PowerShell**: +Open PowerShell and run: ```powershell irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' | iex ``` -This downloads the current version of the script into memory and executes it. +This downloads the latest version into memory and executes it without saving the script to disk. -Nothing needs to be manually downloaded or installed. +The default report is intentionally compact and is intended to provide a quick overview in roughly 20 lines. -For the most complete report, run PowerShell **as Administrator**. +For access to all available diagnostics, running PowerShell **as Administrator** is recommended. -### Run from Command Prompt +## Report Levels -The script can also be launched directly from `cmd.exe`: +### Compact — Default -```cmd -powershell.exe -NoProfile -Command "irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' | iex" -``` - -## Running With Parameters - -The script supports command-line parameters such as: - -* `-OutputDirectory` -* `-EventLogDays` -* `-MaxEventErrors` - -When parameters are required, create a PowerShell script block from the downloaded script: +Run: ```powershell -& ([scriptblock]::Create((irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1'))) -EventLogDays 30 +irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' | iex ``` -For example: +The compact report provides a quick maintenance snapshot including: + +* Computer manufacturer and model +* Windows version and build +* BIOS version +* CPU +* RAM usage +* GPU +* Disk free space +* Physical disk health +* Installed software count +* Startup-entry count +* Automatic-service status +* Problem-device count +* Latest Windows hotfix +* Microsoft Defender status +* System uptime +* Administrator/elevation status + +This is intended to answer the basic question: + +> What is this machine, and is there anything obviously wrong with it? + +## Mid Report + +The Mid report provides the useful inventory information without the noisier diagnostic sections. + +Because parameters cannot be passed directly through `irm | iex`, first retrieve the script and create a script block: ```powershell -& ([scriptblock]::Create((irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1'))) -EventLogDays 30 -MaxEventErrors 250 +$src = irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' +& ([ScriptBlock]::Create($src)) -Mid ``` -To save the resulting report in a specific directory: +The Mid report includes: + +* Operating System / Computer / BIOS +* CPU +* Memory Modules +* Motherboard +* GPU / Display Adapters +* Storage / Free Space / Health +* Installed Programs +* Microsoft Store / AppX Packages +* Startup Registry Locations +* Automatic Services +* Signed Drivers +* Windows Updates / Hotfixes +* Windows Defender Status +* Non-Microsoft Scheduled Tasks + +Logical disks, physical disks, and storage-health information are combined into a single storage section. + +## Full Report + +For the complete diagnostic report: ```powershell -& ([scriptblock]::Create((irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1'))) -OutputDirectory 'C:\Temp' +$src = irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' +& ([ScriptBlock]::Create($src)) -Full ``` +The Full report contains everything from Mid plus additional information such as: + +* Uptime details +* Startup programs +* Startup folders +* Automatic services that are not running +* Devices reporting problems +* Windows Firewall profiles +* Network adapters +* Full IP configuration +* DNS configuration +* Listening TCP ports +* Power plan +* Battery information +* Processes using the most memory +* Recent System event-log errors +* Recent Application event-log errors +* DISM component-store health +* SFC system-file verification +* Important Windows directories + +The Full report is intended for troubleshooting rather than quick inventory. + ## Local Usage -You can also download or clone the repository and run the script normally: +If you already have the script: ```powershell .\WindowsMaintenanceReport.ps1 ``` -If the local PowerShell execution policy prevents the script from running: +Mid report: + +```powershell +.\WindowsMaintenanceReport.ps1 -Mid +``` + +Full report: + +```powershell +.\WindowsMaintenanceReport.ps1 -Full +``` + +If PowerShell execution policy prevents a locally downloaded script from running: ```cmd powershell.exe -NoProfile -ExecutionPolicy Bypass -File WindowsMaintenanceReport.ps1 ``` -The `-ExecutionPolicy Bypass` option applies to that PowerShell process only. It does not permanently change the machine's configured execution policy. +This applies `ExecutionPolicy Bypass` only to that PowerShell process and does not permanently modify the machine's execution policy. -## What It Collects +## Options -The report includes information such as: +### Output Directory -* Windows version, build and installation information -* System uptime -* Manufacturer and computer model -* BIOS information -* CPU -* Physical memory modules -* Motherboard -* GPU/display adapters -* Logical disks and available space -* Physical disks -* Available disk-health and reliability information -* Installed desktop applications -* Microsoft Store/AppX packages -* Startup programs -* Startup registry entries -* Startup folders -* Automatic Windows services -* Automatic services that are not running -* Devices reporting problems -* Installed signed drivers -* Installed Windows updates/hotfixes -* Microsoft Defender status -* Windows Firewall profiles -* Network adapters -* IP configuration -* DNS configuration -* Listening TCP ports -* Active power plan -* Battery information -* Non-Microsoft scheduled tasks -* Processes using the most memory -* Recent System event-log errors -* Recent Application event-log errors -* Windows component-store health -* System-file verification status +Reports are saved in the current working directory when it is writable. + +Specify another directory with: + +```powershell +.\WindowsMaintenanceReport.ps1 -OutputDirectory C:\Temp +``` + +This can be combined with a report level: + +```powershell +.\WindowsMaintenanceReport.ps1 -Mid -OutputDirectory C:\Temp +``` + +If no output directory is specified and the current directory is not writable, the script attempts to use the Windows temporary directory. + +### Event Log History + +The Full report includes recent Windows event-log errors. + +The default range is 7 days. + +To inspect the last 30 days: + +```powershell +.\WindowsMaintenanceReport.ps1 -Full -EventLogDays 30 +``` + +### Maximum Event Errors + +By default, up to 100 errors from each event log are included. + +For example: + +```powershell +.\WindowsMaintenanceReport.ps1 -Full -EventLogDays 30 -MaxEventErrors 250 +``` ## Output -By default, the report is created in the current directory. +The report is displayed live in the terminal while it is being collected. + +At the same time, the output is continuously written to a text file. The filename contains the computer name and timestamp: @@ -125,27 +206,49 @@ windows_system_report_COMPUTERNAME_YYYYMMDD_HHMMSS.txt For example: ```text -windows_system_report_DESKTOP01_20260904_114500.txt +windows_system_report_DESKTOP01_20260904_124500.txt +``` + +The report file is flushed continuously, so information already collected remains available even while slower diagnostics are still running. + +## Administrator Privileges + +The script can run without Administrator privileges. + +When not elevated, it collects everything available to the current user and skips diagnostics that require administrative access. + +For the most complete results, launch PowerShell **as Administrator**. + +The report indicates whether the current session is elevated: + +```text +Administrator: True +``` + +or: + +```text +Administrator: False ``` ## Read-Only Diagnostics -WinDiagnostics is intended to gather information, not modify the machine. +WinDiagnostics is designed to inspect the machine, not modify it. -The script does **not**: +It does **not**: -* uninstall applications -* disable startup programs -* start or stop services -* modify registry values -* install Windows updates -* delete temporary files -* modify networking -* change Windows Defender settings -* change Firewall settings -* automatically repair Windows +* Uninstall applications +* Disable startup programs +* Start or stop services +* Modify registry values +* Install Windows updates +* Delete temporary files +* Modify network configuration +* Change Windows Defender settings +* Change Firewall settings +* Automatically repair Windows -The maintenance commands used by the script are diagnostic: +The Full report can execute these diagnostic commands: ```cmd DISM.exe /Online /Cleanup-Image /CheckHealth @@ -157,7 +260,9 @@ and: sfc.exe /verifyonly ``` -The script deliberately does not automatically execute repair operations such as: +These inspect Windows health without automatically performing repairs. + +WinDiagnostics deliberately does not automatically execute: ```cmd DISM.exe /Online /Cleanup-Image /RestoreHealth @@ -169,19 +274,62 @@ or: sfc.exe /scannow ``` +## Remote Administration + +WinDiagnostics works well with an interactive PowerShell session obtained through Windows Remote Management / WinRM. + +Once connected to the Windows machine, the compact report can be executed directly: + +```powershell +irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' | iex +``` + +This makes it possible to diagnose a Windows machine remotely without copying the script using a USB drive. + +For Mid: + +```powershell +$src = irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' +& ([ScriptBlock]::Create($src)) -Mid +``` + +For Full: + +```powershell +$src = irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' +& ([ScriptBlock]::Create($src)) -Full +``` + +## Enabling WinRM + +If remote PowerShell administration is required, WinRM can be enabled from an elevated PowerShell session on the Windows machine: + +```powershell +Enable-PSRemoting -Force +``` + +This is a one-time configuration on the target machine. + +Only enable remote administration on machines and networks where doing so is appropriate. + ## Running Remote Scripts Safely -The short command: +The convenient syntax: ```powershell irm 'URL' | iex ``` -is convenient, but it also means that PowerShell executes whatever content the server returns at that URL. +means: -Only use this technique with a repository and server that you trust. +* `irm` — `Invoke-RestMethod` downloads the script +* `iex` — `Invoke-Expression` executes the returned PowerShell code -If you want to inspect the script before executing it, download it first: +Nothing needs to be manually downloaded, but PowerShell will execute whatever the server returns. + +Only use this technique with a repository and server you trust. + +To inspect the script before running it: ```powershell irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' -OutFile '.\WindowsMaintenanceReport.ps1' @@ -193,35 +341,69 @@ Then inspect it: notepad .\WindowsMaintenanceReport.ps1 ``` -and run it afterward: +and execute it afterward: ```powershell .\WindowsMaintenanceReport.ps1 ``` -For higher-assurance deployments, consider pinning the download URL to a specific repository commit rather than executing whatever happens to be on the `main` branch. +For higher-assurance environments, consider using a URL pinned to a specific repository commit rather than executing the current `main` branch. ## Privacy -The generated report can contain potentially sensitive machine information, including: +Generated reports may contain information that should not be published publicly, including: -* computer and Windows user names -* hardware serial numbers -* installed software -* running processes -* scheduled tasks -* network interface information +* Computer and Windows user names +* Hardware model and serial information +* Installed software +* Drivers +* Running processes +* Scheduled tasks +* Network configuration * MAC addresses -* local IP configuration +* Local IP addresses * DNS servers -* event-log messages +* Event-log messages -Review the generated report before publishing it or sending it to another person. +Review Full reports before sharing them. + +The Compact report intentionally exposes substantially less information than the Full report. ## Requirements -* Windows 10 or Windows 11 -* Windows PowerShell -* Internet access when running directly from the repository +### Windows machine -No additional dependencies are required. +* Windows 10 or Windows 11 +* Windows PowerShell 5.1 or later +* Internet access when executing directly from the repository + +No Python or third-party PowerShell modules are required. + +### Remote diagnostics + +When administering Windows remotely from another machine, the Windows target must have WinRM configured and reachable. + +## Quick Reference + +```powershell +# Compact +irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' | iex + +# Download into memory +$src = irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' + +# Mid +& ([ScriptBlock]::Create($src)) -Mid + +# Full +& ([ScriptBlock]::Create($src)) -Full + +# Local +.\WindowsMaintenanceReport.ps1 + +# Local Mid +.\WindowsMaintenanceReport.ps1 -Mid + +# Local Full +.\WindowsMaintenanceReport.ps1 -Full +```